Migrating Next Generation Mail Handlers
Last updated
Last updated
This section provides information on how to migrate Next Generation Mail Handlers from Server to Cloud.
Note: Next Generation Mail Handlers on Server/Data Center provide more or less the same features as Mail Handlers on Cloud.
As feature parity mostly applies between the two platforms, the main differences between Next Generation Mail Handlers on Server and Mail Handlers on Cloud are in the way the user interface is organized.
On Server, you can first Add/Edit, then Configure a mail handler. The configuration page covers the entire workflow, such as Filters, Issue matchers (Issue lookup) and other post-processing actions such as Custom Field Setters. On Cloud, Issue lookup and Filtering can be found under the Find issue and Filters tabs, while other processing actions can be configured under the Rules and actions tab.
On both the Server and the Cloud interface, there is a tree structure that presents the specified Rules. This condition tree can have multiple levels of depth on both platforms. However, there is a generic, built-in condition on Server: whether the issue was found or not. This is a separate main option on Server, but on Cloud, this condition must be explicitly provided.
On the Server interface, most of the configuration is done in pop-up panels, while on the Cloud platform, a configuration box appears on the right side of the condition tree for entering additional parameters.
In this guide, an extensive, one-by-one comparison of all configurable options is not provided.
On the Server interface, do the following:
Go to Mail Handlers under the INCOMING EMAILS section of the sidebar.
Choose the Next Generation Mail Handler you want to migrate. Click the three dots and select Edit.
In a separate browser tab, log in to the Cloud interface, and do the following:
Go to the Mail Handlers menu item of the Incoming Mails configuration tab, click Add, and select the Custom handler, no predefined actions option.
Copy and paste the content from the Edit Mail Handler panel on Server to the General Handler Settings tab of the Add Mail Handler panel on Cloud. As shown in the image below, make sure to:
Copy and paste the content of the following fields:
Name
Description
Mail Accounts
Default reporter
Enable the Fallback to default reporter option as well, as shown in the image below:
(Optional) Save your settings on Cloud. Note that your changes are saved while switching tabs within the Add Mail Handler panel, but your changes are lost if you navigate elsewhere or go offline before saving your changes.
Go back to Mail Handlers under the INCOMING EMAILS section of the sidebar on Server.
Find the same Next Generation Mail Handler you want to migrate.
Click the three dots and select Configure.
Review the actions that are configured under the Filter Emails section of the Configure Mail Handler panel.
Set up message filters in the Filters tab of the Add Mail Handler panel on Cloud.
Make sure to enable the same filters on Cloud as on Server as shown in the image below. Note that some features, such as the Large email filter and the Filter by email attribute are not available on Cloud.
Auto-submitted (auto-replied, auto-generated, auto-notified) → Filter out auto-reply emails
Bulk emails → Filter out bulk emails
Delivery status notification emails → Filter out delivery status notifications
Emails sent from this Jira system → Filter out emails sent from Jira
Emails sent from other Jira systems → Filter out emails sent from Jira
On Server, click the Emails by recipient address action to open the Filter emails by recipient address panel.
Configure the Accept email field on Cloud as seen in the Match recipient addresses field on Server as shown in the image below.
Save your settings in the Filters tab on Cloud.
If sender address filtering is configured on Server, apply the same settings on Cloud.
On Server, click Emails by sender address to open the Filter emails by senders address panel.
On Cloud, click Sender email address filters under INCOMING MAIL FILTER. As it is shown in the image below, the Blocklist and Allowlist filtering types correspond to the Reject and Accept actions on Cloud.
Save your settings on Cloud.
Go back to the Mail Handlers menu item of the Incoming Mails configuration tab, click the three dots next to your new mail handler, and select Edit.
Set up issue lookup in the Find issue tab of the Add Mail Handler or Edit Mail Handler panel on Cloud. (Note that if you had no Emails by sender address configuration to migrate in the previous step, you should still have the Add Mail Handler panel open.)
Migrate your settings from the Find Issues for Email section of the Configure Mail Handler panel of Server. Note that:
Find issues by issues key appearing in the email subject is the default setting.
Find issues by references in email headers on Server can be enabled under the Enable issue lookup by mail handlers field on Cloud.
Find issues by JQL on Server can be enabled and set up under the Enable issue lookup by JQL field on Cloud.
(Optional) Save your settings on Cloud. Note that your changes are saved while switching tabs within the Add Mail Handler panel, but your changes are lost if you navigate elsewhere or go offline before saving your changes.
Define rules for various actions on the matched issue as shown in the image below:
On Server, check the settings under the If Issue found for Email section of the Configure Mail Handler panel. Note that the image below does not show a real-life configuration example on Server. Its purpose is to illustrate how to find the matching option on Cloud for each action type.
On Cloud, click on the Rules and actions tab in the Add Mail Handler or Edit Mail Handler panel, and click the plus sign to see the available options.
Define your comment-related actions. For example, to migrate a public comment-related action where no attachments are added, do as follows:
On Server, select the Add comment to issue with visibility: Add public comment action to open the Add comment panel.
On Cloud, click on the plus sign under the Rules and actions tab and choose the Add comment action.
On Cloud, select All Users in the Visibility dropdown list.
On Cloud, select Never add in the Attachment handling dropdown list.
You can migrate other values of the Add attachments field to the Attachment handling field as follows:
Always add attachments → Always add
Do not add attachment if one with the same name exists → Skip if attachment with same name exists
Do not add attachment if one with the same name and size exists → Skip if attachment with same name and size exists
Filter attachments using the Attachment Filters → Skip if attachment with same hash exists
Filter attachments using the Attachment Filters → Skip if attachment name matches any of the following regexps
Migrate any custom filters from the Attachment Filters Server menu. Note that attachment handling is more versatile on Server, but some custom filters can be migrated to Cloud as shown in the image below.
The Attachment Filters menu is under the INCOMING EMAILS section of the sidebar on Server.
The Add file name filters option under Add on Server corresponds to Skip if attachment name matches any of the following regexps on Cloud.
The Enable Duplicate Filter option on Server corresponds to Skip if attachment with same hash exists on Cloud.
Define your issue creation related actions.
On Server, select an issue creation action under the Issue found for email or Issue not found for email section of the Configure Mail Handler panel.
On Cloud, click the plus sign under the Rules and actions tab in the Add Mail Handler or Edit Mail Handler panel, and choose the Create issue action.
Copy and paste the settings from the Create Issue panel on Server to the Create request panel on Cloud. Make sure to add the same values to the following fields on Cloud as on Server:
Project → Project
Issue Type → Request type (Note that this field is mandatory on Cloud for the time being due to a related Jira Service Management API limitation)
Add attachments → Attachment handling
Split Regex → Split regexp
Define any other actions on Cloud that are configured on Server under the If Issue found for Email section of the Configure Mail Handler panel.
(Optional) Save your settings on Cloud. Note that your changes are saved while switching tabs within the Add Mail Handler or Edit Mail Handler panel, but your changes are lost if you navigate elsewhere, or go offline before saving your changes.
Migrate senders and recipients settings. Note that managing senders and recipients and defining custom actions upon them is somewhat limited on Cloud. The migration steps below illustrate the difference through some examples: On Server, you can select the fields in which you want to save senders and recipients for a particular Create Issue action through the Senders, Recipients, Exclusions, Signup tabs of a single panel which has dropdown lists. On Cloud, some conditions are available, such as checking if the sender has access, or configuring recipients through rules and actions. Exclusion can be achieved by configuring the recipient blacklist for outgoing emails.
On Server, select the Manage senders and recipients option to display the settings that you need to migrate.
Based on the Senders tab of the Manage senders and recipients panel on Server, configure your rules and actions on Cloud as follows.
On Server, select the Senders tab of the Manage senders and recipients panel.
On Cloud, click on the plus sign under the Rules and actions tab in the Add Mail Handler or Edit Mail Handler panel and add your actions.
Migrate the settings from the Senders tab on Server to the Rules and Actions tab on Server for each action.
In the example below, the Request participants value is set in the SD Customer w/o access field on Server. The corresponding Cloud settings for the Add to Request Participants action are shown on the right side of the figure.
If you want to set the sender not as a request participant but into another custom field, you should use the Set field value action. Note that the Set field value action does not support all custom field types. The example below shows the condition for saving senders who have or don't have access to the issue through IF and ELSE conditions on Cloud:
Based on the Recipients tab of the Manage senders and recipients panel on Server, configure your rules and actions on Cloud as follows.
On Server, select the Recipients tab of the Manage senders and recipients panel.
On Cloud, click on the plus sign under the Rules and actions tab in the Add Mail Handler or Edit Mail Handler panel and add your actions.
Migrate the settings from the Recipients tab on Server to the Rules and Actions tab on Cloud for each action. In the example below, the Request participants value is set in the User w/ permissions field on Server. The corresponding Cloud setting is a separate action called Add to Request Participants, which is shown on the right side of the below figure.
To → To
If you want to set the recipients not as request participants, but into another custom field, you should use the Set field value action. Note that the Set field value action does not support all custom field types. The example below shows a scenario in which the To and CC recipients are saved into the Workaround custom field instead of being saved as request participants:
Save your settings on Cloud.
Based on the Exclusions tab of the Manage senders and recipients panel on Server, configure your recipient blacklist on Cloud as follows.
On Server, select the Exclusions tab of the Manage senders and recipients panel.
On Cloud, select Recipient Restrictions under the RESTRICTIONS menu item of the Outgoing Mails configuration tab and scroll down to the Recipient allowlist and blocklist panel. Copy and paste the email addresses from the Email Address Exclusions field on Server to the Recipient Blacklist field on Cloud.
Based on the Signup tab of the Manage senders and recipients panel on Server, configure your rules and actions on Cloud as follows.
On Server, select the Signup tab of the Manage senders and recipients panel.
On Cloud, click on the plus sign under the Rules and actions tab in the Add Mail Handler or Edit Mail Handler panel and add your actions.
Migrate the settings for each action from the Signup tab on Server to the Rules and Actions tab on Cloud. In the example below, the Sender checkbox is checked on Server, which means that a customer must be created if the sender is an unknown address. The corresponding Cloud settings for the Create customer action are shown on the right side of the figure. Note that:
Public signup is only possible for sender addresses on Cloud.
The associated Service Management project must be selected from the Add to Service Desk dropdown list.
Save your settings on Cloud.
For more information, see:
Server documentation: Next Generation Mail Handlers
Cloud documentation: Incoming Emails (Mail Handler) Documentation and Recipient Restrictions
In this specific case, if the sender has no access, their email address will be saved in the “Text field for testing” custom field. If the sender has access, they will be saved as assignees:
CC → CC
