# 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 (Deprecated with version 9.2.0) and Next Generation Mail Handlers are shown as follows: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FWIBBklpOgq6vQ3z5U9NH%2Fimage.png?alt=media\&token=938f33ae-0d09-4911-8ec8-2f8d59fc5a9f) 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](https://docs.meta-inf.hu/email-this-issue/email-this-issue-for-jira-server-data-center/documentation/administration/incoming-mail-connections). ## General settings The mail handler General Settings may be edited using the **General Settings** button.\ The settings here affect all Next-Gen mail handlers.

Mail Handler's General Settings page

AttributeDescription
Global Email Address Exclusions

Global Email Address Exclusions serve the same functionality as the Save senders and recipients action's Exclusion option.

Under the Exclusions tab, regular expressions may be defined. If the email's sender address or recipient addresses match any of these regexes (or static addresses), they are discarded and not saved as values in 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.

Global Email Address Exclusions are applied to all Next-Gen mail handlers and are added in addition to unique settings in the 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 ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2F8yzazeJ9Cl2jim33fT9z%2Fimage.png?alt=media\&token=f26fa792-e515-49cd-bde1-a667f2b656a2) ### Basic Attributes When you add or edit a handler, the following attributes can be specified as basic attributes: | Attribute | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | Unique name of this handler. | | Description | A longer description of the purpose of the handler. Optional. | | Incoming Mail Connections |

Incoming Mail accounts from which the handler receives the incoming emails.

These accounts are defined in Email This Issue and are independent of the mail accounts defined in Jira.

Next Generation Mail Handler may be used with multiple mail accounts which makes them ideal to provide a single channel to process emails sent to different mailboxes (you can use more than one email addresses for one project).

| | Default reporter |

The default account used to create issues or requests and add comments when the email sender is not permitted to carry out these operations.

Required Permissions

In order to make the handler fully compatible with Jira Service Management, the default reporter must have Project Administration and Service Management Agent permissions. It is typically achieved by assigning the default reporter to the Administrators and Service Management Team project roles and assigning Service Management application access.

When the handler is configured to work with a non-Service Management project, the default reporter must have Browse Projects, Create Issue, Create Attachments, Add Comment, Manage Watchers, Transition Issues permissions.

| | Debug | If enabled, the Next Generation Mail Handler will generate much more verbose output to the [Incoming Mail Log](https://docs.meta-inf.hu/email-this-issue/email-this-issue-for-jira-server-data-center/documentation/administration/incoming-mail-log). | ### Handler Operations Next Generation Mail Handlers offer a few operations via the action menu: ![Mail handler menu](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FCCqqMbYXgFvWzXQ2j5CJ%2Fimage.png?alt=media\&token=c0d0b7aa-4ac6-4734-9078-145ffcae7b35) | Operation | Description | | ---------------- | ---------------------------------------------------------------------------------- | | Edit | Edit the handler's basic attributes | | Configure | Configure the actions the handler executes when processing an email (see below) | | Delete | Delete the handler | | Disable / Enable | Disable or Enable the handler. Disabled handlers will not process incoming emails. | ## 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: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FvI2qZimC8RCU8RzU2Yet%2Fimage.png?alt=media\&token=d73a2d91-5c32-4e56-8bbb-ddbfed017afb)
Example configuration: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FkOldto4pXu6F7tUDXbdS%2Fimage.png?alt=media\&token=ce1fd733-2cdb-46ff-80dc-da318a94495f) ## 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 ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FULIwccWgyXuSwT4S8ic8%2Fimage.png?alt=media\&token=24115191-11ba-470d-911e-6c71a4772059) ### 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. ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2F8iIR201Scm5mwfzaIAPn%2Fimage.png?alt=media\&token=52e4393f-6097-4a3c-88e5-cd17632c7e9e) Available Email Filter Actions: | Filter | Description | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bulk Emails | Filters out emails with Precedence: bulk header | | Delivery Status Notification Emails | Filters out delivery notification emails, which means emails with content type report-type=delivery-status | | Auto-submitted Emails |

