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).
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 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
- 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.messageidsissue 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.messageidsissue entity property is present in the References header of the incoming message.
- 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).
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.
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 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.