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):

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:

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":

Regexp foreign key association

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:

Open

This makes the necessary settings visible on screen:

For our example, we have the following configuration:

Open

The results: