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.

For any case, only one matching issue is accepted. If there are multiple hits or none, no issue will be selected for a further processing defined by the mail handler actions. To make sure that the lookup (or eventually a suite of issue matchers) returns exactly one match, the appropriate conditions shall be specified in accordance with the issue processing rules (if-else conditions).

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

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

There are different sorts of lookups. They are executed in the following, fixed precedence order:

• Find issue by issue key extracted from the message Subject (built-in, always active):

  1. It extracts parts from the mail Subject that looks 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.

• Find issue by message reference present in message headers (optional - for more information scroll down to Header-based issue lookup). 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.

• 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

Header-based issue lookup

• 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 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 case an issue ID is extracted from the Message-ID itself in order to identify the corresponding issue.

• Find issue by issue key by substituting value into a JQL search query, where the value is extracted from some message attribute, based on a regular expression (optional).

JQL lookup

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 and even if more from these would result in potential matches (e.g. if multiple recipient addresses would satisfy the JQL condition). In such cases, 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.

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

Note: When saving a JQL lookup, basic formal validations are executed and potential errors are displayed.

Important: If you make use of the issue key in your JQL condition (e.g. issuekey = “$!group1“), the JQL validator may not discover actual problems with the expression provided, since validation errors on issue keys needed to be suppressed.

Handling multiple matches

When a JQL search query returns multiple results (i.e. more than one Jira issues match the filter condition), the first item from the result list will automatically be selected (as returned by the Jira API). If you want to make sure that the result list is sorted and the matching issue is selected in a systematic way, then please append an ORDER BY clause to the end of your query that best suits your needs.

For example, to get the issue with the lowest issue ID (practically the oldest one), apply this clause:

"ORDER BY key ASC"

Important: If you make use of the issue key in your JQL condition (e.g.issuekey = “$!group1“), the JQL validator may not discover actual problems with the provided expression. Validation errors on issue keys need to be suppressed as Jira returns an error message by default if the query is run for a non-existing issue.

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.

• If you make use of the issue key in your JQL condition (e.g. issuekey = “$!group1“), the JQL validator may not discover actual problems with the expression provided, since validation errors on issue keys needed to be suppressed, as Jira returns an error message by default if the query is run for a non-existing issue.