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-451
Custom 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 123
When 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: