Introduction

This page is a guide for setting up JEMH for basic incoming email processing and outbound event notifications. This guide attempts to keep things simple - for information on the many advanced feature of JEMH, a great place to start looking is the How Do I.... section.

The following diagram illustrates the basic Jira mail handler system.  Jira users can send emails to Jira which are then used to create and comment on issues via its own mail handler.  As part of creating issues, events are fired that are picked up by the Jira Event Listener. This listener uses the project's configured Notification Scheme in order to trigger notifications.

When using JEMH, the general flow is similar, but it takes over processing.  Users (with or without Jira user accounts) are able to send emails to JEMH's mail handler. It picks them up and creates or updates issues with a wide array of powerful features. Jira will then fire issue events as a result of the actions made via email processing. If JEMH's Event Listener is enabled it will detect the fired event.

Install the add-on

The easiest way to install JEMH is via Jira's built-in add-on management system (UPM). Go to Jira Administration > Manage apps and select Find new apps.

Open

Open

Search for "JEMH" and an Install button will be displayed. Clicking this button will begin the installation process.

Alternatively, the add-on can be installed manually by uploading a version downloaded from the Marketplace version history page.

Add a license

In order to use JEMH, a license must be present.  A free evaluation license for JEMH can be generated by doing the following:

• Access JEMH via Jira's Quick Operations menu

  , or by going to Jira Administration > Manage apps > Configure JEMH.
  
  

  
  
  
  

• Go to the Licensing tab and from the Shop Form, select Free 30day evaluation. Follow the prompts and enter a valid email address - this is where the license key will be sent.
  
  

   

  
  
  
  

• Check your mail, the license key should be delivered almost immediately. If you don't receive anything after 30 minutes, check you spam folder and that the entered address was correct. As a last resort, use the 'by Email' link and we will contact you with a key personally. When you do get a key, it should like similar to this:
  
  

• Copy the license key text, ensuring that the leading and trailing <JEMHLicense>...</JEMHLicense> tags are also copied.

• Paste the key into the License Entry form and click submit

• The Licensing page should now show that your license has been activated (as below) and the full JEMH navigation menu should show.
  
  

Update the JIra project Notification Scheme

When Jira projects have a Notification Scheme set, it will cause Jira to send emails which may duplicate notifications sent by JEMH. To prevent this, simply deselect the Notification Scheme in the Jira project.

Create a Jira Custom Event

Issue creation happens in two phases due to limitations in Jira. In the first phase, an issue is created along with custom fields. In the second phase, watchers and attachments are added.  A consequence of this is that non-Jira notification recipients would not see attachments that were added when the standard issue created event is fired.  To work around this, a Custom event filter script is needed to allow JEMH to trigger notifications during creation.

See https://confluence.atlassian.com/display/JIRA/Adding+a+Custom+Event

Example custom event:

Stopping Duplicate Notifications

After enabling a custom event and enabling JEMH notifications, JEMH will actually sent two notifications. The first in response to Issue Created, and  the second due to Custom Event. You would normally want to inhibit the notification when it was driven by JEMH, rather than an interactive user. The suggested approach is to set a Custom Field default value on Create to identify the source as JEMH, this Custom Field value can then be detected int the JEMH notification section and used to filer/stop the Issue Created notification. See Enable Issue Created Notification for both Portal and JIRA Email Users (and prevent duplicate notifications).

Enabling Attachments and Inline images

1. Disable JIra's Notification Scheme (To prevent duplicate notifications).

2. Enable Include Attachments in Notifications, Inline images and Attach inline images.

Update the Jira Notification Scheme

The notification scheme needs to be updated when Jira users may be involved and JEMH is used to notify them. From the Jira Administration screen, select the 'Notifications' operation on the appropriate scheme.

Replicate the roles related to the ISSUE_CREATED event for the new Custom Event (e.g. Reporter, Current Assignee, All Watchers). The end result should look like the below.

Create custom fields for Non-Jira user details

When non-Jira users (email only users) communicate with Jira, their addresses need to be stored on the issue via a custom field.

Create a TEXT (unlimited) type custom field to store this information in.  It is recommended that the naming makes it clear what it is used for (e.g. 'Email Users', 'Sender Name' and 'Sender Email Address').

Create a JEMH Profile

Profiles are containers for email processing configuration - essentially they tell JEMH what should happen when an email is processed.  First, create a new Profile.  Then, at the minimum you will want to make the following changes.

Set a default project mapping

An important part of email processing is deciding which project an email is destined for.  JEMH uses Project Mappings to make this decision.  For now, lets just set a default mapping that will determine the project that emails will go to.  Later, additional mappings can be added that allow project selection to be based on email criteria.

From version 2.5.0, a default mapping is always present. In this case, click the edit icon ().  If there is no default mapping, click the "New Project Mapping" link.

Select a project from the drop-down list, and (if it is not already the default mapping) enable the Is Default Mapping setting.

