- This line was added.
- This line was removed.
- Formatting was changed.
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 Contexts are used with Classic Mail Handlers for incoming emails. You must explicitly enable these features (namely field initialization, issue lookup, workflow execution, and filter emails) in the Classic Mail Handlers otherwise they do not work. Field Contexts do not work with Next-Gen Mail handlers. For more information please check the Next-Gen handler documentation.
Enabling Field Rules in a Classic Mail Handler
Field rules have to be enabled in the Classic Mail Handler settings. Navigate to the Mail Handlers menu and click on the checkbox of the mail handler actions you'd like to employ.
Configuring Field Contexts
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, click on Add and edit the scope and click Save:
In the below image, you can see some examples for the 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.
If you delete a context, all its field rules are deleted as well and they are non-retrievable.
Configuring Field Rules for Field Contexts
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:
|Regular Expression||Matched against the email. See example regular expressions below.|
|Matches email field||Specifies which email attribute we try to match the regex in: Subject, Body, Sender Email Address, Recipient Email Addresses, Headers etc.|
Add Sender Condition
|Condition of the sender. If one is selected, it must match in order to execute the field rule.|
|Add JQL Condition||Issue in the rule's context must match the JQL condition if specified.|
|Use Value From|
Specifies how to extract the value from the email using regular expressions. Options are Capture Groups or a value set manually.
|Issue Field||Specifies the field with which the Field Rule is associated, depending on the type of the rule, this field will be set with the value or the issue is searched by this field.|
|Order||Species in which order the field rules are applied.|
The Regular Expressions in the Field Rules are velocity templates essentially. This means you can use references to issue fields. E.g as $!issue.project.key or $!issue.getCustomFieldValue("customfield_12345").
Initializing Issue Fields
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 Desk 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.
How to initialize Date and DateTime picker fields
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 $parser.parseDate("dd/MM/yyyy", $group1).
The date or datetime pattern follows the syntax in Java SimpleDateFormat.
How to initialize multi-select fields
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
How to initialize cascading select fields
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: $parser.cascade("<parent-value>", <child-value>").
- $parser.cascade($group1, $group2) or
- $parser.cascade("static value for parent", "static value for child")
How to add new issues to Epics
Email This Issue Mail Handler can initialize the Epic Link field in stories. Add a field rule that sets the Epic Link field. The Field Rule's value is the Epic's issue key or issue summary (not the Epic name!)
Custom Issue Lookup
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
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: "Order Nr"~"A001"
In order to produce the most reliable and successful lookups, mail handler contexts should be as specific as possible.
Execute workflow transitions
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.
If you want to use workflow field rules, you must enable executing workflow transitions in the mail handler by ticking the Mail Handlers.
Block emails from being processed
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.
Blocked emails will remain in the mail box and will not be deleted by Email This Issue. Therefore they should be cleared regularly as having hundreds of blocked emails will significantly increase the time a valuable email is ultimately processed by your mail handler.
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.
Regular Expression Examples
|Regexp||Match in||Use Value||Set Issue Field||Explanation|
Matches if the word Urgent is contained in the email subject case insensitively.
Case insensitivity is specified by the modifier: (?i)
|(.*)@mycustomerdomain\.com||Sender Email Addresses||My Customer||Emailing Customer||If the email was sent from the "mycustomerdomain.com" domain, then |
set the Emailing Customer field to "My Customer." "Emailing Customer" here is either a Text or Select field.
|(?i)(\r\n)Affected system:\s*(.*)(\r\n)||Email Body||Capture Group: 2||Components|
If Email Body contains a line of text starting with "Affected system:" then
Dispatch issues between multiple projects based on email attributes:
If email subject contains the word "MyProject", store issue in the Jira project called "MyProject".
Example Use Cases
There may be numerous use cases that may need field initialization and/or issue lookup.
e.g. 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.
Integration with Other Ticketing System
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, e.g :
- 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.