Field Rules

Important: As of version 9.2.0 Classic handlers have been deprecated and do not work anymore. Field Rules have been integrated in the Next Generation mail handler.

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

Note: 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. Read more here. Field Contexts do not work with Next Generation Mail Handlers. For more information click here.

Enabling Field Rules in a Classic Mail Handler

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.

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

Important: 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:

Attribute	Description
Regular Expression	Matched against the email. See example regular expressions below. Read more here.
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. Read more here.
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.

Note: The Regular Expressions in the Field Rules are essentially velocity templates. 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

  • Assignee

  • Components

  • Description

  • Due Date: reporter must have Schedule Issue Permission

  • Environment

  • Fix Versions

  • Issue Type: It is possible to create issues of different types depending on data in the email

  • Labels

  • Original Estimate

  • Priority

  • Project: It is possible to create issues in different projects depending on data in the email

  • Reporter

  • Security Level

  • Summary

• 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

  • Labels

  • Number

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

Initializing 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. Read more here.

Initializing 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

Initializing 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>").

For example:

• $parser.cascade($group1, $group2) or

• $parser.cascade("static value for parent", "static value for child")

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

Important: The Field Rule's value is the Epic's issue key or issue summary, and 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.

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: "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

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.

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

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

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

Regular Expression Examples

Regexp	Match in	Use Value	Set Issue Field	Explanation
(?i)(Urgent).*	Email subject	Blocker	Priority	Matches if the word Urgent is contained in the email subject case insensitively. In this case, set priority to Blocker. 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 extract the rest of the line and store it in Components field of the Issue.
(?i)(MyProject).* (?i)(MyOtherProject).*	Email Subject Email Subject	MyProject MyOtherProject	Project Project	Dispatch issues between multiple projects based on email attributes: If email subject contains the word "MyProject", store issue in the Jira project called "MyProject". Otherwise if subject contains "MyOtherProject", store issue in "MyOtherProject" in Jira.

Use case examples

There may be numerous use cases that may need field initialization and/or issue lookup.

Order tracking

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.

Integration with another 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, for example:

• Ticket number

• Importance

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