Getting started

Hello! This guide will walk you through all the necessary configurations to achieve the best Jira email integration possible. The process will take 20-35 minutes, depending on the specific features you require.

Prerequisites

In order to successfully complete this guide, you will need the following:

• An active Jira Cloud instance that you have administration rights for

• To process inbound email:

  • A Jira project

  • An external (non-Atlassian) mail source, for example a POP or IMAP server visible by JEMHC - Setup JEMHC Inbound mail (typically through a cloud provider like Microsoft 365 or Gmail, but could be your own).

• To send outbound email notifications:

  • An external (non-Atlassian) SMTP mail server.

Installing the app

First, we will show you how to install JEMHC on your Jira Cloud instance. Open the Apps drop-down menu from the top Jira navigation bar. Click Find new apps.

Open

On the app search screen, search for the term 'JEMH'. In the search results, you should see Enterprise Mail Handler for Jira (JEMH). Clicking the search result will show you a Marketplace listing for the app.

Open

Click the Try it free button to begin an evaluation of the app. Atlassian will then ask for confirmation.

After confirming, the app will then be installed. This could take a minute so please wait!

Once installation is complete, use the Get started link to open JEMH Cloud startup wizard, which will assist you with creating a basic configuration.

Later, this wizard can be revisited via a link on the Welcome page. For the purposes of this guide, we'll choose to configure both inbound processing and outbound notifications.

Setup inbound mail processing

First, if your services are using IP-based security measures, make sure all relevant IP addresses used by the app are allowed access.

Next we will configure JEMHC to process emails retrieved from an incoming mail server. Firstly, we will select a project that emails should create issues in. Later on you can add additional projects to the configuration - this is just for initial set up. You will also be asked for an issue type.

Next, we’ll set up our inbound mail server connection. Selecting Create new message source will allow you to specify your connection settings. Alternatively, if you’re connecting to a Google or Microsoft email account via OAuth, you can use the respective sign in buttons. See Integrating with Gmail using OAuth and Integrating with Microsoft 365 using OAuth for more information.

For the purposes of this guide, we'll select Create new message source and connect to an example POP3 mail server. JEMHC provides some standard presets. You can choose Custom to pick your own specific hosts and ports, but it's on you to ensure it's correct!

Once the server details have been entered, click the Test configuration button to validate the connection. If it's valid, you’ll see a message similar to the below:

If you're using Google Mail you may see a warning. If this happens, use the link in the message and follow its advice.

Submit the connection settings once they are valid. Lastly, you’ll be asked to enter the Inbound email address. Typically this is the username used in the inbound mail server connection.

Setup outbound mail sending

Now we will configure JEMHC to be able to send email notifications out to Jira users and also users without a Jira user account (we call them non-Jira users). The first thing to do is configure the outbound mail server connection.

Similarly to inbound mail server configuration, we have the choice of manually defining a connection, or using single-sign-on with Google or Microsoft if desired.

Use the Test configuration button and submit the configuration once it is validated.

Click next to move on to the next wizard section.

Setup Custom Fields

In order to support email integration for users with no Jira user account, JEMHC needs to store email addresses in custom fields. Select what custom field is used to store a non-Jira email sender's name and address. You can also choose what where additional user email recipients (CC and BCC) are stored.

Owing to choices Atlassian made long ago, the default readonly “Email Participants” field created by the app (should be a TEXT type) was implemented by Atlassian as a single line field, this may impact you if more than a handful of email-only ‘additional recipients’ would be involved. If you plan to use this feature extensively, you should pre-create another “Email Participant Addresses” field or similar that is of type text multi-line, then, in the wizard, pick that instead of the bundled field that is limited to 255 chars.

If you see a warning that a field isn’t present on the projects issue screen (as above), click the link in the message. You will then be able to associate the field with the appropriate screen related to your project

Repeat this process until all 3 custom fields of your choice are showing as "found" in the wizard.

Click next once this is done. Finally, you’ll see a brief summary of the changes that will occur. Clicking submit here will complete the wizard.

On the final screen, you are given some suggestions of what to do next. If you want to go to the welcome screen at this point, click Go to configuration.

Reviewing outbound settings

Outbound mail

Outbound mail configurations are found under Messaging > Message Outbounds:

Until the mail server setting has been used, its status will be 'unknown'.  To validate this, use the ▸ ping action, loacated under the … more actions icon. Here, the outcome is that the SMTP server is now Online (this would have happened anyway on first actual usage):

Using JEMHC for Notifications

The configuration for controlling what Jira Projects will drive notifications is accessed through Notifications > Notification Mappings > Email:

