@Since JEMH v1.8.20

How Thread Matching Works

In order to match replies to the original email, the Message-ID, In-Reply-To and Reference headers are used.  The below image shows how mail threading headers are structured.

Open

When an email reply is received by JEMH, the In-Reply-To header is first checked against Message-ID's that have been seen before.  If a match is found, the associated issue will be commented against.  If a match is not found, JEMH will then try to match one of the message ID's found in the References header.  At this point, if an associated issue is found a comment will be made. If an existing issue has still not been found, then a new issue will be created (if permitted by JEMH operating mode).

Scenario: Just comment on the (closed issue)

Whilst this feature is here for all the other outcomes of commenting on a closed issue, its probably work listing here for others how to enable closed comments to commented on, i.e. its a Jira workflow property that puts the issue in a non-editable state on closure. So, if you want to edit/comment, on all issues, don't set the property:

• https://confluence.atlassian.com/jira/allow-editing-of-closed-issues-138704.html

Scenario: Notify sender of failure to process due to Issue Closure

It may be desirable to encourage users to log new issues rather than commenting on old issues (which may now be closed). 

When JEMH is configured with an Email > Pre-processing > Thread Matching Limit, if the issue identified through the issue key (or mail thread) is found to fail this, JEMH can just go and automatically create a  new issue, easy!  

The scenario here, is when the JEMH Profile is locked into COMMENT only behaviour through

• Email > Email Selection > Operating Mode : Comment Only (drop non-comments)

What will be described here, is the configuration to get into this state, and how to notify users of this condition, and what to do next (like mail a different address to create issues)

Scenario: Add Issue Creation notification and all further notification to the initial email Thread

In this scenario will be shown how to configure JEMH in order to include the Issue creation notification and all other Issue events notification to the initial email thread which has been sent to create an issue in the Jira.

Please review the following link on how to configure it - Associate issue creation and other events with initial email Thread

Configuration Steps

Here are the steps necessary to configure a Thread Matching Limit failure notification:

Setup Operating Mode for Create and Comment

We do this to confirm the expected operation of Creating and Commenting:

Open

Apply a Thread Matching limit

Setup the Thread Matching Limit to require issues not not have a resolution:

•  Email > Pre-processing > Thread Matching Condition : Open Issues Only (in this)

Create a Test Case for Create and Comment

 Here we'll create a Test Case email, validating we can create and comment on issues:

• Create a TestCase

Once the issue has been created, modify the test case, adding the same issue key in the subject, save and run the Test Case, after running, the result screen will show the issue commented on:

Update Issue Status to fail the Thread Match condition

In this case, resolving the issue will set a resolution date, which will fail the 'Open Issues Only' Thread Matching Limit condition:

Now, re-execute the Test Case, notice that a new issue is created, as we are only allowing commenting on open issues (and issue creation is allowed).

Update the Operating Mode to be Comment Only

JEMH will just drop messages by default in this situation:

Now re-execute the Test Case again, without changing its subject, it will attempt to match against TEST-128, but will not be able to create a new issue as just shown:

With Outbound Mail enabled, you'll find no trace of the message or a response.

Notify of Thread Match Reject

Edit the Profile > Email section and check the option:

The Template used for this notification will be the internal DEFAULT template, you can select a possible custom TemplateSet (if created) from the Templates section at the very bottom of the Email page:

Create new Templates

In the top level Template Sets  page, a new tab can be found, where new templates can be created:

The edit time contains both TEXT and HTML, where the standard JIRA CSS is applied, for custom CSS (to stop auto-inlining) it can be deselected:

After setting an issue key in the Preview field:

Its then possible to use the blue square preview icon:

JIRA users will be notified with a template according to their user profile.  Non-JIRA senders will receive a format according to the:

• Email > Templates > Non JIRA User notification format

Validating notification

With:

• the Profile operating mode Comment Only

• the Thread Matching Limit set to Open Issues

• the issue to be commented on in a Resolved state

• the email referring that issue

• the check-box enabled to notify for thread match rejects

The following will be seen to be enqueued when the Test case is run:

The mail received:

Customizing the Sender From: address (via Issue Custom Field)

By default JEMH will use the Profile > Email > Addresses section to set the: From details (Personal and Address), if not present, the system (mailserver) default will apply.  Its also possible use a derived From address, based on the content of a custom field in the issue that the comment was attempted on.  This requires a single line TEXT custom fields to be available, and to contain an RFC 822 compliant email address, that may or may not contain a Personal Part.  Some valid examples are given below:

• Support People <support@yourorg.com>

• support@yourorg.com

The thread matching section is shown below, where the Thread Match From: source (1) is shown, and the Use Issue Custom Field for Reject Sender custom field selector (2).

After saving, the notification enablement and From: address source will be identified:

The above configuration will use an email address if found, setting that custom field to an appropriate value can be done in the following ways:

• literally set the custom field definition with a default value

• Use the JEMH Profile > Custom Field Defaults

• Use the JEMH Profile > Project > Project Mappings, where you can define 'user defined fields', e.g., the customfield_12355 ID of the the field as the key and the address as the value.

 Its up to you to confirm that the address is valid for your mail server to send 'from' !

Reviewing an issue, with that custom field populated with an RFC822 email address:

The mail received has the expected From: header:

Example Thread Matched mail

Thread match example scenario

Here, initially with our Profile, I use an example mail with a unique messageID

The messageID gets stored on the created issue (here TASKS-23) so that when email replies that refer it come in:

The log shows this associates through threading:

JEMH found issue [TASKS-23] through In-Reply-To/References header (with JRA-43397 fixed locally)

Related articles