SINCE VERSION 5.5.1
Field Contexts contain Field Rules that:
- Initialize issue fields when a new issue is created from email
- Initialize issue fields when an existing issue is affected by the email
- Affect how an issue is looked up for an incoming email
- Execute workflow transitions
- Block emails from being processed (e.g. if identified as spams)
Configure your Mail Handlers to Use Field Contexts
Field Contexts are used in conjunction with Mail Handlers and incoming emails, you must explicitly enable these features (namely field initialization, issue lookup, workflow execution and filter emails) in the Mail Handlers.
Just like any other "Contexts" in Email This Issue, Field Contexts are also mapped to Project(s) and/or Issue Type(s). Always the best matching Field Context is resolved for an issue.
Context resolution is as follows:
- If a Field Context is configured for the issue's project and type, use it
- Otherwise if a Field Context is configured with the issue's type, use it
- Otherwise if a Field Context is configured with the issue's Project, use it
- Otherwise if a Field Context is configured without a project or type, use it
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.
Field Rules of both types have the following attributes:
- A Regular Expression that is matched against the email. See example regular expressions below.
- Match In specifies which email attribute we try to match the regex in: Subject, Body, Sender Email Address, Recipient Email Addresses
- Use Value specifies how to extract the value from the email using the regular expression: 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
Initialize Issue Fields
There may be multiple rules configured for each issue field in the field contexts. They are applied in the order of Order, Field Name, Expression.
If a Field Rule matches the email and yields a non-emtpy value for an issue field, subsequent field rules for the same issue field are skipped. In other words, only one successful rule for each field is applied.
Issue fields that accept multiple values (like version, component, or custom field) will be set by one value as of now. Later, multiple value support may be added.
Not all type of custom fields may be initialized. Issue fields supported:
- 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 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
- static value entered manually
- dynamic value: combination of static content, issue attriubutes and capture groups.
SINCE VERSION 6.1
How to initialize Date and DateTime picker fields
if you want to set Date or DateTime picker fields, date or date time values from the email must be parsed. Email This Issue provides an object that supports date parsing.
E.g. say your regexp 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 date time pattern follows the syntax in Java SimpleDateFormat.
How to initialize multiselect 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 group 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("some value for parent", "some 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 associated issue for an incoming email is as follows:
- Apply JIRA strategy to associate emails to existing issue
- If JIRA finds the issue, use it for further processing by the mail handler (e.g. to comment 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 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 JQL
- If the Mail Handler Context is configured with a Issue Type, add the issue type criteria to 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 with the mail handler context, but project: "Order Nr"~"A001" AND project=Customer Orders
- if project is not configured with the mail handler context, but issue type: "Order Nr"~"A001" AND issuetype=Customer Request
- if neither project nor issue type is not configured with the mail handler context: "Order Nr"~"A001"
In order to produce most reliable and successful lookups, mail handler contexts should be as specific as possible.
Execute workflow transitions
SINCE VERSION 6.3
Email This Issue Mail Handler has 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 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 Execute Transitions checkbox.
Block emails from processing
By setting up field rules of type Email Filtering, 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 utlimately processed by your mail handler.
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)Crashed system:(.*)(\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".
Please leave a comment in this page to add further ideas of regexps you configured successfully.
Example Use Cases
There may be numerous use cases that may need field initialization and/or issue lookup.
e.g. you maintain a web shop 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.
The 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.