Create and comment on multiple Issues via Script

1 Introduction
- 1.1 Result Maps
  - 1.1.1 Creating a Result Map
  - 1.1.2 Create a Result Map for a different Project
- 1.2 Required Fields
  - 1.2.1 Finding Required Fields
- 1.3 Creating comments
2 Create Issues for each Catch Email address Since 3.4.11, 4.0.17, 4.1.8
- 2.1 Scenario
- 2.2 Implementation
  - 2.2.1 Script
  - 2.2.2 Profile
  - 2.2.3 Email
  - 2.2.4 Result
- 2.3 Setting Project for Result Maps
  - 2.3.1 Example
  - 2.3.2 Script
- 2.4 Apply Project Mapping values for Result Maps
  - 2.4.1 Example
  - 2.4.2 Script
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

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 multiple issues from a single email

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.

Email

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:

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:

Understand how Issue association works

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:
1. 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