Email This Issue
📈 Marketplace❓ Support❤️ Feedback🏠 META-INF Apps
Email This Issue - for Jira Server/Data Center
Email This Issue - for Jira Server/Data Center
  • ⬇️Start Here
  • Email This Issue - for Jira Server/DC
  • Features
  • Secure the email channel with Email This Issue
  • Comparing Email This Issue and Jira Server/DC
  • 🤓Documentation
    • Outgoing Emails
      • Sending manual emails
        • The difference between email editors
        • Enabling template categories so templates can be chosen on the Email screen
        • Mail Generation Queue (formerly called Event Queue)
        • Manual Email Default Settings
      • Sending issue filters by email
      • Email templates
        • Adding custom macro to email templates
        • Adding Email Audit Log to email templates
        • Adding fields to email templates
        • Adding issue comments to emails
        • Adding issue link information to your template
        • Adding issue operation links to the email
        • Adding a signature with a company logo to emails
        • Adding user properties to emails
        • Disabling links and avatars or icons in templates
        • Formatting Date and Time values
        • Using reply templates
        • Using Mail Body Initializer templates
        • Rendering templates within templates
        • Velocity Context in email templates
        • Formatting number values
        • Searching for issues in email templates
        • Changelog information in email templates
        • Canned responses
      • Contexts
        • Context Resolution Algorithm
      • Event Notifications
      • Distribution lists
      • Workflow post functions
      • Custom fields
    • Incoming Emails
      • Attachment Filtering
      • Next Generation Mail Handlers
        • Jira automation and Next Generation Mail Handlers
        • Using regular expressions
      • Classic Mail Handlers - Deprecated
        • Mail Handler Error Log
        • Step-by-step Classic Mail Handler to Next Generation Mail Handler migration aid
        • Field Rules
        • Phasing out the Classic Mail Handler
        • Comparing the Classic and the Next Generation Mail Handlers
    • Integrations
      • CRM for Jira
      • nFeed
      • Glass Documentation
      • API - Integration with other services
    • Administration
      • General configuration
      • Email Audit Log
      • Outgoing Mail Connections
      • Outgoing Mail Queue
      • Incoming Mail Connections
      • Incoming Mail Queue
      • Incoming Mail Log
      • Backup and restore settings
        • Backup and restore administration
          • Backup menu
          • Restore menu
        • Backup and Restore Tutorials
          • Backup and restore for empty email settings
          • Backup and restore only parts of a configuration
          • Backup and restore every setting in the same instance
      • OAuth2 Authorizations in Email This Issue
        • OAuth2 Client Credentials
        • Authorizing Email This Issue to access Gmail accounts
        • Authorizing Email This Issue to access Microsoft 365 accounts
        • Enabling OAuth2 Authorization in your Google Account
        • Enabling OAuth2 authorization in your Microsoft 365 account
        • Troubleshooting guides for Microsoft OAuth2 Connections
          • How to fix "Authorization Was Interrupted" error
          • How to fix "BAD User is authenticated but not connected" error
          • How to fix "401 Unauthorized" error
          • How to fix "key expires_in " error
          • How to fix "Need admin approval" error
      • Alerting via Webhooks
        • Webhooks
          • Configuring Slack to receive webhooks
          • Configuring OpsGenie to receive webhooks
        • Webhook execution logs
      • Email Security
    • Service management integration
    • JQL Functions
    • Top-level menu navigation
  • ☁️Server to Cloud Migration
    • Server to Cloud - Automatic Migration tool
    • Server to Cloud - Manual migration guide for Email This Issue
      • Overview of available features
      • Differences of the Server and Cloud user interface
      • Migrating Outgoing Settings
        • Migrating Templates
        • Migrating Notifications
        • Migrating Manual Email Defaults
        • Migrating Contexts
        • Migrating Canned Responses
        • Migrating Post Functions
        • Migrating Outgoing Mail Connections
      • Migrating Incoming Settings
        • Migrating Classic Mail Handlers
        • Migrating Next Generation Mail Handlers
        • Migrating Incoming Mail Connections
        • Migrating Incoming Mail Queue Settings
        • Migrating Incoming Mail Log Settings
      • Migrating Other Settings
        • Migrating OAuth2 Credentials
        • Migrating global default email settings
        • Migrating permissions for sending emails manually
        • Migrating recipient restrictions
  • ❓FAQ
    • FAQ
      • How to bypass workflow conditions
      • How to avoid email loops
      • How to control who to send emails to
      • How to customize Email From in outgoing emails
      • How to enable logging
      • How to install license keys
      • How to find out why the Email button is missing
      • How to obtain a community or non-profit license
      • How to prevent duplicate emails
      • How to remove old content from reply emails
      • How to send personalized emails to recipients
      • How to set up auto-reply or acknowledgment emails
      • How to track cases when you don't get any emails
      • How to view the log of incoming and outgoing emails
      • The iOS Mail app does not show attachments
      • How to route emails to projects
      • How to maintain email threads in Jira
      • How to fix issues with a corrupt index state
      • How to set polling interval for mail accounts manually
    • Tutorials
      • Configuring email approval
      • Customizing the email template used with manual emails
      • Enhance Jira Service Management with Email This Issue
      • Getting Started
      • Setting up an Email Help Desk
      • Setting up customized notifications
      • Setting up a Service Management with a Next-Gen Mail Handler
  • 🌪️Misc
    • Open Source Components
    • Pricing Updates
      • Pricing Update effective October 1st 2018
      • Pricing Update effective December 1, 2021
    • End of Support Policy
    • Security Advisories
      • Email This Issue Security Advisory 2020-02-18
    • Database Tables
    • Translations
  • 🆕Release Notes
    • Release notes
      • 9.x.x
        • 9.15.0 Jira 10 compatibility
        • 9.13.0 Improvements and Fixes
        • 9.11.0 Improvements and fixes
        • 9.10.0 Major improvements and fixes
        • 9.9.1 Improvements and fixes
        • 9.9.0.2 Major improvements and fixes
        • 9.8.0 Improvements and fixes
        • 9.7.0 Improvements and fixes
        • 9.6.0 Improvements and fixes
        • 9.5.0 Improvements and fixes
        • 9.4.0 Bugfixes
        • 9.3.3. Improvements and fixes
        • 9.3.2 Major improvements
        • 9.3.1 Automatic cloud migration
        • 9.2.2.1 Bugfixes
        • 9.2.2 Improvements and fixes
        • 9.2.1.3 Compatibility changes for Jira 9.0.0
        • 9.2.1 Major improvements
        • 9.2.0 Improvements and fixes
        • 9.1.1 Improvements and fixes
        • 9.1.0.1 Alerting and other major new features
        • 9.0.2 Bugfixes, next step in deprecating the Classic Mail Handler
        • 9.0.1 Minor improvement and fixes
        • 9.0.0 Major improvements
        • 9.12.0 Improvement and fixes
        • 9.17 Improvements and Fixes
        • 9.18.0 Improvements and fixes
        • 9.23.0 Improvements and Fixes
      • 8.1.x
        • 8.1.3 Classic handler is deprecated, timezone support, bug fixes
        • 8.1.2 Important bug fixes
        • 8.1.1 Microsoft 365 OAuth2, improvements and fixes
        • 8.1.0 Microsoft 365 OAuth2, improvements and fixes
      • Up to 8.0.6
