The pupose 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, i. e. if If there are multiple hits or none, no 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 matchersmatches) returns exactly one match, the appropriate conditions shall be specified in accordance with the issue processing rules (if-else conditions).
| Infonote |
|---|
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. |
...
Find issue by issue key extracted from the message Subject (built-in, always active):
It extracts parts from the mail Subject that look looks 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).
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:Find issue by message Message-ID extracted from the the In-Reply-To header: it looks for an issue, where an ID in any of the Message-Ids field is present in 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 message Message-ID extracted from the References header: it looks for an issue, where an ID in any of the Message-Ids field IDs stored in the
com.metainf.emailthisissue.entityproperty.messageidsissue 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).
...
To define a static JQL condition: in this case, the Email Fileld Field and the Regular expression fields shall be kept empty, only the JQL condition is used for the lookluplookup. 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 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:
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.
...
| Note |
|---|
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”. |
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"
| Note |
|---|
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. |