Create and comment on multiple Issues via Script
- 1 Introduction
- 2 Create Issues for each Catch Email address Since 3.4.11, 4.0.17, 4.1.8
- 3 Issue Association via Script
- 3.1 Background
- 3.2 Associate with Message ID via Script
- 3.2.1 Pre-requisites
- 3.2.2 Script
- 3.2.3 Example Emails
Introduction
The following page details how to use JEMH scripting to create and comment on multiple issues using information from a single email. To provide some context on how JEMH creates Issues and comments and how to make use of this in a script the following primer has been written that describe some key concepts and gotchas for creating issues via Script.
Result Maps
JEMH uses Result Maps as part of email processing to map extracted email content to specific fields in a Jira issue. The Result Map is a Key/Value map which include a Key (Field name or key) and the intended value. For example, a Result Map for an Issue with a provided Summary, Description, and Reporter could be represented as:
Key | Value |
|---|---|
summary | This is a Test Issue |
description | This issue was created via script |
reporter | user1@test.com |
Or in a script as:
resultMap.put("summary", "This is a Test Issue");
resultMap.put("description", "This issue was created via script");
resultMap.put("reporter", "user1@test.com");
Creating a Result Map
Using the Script Field processor, or a Script rule, it is possible to create an Additional Result set in JEMH to create an additional issue. This can be done using the jemhUtils class provided in the JEMH scripting context. For example:
var newResultSet = jemhUtils.createResultSet();For a step by step example of creating multiple result sets via Script please see:
Create a Result Map for a different Project
Project Mapping rules only apply to the original Result Map created by JEMH. If no Project is defined in the New Result Map the issue will be created in the Project defined in the Default Project Mapping in your JEMH Configuration. To specify the Project the New Result Map must contain a Project Key (or Issue Key for commenting). For example:
var newResultMap = jemhUtils.createResultSet();
newResultMap.put("project", "COREONE");
Required Fields
Jira has a number of required fields and will not allow issue creation unless they are present. For example the Reporter, Issue Type and Summary. Typically, JEMH will resolve these required fields as part of email processing, however for new Result Maps created via Script the only fields applied by JEMH would be found in the Default Project Mapping. Any required fields not included in the Default Project Mapping must be manually set as part of the Script. For example, if your default Project Mapping refers to an Issue Type that is not available in the target Project.
Finding Required Fields
Required fields for a Project are listed in the Fields section of your Jira Project Settings at:
Jira > Project > Project Settings > Fields
Creating comments
To create a comment via Script, the Issue Key of the target Issue must be included in the Result Map. For example:
Create Issues for each Catch Email address Since 3.4.11, 4.0.17, 4.1.8
Scenario
You may want to create multiple issues from a single email based on the email recipients. For example, a customer might CC another email address within your organisation specific to a different Jira Project. In this case, one email should create two issues, one for each recipient.
Implementation
The jemhUtils class can be used to create a list of Result Maps for each Catch Email address match in the email. This is specific to the Profile the script is used in. Please see the following example:
Script
Using the jemhUtils.createResultSetForEachMailboxAddress() as part of a script will create a list of Result Maps for every recipient in the email who matches a Catch Email Address. Each Result Map will only contain the Recipient Address that triggered the result map to be created.
The actual Caught Email address will not be used to create an additional Result Map as this would functionally create two issues for the same Catch Email address. The original Result Map could be added to the list of Result Maps
Profile
A Profile with the following Catch Email Address configuration includes a Catch Email address match for, test@test.com, blue@test.com, and green@test.com.
The following example email would result in the creation of three Result Maps and therefore Issues. Without further configuration these would all create issues in the Project defined by the Default Project Mapping:
Result
Setting Project for Result Maps
As mentioned Result Maps created via script will result in issue creation in the Project defined in the Default Project Mapping. To automatically map an Additional Result Map to a Project an Addressee Domain rule can be configured to detect the Catch Email Address used to create the Additional Result Map. For more info on how to create a Project Mapping Domain Rule please see:
https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/2850927/Use+Project+Mappings#Domain-Rule
Example
Using a pre-defined Domain Rules for separate projects, for example the following Domain Rule for the SOFTWARE-ONE Project.
Script
The Script will need to make use of the jemhMapperUtils class which will apply a Project Match based on the email recipient. Fore Example:
Using the Testcase from the previous example will result in the following outcome:
Apply Project Mapping values for Result Maps
As previously mentioned Project Mappings are only applied to the initial ‘Result Map’. In order to apply values from the Project Mapping to newly created Additional Result Maps, another method of the jemhMapperUtils can be used, 'applyProjectMappingDomainRulesToResultMaps'.
Example
Using a pre-defined Domain Rules as an example:
Script
Using the Testcase from the previous example will result in the following outcome:
Issue Association via Script
If creating multiple issues via Script, Issue association must also be handled via Script. Typically JEMH expects to an email to be Associated to a single Issue for commenting however, for multiple issues Threading must occur for each Result Map independently.
Background
JEMH handles thread matching via Message ID by storing the ID of the email used to create an Issue in a dedicated table. Any emails which contain the specific Message ID associated to the Issue in either the In-Reply-to, or References header are considered to be associate and are added to the issue as a comment. For more info on how JEMH associates emails to Issues please see:
To replicate JEMH (and Jira’s) typical Issue association the Message ID of an email should be added to the Issue on Issue creation as a hashed value in a custom field.
Associate with Message ID via Script
Pre-requisites
A custom field to store the hashed Message-ID
Default JEMH Thread Matching should be disabled at:
JEMH > Profile > Email > Pre-Processing > Disable Thread Checking
To then associate issues via Script the Script can make use of the 'resolveFilteredIssueAssociationByMessageIdForAdditionalResultMaps' of the 'jemhThreadUtils' class.
The 'resolveFilteredIssueAssociationByMessageIdForAdditionalResultMaps' method requires the following parameters in order to associate issues:
mapList: A list of all Result Maps that should have issue association resolved based on the Message ID.
onIssueIDField: The ID of the custom field the Message ID of the email will be stored on the issue.
Script
Example Emails
The following example emails can be used to validate issue association via Script.
Create Testcase
Comment Testcase
Outcome