Filters out auto-submitted (auto-replied, auto-generated, auto-notified) emails such as Out of Office mails.

This includes emails with header Auto-Submitted set to anything else but "no"

| | Large Emails |

Filters out emails larger than a specified size threshold (which is 25MB by default) including attachments.

| | Emails Sent from This Jira | Filters out emails sent from this Jira instance (based on the Jira fingerprint header) | | Emails Sent from Other Jira | Filters out emails sent from any other Jira instances (based on the Jira fingerprint header) | | Emails by Recipient Address |

Filters out emails that were not sent to recipients configured in this action. You can specify multiple email addresses or regular expressions that will be matched against the recipients (To, Cc) of the email. Unless either of the recipients matches any of the email addresses or regular expressions, the email is filtered out.

| | Filter by Sender Address |

Filters incoming emails by the senders email address

Filter Name: name of the filter item, you can add more of this filter to the handler with a unique name

Filter by global blocklist: there is a global sender blocklist available in General Configuration, enable this option to use it in this filter

Filter type: if not using the global blocklist, you can specify if this filter accepts or refuses emails sent from addresses matching the regular expressions

Regular expressions: these regexes (Java format, one per line), are matched against the sender's address. If one of the regexes matches, we accept or refuse the email depending on the type being allowlist or blocklist. As a safety measure, please always start your regex with (?i) when matching email addresses.

| | Emails by email attribute |

SINCE VERSION 8.0.3

Filters out emails if the regular expression matches the text in the configured email attribute.
You may define a Template to send a bounce email if this filter rejects the incoming email.

| ### 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. ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2Fin24f3uJ3vAfROR0OCTP%2Fimage.png?alt=media\&token=568fd9ab-8f29-48e5-9746-64dddab54054) Available Issue Lookup Actions: | Action | Description | | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Find issues by issues key appearing in the email subject |

This is the most well-known form of mapping emails to issues. If an issue key appears in the subject, the handler looks up the issue and will use it later on during the process.

If more than one issue keys are included in the subject, they are evaluated from left to right.

| | Find issues by references in email headers |

The handler investigates the In-Reply-To and References email headers. If they refer to an issue, the handler searches for the issue and if found, it will use it later on during the process.
This lookup action can be used to maintain email chains. Please refer to this documentation on how: Maintain Email Chains (Email Threads) in Jira

| | Find issues by JQL |

This lookup action extracts content from the email and executes a JQL query to find the issue:

| ### 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. ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FyUQCLijDzBGr2Al7MvtH%2Fimage.png?alt=media\&token=bbe8a4f7-9aa3-4abb-a13b-dd6c1f74e1cf) The summary of actions to be used here is as follows: | Action | Summary | | --------------------------- | ------------------------------------------------------------ | | Add comment to the issue | Adds a comment to the issue. | | Update Issue | Groups actions setting issue fields | | Add extra audit log | Adds an additional audit log to the Emails tab. | | Execute Workflow Transition | Executes a workflow transition in the issue's current status | | Send Auto-reply email | Sends an auto-reply email using a selected template | | Save senders and Recipients | Saves email senders and recipients to issue fields | | Set Field | Sets an arbitrary issue field | | Condition | Provides conditional processing | #### 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: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FjlxpOxSFGkHDp8gk3kLW%2Fimage.png?alt=media\&token=f661a479-d06f-4346-9782-0fda3c68a1b2)
AttributeDescription
Comment Visibility

Defines the visibility of the comment added by the action.

For Service Management projects, options include:

  • Default: comment will be public if added by a Customer of the request, or by an agent
  • Internal: all comments become internal (comments by customers will be added by the default reporter)
  • Public: all comments will become public (comments by collaborators will be added by the default reporter)
  • Public if customer: only customers comments will be public

For Software and Business projects, a user group or project role may be selected.

Add attachments

