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.
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.
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.
