Next Generation Mail Handlers

SINCE VERSION 8.0.0

Mail handlers can be accessed from the app's administration page. To see the list of mail handlers, go to INCOMING MAILS --> Mail Handlers. The different types of mail handlers are displayed separately. Classic Mail Handlers and Next Generation Mail Handlers are shown as follows:

Unlike with the Classic Mail Handler, when using Next Generation Mail Handler you need create an Incoming Mail Connection first. Handlers of this type prove to be simpler and more powerful as they do not require or use any incoming mail accounts or handlers from Jira's Incoming Mail page. This is a standalone, Email This Issue-only component free from any limitations or malfunctions Classic Handlers inherit from Jira.

Read more about creating Mail Accounts here.

General settings

The mail handler General Settings may be edited using the General Settings button. The settings here affect all Next-Gen mail handlers.

Adding or editing a Next Generation Mail Handler

Next Generation Mail Handlers may be added using the Add Next-Gen Mail Handler button and Edited by clicking the three dots next to their name and choosing Edit.

Handlers are composed of two main sets of attributes:

• Basic attributes

• Configurable Handler Actions

Basic Attributes

When you add or edit a handler, the following attributes can be specified as basic attributes:

Handler Operations

Next Generation Mail Handlers offer a few operations via the action menu:

General Behavior of Mail Handlers

Mail Handlers (regardless of them being Classic or Next Generation Mail Handlers) follow the same scheme of behavior. They process emails in three phases as shown in the following diagram:

Example configuration:

Configuring a Next Generation Mail Handler

Unlike the Classic Mail Handlers, Next Generation Mail Handlers are built from small, configurable actions. Each of them performs a very specific operation.

The actions in each section are invoked in the order they are listed. Common operations of each action are the following:

• Edit: modify the parameters in the actions (not available to all action types)

• Move up: moves the action up by one position

• Move down: moves the action down by one position

• Delete: deletes the action from the handler

Email Filter Actions

Email filter actions check different characteristics of the incoming emails. If an email passes a filter, the next filter is checked. If an email does not pass a filter, then the process stops and the email is marked as filtered out and is not processed.

There can be multiple filter actions added to a handler. To add a filter action, use the + icon.

Available Email Filter Actions:

Finding Issues for Emails

This part of the handler contains Issue Lookup Actions whose responsibility is to find issues associated with the email using different approaches. The approaches to find issues associated with emails are:

• Find issues by the issues key appearing in the email subject

• Find issues referenced by the In-Reply-To or References headers

• Find issues by a JQL query composed of the email attributes

There may be multiple issue lookup actions and they are executed in the order of appearance. If a lookup action finds a single matching issue, the rest of the actions get executed and the issue is later used by the handler.

If the lookup actions do not find any issues or find multiple issues, it is considered as no issues are associated with the email and the email is not processed.

Add lookup actions by clicking the + icon.

Available Issue Lookup Actions:

Altering Existing Issues

The "Issue found for email" section of the mail handler is composed of actions that are executed if the handler could associate an existing issue with the email that is being processed. Unlike the Filter Emails and Find Issues sections, which include actions of the same kind, this section has a variety of different actions.

Add actions by clicking the + icon of the section.

The summary of actions to be used here is as follows:

Adding comments to issues

This action adds a comment to an existing issue that is found by the issue lookup commands. The action may be configured based on the below popup dialog:

Updating issues

This action is a placeholder for actions that modify the issue fields. It has no attributes to configure. Child actions may be added via the eclipse menu.

Adding extra audit logs

This action adds an additional audit log to the incoming mail log, and the incoming email will be visible on the email's tab.

This option may be used when you would like to update an issue without adding a comment (for example modify a field) but you need it to show in the request (in the email tab).

This action cannot be edited, it may only be added or removed from the list of actions.

Executing Workflow Transitions

This action executes a workflow transition on the issue. The transition to execute is either determined by a transition property or by email content. The action can be configured as shown here:

Example: Execute the transition named in the email body

Note: Workflow Conditions and Workflow Validators may block the transition from being executed but this does not affect the processing of the email.

Sending auto-reply emails

This action sends an auto-reply emails to the email sender using a selected email template. By deafult the sender of the auto reply is the default reporter. The action can be configured as shown here:

Saving senders and recipients

This action saves email senders and recipients into issue fields. The action can be configured as shown here:

Note: It is possible to configure from which email field the app should save the recipients to issue fields. Click on the TO and CC labels to enable/disable the corresponding email fields.

Adding email address exclusions

Under the Exclusions tab, regular expressions may be defined. If the email's sender address or recipient addresses match any of these regexes, they are discarded and not saved to issue fields.

This is useful to filter out senders and recipients not matching a certain domain or to prevent saving the mail box email address to issue fields.

Sign-up settings

SINCE VERSION 8.0.3

In case of Jira Service Management and if the Service Desk is Open for signup, you can define from which email fields you would like to create a new customer. If you turn off the creation of new customers, then the Mail handler treats the email address as "Unknown to Jira".

You can also send a signup notification to your new customers, with the Notify newly created customers option. After enabling it you can see the settings for the notifications:

Setting issue fields

The action sets issue fields from email content. The action can be configured as shown here:

Example for extracting value from email:

Example for entering value manually:

The How to set fields option is a method selector:

Input helping table for system fields

Input helping table for custom fields

Text fields truncate