Defines how the action handles attachments in the email. Options include:

  • Always add Attachments
  • Do not add Attachments
  • Do not add attachment if one with the same name exists
  • Do not add attachment if one with the same name and size exists
  • Filter attachments using the Attachment Filters
Split RegexThis field may contain Java regular expressions that will be matched against the comment body. If either of the regexes matches the body, the body is split at the match position. The part of the body before the match position will be added as the comment, while the rest is dropped. As a safety measure, please always start your regex with (?i) when matching email addresses.
Default Reporter Comment Event

If a public comment would be added by an external sender it is added by the default reporter in Jira Service Management projects. This setting provides you with a choice to configure how to handle such cases.

  • No event: The comment does not trigger anything in the system. This means that there will be no Service Management events thrown, automations will not be triggered, Email This Issue or Jira Service Management notifications will not be sent, but the SLA remains intact.
  • Email This Issue Event: The comment only sends notifications from the app. This means that there will be no Service Management events thrown (Jira Service Management notifications will not be sent), no automation will be triggered, but Email This Issue notifications will be sent and the SLA remains intact.
  • Service management Event: The comment is added as if it was left by an administrator. This means that Service Management events will be thrown as usual, automations will be triggered as usual, Email This Issue and Jira Service Management notifications will be sent but your SLAs will not work as they should (they will be stopped by the comment even if they should not).
Attach original email as .eml attachmentIf enabled, the original email is attached to the issue as an email file (.eml format).
#### 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. ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FMmGLY66xIRmJge5XVatI%2Fimage.png?alt=media\&token=2e90a828-a386-443d-94fe-72818271ae41) #### 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. ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FxRe7NWSYTQmaiPyIDx5i%2Fimage.png?alt=media\&token=1c5b68dd-0e7c-4f07-acb3-f41421699ad4) #### 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: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FlIvtxCphMwg22Z4ETMX0%2Fimage.png?alt=media\&token=b8dedb33-9d0f-4f76-a20e-9b0267c3ae03) | Attribute | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Select transition |

Defines how a transition to be executed is selected. There are two options:

| | Regular Expression | A regex that is matched against the selected email field. It may extract part of the content into capture groups. As a safety measure, please always start your regex with (?i) when matching email addresses. | | Email Field | The email attribute against which the regex is matched. | | Transition | Name or ID of the transition to execute, it may refer to capture groups of the regex. | **Example**: Execute the transition named in the email body ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FCJLNND1TcJvJ7hRUtx3I%2Fimage.png?alt=media\&token=f7b4ebd4-b02d-4753-a747-44a707ec6f60) {% hint style="info" %} **Note**: Workflow Conditions and Workflow Validators may block the transition from being executed but this does not affect the processing of the email. {% endhint %} #### 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:

The send auto-reply email screen

