Setup JEMH Notifications for Jira, and Email Only users
Summary
This page details how to setup basic JEMH’s Notification configuration from scratch, to allow for Email Only Notifications, Jira User Notifications, and to include Attachments in both. This page also demonstrates how to get around pitfalls related to Jira’s two phase Issue creation process.
This page is targeted towards JEMH 6.0.x and above, and specifically refers to new UI elements introduced in version 6.0.0.
For older versions of JEMH (5.x and below) please see these pages instead:
Before you begin
Before you configure JEMH’s Notifications we assume that you already have a basic setup for Jira and JEMH. Here are some things to look out for which you should do before continuing.
Jira Project Notifications disabled
To prevent duplicate Notifications we expect Jira Notifications are disabled, for the Project you would like JEMH to manage Notifications for. This is done by setting your Project Notification Scheme to ‘None’:
JSM Customer Notifications must be disabled separately. Unfortunately, each Customer Notification must be disabled individually, as there is no Project wide option to disable JSM Customer Notifications:
Jira Notification Scheme for Project exists
Whilst we have just disabled Jira Notifications, the Jira Notification Scheme is used by JEMH to drive Notifications, by telling JEMH who should receive Notifications for a given Issue Event. See the following for more info:
JEMH Profile Created
We assume you already have a JEMH Profile which is already configured to handle mail. For details on how to setup a JEMH Profiles please see our Quick-start guide:
Within your Profile we expect the following (See the above linked page if any of these are missing):
You have setup Email Only User fields, to allow for JEMH to notify Email Only Users
You have a Default Reporter configured
You have a Default Project Mapping
Getting started
Some background on Jira’s Issue Event system, and Two phase Issue Creation process.
Issue Events
Events drive Notifications in both Jira and JEMH, specifically Issue Event in this scenario. Issue Events in Jira are driven/ triggered via the Workflow configuration. For example a new Issue/Work Item is created, which triggers the Create workflow step, which ultimately triggers an Issue Created event. Apps like JEMH then listen for the events and act accordingly.
Because the Workflow can be configured, it is possible that the Events triggered for a Workflow step may not actually reflect the expected step. For example Jira can sometimes default to ‘Generic Event’ for all workflow steps.
Issue Creation Process
Jira’s creates Issues in a two phase process, where first the Issue is created with ‘Core’ information, and then the Issue is updated with additional information, such as Watchers, and Attachments. Unfortunately, when creating an Issue as a Third party app Jira will trigger the Created event, before the second phase of Issue creation is started. This means that the Issue Event does not contain some information, such as attachments. These are therefore not included in the final Notification.
JEMH’s solution to this problem is to trigger a second Notification, whilst blocking the first to prevent duplicates. This is covered in more detail later in this page.
TL;DR
To fix a quirk in Jira’s Issue creation process, JEMH requires you to perform an additional configuration step for Watchers to be notified, and attachments to be added to Create Notifications.
Prepare Jira for JEMH Notifications
To solve the Issue Creation quirk mentioned previously you will need to create a new Issue Event, and a new Custom Field. We will do this first so you don’t have to go back over the same configuration pages.
Create a new Issue Event
Create a new Issue Event which JEMH will trigger after it has created an Issue, and Attachments, and Watchers have been added to that Issue, the JEMH Post Create Event. The Issue Event should follow the Issue Created Template and should use the same Notification Recipients as your Issue Created Event in your Jira Notification Scheme for our project.
Create a ‘Created Via’ Custom Field
Create a new text Custom Field, adding it to appropriate Screens (it needs to be on the Issue). Name the field something like ‘Created Via’, or ‘JEMH Created by'. This field will indicate if JEMH created the Issue, or if the Issue was created any other way, i.e. through the UI.
Please see the following page for more details on creating Custom Fields:
Set JEMH ‘On Create Custom Event’
Now we have the Event, and Custom Field, we can move to JEMH specific configuration. Set the On Create Custom Event field in your JEMH Profile to your new JEMH Post Create Event. This is found at:
JEMH → Profiles → Configure → Notifications → On Create Custom Event
Create a Custom Field Default for the ‘Created Via’ Custom Field
In your Default Project Mapping for this Profile create a Custom Field Default, which will set the value of your Custom Field every time an Issue is created by JEMH in this Project. This is done at:
JEMH → Profiles → Configure → Project Mappings → Default Project Mapping → Custom Field Defaults → Create Custom Field Default
Chose the Custom Field you created previously
Set the Value to Email
Make sure the Apply Rule is set to Create only
Make note of the Custom Field ID, in the following screenshot the ID is ‘10300’
For more information on Custom Field Defaults please see:
Optional
You can now test this Custom Field Default by sending an email to your mailbox, or running a JEMH Test Case against your Profile. Assuming that the email is valid, you should see that new Issues created by JEMH now have the ‘Created Via’ field set to ‘Email’. For more information about JEMH Test cases please see:
Issue Events
With the Profile configuration finished you can move to the Notifications section. Here you should enable the Issue Event Listener, and set a Privileged User. This configuration is found at:
JEMH → Notifications → Issue Events → Issue Events → Edit
Notification Mapping
JEMH Notification Mappings are JEMH specific configuration for Outbound Notifications on a per Project basis. There are two configurations for each Mapping which share some but not all configuration options. The basic requirements for a working Notification Mapping are:
A Project
A Template mapped to a Specific Event
There are additional fields covered more on the following page:
Non-Jira Notifications (Email Only)
Assuming you want to use JEMH’s Email only Notification feature, navigate to the Notification Mapping section and Create a new Non-Jira Notifications configuration at:
JEMH → Notifications → Transports → Email → Non-Jira Notifications → Project Specific Configurations → Create Notification Mapping
Set initial Configuration
Set the following values for your Non-Jira Notification mapping:
The Project key, or Keys you want this mapping to apply to. This value can be a Regexp if you have multiple Projects this Mapping should apply to
Email Custom Fields: These fields are Custom Fields created as part of your Profile
These Fields will hold the Email Addresses of the Email sender if they are not a Jira User, or any additional recipients who are not Jira Users. This option is used to tell JEMH which fields it should look at in the Issue to find who should be notified.Please note: This is a different Field than the ‘Created Via’ custom field.
Include Attachments in Notifications to true if you want attachments in your Notifications
For more information on these options please see:
Set Template Mappings
Template Mappings indicate which Notification Template should be used for a given Issue Event. No Template selection will mean no Notification for the given Issue Event.
You can configure the Template selection to the needs of your Project, however for this configuration you will need at least a Template selection for:
Issue Created
Your Custom Event (JEMH Post Create)
Jira User Notifications
If you created a Non-Jira Notifications configuration, you should already have a Notification Configuration for Jira-Users which you can navigate to, and edit at:
JEMH → Notifications → Transports → Email → Jira Notifications → Project Specific Configurations → Edit (Pencil icon)
Alternatively, you can create a new Configuration using the Create Notification Mapping button.
Set initial Configuration
Set the following values for your Jira User Notifications mapping:
The Project key, or Keys you want this mapping to apply to. This value can be a Regexp if you have multiple Projects this Mapping should apply to
Set the Notification Scheme to the Notification Scheme for your Project, which includes your custom JEMH Post Create event
Include Attachments in Notifications to true if you want attachments in your Notifications
Set Template Mappings
Template Mappings indicate which Notification Template should be used for a given Issue Event. No Template selection will mean no Notification for the given Issue Event.
You can configure the Template selection to the needs of your Project, however for this configuration you will need at least a Template selection for:
Issue Created
Your Custom Event (JEMH Post Create)
Event Selector Script
The final configuration is shared between both Notification Mapping configuration and is required to prevent duplicate Issue creation Notifications.
Setting this configuration in either the Non-Jira Notifications, or Jira Notifications configuration will apply this to both.
Event Selector Script
The Event Selector Script is a Velocity script used by JEMH before it sends a Notification to identify if it should continue with the Notification, or drop the Event. We will use this script to drop the Issue Created event IF the Issue was Created Via email.
We will drop the event because we know that JEMH will now trigger a second Event, with Watchers, and Attachments which will be processed.
The following Script has been written by us for you to use. You will have to modify the script to include your Created Via Custom Field created at the start of this tutorial.
Script
#set($cf = $customFieldManager.getCustomFieldObject("customfield_YOURCUSTOMFIELDID"))
#set ($cfValue = $customFieldUtils.getCustomFieldValue($issue, $cf))
#if ($issueEvent.getEventTypeId() == "1" && $cfValue == "Email")
$result.setIgnoreEvent(true)
$result.setReason("Stop duplicate")
#else
Its normal, leave alone
#end
See the following example:
Save your configuration and run a Test Notification.
Example Outcome
The following example shows a Jira Issue created via email, and the resulting Notification which includes both attachments:
Note: In addition to the configuration listed above the Notification Format was set to HTML, Inline Images was set to true, and Attach Inline Images was also set to true. All options are available in the Notification Mapping configuration
Jira Issue | Received Notification |
|---|---|
|
|