There is a limitation in Jira for the length of the text fields. Before the Set Field action adds value for text fields, it truncate the text to this maximum length. The default maximum length of the text fields is 32767 characters.

How to initialize Date and DateTime picker fields

If you want to set Date or DateTime picker fields, date or date-time values from the email must be parsed. Email This Issue provides an object that supports date parsing.

For example:

regexp returns the date string in the first capture group: 23/07/2015. Then set the Value to $parser.parseDate("dd/MM/yyyy", $group1).

The date or date-time pattern follows the syntax in Java SimpleDateFormat.

There is a possibility to set the current timestamp as the target value of any Date or DateTime picker field. To do this, set Value to $parser.now().

Note: the latter feature is also available for text (single line) field assignments. Moreover, in this case the user can specify any valid date/time pattern, how the text shall be written into the field, e.g. by using $parser.now("dd/MM/yyyy"). On the other hand, Date and DateTime picker fields accept data only in a specific format, therefore you do not need to specify any pattern for them. If you still do it, the expression will be automatically overwritten to the parameter-free variant of the parser.

Initialize multi-select fields

In order to save values in multi-select custom fields, the value must be a comma-separated list of literals. Each literal must match a valid option in the field.

e.g. your regex returns the values in groups 1, 2 and 3. Then set the value to $group1, $group2, $group3

Initialize cascading select fields

It is possible to save values in Cascading Select fields.

If you want to initialize the parent value of a cascading select field, configure the rule with a manual value or with a value from a capture group.

If you want to initialize both the parent and child values, use a special syntax in the Value field: $parser.cascade("<parent-value>", <child-value>").

For example:

• $parser.cascade($group1, $group2) or

• $parser.cascade("some value for parent", "some value for child")

Increment or Decrement number fields

If Value is set to a number prefixed with a + or -, and the Issue Field selects a number custom field, the current value of the field will be incremented or decremented respectively, otherwise, the field is set to the value.

E.g if Value is "+2" the field value is incremented by 2.

Mandatory field support

If you have mandatory fields on your create issue screen or on your service management portal, the create issue action shows it on the Mail handler configuration screen:

Conditional processing

Conditions allow for the conditional processing of emails. This is useful when fields must be set differently depending on some conditions. Conditions can be configured as shown here:

Condition actions provide conditions:

• on the sender

• on the issue

• on the email content

Note: It is not necessary to specify all types of conditions in a Condition action. It is perfectly valid to have any number of combinations. If multiple condition types are provided, they are AND-ed.

The simplest conditional processing is using a static regular expression on an Email Field. In this example, we are looking for the text Project: HR in the incoming email's subject:

You can also use JQL queries during conditional processing. In this example, we are checking if the issue found for the incoming email has the issue type "Service Request":

You can combine the above two examples by using a JQL and a regular expression in order to narrow your condition for further mail handler actions: In this example, we are checking the incoming email's body to see if it contains a text "INT-" and then any four digits. If the body of the email contains this string, we'll then check if the issue we found also has the same value for the custom field called "Serial number" as the four digits in the email's body (in this case $!group1 refers to the four-digit part of the regex).

Available Child Actions

Conditions typically have child actions that can be added by clicking the three dots next to the condition:

Child actions include all the above-mentioned action types, plus two additional ones:

• Condition

• Else

Nesting Conditions

It is possible to add a condition action within another condition action, therefore nesting conditions into each other:

Else

"If" condition may include an "Else" part, which is executed if the condition is not met. You can add this by selecting Else after clicking the three dots next to the condition's name.

Else actions also have their own child actions and conditions:

Creating a new issue and linking it to an existing issue

SINCE VERSION 8.0.4

The Create Issue action creates a new issue. If added to the section "If Issue found for email", it will create a new issue instead of commenting the existing one. The two issues may be linked using the link type attribute, but this is optional.

This feature can be useful if your processes do not allow commenting on closed issues. In this case, simply add a Condition that checks if the issue which was found for the email is closed, resolved etc. If so, create a new issue, otherwise comment the existing one. If you use the Advanced option for issue creation, please find the Link type field on the Other Settings tab.

Creating new issues

The "Issue not found for email" section of the mail handler is composed of actions that are executed if the handler could not associate an existing issue with the email that is being processed. Unlike the Filter Emails and Find Issues sections, which include actions of the same kind, this section has a variety of different actions.

Actions may be added by clicking the + icon of the section.

Summary of actions to be used here is as follows:

Create Issue action

This action creates a Service Management request or Jira Issue from the email content. The incoming email's subject will be the Summary of the created issue, while the email's body will be the Description by default. Basic and advanced issue creation options are available. The action can be configured as shown in this section. Example for basic issue creation:

By choosing the Advanced option it is possible to set the Project, Issue Type and Request type based on the incoming email.

Example for advanced issue creation:

Please note that fields marked with * are required.

Note: There are no required fields on the Request Type tab. If no rules are configured for request type resolution and the Project is a Service Management Project, the created issue won't have a valid request type.

Routing emails to multiple projects

By using conditions, you can route incoming emails to multiple projects depending on the email content. Below is an example that creates issues in different projects depending on the recipient address via which the email was received.

Testing your Mail Handler

You can test your Mail handler by clicking on the Test Handler button.

On the upcoming screen, you can upload any .eml file to test the configuration of the current Mail Handler.

It is important to know, that this is an ordinary mail handler execution, therefore it is only to be used for testing purposes.