| Attribute | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Template | An Email This Issue [Email Template](https://docs.meta-inf.hu/email-this-issue/email-this-issue-for-jira-server-data-center/documentation/outgoing-emails/email-templates) that is used to generate the auto-reply emails. Auto-reply emails usually acknowledge the successful processing of the emails. | | Outgoing Mail Connection |

An Outgoing Mail Connection that will be used to dispatch auto-reply emails.

Possible values:

| | From Address | Optionally you can override the From Address set in the auto-reply email. Your SMTP server must accept the specified From Address as valid sender (support relaying). | | From Name | Optionally you can override the From Name set in the auto-reply email. | | Reply-to Address | Optionally you can specify a reply-to address. Emails as a reply to the auto-reply email will be sent to this address | #### Saving senders and recipients This action saves email senders and recipients into issue fields. The action can be configured as shown here: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2F0OxNzJQTpRhaehR9qhDH%2Fimage.png?alt=media\&token=4938bf40-a293-4f15-b004-613730fd5bf4) ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FbvgRVhN4JCgsi6xGZSRf%2Fimage.png?alt=media\&token=f60f3af0-b6d4-45fe-915d-d1824c117a80) {% hint style="info" %} **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. {% endhint %} | Attribute | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Senders: User w/o permission |

Select the issue field to which the sender will be saved if s/he does not have permission to create or access the issue in Jira.

User picker or text fields are available.

| | Senders Unknown to Jira | If the sender is unknown to Jira (neither a user account nor a customer account exists for the email address), the email address may be saved to a text field. Email addresses saved here may be set as recipients in notifications or manual emails. | | Recipients: SD Customer | If a recipient email address is recognized as a SD Customer (and the issue is a SD Request), then the customer account will be saved to the selected user picker field. (Default is Request Participants). | | Recipients: SD Agent | If a recipient email address is recognized as a SD Agent (and the issue is a SD Request), then the user account will be saved to the selected user picker field. (Default is Watchers). | | Recipients: User w/ Permission | If a recipient email address is recognized as a User with permission i.e. Collaborator in SD projects (and the issue is a SD Request), then the user account will be saved to the selected user picker field. | | Recipients: User w/o Permission | If a recipient email address is recognized as a User without Permission to view the issue, then it will be saved to a user picker field or his email address is to a text field. | | Recipients: Unknown to Jira | If the recipient is unknown to Jira (neither a user account nor a customer account exists for the email address), the email address may be saved to a text field. Email addresses saved here may be set as recipients in notifications or manual emails | **Adding email address exclusions** ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FHBePfnruTGjzLH47q1nn%2Fimage.png?alt=media\&token=244a4e18-bda9-4a89-9f89-f7021237240e) 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 ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FDXMxpMzm7KY1QIYq9Bze%2Fimage.png?alt=media\&token=f696b589-bb14-4f19-b0cb-4a44abaeb6b6) 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:

Customer signup notification settings

AttributeDescription
TemplateSelect a template that will be used to generate the signup notification emails. Note that you can only choose templates here that were created from the Service Desk Customer Invitation theme.
In the template, you can use the $!customer.displayName field to refer to the name of the newly created customer (the names of newly created customers are their email addresses).
Outgoing Mail Connection

Select an Outgoing Mail Connection that will be used to dispatch customer signup notification emails.

Possible values:

  • Use Jira's outgoing mail settings - This option will use the connection configured in your Jira.
  • Use the default connection - This option will use the connection set as 'default' in the Email This Issue Outgoing Mail Connections.
  • You can also select any connection that was previously configured in Email This Issue Outgoing Mail Connections.
#### Setting issue fields The action sets issue fields from email content. The action can be configured as shown here: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FbnGWDMCsaITFYVfyZneE%2Fimage.png?alt=media\&token=2128c299-535b-47b4-94ed-dd2846b00f18) Example for extracting value from email: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FnDwHb6UKKboM4u7Mo9RD%2Fimage.png?alt=media\&token=9f8a0e01-986c-4f1f-9188-5ce71b072eef) Example for entering value manually: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FiBJnsJmotSZ6FBcuku1t%2Fimage.png?alt=media\&token=bf4d9580-bfd2-43f1-aa75-9d667d3c0300) The **How to set fields** option is a method selector: | Method | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | Extract value from email |

This method extracts a value from an email field. This extracted value should be used in the Value field.

| | Enter value manually |

This is a manually added value.

| | Attribute | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Issue Field | The (system or custom) field to be set in the issue. | | Regular Expression | A Java regular expression that is matched against the selected email field. It may extract part of the content into capture groups. As a safety measure, please always start your regex with (?i) when matching email addresses. | | Email Field | The email attribute against which the regex is matched. | | Value | Manually entered value (e.g. name of a Priority) or reference to the capture groups of the regex. As shown in the example, it follows Velocity Markup syntax therefore it is possible to use #if or other Velocity statements, value transformations. | | Default | If the result of the **Value** attribute is empty or the regular expression does not match the content of the given mail field (for example **Value** is "Allan the Admin guy" for the CC field but there are no recipients in CC or nobody in the CC field is called "Allan the Admin guy"), the **Default** attribute will be added as a result. This is a simple text value. | **Input helping table for system fields** | Field | Input | Value | Value example | Description | | ------------------ | -------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Affected version | Multiple | Version number, what existing in the project | 1.1.1, 1.2.3 |


