SINCE VERSION 5.5.1
Field Contexts can be used with Classic Mail Handlers and they contain Field Rules.
Field Rules are used to run different actions based on the attributes of an incoming email. Using field rules you can:
- Initialize issue fields (give values to issue fields) when a new issue is created from an email
- Initialize issue fields (give values to issue fields) when an existing issue is affected by the email
- Define how an issue is looked up for an incoming email
- Execute workflow transitions on an issue that is found
- Block emails from being processed (e.g. if identified as spams) and optionally send a bounce email back to the sender
Field rules have to be enabled in the Classic Mail Handler settings. Navigate to INCOMING EMAILS --> Mail Handlers and choose the mail handler actions you'd like to employ.
Just like any other context in Email This Issue (for example the scope in the Notifications settings), Field Contexts are also mapped to Project(s) and/or Issue Type(s). It is always the best matching Field Context that is resolved for an issue.
Context resolution is as follows:
- If a Field Context is configured for the issue's project and type, then this one is used
- Otherwise, if a Field Context is configured with the issue type, that one is used
- Otherwise, if a Field Context is configured with the issue's Project, that one is used
- Otherwise, if a Field Context is configured without a project or an type, that one is used
The project attribute of a Field Context may be left empty, this way the context applies to all projects. Similarly, if the issue type attribute is empty, the context applies to all issue types. To add a field context, Navigate to INCOMING EMAILS --> Field Rules, click on Add, edit the scope and click Save:
Examples for context setup:
Clicking on the three dots at the end of a row displays options to Edit the context, access your Field Rules and Delete the context.
After setting up a field context, you have to add field rules according to your requirements. For this, click on the menu at the end of your field context and select Field Rules.
You can add field rules to your context in this menu and all your existing field rules are displayed here for the context you've opened as well. To create a field rule, click on Add Rule and select the rule type you'd like to use:
In general, the following attributes are displayed in a field rule:
There can be multiple rules configured for each issue field in the field contexts. They are applied in the processing order of Order, Field Name, Expression.
If a Field Rule matches the email and yields a non-empty value for an issue field, subsequent field rules for the same issue field are skipped. In other words, only one successful rule is applied to each field.
Issue fields that accept multiple values (like version, component, or custom field) are set by one value as of now. Later, multiple value support may be added.
Not all types of custom fields may be initialized. Issue fields supported are as follows:
- System fields:
- Affected Versions
- Due Date: reporter must have Schedule Issue Permission
- Fix Versions
- Issue Type: It is possible to create issues of different types depending on data in the email
- Original Estimate
- Project: It is possible to create issues in different projects depending on data in the email
- Security Level
- Custom field types:
- User Picker, Multi User Picker
- Group Picker, Multi Group Picker
- Text (Single line), Free Text (multi line)
- Select, Multi Select, Multiple Checkbox
- Cascading Select
- Date and DateTime picker
- Jira Software Epic Link
- Service Management Customer Request Type
The value stored in the fields is determined by the matching field rule's Value attribute. It can be either of the following:
- Value of a capture group that extracts content from the email (e.g.: $group1)
- Static value entered manually (e.g. Customer type - Value = VIP)
- Dynamic value: a combination of static content, issue attributes, and capture groups.
If you want to set date or datetime picker fields, date, or datetime values from the email, the values must be parsed. Email This Issue provides an object that supports date parsing.
For example, if your regex returns the date string in the first capture group: 23/07/2015. Then set the Use Value From attribute to Manual and enter
In order to save values in multi-select custom fields, the value must be a comma-separated list of literals. Each literal must match a valid option in the field.
e.g. your regex returns the values in groups 1, 2 and 3. Then set the value to
$group1, $group2, $group3
Using field rules you can easily save values in cascading select fields.
If you want to initialize the parent value of a cascading select field, configure the rule with a manual value or with a value from a capture group.
If you want to initialize both the parent and child values, use a special syntax in the Manual value field:
static value for parent", "static value for child")
Email This Issue Mail Handler can initialize the Epic Link field in stories. Add a field rule that sets the Epic Link field.
There may be multiple issue lookup rules in the field contexts. They are applied in the order of Order, Field Name, Expression. The algorithm to find the associated issue for an incoming email is as follows:
Apply Jira strategy to associate emails to an existing issue.
- If Jira finds the issue, use it for further processing by the mail handler (e.g. to comment on it).
- If a Field Context can be resolved for the Mail Handler's Project and Issue Type attribute, match the issue lookup rules.
- If an issue lookup rule yields exactly one matching issue, it is used for further processing by the mail handler (e.g. to comment on it).
Only one lookup rule is tested to find an issue, lookup rules are not combined into more complex queries.
Field Rules are converted to JQL queries to search for issues. If multiple issues are found, the query is considered to be ambiguous, so the result is not used. It is as if no matching issues were found.
The JQL query is built as follows:
- If the Mail Handler Context is configured with a Project, add the project criteria to the JQL.
- If the Mail Handler Context is configured with an Issue Type, add the issue type criteria to the JQL.
- Add the field rule criteria to JQL.
The generic format of the JQL query:
"<field from the field rule>=<value from the field rule> AND project=<project from the mail handler context> AND issuetype=<type from the mail handler context>"
Example JQL queries:
priority=Blocker AND project=Support AND issuetype=Request
"Order Nr"~"A001" AND project=Customer Orders AND issuetype=Customer Request
- if issue type is not configured within the mail handler context, but project:
"Order Nr"~"A001" AND project=Customer Orders
- if the project is not configured within the mail handler context, but issue type:
"Order Nr"~"A001" AND issuetype=Customer Request
- if neither project nor issue type is configured with the mail handler context:
In order to produce the most reliable and successful lookups, mail handler contexts should be as specific as possible.
SINCE VERSION 6.3
Mail Handlers have long been able to execute workflow transitions. Now, Field Rules allow you to select the workflow transition based on the content of the email.
Use tokens or tags or directives in the email body, subject, etc. to name the transition that will be executed. The Field Rule's value must be the name or the numeric ID of the transition.
The transition name may be set statically or extracted from the email.
By setting up Email Filtering rules, you can block emails from being processed by your mail handler.
E.g. if sender email address matches a certain domain, or email subject indicates it is an Out Of Office or other irrelevant email types that you do not want to import, configure the appropriate rules to block these emails.
Additionally to Blocking emails, it is possible to Bounce an email back to the sender using a custom email template. Templates created from the Bounce Email theme will be listed in the template selection field.
There may be numerous use cases that may need field initialization and/or issue lookup.
For example you maintain a webshop and sell items. Users may ask you about the status of their order, they send you emails with the order number in the subject as a reference to the order they are inquiring about.
When the first email is imported into Jira, you want to save information like:
- Order number from the subject into a custom field
- Importance of the request in priority
When you process the request and open the issue, you'll see all details needed. Then you can click the Email button and reply to the customer.
Days later the same customer sends another, completely new email (not a reply to the email you sent) with another question and references the same order.
Without the issue lookup, Jira Email This Issue would not be able to associate the second email with an existing issue therefore a new ticket would be created. It may be perfectly right if you prefer this.
However, with an issue lookup rule based on the "Order Nr" custom field, Email This Issue can find the original issue for the same order number and add the new customer question as a comment rather than creating a new issue.
You have a legacy ticketing system (or another Jira instance) that you want to synchronize with Jira. When a new ticket is created in the legacy system, an email is sent to JIRA. You want to extract information from the email and store them as field values, for example:
- Ticket number
- Type of request
- Product names
Later, updates in the ticketing system generate emails to Jira with the updated information. With the issue lookup rule configured for the ticket number, you can keep your Jira issue in sync with the ticket.