Powered by GitBook
On this page
  • Before you begin
  • Use case
  • Procedure
  • Results
  • Related articles

Was this helpful?

  1. FAQ
  2. Tutorials

Setting up a Service Management with a Next-Gen Mail Handler

PreviousSetting up customized notificationsNextOpen Source Components

Last updated 3 years ago

Was this helpful?

In this guide, we are showcasing how to set up a service management with Email This Issue's next-generation mail handler through the example of a company's HR department who is testing the new handler.

Before you begin

In order to ensure working in the above scenario, a number of settings will need to be configured on both Jira's and Jira Email This Issue app's site. For more information, see the rest of our user documentation.

Note: The following is a test case, only meant as a basic setup to showcase a new functionality. Differing setups will yield different results, please keep that in mind when creating your unique setup.

You should have your Jira-related setup ready before creating the mail handler, such as:

  • Three custom fields created in Jira:

    • one multi-user picker field called Internal participant

    • one single-line text field called External participant

    • and one select list (single choice) custom field called Customer Category with the options "Regular" and "VIP"

  • Proper permissions set up for agents and customers, including a technical user who will be your default reporter.

  • Project-level Customer permissions set up according to your needs.

  • Workflow configured with the transition property "jeti.on.email.transition" on a re-open transition.

You should have some Email This Issue-related setup ready before creating the mail handler as well, such as:

  • One template for the "Issue created" notification. We recommend that you create it based on the Theme: Service Management Request Created. Read more about templates .

  • One notification set up in Email This Issue for the "Issue created" event with the above template. Read more about notifications .

  • One context set up with the above notification (recipient being the reporter). Read more about contexts .

  • SMTP server setup and mapped in the context (alternatively use Jira's built-in SMTP connections). Read more about connections .

  • Have a Mail Account setup for the mail handler. Read more about mail accounts .

Use case

HR would like to open requests via email every time a new employee needs to be hired (a new request opened) and comment on those requests when there is a reply in connection to the original email.

When a request is opened, an email should be sent to the reporter, notifying them of a successful request creation.

If a new request is created from an email with the sender address ending in "@gmail.com", the customer category of the request should be set to "VIP" (as they need to process these requests in a different manner).

When the customers send a reply email, a public comment should be left on the issue, while an agent's reply should always leave an internal comment. Related issues should be found by issues keys appearing in the email subject.

In both cases of new and reply emails, the senders and the recipients should be saved as follows:

  • By default, email senders are saved as Reporter in newly created issues.

  • User senders without (create issue and browse) permissions should be saved in a custom field called "Internal participant".

  • Senders unknown to Jira should be saved in a custom field called "External participant".

  • SD Customer recipients should be saved as Request participants.

  • SD Agent recipients should be saved as Watchers.

  • User recipients with (create issue and browse) permissions should be saved as Watchers.

  • User recipients without (create issue and browse) permissions should be saved as Internal participants.

  • Recipients unknown to Jira should be saved as External participants.

If the sender does not have permission to either open a request or leave a comment, a technical user should take action in the name of the sender.

It is also important for them that only relevant emails create requests and that reply emails to the Issue Created notifications are cut. This way, their comments will be short and only include relevant information.

When the request is resolved and it is in "Done" status, it should be re-opened upon a new comment being added to the request.

Procedure

1. Go to INCOMING EMAILS --> Mail Handlers.

2. Click on Add, and select Add Next Gen Mail Handler from the dropdown list.

3. Fill in the fields with the following information, making sure to add a name and a mail account as well as a technical user for "Default reporter". This user should have all permissions to create issues and add comments on the project. You can always open this dialogue by clicking on the three dots at the end of the handler's row and clicking on Edit.

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

4. Click Save to save the settings or Cancel to exit this configuration without saving.

Note: Once the handler is saved, it is displayed in the list of Next Gen Mail Handlers as "DISABLED". You will need to click on the three dots and "ENABLE" eventually, to ensure its working, however, you may also carry out this step after having the mail handler configured.

5. Click on the three dots and then choose Configure to open the setup page for your new mail handler. There are four sections presented that need to be configured in a Next Generation Mail Handler:

  • Filter Emails: set up by default, filtering emails that could be spam messages, large emails or emails of similar nature that you do not want to get processed. Leave it as it is, for now, it will filter emails based on the following attributes:

  • Find Issues for Email: set up by default as "Find issues by issues key appearing in the email subject". Leave it as it is, for now, it will find related issues based on the issue key in the reply emails.

  • If Issue found for Email: actions to take when an issue is found based on the issue key in the email's subject.

  • If Issue not found for Email: actions to take when an issue is NOT found based on the issue key in the email's subject.

6. To configure the actions "If issue found for email", click on the + icon at the end of its row. For our configuration, first, click on Condition to create an IF statement. Define the "Email Sender is" parameter as "Service Management Customer" and click on Save:

7. Click on the + icon at the end of the "If Sender is Service Management Customer" row we just created, then click on Add Comment. Set the "Comment Visibility" to Add public comment, the "Add attachments field" to Filter attachments using the attachment filters, and copy-paste this line in the Split regex section:

\s*From:|___.|On|On .wrote:|----Orig.|On .(JIRA).

Note: Leave the "Attach original email as .eml file" toggle disabled for this scenario.

8. Click Save to carry on with the rest of the configuration.

9. Click on the + icon at the end of the "If Sender is Service Management Customer" row we just created, then click on Else to create a condition for when the email sender is not a service management customer.

10. Click on the three dots at the end of the Else row and select Add comment. Set the "Comment Visibility" to Add internal comment, the "Add attachments field" to Filter attachments using the attachment filters, and copy-paste this line in the Split regex section:

\s*From:|___.|On|On .wrote:|----Orig.|On .(JIRA).

Note: Leave the "Attach original email as .eml file" toggle disabled for this scenario.

11. Click Save to carry on with the rest of the configuration.

12. Click on the + icon at the end of the "If Issue found for email" row, then click on Update issue to create an action that runs separately from the IF-ELSE conditions we created. This means that this action will be carried out by the handler regardless of the project role of the sender.

13. Click on the three dots at the end of the "Update issue by setting fields" row we just created, then click on Save Senders and Recipients.

  • On the Senders tab, set the "User w/o permissions" field's value to the custom field Internal participant and the "Unknown to Jira" field to the custom field's value to External participant.

  • On the Recipients tab, also set the "User w/o permission" field's value to the custom field Internal participant and the "Unknown to Jira" field to the custom field's value to External participant. Leave other fields as they are, for now.

14. Click Save to carry on with the rest of the configuration.

15. Click on the + icon at the end of the "If Issue found for email" row, then click on Execute Workflow Transition to create an action that runs separately from the "IF-ELSE" conditions we created earlier. This means that this action will be carried out by the handler regardless of the project role of the sender.

Note: A dialogue is displayed, where only one attribute has to be configured in our use-case: the "Select transition" option has to be set to By transition property. This is selected by default, but if you are editing a handler and this is not the default value, select this option and click Save.

The handler should now look like this:

16. To configure the actions "If issue not found for email", click on the + icon at the end of its row. For our configuration, click on Create issue and define the parameters according to your project and issue type. In our case, the "Project" is New Handler Project, the "Issue Type" is set to Service Request and the "Request Type" is New employee. Set the "Add attachments" field to Always add attachments, leave the split regex field empty and leave the "Attach original email as .eml file" disabled for now:

17. Click Save to carry on with the rest of the configuration.

18. When a Create issue action is created, a Save Senders and Recipients action is automatically created as well. Click on the three dots at the end of the "Save Senders and Recipients" row that just has been created, then click on Edit.

  • On the Senders tab, set the "User w/o permissions" field's value to the custom field Internal participant and the "Unknown to Jira" field to the custom field's value to External participant.

  • On the Recipients tab, also set the "User w/o permission" field's value to the custom field Internal participant and the "Unknown to Jira" field to the custom field's value to External participant. Leave other fields as they are, for now.

19. Click Save to carry on with the rest of the configuration.

20. As a last configuration step, click on the three dots at the end of the "Create Service Request (New employee) in New Handler Project (NHP)" row. For our configuration, click on Set issue field and define the parameters as below:

21. Click on Save to finish configuring your mail handler, which should look like this by now:

Results

If the above procedure has been followed correctly, a request with comments should be created from the incoming email as follows:

It is visible that as per our guide, the issue is created in the New Handler Project with the Service Request issue type and New employee request type.

Because of the field rule, the Customer Category is set to VIP as the reporter's email address ends in the domain "gmail.com".

Two comments are left on the issue:

  • a public comment from the reporter which is a reply email from the customer to the Issue Created notification

  • an internal comment from the assignee (who is an agent) that is related to the request and mentions the issue key in the email subject.

Related articles

This section only details how to set up the next generation mail handler for your service management project. Its goal is not to detail any Jira-related setup or any Email This Issue-related pre-requisites, but show the setup of a new kind of mail handler. For more information about Next Generation Mail Handlers see . For Classic Mail handlers, see .

❓
here
here
here
here
here
here
here
Email Templates
Event Notifications
Service Management Integration
Contexts
FAQ