Integrate EMQ with JEMH

Owned by Mike Harrison
Last updated: Jun 29, 2020 by Andy Brook [Plugin People] (Unlicensed)
4 min read

What is EMQ?

The Enterprise Mail Queue for JIRA (or EMQ for short) is a system for reducing JIRA notification traffic by condensing emails into one or more digests.  For more information on EMQ, please check out the EMQ wiki.

With JEMH (Enterprise Mail Handler) 2.1.0 (for JIRA 7.3+) and EMQ (Enterprise Mail Queue) 1.5.0+, the two add-ons are able to work together to provide a set powerful features for both inbound and outbound JIRA communications.

How do they work together?

Issue Events

When JEMH receive an issue event (configured through JEMH > Notifications), it is then passed on to EMQ's API for notification email digestion.

EMQ will determine what queue should be used by default, but since JEMH 3.3.9+ and EMQ 1.9.11+ , it is also possible to drive the queue selection from an issue custom field containing the EMQ queue ID (an integer), this allows for scenarios where the Issue can drive notifications to be sent through a specific EMQ queue. Configure this

Adhoc / Postfunctions

Are not current supported, its a work in progress

Prerequisites

  • JIRA Core/Software/Service Desk 7.3.0 (or newer)

  • JEMH 2.1.0 (or newer)

  • EMQ 1.5.0 (or newer)

Configuration Steps

Is JEMH currently installed?

In order for this integration to work smoothly, it is currently required that EMQ is installed before JEMH is installed.  Do not worry if you already have JEMH installed - you can safely un-install JEMH via the JIRA add-ons section whilst still keeping your JEMH configuration intact.

Setting up EMQ

First, you will want to find and install the EMQ add-on from the Atlassian Marketplace.  Make sure that you install at least version 1.5.0 and are using a compatible JIRA version!

Configure EMQ

Access EMQ by either pressing full stop  on your keyboard followed by "emq" and pressing Enter/Return, or going to Add-ons>Manage add-ons and choose Configure when EMQ is selected.  EMQ needs to be configured to digest issue event notifications.  Follow this simple guide to set up EMQ.

Once set up navigate to EMQ > General > Event Source and change to Event Source to either JIRA and API or API (API is needed for EMQ to process JEMH notifications).

Setting up JEMH

Once EMQ is installed and configured, you should then install the JEMH add-on.  Again, make sure you install at least version 2.0.12.

Configure JEMH

If this is your first time installing and setting up JEMH, you will want to consult our extensive wiki library for information.  Access JEMH by either pressing full stop on your keyboard followed by "jemh" and pressing Enter/Return, or going to Add-ons>Manage add-ons and choose Configure when JEMH is selected.  A great page to start on is configure JEMH from scratch.

If you have re-installed JEMH after having it previously installed, your old configuration should have been reinstated.

Go to JEMH's Event Listener section.  Scroll down the page until you see the Transports sub-section.  Under the Email notification transport, you will see where JEMH's Non-JIRA user and JIRA user notifications are configured.  If you have not previously configured the Event Listener to notify Non-JIRA and JIRA users, please follow this wiki guide: Use Event Listener for Issue Events.

Enabling digestion for an Event Listener mapping

Create or Edit an Event Listener mapping for either Non-JIRA or JIRA Users, depending on your goals.  You will then be presented with the JEMH > Notification mapping edit screen.  If EMQ and JEMH are successfully integrated, you should see an extra configuration settings present on the screen.

(1) EMQ Digesting will drive custom notifications sent by JEMH through EMQ for digesting or delivery through dedicated SMTP Servers.

(2) EMQ Queue customfield Selector allows the selection of a custom field (typically single line text) that will be checked for a numeric ID representing an EMQ Queue ID. This allows fine grained control over which queue (and which SMTP server) is used on a per issue basis (NOTE: minimum JEMH required is 3.3.9 and EMQ 1.9.11 - check compatibility with your Jira!)

(3) EMQ Jira recipient blacklist add csv recipient addresses (regexp capable) to exclude from digesting, causing matches to be sent default Jira mailserver

(4) EMQ Jira recipient whitelist add csv recipient addresses (regexp capable) to include for digesting, causing matches only to be sent through EMQ. Where both are excluded, the blacklist exclusion applies within the whitelist.

 

If you are configuring digestion of non-JIRA user notifications, make sure that you have entered the custom fields that JEMH is populating with email addresses with under the setting CSV email Custom Fields.  The configuration required to get these custom fields populated can be found in the configure JEMH from scratch guide.

Press Submit to save changes.  You should now see that the mapping's status shows that email notifications are to be digested:

Troubleshooting

EMQ not digesting JEMH's notifications? First, check the JEMH Diagnostics page.  Here, you will see the current availability of the EMQ API extension.  As you can see in the image below, in this case the EMQ add-on license has expired or is invalid: