| Redirect | ||||||
|---|---|---|---|---|---|---|
|
Thank you for visiting our old product documentation site. Note that weare in the process of migrating our product documentation and soon we will notno longer store or update our documentation here.Please navigate to our new documentation site and update your bookmarks accordingly. If you're looking for the former content of this page, click here. |
Introduction
Email Chains are important to keep track of email conversations and properly represent them in Jira as issues and their comments.
By default, messages that are part of a particular mail thread are identified and the corresponding email thread is maintained based on the Jira issue key appearing in the messages' subject.
Even if the issue key is not included in the subject, there is still another way to identify issues based on the incoming email: the Message-ID.
A Message-ID is a globally unique message identifier that refers to a particular version of a particular message. It is generated and set in the header part of the email by the email server that dispatches it.
Although - according to the RFC-5322 standard - Message-IDs are not mandatory (header) attributes of an email, it is highly recommmended to provide one and most service providers comply with this.
Typical use cases
To better understand the need for managing mail threads, consider the following, quite usual situation:
Anne sends an email to Bill and Corp, where Corp is the mail account that is processed by Jira. The email does not contain any references to an existing issue in Jira.
The issue is created in Jira by our Mail Handler.
Bill receives the email and uses the Reply-All function to send a reply to Anne and implicitly to Corp as well, since Corp was on the original email.
The reply email reaches Anne and Jira, but as it lacks a valid issue key, a new (kind of duplicate) issue is created again by the Mail Handler.
| Info |
|---|
However, the preferred (or even the expected) behavior was to save Bill’s response as a comment in the issue created from Anne’s original email. |
Let’s see a bit more complex example:
Anne sends an email to Bill and Corp, where Corp is the mail account that is processed by Jira. The email does not contain any reference to an existing issue in Jira.
The issue is created in Jira by our Mail Handler.
Bill receives the email and replies to Anne and Daniel (using the Reply or the Forward option of his mailer app), but does not include Corp in the recipient list (i.e. explicitly removes it).
Daniel receives the email and replies to Anne, but not to Bill and Corp.
Anne receives the email and replies to Daniel’s response, but at the same time, she decides to send the message also to Corp (she adds it to the recipients again).
The reply email reaches Daniel and Jira, but as it lacks any valid issue key, a new (kind of duplicate) issue is created again by the Mail Handler.
| Info |
|---|
However, the preferred (or even the expected) behavior was to save Anne’s response from the 5th step as a comment in the issue created from Anne’s original email. It is worth noting that in contrast to the previous example, the mail sub-thread in the 6th step is completely detached from the original (main) thread started in steps 1 and 2. If - in the meantime - somebody replies from Jira to the original message (to Anne or Bill or both), a completely independent sub-thread is created possibly containing several replies of its own. On the other hand, these two sub-threads will never be mixed again (even if there are some common recipients every now and then), the only common item is the original message sent by Anne in the 1st step. Assuming that the initial subject stated in the original email sent by Anne in the 1st step is valid and relevant in any message of any sub-thread, it is a justified expectation to have them assigned to the very same Jira issue. |
At last, let’s consider the following use case:
Anne sends an email to Bill and Daniel. The email does not contain any reference to an existing issue in Jira.
Bill receives the email and decides to have a Jira issue created from the topic, therefore he replies both to Anne and adds Corp (the mail account that is processed by Jira) as a CC recipient. Besides, he removes Daniel from the recipient list.
The issue is created in Jira by our Mail Handler.
Anne receives the email but replies to Bill only (instead of Reply-All, she uses the Reply function). As a consequence, Jira is not notified about the update, it does not know about the reply message.
Daniel also receives the original email from Anne, then he also decides to have a Jira issue created from the topic (he does not know about the already created issue as he was excluded from the reply emails in the main thread) and thus replies both to Anne, Bill and adds Corp as a CC recipient.
The reply email reaches Anne, Bill and Corp (the mail handler in Jira), but as it lacks any valid issue key, a new (kind of a duplicate) issue is created again by the Mail Handler.
| Info |
|---|
However, the preferred (or even the expected) behavior was to save Daniel's response from the 5th step as a comment in the issue created from Bill’s reply in the 2nd (and 3rd) step. In this last example, we saw an incident, when Jira was not involved in the conversation from the very beginning, but it was notified from two different sub-threads at different stages during the flow of conversation. On the other hand, it is expected to get those replies to appear as comments in the very same Jira issue. |
The occurrence of such duplicate, but seemingly unrelated Jira issues is a recurring problem - especially when managing lots of customer requests - and causes confusion in many cases, as cohesive messages and their history are administered in separate Jira issues.
In addition to the propositions above, it is extremely unlikely for mail threads to have a linear history. There is an almost unlimited number of combinations for creating branches, that is, sub-threads in a mail thread, where some of the original recipients are excluded or other recipients are added (or re-added) on the way.
The main purpose of mail chain management is to identify such mail threads correctly and preserve the cohesion of the messages in a thread that do not have any issue keys in the emails' subject. In other words, mail chaining exists to avoid creating duplicate issues.
To get around the problem of ensuring the cohesion of email threads, please follow the instructions below.
Configuration
To support email thread management based on Message-IDs, you just have to enable the Enable issue lookup by mail headers option on the Find issue tab on the Edit Mail Handler page. After this, your email chains will be automatically maintained.
...
As a result, the handler will attempt to find issues by extracting Message-IDs from the References or In-Reply-To email headers of the reply emails. If found, the reply mail’s body is added as a comment which is the desired behaviour in most use cases.
| Note |
|---|
Please note that in order to take this rule effect, the messages' subjects must not contain any existing issue keys, otherwise the issues will be matched by the issue key in subject rule due to its precedence. This may lead to confusion in particular situations, if the two rules would otherwise result in different issue resolutions (that should not happen in an ideal setting). |
Operation principles
General
If possible, for all incoming emails, all available Message-IDs that can be extracted from the headers of the current incoming email are saved to their respective Jira issues, even if this particular lookup is disabled (i.e. if the matching issue is found based on the “issue key in subject” rule or based on a JQL filter condition).
| Info |
|---|
By implementing this kind of retroactive Message-ID storage, the Jira issue will also know about the preceding part of the mail thread, even if Jira was getting into the loop at a later stage. |
By disabling the Enable issue lookup by mail headers option, the matching issue will no longer be found based on the Message-IDs. This may result in creating new issues, as described in the use cases section above. However, re-enabling this lookup will then possibly return multiple issues for the given search, which can be problematic by nature.
Handling multiple matches
Provided that the mail chaining feature is turned on, multiple matches are not possible anymore (following a phasing-out mechanism).
However, if either the mail chaining feature is temporarily disabled or if duplicate issues already exist for a particular mail thread in the system (at the time of the introduction of this feature), the problem of multiple matches must be addressed.
As email processing runs in the background (without user interaction), our primary goal is to provide a systematic approach to an unambiguous resolution of the matching issue in most possible cases, that is, we try to identify the issue, which the message shall be assigned to.
In the case of multiple results, the issue having the lowest issue ID is automatically selected. The reason behind this logic is that most probably the oldest Jira issue - the issue with the lowest issue ID - was created first in time as the original entry point for the given topic and all other issues can be considered as duplicates.
Search issues manually by Message-ID
Technically speaking, the list of the associated Message-IDs are stored as a JSON array in a Jira entity property of the given issue. It is possible to check the saved data from Jira’s user interface too, as this entity property was made publicly searchable. In order to do this, navigate to the advanced issue search page (Filters / Advanced issue search menu) and enter any of the following expressions by substituting with the appropriate data.
To search for issues based on a known Message-ID (e.g. “messageId1“) that appears in the associated mail thread, enter the following JQL search query:
Code Block language text issue.property[com.metainf.emailthisissue.entityproperty.messageids].messageIds = "messageId1"To search for issues based on a known Message-ID (e.g. “messageId2“) that was the entry point of the given mail thread for the mail handler, enter the following JQL search query:
Code Block language text issue.property[com.metainf.emailthisissue.entityproperty.messageids].initialMessageId = "messageId2"The expressions above can also be combined, e.g. to search for issues that have any of the Message-IDs (“messageId1“ or “messageId2“) in their mail threads, use the following JQL search query:
Code Block issue.property[com.metainf.emailthisissue.entityproperty.messageids].messageIds = "messageId1" OR issue.property[com.metainf.emailthisissue.entityproperty.messageids].messageIds = "messageId2"
...
This manual search feature is a great tool to double-check your issue metadata and start troubleshooting if you encounter anything out of the ordinary (e.g. not the expected issue is being processed by the mail handler), possibly due to multiple matches. In the case of “mail thread equivalent duplicates”, you need to do the clean up among the issues to ensure correct behaviour.
| Info |
|---|
Normally, an ever-increasing record is built from the Message-ID list of a continued mail thread. However, if the size of the Message-ID list exceeds 32 kB, only the most relevant Messsage-IDs will be preserved, the less relevant ones will be discarded. Usually, this won’t bring the mail chaining feature to a halt, as a mail thread can also be identified typically based on one of the “most relevant” Message-IDs only. One of such special purpose Message-IDs is the |
Message-IDs in outgoing emails
The outgoing emails sent by Email This Issue contain Message-IDs specific for Jira (as Message-IDs are generated by the service provider’s own choice). This Message-ID contains the numeric issueId to easily identify the associated issue of any message sent by Jira later on.
...