| | Assignee | Single |

username
user key
email address
Full name (if only one user exist with this name)

|

admin
JIRAUSER10000

John Smith

|


| | Component | Multiple | Component name, what exists in the project | Jira, Intranet |


| | Description | Single | Text | This is my description | If the length of the description is longer than the maximum length of the description field, the truncate process could cause formatting problems in the formatting. | | Due date | Single | A date in this format: yyyyMMdd HH:mm:ss | 20200506 06:00:00 | Please use the date parser. | | Environment | Single | Text | My environment | This field is truncated if necessary. | | Fix version | Multiple | Version number, what existing in the project | 1.2.3, 1.1.1 |


| | Issue security | Single | Security level name, what exists in the project | SecurityL1 |


| | Issue type | Single | Name of the issue type, what exist in the project | Task |


| | Labels | Multiple | Text | Label1, Label2 | If the label does not exists in the issue, Email this Issue creates it. | | Original estimate | Single | Number | 12 |


| | Priority | Single | Priority name, what exists in the system | High |


| | Project | Single | Project key, what exists in the system | TESTP | The email sender must have create issue right for this project. | | Remaining estimate | Single | Number | 12 |


| | Reporter | Single |

username
user key
email address
Full name (if only one user exist with this name)

|

admin
JIRAUSER10000

John Smith

|


| | Summary | Single | Text | This is my summary | This field is truncated if necessary. In this case the maximum length is 255 characters. | **Input helping table for custom fields** | Field | Input | Value | Value example | Description | | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | Cascade select | Single |

Json array of parent and child: \["parent","child"]
Json array with parent element: \["parent"]
Single parent name

|

\["Europe","Hungary"]
\["Europe"]
Europe

| You can use the cascade parser. | | Date | Single | A date in this format: yyyyMMdd HH:mm:ss | 20200506 06:00:00 | Please use the date parser. | | Date time | Single | A date in this format: yyyyMMdd HH:mm:ss | 20200506 06:00:00 | Please use the date parser. | | Epic link | Single | An epic issue key | TESTP-12 |


| | Group | Multiple | Group names in the system | jira-users, my-group |


| | Label | Multiple | Text | Label1, Label2 | If the label does not exists in the issue, JETI creates it. | | Multi select | Multiple | Fields option names | Option1, Option3 |


| | Multi user | Multiple |

username
user key
email address
Full name (if only one user exist with this name)

|

admin, user1
JIRAUSER10000, JIRAUSER10001
,
John Smith, John Doe

|

The list could be a mix of these values:
admin, JIRAUSER10001,

| | Number | Single | Number | 12 |


| | Select | Single | Option name, what exists in the field | Europe |


| | Request type | Single | Request type in the issue | HR request |


| | Text | Single | Text | My text |

Supports single and multi line text fields.
This field is truncated if necessary.

| | User | Single |

username
user key
email address
Full name (if only one user exist with this name)

|

admin
JIRAUSER10000

John Smith

|


