Setup JEMH Notifications for Jira, and Email Only users

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

Jira Notification Schemes are chosen on a per Project basis. You can set the Notification Scheme for your Project to ‘None’ at: Jira → Project → Project Settings → Notifications → Actions → Select a scheme For more information please see the following page:

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:

JSM Customer Notifications are disabled for a JSM Project at: Jira → Project → Project Settings → Customer Notifications → Edit → Enable

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

  1. You have setup Email Only User fields, to allow for JEMH to notify Email Only Users

  2. You have a Default Reporter configured

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

New Issue Events can be created via the Jira Administration section at: Jira → Administration → System → Advanced → Events → Add New Event For more info on creating events please see: Once the event is created, navigate to the Notification Scheme for your project, and add Notification Recipients to the JEMH Post Create Event. This is done at: Jira → Administration → Issues → Notification Schemes → Notifications

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.

When JEMH creates an Issue, two Issue events are now going to be triggered; Issue Creation, and JEMH Post Create. This will cause two different Notifications for the same action. You could block the standard Issue Creation event, however if a user created an Issue via the UI only the Issue Creation event would run, so you would get no Notifications. JEMH needs a way to know if the Issue Created Event is going to be followed by a JEMH Post Create Event. This Custom field will tell JEMH if it should block, or allow the Notification.

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

The JEMH Profile Notifications configuration screen, showing the JEMH Post Create Event set in the

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

  1. Chose the Custom Field you created previously

  2. Set the Value to Email

  3. Make sure the Apply Rule is set to Create only

  4. Make note of the Custom Field ID, in the following screenshot the ID is ‘10300’

Custom Field Default Creation screen showing the Custom Field 'Created Via' being set to Email

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 with Created Via custom field automatically set to Email

 

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

Issue Events configuration showing the Listener Enabled option set to enabled, and the Privileged User set to the Admin user

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:

  1. A Project

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

Notifications Configuration screen highlighting the Create new Notification button

Set initial Configuration

Set the following values for your Non-Jira Notification mapping:

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

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

    1. Please note: This is a different Field than the ‘Created Via’ custom field.

  3. Include Attachments in Notifications to true if you want attachments in your Notifications

non_jira_notification_mapping_configuration.png

 

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:

  1. Issue Created

  2. Your Custom Event (JEMH Post Create)

Event template selection showing a selected template for the Issue Created Event
Event template selection showing a selected template for the JEMH Post Create Event

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.

Notifications configuration screen, showing the Jira Notifications tab selected, and an existing configuration which can be edited

Set initial Configuration

Set the following values for your Jira User Notifications mapping:

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

  2. Set the Notification Scheme to the Notification Scheme for your Project, which includes your custom JEMH Post Create event

  3. Include Attachments in Notifications to true if you want attachments in your Notifications

Jira Notification Mapping showing the Project Key Set to TES, and the Notification Scheme set to the default Notification Scheme

 

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:

  1. Issue Created

  2. Your Custom Event (JEMH Post Create)

Event template selection showing a selected template for the Issue Created Event
Event template selection showing a selected template for the JEMH Post Create Event

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:

Event Selector Script showing the custom fiekd id highlighted in red

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

Jira Issue

Received Notification

Jira Issue with two image attachments

 

JEMH Notification shown in Email client with both attachments inlined, and included in the email