Issue lookups

Thank you for visiting our old product documentation site. Note that we are in the process of migrating our product documentation and soon we will not store or update our documentation here.

Please navigate to our new documentation site and update your bookmarks accordingly. If you're looking for the former content of this page, click here.

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, which 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 results the first issue will be selected from the results list for further processing defined by the mail handler actions. To make sure that the lookup (or eventually a suite of issue matches) returns exactly one match, the appropriate conditions shall be specified in accordance with the issue processing rules (if-else conditions).

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, which 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).
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. Please refer to the following documentation for more information on how this works: https://metainf.atlassian.net/l/c/dk2f3091
The header-based issue lookup works as follows:
1. Find issue by 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.*
2. Find issue by 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.*
  * 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

As the JQL-based lookup is a bit more complex than the others, we review it in this dedicated chapter.

Basically, you have two options with JQL filters:

To define a static JQL condition: in this case, 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 a bunch of incoming messages to a single Jira issue, which can be found by a constant JQL query.
To construct a dynamic JQL condition: in this case, some information is extracted from the message via a regular expression and then substituted into the JQL condition. Here, all three input fields must be specified:
1. First, you can choose an attribute (field) of the incoming message, whose content will be passed to the regular expression in the next step. If you opt for using a message header, you also have to provide the name of the respective header.
2. Second, you can specify a regular expression to extract some relevant part of the value coming from the email attribute. Here, you may want to make use of capture groups to store the relevant part in a referable variable.
3. Finally, you can construct 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. Of course, you can also 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), which results in an unambiguous match with a Jira issue, will be used.

A bit more complex example:

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

Please note that if you make use of the $!group0/$!group1/etc. placeholder (i.e. a capture group reference) in your JQL condition, it must be put between double quotes, e.g. as ”$!group0”.
Unfortunately, the Tips section currently contains a wrong example, we are working on this.

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"

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.