| | Assets Object | Single | AQL query | label LIKE "Computer" | Value resolves to the asset object(s) returned by the query. See also "Limitations on setting Assets Object 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](http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html). 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("\", \")*. 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. **Limitations on setting Assets Object custom fields** There are some limitations when updating the value of custom fields with Assets Object type. * If the AQL query returns too many results, only the first 100 is saved to the custom field. * On the custom field configuration section in Jira, you can specify "Object Shema", "Filter Scope (AQL)" and "Filter Issue Scope (AQL)" to limit the scope of the custom field. Currently the mail handler is only able to validate against the "Object shema" setting. "Filter Scope (AQL)" and "Filter Issue Scope (AQL)" should be included in your mail handler action configuration if you have to apply these settings while processing incoming mails. **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: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FdadQb5a4n3hqpU3NBwSa%2Fimage.png?alt=media\&token=8aaec2e1-0210-4d6a-9e66-c53c9fc97cfe)
IconDescription
(tick)There is no required field, or all required fields are covered by a Setter action
In case of service management, you can not create request if a field is required on the portal and you don't have a Setter action for that field.
In case of Jira project if any field is required, you don't need to add Setter action
#### 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: ![Generic conditional processing example](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2Fhbr7h8PDeW93e8sliekG%2Fimage.png?alt=media\&token=61defd2f-d981-4dcb-be37-426deee86b04) Condition actions provide conditions: * on the sender * on the issue * on the email content {% hint style="info" %} **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. {% endhint %} \ 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: ![Example of a regex condition without JQL](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FaDEt5IxAVTElR0bL4rRx%2Fimage.png?alt=media\&token=4e80d07b-5035-43a9-971c-ac409726d3e8) 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": ![Example of a JQL condition without regex](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FNPPhVwv75in6QlG2CHii%2Fk%C3%A9p.png?alt=media\&token=6f783297-08e2-484a-8c23-61068f978077) 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). ![Example of an advanced JQL condition](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FpqmzOfuk6ycy8Z0QqkdH%2Fk%C3%A9p.png?alt=media\&token=f40e76e2-4954-462e-b7d9-e974ad1364f1) | Attribute | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Email Sender is |

This is a multi-select dropdown to set conditions on the sender. Options include:

Since version 8.1.1 it is possible to select Jira User groups as well. Just start typing the name of the groups you want to add and select from the matching groups.

| | Project |

If no issue is found and the sender condition requires a project, the admin can select a project here for the permission check. If no Project is selected, the project selected in the first Create Issue child action will be used.

The following sender conditions require a project:

| | JQL | If specified, the issue is required to match the given JQL to fulfill the Condition | | Email Field | Email Field that is matched against the regex. The condition is met if the email field matches the regex | | Regular Expression | Regular expression to match against the email field. As a safety measure, please always start your regex with (?i) when matching email addresses. | **Available Child Actions** Conditions typically have child actions that can be added by clicking the three dots next to the condition: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FuDT9EeZk9d2SD76vrPJ8%2Fimage.png?alt=media\&token=e8498f7a-0f93-467f-b539-b1519ededff2) 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: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FRVzT2nZp0NUyoW4IdbJV%2Fimage.png?alt=media\&token=3905b2b0-4647-428e-8979-8464f3cb2fb3) **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: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FK4j8v01lRU5FISi9KJCb%2Fimage.png?alt=media\&token=96d79720-3d6b-40fb-8d5d-306cec3be63e) #### Creating a new issue and linking it to an existing issue SINCE VERSION 8.0.4 ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2F9fzaNvfvXKEgWIwtWhDI%2Fimage.png?alt=media\&token=bc7b02c2-dbc5-48d7-99e4-3fbb77f95d19) 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. ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2F6dM5sIVftYtFtrh2fUHp%2Fimage.png?alt=media\&token=3b95191b-168a-4d14-a50b-51e3ead2e70d) ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FUkZGv04sulFS7sxyWzOc%2Fimage.png?alt=media\&token=b7ff5bbe-71b7-42ee-b996-02c6b2ae9f48) ## 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. ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2F1ANJEVLDPXIFZaNbxH16%2Fimage.png?alt=media\&token=6b13a5b4-87e8-4d24-a402-7a20802ec1ab) Summary of actions to be used here is as follows: | Action | Summary | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Create Issue | Creates a new issue from the email. | | Execute Workflow Transition | Executes a workflow transition in the issue's current status. | | Send Auto-reply email | Sends an auto-reply email using a selected template | | Save senders and Recipients | Saves email senders and recipients to issue fields. This action may be added as a child action of the Create Issue Action. | | Set Field | Sets an arbitrary issue field. This action may be added as a child action of the Create Issue Action. | | Condition | Provides conditional processing. | ### 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: ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FGbFR4KKLwJxcbs1KyGQS%2Fimage.png?alt=media\&token=2d9b411e-fe6b-4f06-bbb0-6656d98dc943) | Attribute | Description | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Project | Defines the project in which the issue will be created. Mandatory field. | | Issue Type | Defines the issue type for the new issue. Mandatory field. | | Request Type |

