Associate an email with an issue

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:

SettingDescription

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

@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.

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

MIME-Version: 1.0
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
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: This is a starting email template, update as required
From: "Andy Brook" <andy@localhost>
To: changeme@thiswontwork.com
Content-Type: text/plain; charset=UTF-8

some text

This was mentioned in custom project YY-4444 but we should put this on XX-2 for further review

more text

Example Script

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[0]) !==null)
        {
            resultMap.put("issueKey", res[0]);
            print('issueKey='+res[0]);
        }
        else
        {
            print('found match but the issue '+res[0]+' could not be found, one will be created')
        }
    }
    else
    {
      print('no issue keys found');
    }
}
else
{
    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):

Local Part

To: ABC-123@mycompany.com

(warning) One of the profile's catch email addresses must match ABC-123@mycompany.com

Sub-domain

To: support+ABC-123@mycompany.com

(warning) One of the profile's catch email addresses must match support@mycompany.com (sub-domain excluding from matching)

Related articles