Finding issues

The purpose of issue lookups is to find the matching issue based on a particular attribute (or part of its value) of an incoming email message that has not been filtered out by the global sender address filters or any of the active mail handler filters.

Only one matching issue is accepted for any incoming email.

If there are multiple hits, the first one returned by Jira API will be taken as the match. You can use IF/ELSE conditions in the Rules and Actions tab to ensure that the issue found in the lookup is the one you would expect.

The issue lookups can be configured on the Find issue tab:

Find issue tab

There are three different kinds of lookup methods, executed in the same order they appear in the UI (cannot be changed):

• Issue key-based lookup

• Header-based lookup

• JQL-based lookup

Note: Please keep in mind that if multiple issue lookups are enabled at the same time, the lookup process is stopped after the first unambiguous match is found.

Issue key-based lookup

Find issue by issue key extracted from the message Subject. This is always active.

1. It extracts parts from the mail Subject that look like an issue key.

2. It checks if there is an issue with the extracted issue key.

3. If such an issue does not exist, then it continues with the next extracted part from the Subject that looks like an issue key.

Header-based issue lookup

Find issues by message reference present in message headers.

• Find issue by the Message-ID extracted from the In-Reply-To header: it looks for an issue, where any of the Message-IDs stored in the com.metainf.emailthisissue.entityproperty.messageids issue entity property equals to the message-ID in the In-Reply-To header of the incoming message.

• Find issue by the Message-ID extracted from the References header: it looks for an issue, where any of the Message-IDs stored in the com.metainf.emailthisissue.entityproperty.messageids issue entity property is present in the References header of the incoming message.

Note: The In-Reply-To or the References headers may also contain internal (Jira-specific) Message-IDs, in this case an issue ID is extracted from the Message-ID itself in order to identify the corresponding issue.

This lookup action can be used to maintain email chains (i.e., email threads) without having to include the issue key in the email subject. Read more about it here.

JQL lookup

Find issues by using a JQL filter based on a regular expression that matches a part of the incoming email to a value of a JQL expression.

The JQL-based lookup is a bit more complex than the others. JQL filters have the following options:

• Defining a static JQL condition: the Email Field and the Regular expression fields shall be kept empty, only the JQL condition is used for the lookup. This can be useful if you want to associate multiple incoming messages to a single Jira issue which can be found by a constant JQL query.

• Constructing a dynamic JQL condition by referencing the extracted value via capture group(s), e.g. $!group0, where the decimal refers to the index of the capture group. It is possible to compile a JQL query as a mix of dynamic and constant conditions.

It is allowed to parse an email attribute that contains multiple values. If more from these would result in potential matches (e.g. if multiple recipient addresses would satisfy the JQL condition), the first applicable term (extracted from the attribute with the help of the regex) that results in an unambiguous match with a Jira issue is used.

If a JQL query can return multiple results, be sure to use the ORDER BY clause to ensure that the first returned result is the one needed. For example, to get the issue with the lowest issue ID (practically the oldest one), apply this clause: "ORDER BY key ASC"

When entering a JQL lookup, Check now option can be used to validate the JQL.

Important: If you make use of the issue key in your JQL condition (e.g. issuekey = “$!group1“), the JQL validator will return an error and may not discover other actual problems with the expression provided.

Please check the JQL validity using an actual issue key for validation, then replace it with the group values before saving.

Example:

Note: If you send issue keys in your custom X-Issue-Key email header, it can be extracted by a regular expression and the matching issue can be found. The header may contain multiple values. In the latter case, the first value matching the regex will be replaced into the JQL condition.

Eg. the X-Issue-Key: TPA-123 GLAS-42.mod header line results in the following JQL condition: issuekey = "GLAS-42".

Limitations

• If you need to combine various needs that cannot be expressed in a single lookup (or with the linear combination of the subsequent lookups), you need to create different Mail Handlers to cover those (mutually exclusive) logical rules.

• The issue lookup is not confined to any specific project; it will always search your entire Jira instance for matches, so be sure to add conditions in Rules and Actions to restrict the issues found, if necessary.