Associate an email with an issue
- Mike Harrison
- Andy Brook [Plugin People]
Introduction
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:
Setting | Description |
|---|---|
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 |
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. |
Email Threading
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):
@issueKey=EX-451Custom 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:
@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.
Directive JQL
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.
The example mail below contains some text, including an issue key YY-4444, but the one we want is XX-2. The javascript below uses a RegExp match, scoped to some expected specific projects, ABC, DEF and XX, so as to ignore YY. Use of regexp capture groups ( expr ) will return more matches, the first is always the whole expression match. So, here we use the extracted email payload through supplied variable body and test for a match. If there is one, we the use the issueManager to lookup the related issue by key, and only if it exists, put the key in the $resultMap aginst "issueKey" to drive commenting on that issue.
Example Mail
Example Script
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):
Local Part
One of the profile's catch email addresses must match ABC-123@mycompany.com
Sub-domain
One of the profile's catch email addresses must match support@mycompany.com (sub-domain excluding from matching)