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.

Jira's own Event Listener will try to send notifications to Jira users. If you are planning on having JEMH do this instead, you will not want that to happen. In order to prevent Jira doing so, the Notification Scheme should be removed from the Jira project itself by deselecting it via the Jira Project Administration view. This will prevent duplicate notifications from being sent.

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.

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

  Open

  

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

  Open

  
  Open

  

  
  
  
  

• 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.
  
  

  Open

  

   

  Open

  

  
  
  
  

• 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:
  
  

  Open

  

• 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.
  
  

  Open

  

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.