The pupose 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, i.e. if there are multiple hits or none, no issue will be selected for 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).
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):
It extracts parts from the mail Subject that look like an issue key.
It checks if there is an issue with the extracted issue key.
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):
Find issue by message ID extracted from the the In-Reply-To header: it looks for an issue, where an ID in the Message-Ids field is present in the In-Reply-To header of the incoming message.
Find issue by message ID extracted from the References header: it looks for an issue, where an ID in the Message-Ids field 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).
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 Fileld and the Regular expression fields shall be kept empty, only the JQL condition is used for the looklup. 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: int his 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:
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.
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.
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”. |
If you need to combine various needs, which 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.