Defines the Customer Request Type of the new issue. A mandatory field for Service Management projects. If you do not select a request type, the Core API will be used. In this case, customer creation and setting the sender customer as a reporter will not work.
As long as you have a Request type selected the Jira Service Management API will be used by the handler; customer creation and setting a sender customer as a reporter will work as intended.

| | Add attachments |

Defines how the action handles attachments in the email. Options include:

| | Split Regex | This field may contain Java regular expressions that will be matched against the comment body. If either of the regexes match the body, the body is split at the match position. The part of the body before the match position will be added as the comment, while the rest is dropped. As a safety measure, please always start your regex with (?i) when matching email addresses. | | Attach original email as .eml attachment | If enabled, the original email is attached to the issue as an email file (.eml format). | 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: ![](https://metainf.atlassian.net/wiki/download/thumbnails/436469838/image2021-10-12_10-13-36.png?version=1\&modificationDate=1634026418018\&cacheVersion=1\&api=v2\&height=400) Please note that fields marked with \* are required.
AttributeDescription
Regular Expression *Enter the Java regular expression you want to use to extract values from the email.
Email Field *Specify the email attribute to match the regular expression.
Value *Enter the value to set the project. The result should be a project key or ID. Velocity Markup can be used (e.g. $!group0).
Default

This value will be used if the Value field returns an empty result.

When a project key can't be extracted from the email or the project does not exist, the default value will be used.

The default value should be an existing Project key.

![](https://metainf.atlassian.net/wiki/download/thumbnails/436469838/image2021-10-12_10-27-1.png?version=1\&modificationDate=1634027223327\&cacheVersion=1\&api=v2\&height=400) | Attribute | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Regular Expression \* | Enter the Java regular expression you want to use to extract values from the email. | | Email Field \* | Specify the email attribute to match the regular expression. | | Value \* | Enter the value to set the project. The result should be a project key or ID. Velocity Markup can be used (e.g. $!group0). | | Default |

This value will be used if the Value Field returns an empty result.

When an issue type can't be extracted from the email or the issue type does not exist, the default value will be used.

The default value should be the name of the ID of an existing Issue Type.

| ![](https://metainf.atlassian.net/wiki/download/thumbnails/436469838/image2021-10-12_10-31-25.png?version=1\&modificationDate=1634027486456\&cacheVersion=1\&api=v2\&height=400) {% hint style="info" %} **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. {% endhint %} | Attribute | Description | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Regular Expression | Enter the Java regular expression you want to use to extract values from the email. | | Email Field | Specify the email attribute to match the regular expression. | | Value | Enter the value to set the request type. The result should be a request type name or ID. Velocity Markup can be used (e.g. $!group0). | | Default |

This value will be used if the Value Field returns an empty result.

When a request type can't be extracted from the email or the request type does not exist, the default value will be used.

The default value should be the name of the ID of an existing Request Type.

| ![](https://metainf.atlassian.net/wiki/download/thumbnails/436469838/image2021-10-12_10-39-40.png?version=1\&modificationDate=1634027981990\&cacheVersion=1\&api=v2\&height=250) | Attribute | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Add attachments | Defines the attachment policy | | Split Regex | If set, only the content of the email body above split regex will be added to the Description. The split regex functionality uses Java Regex Syntax. | | Attach original email as .eml file | Choose this to attach the original email in .eml format to the created issue | ### 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. ![](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FcZQCPv0t317HjN1VrMfC%2Fimage.png?alt=media\&token=8dcbf438-ba96-4adb-9895-d3af9d3647e6) ### 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.
{% hint style="info" %} It is important to know, that this is an ordinary mail handler execution, therefore it is only to be used for testing purposes. {% endhint %}