You can have the system automatically convert emails into new issues through Incoming Email (IEM). You may configure Issuetrak to retrieve messages from Exchange, IMAP, POP3, Google, or Office365 mailboxes. If you are also using Issue Notifications or any Outgoing Email in your site, IEM will also convert Replies or Forwards related to those messages into notes on their originating issues.
All emails sent from your site include embedded issue tags in the subject line in case they ever come back in a Reply or Forward through IEM (e.g. RE: Issue #12345 ).
Once configured, Issuetrak will log into the designated mailbox and process any messages in the Inbox folder that are unread into the Issuetrak site. Issuetrak will then attempt to determine if the message is a response to an issue that already exists and if it is unable to match the message to an Issue, a new Issue will be created based upon the settings configured in the mailbox.
If there is a problem processing a message an email will be sent to the designated Notify on Error user, this user is designated at the bottom of the Incoming Email settings for the account in question. The "Notify on Error" message sent will state what mailbox is having the issue as well as the reason for the failure.
To see the available setting options for Incoming Email features, please see our Managing IEM Mailboxes article.
Adding Notes to Existing Issues
The easiest way to add a note to an issue is to reply to its associated outgoing email notification you have received from Issuetrak. However, you can manually reply or forward a message by adding the appropriate subject to the beginning.
Normally, Issuetrak requires that users have visibility on an issue in order to add notes. The option "Require users to have issue visibility to add notes" can be unchecked on the IEM mailbox configuration page in order to remove this requirement and allow users that cannot view the issue to add notes to it.
IEM searches the subject line of each email message for special values that would indicate this message is a response to an existing issue.
The following subject line prefixes are supported by IEM:
- RE:
- VL:
- REF:
- TRS:
- FW:
- SV:
- TR:
- RV:
- FWD:
- ODP:
- Vá:
- ENC
- AW:
- BETR:
- Továbbítás:
- PD:
- FS:
- CV:
- R:
- YNT:
- VS:
- RES:
- RIF:
- ILT:
- WG:
- Antw:
- I:
- ATB:
- VB:
- Doorst:
- BLS:
- YML:
- ??:
- RV:
- İLT:
- ΑΠ:
- ΠΡΘ:
- ΣΧΕΤ:
- הועבר:
- השב:
- إعادةتوجيه:
- رد:
- பதில்:
- முன்னனுப்பு:
- 回复:
- 回覆:
- 轉寄:
- 转发:
Example Subjects
If you have changed the Issue Label to something else, simply replace all examples with that label instead of "Issue" to ensure your reply gets processed.
- RE: Issue #1234
- RE: Issue #2345 - Server is down
- FW: Issue #65432
- FW: Issue #555 - Need assistance!
Private Notes
The incoming email module allows replies to email, sent from Issuetrak to be parsed and added as Notes on the sending issue. By default, the notes added to the issue will be set to public. There is one case where that is not true: in a case where a user has the user permission, “Can view and add Private Notes” and where "Private" is enabled on the System Defaults screen. If this combination is in place, then the notes added through replies using the Incoming Email Module will also be set to private.
Application-Level Considerations
There is no limit to the number of mailboxes IEM can process. Each of these mailboxes may reside on a different server and have different access credentials. In addition, each one can be processed differently based on its settings within your Issuetrak interface. This includes —whether or not the system:
- Deletes messages from the mailbox server after processing
- Applies a size limit to the individual Attachments it will add to issues
- Applies a default Assignment, Issue Template, Class, and / or Issue Type to new issues
- Tries to determine Issue Type / Subtypes for new issues using the Subject line
- Tries to determine an Issue Template to use to create new issues using the Subject line
- Adds Subscribers to issues based on the CC line
- Accepts only messages from existing users or from unknown users by:
- Using a default user record to submit their issues
- Using a template to create their user record, then submit their issue
- Using simple defaults to create their user record, then submit their issue
- Emails login credentials to new users it creates from a sender and / or CC line
- Reopens closed issues when additional replies are received
- Accepts only a certain number of messages from the same user within a certain number of minutes (to prevent email loops)
Across all your IEM mailboxes, there are additional options you can configure.
| Option | Definition |
|---|---|
| Email Tokens | When included in an email, it will change values in certain fields, such as user-defined fields, or perform a specific action such as assign or close. |
| Keywords | Specific words or phrases that trigger an email to be bounced and not processed, such as common auto-reply or spam terms. |
| Excluded text | Standard confidentiality or disclaimer statements that are left out of the text when emails are processed. |
| Blocked attachments | Specific attachments that can be excluded from processing, such as a logo or other image file included in email signatures. |
Server-Level Considerations
The messages in your mailbox are processed as quickly as the set frequency of the Windows Scheduled Task controlling IEM. The scheduled task is always deployed with an initial start time of 12:12 AM and set to run every 2 minutes by default with a random offset between 0-120 seconds.
The scheduled task consists of two processes that are launched consecutively: The Email Retriever and the Email Processor. Premises customers can change the frequency of this task, however, it is important that the frequency not be set too short. Especially with multiple mailboxes, you should give the task enough time to process all of its mailboxes before it is set to run again or performance problems can occur.
The system inserts"Submitted by direct email to [Mailbox Account ID]"in the Issue Description or Note as it converts email messages. This is the only noticeable difference between how the system responds to issues or notes added through IEM and those entered through the site’s interface. All other processes will apply as normal, such as Issue Notifications, Workflows, Substatus Rules, Service Level Agreements, etc.
Logging Considerations
There are two logs maintained for Incoming Email: The Product log and the Service log.
The Product log is kept for informational purposes and logs the content of every email processed by Issuetrak. You can locate it by clicking the gear icon in the top right to open the Settings Lightbox > Incoming Email beneath Email > View Log on the right quick menu.
The Service log is generated by the Incoming Email Scheduled Task and contains information related to the Web server's communication with the Incoming Email server(s), as well as receiving and processing the emails into issues. Each log file will be up to 20MB. Once a file reaches 20MB, a new log file is created. Up to 10 log files will be kept. The Service log is stored in each Issuetrak site's web folder within pathto:\WebFolder\Services\IEM\Logs\.
FAQs
Is it possible to automate certain fields to be populated from another system with Incoming Email?
Yes! Incoming email messages sent in from other systems can have their automated messages edited to use Tokens to automatically populate certain issue fields with data.
If a user not associated with an issue needs to add a note to an issue, how would that be done?
User can add notes to existing issues if 3 items are in place to allow the note to be added:
- The setting for "Require users to have issue visibility to add notes" must be unchecked on the IEM mailbox in question.
- The sender of the message must include an approved message reply or forward header to the subject as shown in the list above.
- The sender includes the issue number in the subject in the format of "<issuelabel> #<issuenumber>" replacing the label and number with the appropriate name and issue number for the note to be added.
Activating Incoming Email
As a prerequisite, you will need existing mailboxes to configure your IEM. If you have purchased a mailbox through Issuetrak, make sure you have that account information available.
Steps:
- Click the gear icon in the upper right > click Incoming Email beneath Email.
- Click the checkbox next to Process Incoming Email.
- Click Update.
A confirmation message will display when the update is complete. The Incoming Email menu option will then appear available on the Settings Lightbox.
Adding an Exchange, IMAP, or POP3 Mailbox
- Click the gear icon in the upper right > click Incoming Email beneath Email.
- Click Add beneath Mailboxes in the right quick menu.
- Under Email Account Information, the first option available is an Active check box. This box will be checked by default when adding a new mailbox and can be unchecked to ensure new issues are not created if messages are sent to the specified address.
This can be useful if the mailbox you are adding has existing emails that need to be cleared before going live with this feature.
-
Click the Server Type dropdown option corresponding to the type of mailbox you’re setting up (Exchange, IMAP, POP3).
When you select the Exchange server type, Enable Autodiscover is checked by default. To enter the Mail Server, Domain, and EWS endpoint URL manually, uncheck this option to make the appropriate fields available.
-
Fill out the server, account, and password information. If using IMAP or POP3, make sure you select Use TLS if applicable.
-
If using IEM Exchange, you will need to select your version from the drop-down.
-
-
Include return address and from name information. This needs to be a general account, not one that belongs to an actual user. If you only have a single mailbox, you can omit this step and the system will automatically use the return address specified in System Lightbox > Outgoing Email beneath Email.
If you're using POP, we recommend that your mailbox settings be set to mark messages read or deleted when accessed, instead of "Keep a copy in the mailbox." This is to avoid confusion as to whether the messages were processed.
-
(Optional) Test your connection to the server information provided by clicking on Test Connection.
If the test is successful, a green message will appear next to the Test Connection button that states Connection Successful. If the test is unsuccessful, a red message will appear with details to assist in resolving the connection issue. If you cannot achieve a successful connection after correcting the specified settings, please contact our Support Team for assistance at 757-213-1351, support@issuetrak.com or https://support.issuetrak.com. -
(Optional) Choose whether Issuetrak will only process replies to existing issues from this mailbox.
-
(Optional) Select a user or group to be automatically assigned to new issues created.
-
(Optional) Select a default Class value to apply to all new issues created.
-
Select a default Issue Type to be applied to any new issue where the Type / Subtype was not derived.
-
(Optional) Select whether you want the system to derive the Issue Type / Subtype by scanning the subject line and finding an exact match or a contained match.
-
(Optional) Select whether a default Issue Template should be applied to all new issues created. If this is selected, then the "Assign Issue Type" options above it will be grayed out.
-
(Optional) Select whether you want the system to derive an Issue Template to apply by scanning the subject line and finding an exact match or a contained match to an Issue Template name
-
Under the User creation section, select one of the radio button options.
- Accept mail only from existing Issuetrak users, or active Active Directory users (if module purchased)
- Submit new issues as a specified user. If selected, use the magnifying glass to select the specific user for the issues to be submitted under.
- Create users from this template. If selected, use the magnifying glass to select an existing template, or click Add User Template to create a new template to be used. Users created via template will have organization memberships and permissions mirroring those selected in the template profile.
- Create user with these default values. If selected, use the magnifying glass to set default Organization and Location values.
-
(Optional) If either of the create options were selected, you can select whether to determine the Organization from the email domain. This will look at the email domain and attempt to match it to the web address field of an organization record. You can also select whether you want to email login credentials to those new users.
-
(Optional) If you want the submitting user account to have the ability to add notes to issues regardless of its ability to view those issues, you may uncheck the option labeled with "Require user to have issue visibility to add notes" which is enabled by default.
-
If set to Accept email from existing users only, email from any address not found in your users table will be rejected. If you have specified a user to be notified on error, that user will get a notification that the issue was not created.
-
-
(Optional) Enable Subscribe users from the email's CC list to the Issue.
-
(Optional) Choose between the following three options:
- Only subscribe existing Issuetrak users or existing Active Directory users to Issue
- Create users from this template: (Select a template)
- Create users with these default values: (Select an organization)
- (Optional) Enable Email login instructions when new user is created from a template.
-
(Optional) Enable Attempt to determine organization from email domain when creating a user. If this is enabled, IEM will compare each sender's email domain against the value stored for each organization's "IEM Email Domain" field and will associate the sender with the first matching value.
-
(Optional) Select Reopen Issue if note added after close If you want closed issues to be reopened when someone sends in a reply via IEM.
-
Select a user to be notified if there are any errors in email processing.
-
Adding a value to the Attachments field applies a size limit to the individual Attachments IEM will add to issues.
-
(Optional) Adjust the loop prevention settings. The default is to refuse email when the mailbox received more than five messages from the same person within five minutes.
-
Click Add Mailbox button.
A confirmation message will appear when this process is complete.
Adding an Office 365 Mailbox
In order to add an Office 365 mailbox, you or your Azure administrator must create a new app registration in Azure, the steps to create this app registration and connect it to Issuetrak can be located in the following article.
About Microsoft Office 365 Integration
Once the Application is registered in Issuetrak you will then be able to access the Settings > Incoming Email page and configure the specific account to be processed into the site.
Configuring Issuetrak to Retrieve Mail from Office 365
Steps:
- Click the gear icon in the upper right > click Incoming Email beneath Email.
- Click Add beneath Mailboxes in the right quick menu.
- Under Email Account Information, the first option available is an Active check box. This box will be checked by default when adding a new mailbox and can be unchecked to ensure new issues are not created if messages are sent to the specified address.
- Select the Office 365 option from the Server Type dropdown menu.
- Select the name of the application you added to Issuetrak's Office 365 Applications screen earlier.
- Select the Mailbox Identifier Type:
- Email Address - Requires "User.Read.All" permission on the app registration.
- Principal Name/Object ID - Does not require "User.Read.All" permission on the app registration.
- Fill out the Mailbox Identifier - The email address associated with the mailbox you will be retrieving email from, or Principal Name/Object ID from the app registration screen.
- Include return address and from name information. If you only have a single mailbox, you can omit this step and the system will automatically use the return address specified in System Lightbox > Outgoing Email beneath Email.
-
This needs to be a general account, not one that belongs to an actual user.
-
-
(Optional) Test your connection to the server information provided by clicking on Test Connection.
If the test is successful, a green message will appear next to the Test Connection button that states Connection Successful. If the test is unsuccessful, a red message will appear with details to assist in resolving the connection issue. If you cannot achieve a successful connection after correcting the specified settings, please contact our Support Team for assistance at 757-213-1351, support@issuetrak.com or https://support.issuetrak.com -
(Optional) Select a user or group to be automatically assigned to new issues created.
-
(Optional) Select a default Class value to apply to all new issues created.
-
Select a default Issue Type to be applied to any new issue where the Type/Subtype was not derived.
-
(Optional) Select whether you want the system to derive the Issue Type/Subtype by scanning the subject line and finding an exact match or a contained match.
-
(Optional) Select whether a default Issue Template should be applied to all new issues created.
-
(Optional) Select whether you want the system to derive an Issue Template to apply by scanning the subject line and finding an exact match or a contained match to an Issue Template name
-
Under the User creation section, select one of the radio button options.
- Accept mail only from existing Issuetrak users, or active Active Directory users (if module purchased)
- Submit new issues as a specified user. If selected, use the magnifying glass to select the specific user for the issues to be submitted under.
- Create users from this template. If selected, use the magnifying glass to select an existing template, or click Add User Template to create a new template to be used. Users created via template will have organization memberships and permissions mirroring those selected in the template profile.
- Create user with these default values. If selected, use the magnifying glass to set default Organization and Location values.
-
(Optional) If either of the create options were selected, you can select whether to determine the Organization from the email domain. This will look at the email domain and attempt to match it to the web address field of an organization record. You can also select whether you want to email login credentials to those new users.
-
(Optional) If you want the submitting user account to have the ability to add notes to issues regardless of its ability to view those issues, you may uncheck the option labeled with "Require user to have issue visibility to add notes" which is enabled by default.
-
If set to Accept email from existing users only, email from any address not found in your users table will be rejected. If you have specified a user to be notified on error, that user will get a notification that the issue was not created.
-
-
(Optional) Enable Subscribe users from the email's CC list to the Issue.
-
(Optional) Choose between the following three options:
- Only subscribe existing Issuetrak users or existing Active Directory users to Issue
- Create users from this template: (Select a template)
- Create users with these default values: (Select an organization)
- (Optional) Enable Email login instructions when new user is created from a template.
-
(Optional) Enable Attempt to determine organization from email domain when creating a user. If this is enabled, IEM will compare each sender's email domain against the value stored for each organization's "IEM Email Domain" field and will associate the sender with the first matching value.
-
(Optional) Select Reopen Issue if note added after close If you want closed issues to be reopened when someone sends in a reply via IEM.
-
Select a user to be notified if there are any errors in email processing.
-
Adding a value to the Attachments field applies a size limit to the individual Attachments IEM will add to issues.
-
(Optional) Adjust the loop prevention settings. The default is to refuse email when the mailbox received more than five messages from the same person within five minutes.
-
Click Add Mailbox button.
-
A confirmation message will appear when this process is complete.
Adding a Gmail IMAP or POP3 Mailbox
In order to add a Gmail-based mailbox to IEM in Issuetrak, you or your designated IT contact must perform some steps within Google's environment, and then it is necessary to add the resulting information to Issuetrak's Google Applications screen. Specifically, you must have a Client ID and a Client Secret that has been generated for your Gmail account. Afterwards, you may proceed with adding and configuring a Gmail IMAP or POP3 mailbox using the steps below.
- Click the gear icon in the upper right > click Incoming Email beneath Email.
- Click Add beneath Mailboxes in the right quick menu.
- Under Email Account Information, the first option available is an Active check box. This box will be checked by default when adding a new mailbox and can be unchecked to ensure new issues are not created if messages are sent to the specified address.
- Select either Gmail IMAP or Gmail POP3 from the "Server Type" dropdown menu.
- Select the name of the application you added to Issuetrak's Google Applications screen earlier.
- Set the Return Address and From Name, if desired.
- Select whether you want messages to be deleted after processing. (We recommend that this remain checked).
If you're using POP, we recommend that your mailbox settings be set to mark messages read or deleted when accessed, instead of "Keep a copy in the mailbox." This is to avoid confusion as to whether the messages were processed.
-
(Optional) Test your connection to the server information provided by clicking on Test Connection.
If the test is successful, a green message will appear next to the Test Connection button that states Connection Successful. If the test is unsuccessful, a red message will appear with details to assist in resolving the connection issue. If you cannot achieve a successful connection after correcting the specified settings, please contact our Support Team for assistance at 757-213-1351, support@issuetrak.com or https://support.issuetrak.com -
(Optional) Select a user or group to be automatically assigned to new issues created.
-
(Optional) Select a default Class value to apply to all new issues created.
-
Select a default Issue Type to be applied to any new issue where the Type/Subtype was not derived.
-
(Optional) Select whether you want the system to derive the Issue Type/Subtype by scanning the subject line and finding an exact match or a contained match.
-
(Optional) Select whether a default Issue Template should be applied to all new issues created.
-
(Optional) Select whether you want the system to derive an Issue Template to apply by scanning the subject line and finding an exact match or a contained match to an Issue Template name
-
Under the User creation section, select one of the radio button options.
- Accept mail only from existing Issuetrak users, or active Active Directory users (if module purchased)
- Submit new issues as a specified user. If selected, use the magnifying glass to select the specific user for the issues to be submitted under.
- Create users from this template. If selected, use the magnifying glass to select an existing template, or click Add User Template to create a new template to be used. Users created via template will have organization memberships and permissions mirroring those selected in the template profile.
- Create user with these default values. If selected, use the magnifying glass to set default Organization and Location values.
-
(Optional) If either of the create options were selected, you can select whether to determine the Organization from the email domain. This will look at the email domain and attempt to match it to the web address field of an organization record. You can also select whether you want to email login credentials to those new users.
-
(Optional) If you want the submitting user account to have the ability to add notes to issues regardless of its ability to view those issues, you may uncheck the option labeled with "Require user to have issue visibility to add notes" which is enabled by default.
-
If set to Accept email from existing users only, email from any address not found in your users table will be rejected. If you have specified a user to be notified on error, that user will get a notification that the issue was not created.
-
-
(Optional) Enable Subscribe users from the email's CC list to the Issue.
-
(Optional) Choose between the following three options:
- Only subscribe existing Issuetrak users or existing Active Directory users to Issue
- Create users from this template: (Select a template)
- Create users with these default values: (Select an organization)
- (Optional) Enable Email login instructions when new user is created from a template.
-
(Optional) Enable Attempt to determine organization from email domain when creating a user. If this is enabled, IEM will compare each sender's email domain against the value stored for each organization's "IEM Email Domain" field and will associate the sender with the first matching value.
-
(Optional) Select Reopen Issue if note added after close If you want closed issues to be reopened when someone sends in a reply via IEM.
-
Select a user to be notified if there are any errors in email processing.
-
Adding a value to the Attachments field applies a size limit to the individual Attachments IEM will add to issues.
-
(Optional) Adjust the loop prevention settings. The default is to refuse email when the mailbox received more than five messages from the same person within five minutes.
-
Click Add Mailbox button.
-
A confirmation message will appear when this process is complete.
Updating an Existing Mailbox
Once mailboxes are created, the values can be adjusted at any time.
Steps:
- Click the gear icon in the upper right > click Incoming Email beneath Email.
- Click edit next to the appropriate mailbox in the list.
- Make your changes in the Edit Mailbox screen that opens.
- Click Update Mailbox.
A confirmation message will appear when this process is complete.
Deleting an IEM Mailbox
Note that you can always inactivate a mailbox at any time by toggling them on and off via the Active slider. However, if you choose to delete a mailbox, please follow the below steps.
Steps:
- Click the gear icon in the upper right > click Incoming Email beneath Email.
- Click del next to the mailbox you are deleting.
- Click OK when prompted to confirm.
A confirmation message will appear when this process is complete.
For security reasons, Google will deprecate support for using basic authentication (which relies on your Google account's username and password) with third-party applications when using their Gmail service on May 30, 2022.
It is therefore necessary to use a Google App Password to allow Issuetrak to authenticate with Google when you are using their email service with Issuetrak's IEM feature to prevent disruption of service.
Creating the Google App Password
- Enable 2-Step Verification on your Google account by navigating to this page and signing into the Google account corresponding with the mailbox that you wish to create an app password for, then following the prompts.
- Once you've set up 2-Step Verification in the previous step, navigate to https://myaccount.google.com/apppasswords and (again) sign into the Google account corresponding with the mailbox that you wish to create an app password for.
- Choose Mail for the "select app" drop down.
- Choose the appropriate device for the "select device" drop down.
- Click on GENERATE.
- Copy and save the password shown in the next screen, as this will be the only time you will see this password.
Using the Google App Password for IEM Mailboxes
- Log into the Issuetrak site to be updated.
- Click the settings gear icon in the top right.
- Click Incoming Email under the Email section to launch the mail settings.
- To locate the setting faster, enter incoming email in the search field.
- Depending on your specific usage, you may want to either edit an existing mailbox or create a new mailbox.
- To use the Google App Password on an existing mailbox:
- Click edit next to the mailbox to be updated.
- Under the "Email Account Information" section, paste the Google App Password into the password field.
- Click the Test Connection button to confirm that the settings are working as expected.
- Click the Update Mailbox button at the top left to save your settings.
- To use the Google App Password when creating a new mailbox:
- Click Add under the "Mailboxes" section on the right quick menu.
- Configure all settings based on your mailbox settings and preferences.
- Under the "Email Account Information" section, paste the Google App Password into the password field.
- Click the Test Connection button to confirm that the settings are working as expected.
- Click the Add Mailbox button at the top left to create the mailbox.
- For further instructions on creating new mailboxes, please refer to this Help Center article.
- To use the Google App Password on an existing mailbox:
Afterwards, you should test the functionality of IEM to ensure that emails are being turned into issues in your site.
Note that the steps for creating the Microsoft 365 Application are for Issuetrak version 15.5 and above. If you are running a version older than 15.5 this option will not be present and the server settings will be listed in the incoming email configuration screen.
Issuetrak is capable of processing incoming and outgoing email via Microsoft 365's modern authentication method. It is necessary to perform several steps in your Azure Admin portal to enable this functionality and gather the required information. This article will show you how to perform those steps, as well as where to enter the resulting information in Issuetrak.
Microsoft Azure Steps
In order to add an Microsoft 365 mailbox, you or your Azure administrator must create a new app registration in Azure. But first, let's discuss a couple of configuration items that might apply to your environment.
Shared Mailboxes
If you have multiple IEM mailboxes on your site using Shared Mailboxes in Microsoft 365, then you'll need to choose which of the mailboxes should be used for outgoing email. Shared Mailboxes can't be delegated the "Send As" permission for another Shared Mailbox.
You could decide to use a mailbox that is not a Shared Mailbox for outgoing email. In that case, the mailbox would need to have "Send As" permission granted for all of the IEM Shared Mailboxes.
Creating a New App Registration in Azure
Steps:
- Access the Microsoft Entra admin portal.
- At the top, search for and select "App Registrations".
- Select New Registration.
- Provide a name for the App that will show in Azure, and select Register.
- Take note of the Application ID (will be needed in Issuetrak as Client ID) and Directory ID (will be needed in Issuetrak as Tenant ID).
- Along the lefthand side, expand Manage and then click "Certificates & Secrets".
- If you're going to use certificate authentication (which we highly recommend), there are multiple methods to generate a certificate. The steps to create an Issuetrak certificate can be found in our Using Certificate Authentication with Microsoft Applications article.
- Click Upload a certificate.
- You'll be prompted to navigate to the path of a certificate on your local machine. Find the certificate that you downloaded from the article above. It will use the PEM file extension.
- (Optional) Add description for this certificate.
- Click Add.
- It is possible to use 3rd party certificates or certificates generated in the Azure platform. In which case, the certificate would need to be uploaded to the Azure application as part of the above steps and also in step 3 for adding a provider below.
- If you intend to use a client secret, then click New client secret.
- Enter a description for this secret. It is suggested that you make it clear that this is used for your Issuetrak site.
- Select an expiration date.
- We recommend using the Scheduled Issues feature in your Issuetrak site to set up a reminder before the client secret is due to expire.
- Click Add.
- Take note of the secret value that appears below! You will need this later and it won't be shown again!
- If you're going to use certificate authentication (which we highly recommend), there are multiple methods to generate a certificate. The steps to create an Issuetrak certificate can be found in our Using Certificate Authentication with Microsoft Applications article.
- Move to "API permissions" on the left and select Add a permission.
- Click on Microsoft Graph, then "Application Permissions".
- Expand Mail and select "Mail.Send", "Mail.ReadWrite", and "User.Read.All".
- (Optional) If you will be using "Principal Name / Object ID" instead of the mailbox email address to configure this mailbox in Issuetrak, you do not need the User.Read.All permission.
- Mail.Send is needed if this application will be used to Send email.
- Mail.ReadWrite is used to grant Issuetrak to read messages in the mailbox, then mark them as read or delete them depending on the settings selected for this mailbox in Issuetrak.
- Select Add Permissions.
- Above the list of permissions, click on "Grant admin consent for..." to activate the permissions. If this is grayed out, then your account lacks permission to do this, and an administrator will have to approve the permissions granted.
The steps above explain how to implement an app registration with the right permissions for Issuetrak to utilize your Microsoft 365 mailbox. You may wish to constrain the permissions to just a particular mailbox that you want Issuetrak to have access to. If that is the case, please look here for additional information on doing that.
Adding Microsoft 365 Credentials to Issuetrak
We must now configure Issuetrak so that it knows how to communicate with your Gmail account. This section assumes that you have the information we obtained in the steps above.
- Sign into Issuetrak with a Sys Admin account.
- Navigate to the Settings Lightbox via the gear icon in the upper right, then click on Microsoft 365 Applications under Integrations.
- Click on Add New, then enter a Name that you'd like to associate with the Microsoft 365 account, select the Azure Cloud Type from the drop down, as well as the required Client ID, Tenant ID, Client Secret or Certificate, gathered in the prevous section.
- Click Save.
Once this is complete, you can move onto configuring IEM and / or Outgoing Email.
Configuring Incoming Email to Use Microsoft 365
Please see our article on configuring IEM mailboxes for the relevant steps.
Configuring Outgoing Email to use Microsoft 365
Please see our article on configuring outgoing email for the relevant steps.
There is an email log so that you can view a list of all messages processed by your IEM for the last seven days. Each message includes a system note as to what happened during processing. If the message was converted into an issue or note, the note will include a link to the issue. But if the message did not process, it tells you why, for example, a keyword violation, or an unknown user. Every message has a checkbox that allows you to trigger the re-processing of the message. You can view the log by clicking the gear icon to open the Settings Lightbox > Incoming Email beneath Email > View Log on the right quick menu.
Parsing the View Log
You can sort, search and filter the View Log to get the information you need:
Sorting
The View Log can be sorted by clicking on any of the column headers that appear.
Searching and Filtering
The View Log can be filtered or searched by the following criteria:
- Date Received (enter a date range)
- Date Processed (enter a date range)
- Account ID (of an IEM mailbox)
- Status (of message processing)
- Email Sender
- Status
- Subject
- Attachments
Re-Processing Messages
It is possible to re-process any message displayed in the IEM View Log by checking the box next to the message and then clicking Retry Selected. You also have the option to batch re-process several messages at a time by checking multiple messages and then clicking Retry Selected. Note that if you choose the checkbox column to select all messages, only the messages currently displayed on the screen will be re-processed.
Note that if you attempt to retry processing for a number of messages exceeding your loop violation setting, you will get loop violation notices.
Additionally, for those messages that have had Retry Selected triggered against them, a status displaying how many times each message has been retried will appear to the right.
Incoming email tokens are part of the incoming email (IEM) processor. The processor reads these tokens, allowing you to update certain fields in the issue record. When an email is received, you have the ability to include tokens in the body of an email that will change the value of an issue field. Once configured, these tokens require the incoming email to include [[TokenIdentifier:NewValue]], so that two left brackets [[ precedes the name identifier of the token, which is followed by a colon, the new value for that field, and a final set of right brackets ]].
Basic user fields have tokens already created that can be edited or deactivated. All user-defined fields are able to have tokens created, then subsequently edited, deactivated, or deleted.
There is one Command Token that allows you to close an issue via email. This appears at the bottom of the page with two predefined values. It can also be edited or deactivated.
The new value included in the email must match an existing value for that field. For example, if you want to change the Substatus value to In Process, First, Substatus must be activated with In Process as a value, then the token must be configured to accept changes, then in the body of the email, you would include [[Substatus:In Process]].
For values involving a user, the new value must be that user’s ID. So if you wanted to change the assignment of the issue to John Smith with a user ID of jsmith and you had your assign issue token set to Assign, you would include [[Assign:jsmith]] in the body of an email.
Terminology
The table below contains a few terms that will be used in this article:
| Term | Definition |
|---|---|
| Incoming Email | Issuetrak processor that converts new email messages to issues, or uses email replies to system notifications to create notes on existing issues. |
| Email Tokens | Codes that can be included in the body of an email to either set or update a field value on an issue. |
| Email-based Webform | Web page that allows for user input and converts it to an email. |
| Token Identifier | The word or phrase that indicates which field is going to be updated. |
| Value | The data that is put into the Issuetrak field. |
Managing Email Tokens
To set up your email tokens:
Steps:
- Click the gear icon in the upper right > click Incoming Email beneath Email.
- Click Email Tokens on the right quick menu.
- A list of predefined field tokens will appear at the top of the screen.
- (Optional) Click edit beside the token to modify any of these values.
- For any of your user-defined fields, select the field you want to create a token for from the UDF dropdown list.
- Input a name for the token in the Token Identifier field. This is the value that will be included in the email.
- Click Add.
A confirmation message will appear when this process is complete.
To deactivate tokens:
Steps:
- Click the gear icon in the upper right > click Incoming Email beneath Email.
- Click Email Tokens on the right quick menu.
- Uncheck the appropriate token in the Active column.
A confirmation message will appear when this process is complete.
Tokens can only be used by users with the appropriate permissions. For example, if a user without permission to assign issues attempts the use the assignment token, the issue will not be assigned.
Working with Email Tokens
Let's break down how you can use email tokens in Issuetrak.
The Basics
By adding tokens to the body of your email, you’re telling the Incoming Email processor to set or change the value of a field on an issue. The email processor reads and recognizes the tokens and knows to update the appropriate fields in Issuetrak to the new value indicated by the token’s parameters. This works on both new and existing issues.
All of the tokens start and end with double brackets. The token identifier, a colon, and the new value are contained within the brackets. The token format looks like this: [[Token Identifier:Value]]
Note that there are no spaces between the identifier, the colon, and the value, and that capitalization isn’t necessary. An example token for assigning the issue might be: [[Assigned-To:john.smith]]
The value “john.smith” is the User ID for John Smith. When using tokens to assign or next action the issue, the value must be the User ID of the agent. You must use “john.smith,” not “John Smith.”
It’s important to keep in mind that email tokens do not let you break permission rules. If you can’t assign issues, and you use the Assigned-To token, or if the person you are trying to assign the issue to doesn’t have the permission to be assigned issues, then the token will be ignored.
Tokens can either change the values of an existing issue or set values on a new issue. Let’s say you want to change the priority on an issue and don’t have time to log in. Simply reply to a notification that you’ve already received and include [[priority:critical]] in the body of the email. The token will update the priority on the existing issue to "Critical".
Default Tokens
These email tokens have been set by default:
- Assigned To - [[Assigned-To:UserID]]
- Next Action - [[Next-Action:UserID]]
- Priority - [[Priority:Priority Name]]
- Substatus - [[Substatus:Substatus Name]]
- Location ID - [[Location-Id:LocationValue]]
Each predefined token is editable so you can make them shorter and easier to remember. For example: [[Assigned-To:UserID can become [[AT:UserID]].
User-Defined Tokens
Tokens can also be created for all your user-defined fields. For example, if you’ve created a user-defined field called Customer Name, you could create a token such as: [[Cust-Name:VALUE]]. To create a new token, select the user-defined field that you want to populate from the drop-down, set the token identifier, and click Add.
Once the tokens are created in Issuetrak, you’ll need to include them as part of your email.
Multi-Select List UDF Tokens
A note on using Multi-Select List UDFs with IEM tokens: If you wish to specify multiple values for the same Multi-Select UDF, you must specify the same UDF token multiple times, with each instance referencing a different desired value, like this:
- [[UDF-Identifier:Value1]]
- [[UDF-Identifier:Value2]]
- [[UDF-Identifier:Value3]]
Using Tokens in Incoming Email
Email tokens can simply be included in the body of any incoming email. For example, you need to create an issue in Issuetrak and assign that issue to a technician. The default assigned to the token looks like this: [[Assigned-to:UserID]]. To assign the issue to John, all you need to do is include his UserID of "john.smith" along with the token identifier.
Example:
John,
Please take a look at the software logs on server #1 tomorrow.
[[Assigned-to:john.smith]]
The message is picked up by the incoming email processor, which creates an issue that sets the assigned to value to "John Smith".
Using Tokens in Email-Based Webforms
Webforms that send emails can include token values to set or change fields within Issuetrak. The form sends a populated email, with the data from the form formatted into tokens that Issuetrak recognizes.
When the user clicks Submit on the form, an email is populated that looks something like this:To: PSemailform@myissuetrak.com
_______________________________________
Feedback via Webform
_______________________________________
[[cust-name:John Smith]]
[[cust-email:jsmith@somedomain.com]]
Details of the problem:
I have a complaint or problem!
As long as the email is sent to an incoming email box, it’s then processed by the incoming email processor. The incoming email processor creates a new issue with the "Customer Name" and "Customer Email Address" fields filled out.
Getting this to work properly requires the configuration of the email form. This includes setting up the email that’s generated so that it contains properly formatted email tokens.
Closing Thoughts
If you have any questions or would like the assistance of our product experts, please do not hesitate to contact us with any questions.
You have the option to exclude certain text from email processing. When a block of text is marked for exclusion, IEM scans the message body and removes it from the issue’s description or note if found. This allows you to put in confidentiality or disclaimer text so that it doesn’t clutter your issue content.
Steps:
- Click the gear icon in the upper right > click Incoming Email beneath Email.
- Click List beneath Exclude Text on the right quick menu.
- Add using the right quick menu; edit or delete items already in the list using the links provided.
- Type in or adjust your text content.
- Click Save.
Keywords are words or phrases that cause an email to not be processed. IEM will search each incoming email message for matches in the From Address and From Name, or the Subject line, depending on which the keyword specifies. Default Keywords have been included in your system provided to help get you started. Feel free to build on these default Keywords or delete them and create your own.
Steps:
- Click the gear icon in the upper right > click Incoming Email beneath Email.
- Click List underneath Keywords on the right quick menu.
- Depending on what you want to do, you can click add on the right quick menu underneath Keywords. If you want to edit or delete, you can click the appropriate option next to an existing keyword in the list.
- Type or adjust the keyword value.
- Select whether the keyword looks in the From Address or the email subject line.
- Select Add Keyword or Update Keyword.
We suggest adding the email address of your IEM Mailbox(es) to the Keyword List with From Address as the Search value. This will help prevent spam messages from being spoofed from the address(es) from getting into your system.
This article concerns the Blocked Attachments setting for incoming email. If you are actually looking for the ability to block potentially risky files from being uploaded to your site, then please see "About the Features Screen" or "Security" article instead.
Certain attachments, such as logo files or social media icons can appear repeatedly in your descriptions and notes, especially if included in the signatures of your users. You have the ability to identify the attachments that you may want to block from processing.
Blocking Attachments
Steps:
- Click the gear icon in the upper right > click Incoming Email beneath Email.
- Click Blocked Attachments on the right quick menu.
- (Optional) A list of already blocked attachments will be shown. You can click on the name to preview the file or click remove to no longer block it.
- Click Browse to browse for and add a new attachment to block.
Additionally, if a file comes through that you want to block going forward, you can quickly block it right from the issue screen. When viewing the issue, you can click on Attachments in the right context menu, the paper clip icon by the issue number, or scroll to the attachment list on the issue. Next to each attachment will be a block icon. Clicking that will add that particular attachment to the blocked list.
Post 15.1+ Upgrade
After upgrading from a version prior to Issuetrak 15.1, previously-blocked IEM attachments will need to be re-blocked. This is due to the underlying mechanism that is used for matching blocked attachments being changed.
You may see text on the Blocked Attachments screen indicating that some entries are no longer valid. In order to "clean up" the Blocked Attachments area, you can choose to click on Delete all invalid entries to get rid of all listed invalid attachments.
