Setup EMQ for digesting JIRA events
Summary
This How To wiki page will guide you through setting up EMQ to consume events generated in JIRA for digested delivery.
Background: How EMQ works
When users perform issue operations like created/edit/comment/update, events are generated, these events are what drive EMQ, and other components/addons in JIRA. Events are digested using strategies that define how or what the content is that users are notified of. Currently there is just one 'simple' strategy. An Advanced Strategy is planned, which will condense x number of notifications regarding an issue into one summary entry.
Simple Digest Strategy
The Simple Digest Strategy captures all issue events and stores the rendered message (below) in a database, periodically messages are flushed, at which time those events are collated by recipient, and by issue, from which emails are generated until events are consumed or email number limits are reached.
Example Message:
Format of Simple Digest Strategy Notifications:
Delivery
Default action: Digested Delivery
EMQ will dynamically render the notification templates appropriate for a given issue event, this is by default then reduced and stored for digest delivery, shown below:
Per-User customization
Through the users profile, EMQ allows users to opt-out of digesting, and to further customize exactly what is digested and what isn't. As of version 1.2.0, administrators can also enable Per User Digest Delivery Options, allowing users to configure their own email digest schedule if they wish.
Setup for a single project scenario
Configuration can be carried out up until the point events should be digested. To avoid disruption of notifications this should be done during scheduled maintenance. We will now go through an example set up for using EMQ with a single project. The same example can be used for multiple or all projects by
Disable the Project Notification Scheme
By default the internal JIRA Mail Listener also listens to these events, its still not possible to just turn it off (https://jira.atlassian.com/browse/JRA-19957), to stop the JIRA listener from generating notifications, the Project notification scheme needs to be deselected in the Project > Notifications section (it will be re-selected later):
Disable other non-Atlassian listeners from reacting to that project
Other mail / notification add-ons need to be disabled or they will potentially continue to notify users in parallel. For example JEMH has an Event Listener Project Mapping that identifies the project. A this time JEMH is not yet compatible with EMQ.
Define an outbound mail connection
EMQ introduces support for multiple outbound mail servers, this can be done to support internal v.s. external addressing. Follow the Manage Mail Connections page for details.
Define a Queue limited to a Project
EMQ introduces the concept of queues, these are effectively groups of configuration that are all candidates for consuming a given event, a Queue is associated with a given outbound mail server. Follow the Manage Mail Queues page for details.
It is recommended that you select a notification scheme when setting up the Mail Queue in order to help prevent duplicates.
Limit digesting to a given project
When configuring the Queue, add comma separated list of Project Keys (e.g. TEST) to process, in this way you can scope the queue to only digest notifications for one or manage projects. For advanced users, a regular expression could also be used (e.g. .* matches all projects).
As soon as a default Queue exists, it will start processing and storing issue events. Defining the project key will limit what is initially digested
Queue Activation
When a queue is inactive it will not receive events (the default), here are examples of each state:
Inactive Queue | Active Queue |
|---|---|
Validating notifications are being digested
Adding a comment to TEST-1 as follows:
In this issue the Reporter (andy) and Assignee (admin) are determined through the Notification Scheme set in the Queue, to require notifications. These can be traced through the Search Unprocessed Mail History screen shown below, indicating the event was consumed and is ready for digest sending:
Updating another issue is also reflected near real-time:
Commenting on issues in Projects other than TEST will not be listed as they are ignored by the queue.
Pushing the queue
Then, for testing, all digested content can be sent via the Manage Mail Queues screen:
Watching the Search Sent Mail History , the results will be dynamically updated as recipients receive digested notifications, as well as a progress report calculated as a percentage of the users processed.
Flipping back to the Search Unprocessed Mail History screen, it can be seen there are no new results left to process:
Checking the overall Digest History screen the overall flush status is shown:
Email Examples
Simple Content Aggregating Strategy
Did you want inline image fries with that?
If your users make use of wiki mark-up to refer images, EMQ will render them inline too (if enabled).
JEMH can automatically convert inbound HTML with inline images into wiki mark-up!
JIRA user notification vs Non-JIRA user notification
For this default case, each 'Add Comment' link will take the user back to the related issue. When email only (non-JIRA) users are delivered messages (in the future via JEMH), those links will become mailto: pre-seeded with the relevant issue key in the subject for commenting by email.