Use Subject Issue Key Matching

Owned by Andy Brook [Plugin People] (Unlicensed)
Last updated: Feb 10, 2023 by Finn Gale
3 min read

Summary

JEMH searches email subjects for issue keys using one or more configurable regular expressions.  If a valid issue key is found, JEMH can associate the email with that issue and a comment will be attempted.  If no issue key is found in the subject, defined through a directive, or is present in the mail-thread, then a new issue may be created.

Configuration

The regular expressions that are used can be defined under the setting Subject IssueKey (comment) Regexps found in the Email > Pre-Processing > Thread Matching section of a JEMH profile.

To change the setting, click the edit icon in the Email section of the profile and scroll to the Subject IssueKey (comment) Regexps setting.

If removed or left untouched, matching occurs through the default regular expression (regexp):

\b[A-Z][A-Z_0-9]+-[0-9]+\b

Limiting matches to specific Project(s)

Its a common scenario to have subjects that contain issue keys (or just text) that happen to match issue key format. JEMH will select the first such issue that is found in the local instance, you may want to limit the projects that are considered valid for commenting, eg:

This is an example DDD-123 but what about ABC-123

If DDD-123 happened to be a real issue in the local instance, it would take precedence. You can configure the IssueKey (comment) Regexp field to limit commenting to just the ABC project, the example below shows how multiple projects can be OR’d together to be ‘valid’:

\b(ABC-[0-9]+|DEF-[0-9]+)\b

Capture Groups

JEMH interprets Regexp capture groups (deffined by opened and closed brackets, i.e. ( ))as the matched value to be used in issue association. This means that Regexps which use capture groups should contain the full Issue Key. For example an email with the subject ABC-123:

b(ABC|DEF)-[0-9]+)\b will return a match of ‘ABC', and not associate the issue

\b(ABC-[0-9]+|DEF-[0-9]+)\b will return a match of ‘ABC-123’ and will associate to the issue

Avoiding Subject Issue Key Mismatches

As an example, imagine an email is sent with the following subject:

Subject: Server is broken again, looks like INFRA-333 again

JEMH will use its configured regular expressions to try and match an issue key format.  If INFRA-333 is found to match an expression and be a valid issue key, a comment will be attempted on the issue.  This may be desirable in some cases, but what if JEMH is matching to issue keys that are not the intended target?

With a more specific regular expression, JEMH can more reliably determine what keys it should search for.  A simple way to do this is to use issue keys that are surrounded by some standard text.  Let's say that your Jira is producing notifications in this format:

In order to match only this particular pattern and not any other issue key in the subject, the following regular expression could be used:

This will return issue key of format ABC-123 to JEMH only if they are in parentheses.  Any other issue keys found would be ignored as they do not match the expression.