Understand how Issue association works
Introduction
Issue association is the matching of incoming emails with pre-existing issues in Jira. There are a several ways to achieve issue association, each with varying levels of reliability. These will now be discussed, in the order that JEMHC uses to look for an association.
Issue key Directive
With a Field Processor enabled, a Directive can be used to drive comments/updates to a specific issue. This is a very reliable way to associate emails with issues, as issue keys are unique.
For example, the At(@) Prefix field processor allows the following directive to direct the email to an issue (in this example EX-451):
@issueKey=EX-451Custom Field comparison Directive
This method starts just like a standard issue key Directive, however instead of supplying an issue key directly, we use JQL (Jira Query Language) to compare a custom field against a value for that custom field. This is a less reliable method as multiple issues can have the same value for a custom field.
For example, if we have an existing issue with the value of ABC 123 in a custom field named "codefield", the following custom field comparison directive will associate the email with that issue:
@issueKey=codefield=ABC 123When more than one issue has a matching value for the custom field specified, the first issue key returned by the JQL query will be chosen. Bear this in mind if relying on this method to associate emails to issues.
JQL directive
Similar to a custom field comparison directive, a JQL statement is used to find an issue key to associate the email with. The reliability of this method depends on how specific the statement is.
For example, the following directive would associate the email with an issue where the field "External Id" has a fuzzy match to the value #12345 and where the project has the project key "EX":
@issueKey='External Id' ~ '#12345' and project = 'EX'As with Custom Field comparison directives, the first issue key returned by the JQL query will be chosen.
Regexp foreign key association
Please note that this does not need the Regular Expression Field Processor to set foreign key custom field. If you see a null value for the foreign key custom field in your event data for outbound notifications; ensure that the Regular Expression Field Processor is not setting this field.
Foreign key association project scope
When using the default project mapping
If foreign key issue association is configured within JEMHC > Profiles > Project Mapping > Default Mapping, JEMHC will search for matching Issues against all Projects.
Any further mappings that inherit the default mappings behaviour however will scope to the mappings selected Project.
When using non default project mapping(s)
If foreign key issue association is configured within JEMHC > Profiles > Project Mapping for any Non-Default Project Mapping(s), JEMHC will search for matching Issues against the mappings selected Project. This means any Issues that would match foreign key association that are in a different Project would not be found, and would require a separate mapping for the Project the Issue is in.
About foreign key association
This uses a regular expression to find data (a “foreign key”) in an email subject or body, and store that data in a selected field. Subsequent emails that have the same foreign key regexp match will then be associated with the email that has the foreign key stored. This method is useful when dealing with emails coming from an automated system such as Bugzilla.
The reliability of this method depends on how specific the expression is, and the uniqueness of the values stored. For maximum reliability, use a very specific regexp to extract values that are always unique to the target issue.
Here are two examples of how Regexp foreign key association can be used.
Specific key matching in subject and/or body
This is the standard usage for the method. The below example mail has an identifiable piece of information in its body, which we want to use for subsequent issue association.
In our JEMHC profile, we go to the project mapping of our choice. The profile used in this example only has a default mapping, so that is where we are focussed. Go to Pre-Processing and click Edit. Under the Issue Association section, we set Associate Issue by foreign key to Yes:
This makes the necessary settings visible on screen:
Setting | Details |
|---|---|
Sender Regexes | A CSV capable field, where a list of email address regexps can be entered. If the sender address sender matches one of these regexps, JEMHC will try to associate the foreign key in email with the issue. |
Foreign Key Source | The location in the email where the foreign key is to be found. Choices are Subject or Body. |
Foreign Key Regexp | The regular expression used to extract the foreign key from the email. The first matching group (indicated with round brackets) is the returned value. |
Issue Status | When this field is used, only issues with the selected statuses are candidates for issue association. Leave this field blank to allow non-resolved issues only. |
Disable issue keys in subject | When active, standard issue key in subject association is disabled. |
Foreign Key Custom Field | The custom field to be used for storing the foreign key on an issue. |
For our example, we have the following configuration:
The results:
First email with new foreign key in body | Second email containing same foreign key in body |
|---|---|
Whole subject matching
In this scenario, you do not have a specific key to match with in the email. Instead, you may choose to use the whole email subject as the matching key. Whilst this is possible, it is not a very strong issue association method as there is the possibility of two unrelated emails having the same subject. Therefore, issues could be wrongly associated when using Regexp Foreign Key Association in this manner.
For this example, we want to associate emails that have the following subject, to the same issue:
The set up is similar to the above configuration, however we the source is set to look in the Subject and our Foreign Key Regexp will extract the entire subject instead of just part of it.
Email address association
The recipient address that matches one of the profile's catch email address is tested for a issue key. This association strategy can be enabled via the Profile→ Project Mapping → Issue configuration page.
There are two ways of providing the issue key in email addresses (in these examples, the updated/commented issue is ABC-123):
Local part
In the above example, one of the profile's catch email addresses must match ABC-123@mycompany.com.
Sub-domain
In the above example, one of the profile's catch email addresses must match support@mycompany.com (sub-domain excluded from matching).
Issue key in subject
When an email is processed that contains an existing issue key, JEMHC can make an association between the two and comment on the issue instead of create a new one. If Foreign Key Issue Association is enabled (under Profile Mapping>Pre-Processing), the option to disable subject issue key lookup becomes available.
Email threading
In-Reply-To and References header check boxes
Standard Email Threading
When JEMHC processes an email, the emails message-ID is stored. If a subsequent email refers to the original message-ID in its In-Reply-To and References headers and if enabled sub option(s) are enabled i.e.In-Reply-To and References; then JEMHC will drive threading dependent on the related header(s) options are enabled then issue association will occur. Email Threading behaviour can be disabled or modified via Profile > Project Mapping > Pre-Processing > Issue Association > Email Threading.
Embedded Issue Key in Message ID
Extract the embedded Issue Key from the either Use In-Reply-To header and/or Use References header options enabled (In-Reply-To takes precedence): If the issue key relates to a valid issue key then associate the message.
Example
If the Use In-Reply-To header option is enabled then the associated issue will be:
Allow Uninvolved Senders via Threading
If you want email users who aren’t involved in an issue (not a Jira user and not in any defined email user custom fields) to be able to interact with your issues, you can enable Profile > Project Mapping > Email only users > Non-Jira security > Allow Uninvolved Senders via Threading. This requires email threading to be enabled for the mapping.