While still editing the project mapping, select an Issue Type to be the default.  In general, it should be an issue type that is valid for the project specified.

Set a default reporter

If you plan on processing emails from Non-Jira users (users without a Jira account) you will need to set a default reporter user.  This user will be used to create or comment on issues on behalf the email sender.  You may wish to create a user account specifically for use by JEMH if you do not want a "real" user getting notifications later.

The default reporter (and Jira account holders who may also interact by email) will require several permissions in the project, especially if Profile > Security > Strict Jira Permissions is enabled (it is by default).  The following would be required for a basic scenario:

• CREATE_ISSUE

• EDIT_ISSUE (to set custom fields)

More privileges will be required to support advanced features like Directives, e.g. setting a DueDate requires SCHEDULE_ISSUES.  Be aware that the permission scheme you are using for your project could be being used by other projects.

Edit the User section in the profile.  You will then be able to select a user for the setting Default reporter user name.  Submit the form when done and you should see the following in the overview:

Set a catch email address

Edit the Email section of the profile and find the setting Email Selection > Catch Email Address.  Set this field with your incoming mailbox address.  This is good practice as it is used by JEMH to stop email loops.  If there are multiple addresses that emails are being sent to for the mailbox, you can use a regular expression to match them all.

Select custom fields to hold Non-Jira user details

1. Under Profile > Email > Sender Processing > Non-Jira user, select the custom field to hold the email sender's personal name (if present) for the setting Non-JIRA user sender name to Text custom field.  Set Non-JIRA user sender address to Text custom field with the other custom field created earlier (Sender Email Address as an example).
   

2. For the setting Profile > Email > Addressee Processing > Addressee Handling select both toCustomField and toWatcher options.  This routes Jira users to watchers and non-Jira users to custom fields.
   
   

3. Set Assign non jira-user Email to Text CustomField with the custom field created earlier (Email Users for example).
   
   

Set the custom issue created event to fire

As mentioned earlier, you will want to fire a custom "issue created" event when JEMH creates an issue in order for Non-Jira user notification recipients to see things like issue attachments.

Go to the Profile > Notifications section and select the custom event created earlier for the setting On Create Custom Event.

Configure JEMH Event Listener for outbound notifications

Separate to the incoming email processing, the Event Listener is JEMH's system for generating notifications.  It detects events fired by Jira (or JEMH) and determines what action to take.  It needs to be enabled and configured to listen to specific projects (a performance optimization).  This configuration governs who gets what notifications and allows customization of any/all notifications.

Enable the Event Listener

1. Navigate to the JEMH Configuration screen and select the Notification tab.
   
   

2. Go to Issue Events section, edit, and check the 'Enable' field.
   
   

   
   Select the Non-Jira custom fields created earlier for the setting Fallback email Custom Fields.  Setting it as the fall-back just means it doesn't need adding for each mapping later.

3. Submit the changes, at which point the Issue Event Listener is enabled but is as yet not listening to any specific projects.

Create a Notification Project Mapping

The Project Mapping allows custom notification behaviour on a per-project basis.  Each event needs to be associated with a Template that is used for notification.  Where DEFAULT is selected, this means the internal Jira templates are used.

Go to Transports > Email > Non-Jira notifications and click New Project Mapping.  Configure the Non-Jira user section of the Notification mapping.  Then, proceed to do the same for Jira user notifications.

With the Notification mapping configured, now is a good time to check one last time that the target project(s) does not have a notification scheme enabled.  Newer versions of JEMH will let you know with a marker on the mapping:

Validate configuration using a Test Case

Before starting to process real emails, you will want to confirm that you have configured JEMH as you want.  JEMH's Test Case feature that lets you test real emails without having to connect to a mail source.

Link a profile to an incoming mail source

When you are ready for JEMH to start processing emails from an external mail source, the profile needs to associated with an incoming mail source.  To do this, you will first need to have a mail server defined in Jira.

Add an incoming mail server

Go to Jira Administration>System>Incoming Mail, and select Add POP/IMAP mail server.
 

Enter your target mail server's connection details.  If your mail service provider is listed under Service Provider, select it and some settings will be set for you.  Once done, select Test Connection to validate your settings.  This set up process is also covered by Atlassian here (step 1 only): https://confluence.atlassian.com/display/JIRA/Creating+Issues+and+Comments+from+Email.

Add a JEMH Mail Handler

1. With an inbound mail server defined, select Add incoming mail handler.
   
   

2. Provide a name for the handler, and select the mail server that you previously configured. Make sure that the handler setting is set to Enterprise Message Handler for Jira.
   
   

3. Click Next, and then select your JEMH profile from the list that is shown.  Press Submit to save your configuration. 
   
   

   
   From this point onwards, any unprocessed email found in the mailbox that has a "to" address matching your profile's catch email address(es) will be processed.

Related articles