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:

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.

Related articles