Disabling Jira Notifications to stop duplicates

Software Projects

Jira Software Notifications need disabling, typically done by deselecting the project Notification Scheme, leaving JEMHC to take over. There are variations, eg leave Jira to do Jira notifications, use JEMHC to do email only user notifications.

Here is an example Project > Notifications with no scheme set:

JSM Projects

Service Management projects have both Jira (agent) notifications and customer level notifications. Disable the Project Notification Scheme to stop Jira user notifications, and deselect the Customer notifications (per event) to prevent customer notifications, to leave JEMHC in charge of notifications:

Testing outbound notifications

Recent outbound notifications can be reviewed through: Auditing > Outbound Messages, you can see the outbound message configuration tests sent using ▸ ping.

The Auditing > Events view shows the webhook events sent by Jira, and indicates whether they were handled or not.  Any Jira issue actions that trigger events matching the selected notification mapping(s) will be shown in the Events view:

Shortly after that (about a minute) the notification will be sent. The audit report for the sent outbound notification can be found in the Auditing > Outbound Messages view (The same location the outbound message ping configuration was found):

By default JEMHC will track all recent inbound and outbound notifications, retaining content of email in full in encrypted form within the database, for all Projects scoped in your notification mappings.  At your option, you can opt-out of this retention, but diagnosing any formatting or processing issues will be much harder!

About the Workaround User

The Workaround User is required in order to lookup users, and to do some configuration time validation of some settings, such as validating a user is assignable in a project.  

1. The credentials supplied in JEMHC > Workarounds > User Lookup must have the Jira Global Permission BROWSE_USER, inherited through a group membership.

2. The related user must also be in the Administrator role in the project, typically, this would mean a user in the administrators group.

3. The related user must also have Application Access in order to look up issues in the Lookup User Tester.

When everything is valid, setting a Username and a test Project, will result in confirmation:

See Workarounds for how to generate an API token.

About Atlassian ID

Users created within Jira Cloud must now be validated as real users, this means that a valid email address will need to be provided during user creation. To create a user for the workaround user for example, follow the steps below:

• Within Jira User Management press "Create User"

• On the screen that follows, enter a valid email address, username and full name. To avoid creating an email account for the setup of the workaround user, you can set the email address as an aliased address of your own email account. With an example email account of yourusername@gmail.com you could use yourusername+workaround@gmail.com where "workaround" is the username of the created workaround user. Using the +workaround address will create a unique address for the workaround user that will actually be an alias of your own email account. Emails sent to the +workaround user will arrive in your inbox.

• Within the "Additional Options" sub-menu, make sure "Send invitation email" is ticked.

• Press "Create User"

• An email will now be sent to the email address defined in user creation, click the link in the email to activate the account and set a password for the user.

• User account is now created and can be configured as the workaround user.

Template Customization

If you are familiar with JEMHC (DC) the cloud edition has the same ‘kinds’ of features and names for the features, but they are implemented differently.

Events (where change data comes from that drives notifications)

There are limited events in Cloud, effectively Created and Updated templates exist. We suggest trying to get used to that rather than attempting to generate the complex multi-event structure of a Jira Notification Scheme (in terms of numbers events).

Webhooks

All Jira changes generate webhooks, JEMHC will drop any that are not for projects that you have a Notification Mapping for, so be sure you create a JEMHC > Notification > Email Notification Mapping. Once you do you will start to see data in JEMHC > Auditing > Events, this data represents ‘all’ the data we have access to within the template at render time.

The Event view has a there is an option to generate aPreview Context, effectively saving the (short lived) Event data, that can then be seen in JEMHC > Notifications > Preview Contexts. These preview contexts will be used later during template editing to allow preview of the rendered template.

Where is the data

The data (JEMHC > Auditing > Events & Preview Contexts) is JSON, it is loaded as an object in the template, get familiar with JSON, and the webhook structure to understand how to drill into it, we have a page to provide a starting point for this:

Manipulate webhook data in notification templates

Working with Template Sets

Template can be created without a Notification Mapping etc, or even a Preview Context, but it really helps. There are system ‘themes’ containing sets of templates for Create/Update, with their own CSS and velocity macros. Look at the themes, figure out which you want, create a template based on the theme you want to use, then your customization journey begins!

Remember that when editing an UPDATE template you can only pick an UPDATE preview context …

• Template Sets

• Themes

Selecting those templates in JEMHC Notifications config

Once Templates have been ‘done’ (tested at preview level) to be live they need to be picked in the Email notification mappings .

Current Limitations

There is only one template per event type per Project. If you want to provide ‘variants’ you need to build that functionality into the Template.