Issue association is the matching of incoming emails with pre-existing issues in JIRA. There are a several mechanisms that can be used to make associations. Due to their nature, some are more reliable than others. These will now be described in the order that JEMH uses to look for an association.
Issue Key in Subject
JEMH can detect issue keys in email subjects. If the key points to an existing issue, JEMH can determine that the email is related and comment on the issue instead of create a new one. This behaviour is configurable through two settings found via Profile>Email>Pre-processing:
Subject IssueKey (comment) Regexps
|Regular expression(s) which represent the issue key pattern you want JEMH to look for. By default, JEMH uses the patten |
\b[A-Z][A-Z_0-9]+-[0-9]+\b . One or more can be added if they are separated by commas (CSV).
|Ignore Subject Issue Keys If||If the addressee matches a known project key and auto-assign is enabled, JEMH will ignore issue keys in the subject. This setting is off by default.|
When JEMH processes an email, the emails message-ID is stored. If a subsequent email refers to the original message-ID in its In-Reply-To/References headers, then issue association will occur. Email thread matching behaviour can be disabled or modified via Profile>Email>Pre-processing. For more information, please see our page on Thread Matching.
Issue Key Directive
With a field processor enabled, a directive can be used to drive comments/updates to a specific issue. This could be considered a strong association method 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
The next thing JEMH will look for is a custom field comparison directive. Similar to a standard issue key directive, it uses a field processor to drive email to a specific issue. The difference however is that 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 could be considered a weak association 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:
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.
Similar to a custom field comparison directive, a JQL statement is used to find an issue key to associate the email with. The strength of this method depends on the specificity of the JQL statement used.
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. In order to reduce the likelihood of a mismatch, improve the JQL statement if possible.
Regexp Field Processor
The Regexp Field Processor uses a regular expression (also known as a "regexp") to extract a value in an email subject or body and store that value in a custom field. Subsequent emails that have the same value match will then be associated with the issue that has this value stored. This feature can be useful when handling emails that have come from an automated system (e.g. Bugzilla).
The reliability of this issue association method depends on two factors; the specificity of the regexp, and the uniqueness of the values stored. Therefore, a strong configuration would have a very specific regexp, and the values extracted by the regexp are always unique to the target issue.
For more information see the Regexp Field Processor page.
Script Field Processor
The Script Field Processor can be used to script a custom determination of what issue should be used to comment on based on anything you can code, and/or determine a particular processing outcome for a message.
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Subject: This is a starting email template, update as required
From: "Andy Brook" <andy@localhost>
Content-Type: text/plain; charset=UTF-8
This was mentioned in custom project YY-4444 but we should put this on XX-2 for further review
if (relatedIssue != "null")
print('no issue yet identified, scanning with script');
// for testing
//var body = "This was mentioned in custom project YY-4444 but we should put this on XX-22 for further review";
var patt = new RegExp("(ABC|DEF|XX)-[0-9]+");
var res=patt.exec(body); // This was mentioned in custom project YY-4444 but we should put this on XX-2 for further review
if (res !== null)
if (issueManager.getIssueObject(res) !==null)
print('found match but the issue '+res+' could not be found, one will be created')
print('no issue keys found');
print('issue '+relatedIssue+' has already been identified through subject /other means');
By Email Address
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 in 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):
One of the profile's catch email addresses must match ABCfirstname.lastname@example.org
One of the profile's catch email addresses must match email@example.com (sub-domain excluding from matching)