Send notifications for Issue Events

Introduction

The Event Listener is the main system for generating issue event notifications in JEMH. As the name suggests, it "listens" for events that occur in Jira and then (if configured) creates notifications for those events. Its extensive feature-set allows complete control over:

  • what projects should JEMH listen to for events

  • what events types should notifications be made for

  • who receives the notification

In combination with the Template Sets system, the Event Listener can be used to send customised notifications for events.

Before starting

Check that your target Jira project does not have a notification scheme set at project settings level.  This will stop Jira from sending duplicates of the notifications that JEMH will be sending.

  1. Go to Jira>Your Project>Project Administration

  2. Click Notifications

  3. Click on Actions and choose Use a different scheme




  4. Select None from the drop-down menu and then click Associate to save the change




  5. If you plan on sending issue creation notifications to non-Jira users, you will want to make sure that you have created a custom event (see Atlassian Jira - Adding a Custom Event for more).  When creating the event for the first time, it is advisable to select the Issue Created Template as the default template to start with

  6. Go to JEMH>Profile>Configuration>Notifications and click Edit

  7. For the setting On Create Custom Event, choose the custom issue creation event.  This will cause the event to be fired on issue creation which as explained later is important for notifying of issue creation in certain scenarios.

  8. A typical set up for the relevant settings here may look like this:


     On Comment Event Behaviour : this setting will drive JEMH to always fire an ISSUE_COMMENTED event when a comment is added - mostly JEMH would fire ISSUE_UPDATED as custom fields get manipulated.

Initial configuration

Some settings for the Event Listener are global and are not tied to specific projects/people.

  1. Go to JEMH > Event Listener, located via the main JEMH navigation and edit the ISsue Event section:

  2. Enable the event listener:

  3. Fallback email Custom Fields is used to define any custom fields used for email addresses that you would have set up during first configuration of JEMH





  4. The Email Storm Prevention section can be used to define a notification number limit.  If the limit is exceeded, a certain action can be triggered.

    • Scheme Entity Limit  -  The number of notifications per event, per notification scheme entity (e.g. Watcher, Group).  The default is 0, which essentially disables the prevention system

    • Scheme Entity Limit Action  -  The action to be taken when limit is met

      • capAndNotifyLead  -  allows notifications to send up to the previously mentioned limit for a scheme entity, and send a warning notification to the project lead

      • sendAllAndNotifiyLead  -  allows notifications for a scheme entity to send regardless of if doing so will break the limit.  At this point however a warning notification is sent to project lead

      • sendNoneAndNofifyLead  -  stops any notifications from being sent for a scheme entity if doing so will break the limit.  Project lead is notified of this

    • Scheme Entity Limit Template  -  A custom Ad-Hoc template can be chosen when notifying the project lead



    Example Configuration




  5. Jira's Outgoing Mail should be enabled in order for subsequent notifications to be sent


Configuration of Jira User Notifications

This section will focus solely on the set up of the Event Listener to send issue event notifications to Jira users.  For Non-Jira user notification set up, see Non-Jira User Configuration on this page.

  1. Click the Jira notifications tab under Transports>Email





  2. If you have already created a mapping when setting up Non-Jira User Notifications, click Edit 

    to the right of the mapping. Otherwise, Click New Project Mapping to start setting up a new project specific configuration

Mapping Specific Settings

Setting

Details

Setting

Details

Project Keys

Common to both Jira and Non-Jira notifications this field identifies what Project issue events should be handled within the current notification mapping.

The format of this can be a mix of one or more (comma separated)

  • Project keys (e.g. AAA) to allow per-project specific notification mappings

  • Regular Expressions (e.g. .* ), this allows one expression to match all or a subset of projects

Notification Scheme

The notification scheme that should be followed for notifications to Jira users in this notification mapping

Exclude Subject Prefix

Allows you to remove the Subject Prefix (defined in - Outbound SMTP Mail Server) from outbound notifications

Require BROWSE_ISSUE

Allows notifications to only be sent to Jira users that have BROWSE_ISSUE project permission

Notify Me Condition

Defines how the event listener should decide if a user that triggered an event should be notified also

  • userPreference  -  only notifies initiating user if their user profile it set to do so

  • always  -  always notifies the initiating user of event

  • forSelectedEvents  -  notifies initiating user for events specified from Notify Me Events list

Notify Me Events

When forSelectedEvents is chosen for condition, selected events in list will result in notification for initiating user

Group Restriction

The user group that is used by Group Restriction Condition to specify who is notified.  See also: Event Listener Group Restriction and Conditions

Group Restriction Condition

How the specified group is used to specify who is notified.  See also: Event Listener Group Restriction and Conditions

Included Mail Headers 

SMTP headers containing issue properties can be added to notifications.  This allows the recipients of the mail to sort by these properties

Include Attachments in Notifications 

Attachments added in the last 10 seconds from event time can be chosen to be added to messages

Inline Images

Images referred through wiki mark-up in the content can be chosen to be displayed in-line

Store Notification History

If enabled, notifications sent by JEMH through the Event Listener will be tracked in the Notification History Issue Tab for issues in that project.  See Enable the Notification History Issue Tab for more information

Event Selector and Filter script

Allows velocity script to be used to enable logic to be applied in order to change how a notification is handled.  Please see Change the EventID or Ignore an Event for more information

Treat Events with Comments As

When an issue event has a comment tied to it when it is fired, the event listener can be configured to notify of this event as if it were a different issue event (e.g. all events as ISSUE_COMMENTED)

Require a comment to notify 

Enabling this prevents issue events from resulting in notifications unless a comment is also contained within the event

Bcc Addressees

Email addresses added here are added to outbound notifications as Bcc

Custom From: Custom Field

Allows a custom field to provide the From address used in notifications

Custom From: Address

Allows a specified email address to be used as the From address in notifications

Custom From: Personal Custom Field

Allows a custom field to provide the Personal name of the From address in notifications

Custom From: Personal

Allows a specified name to be used as the Personal name of the From address in notifications

Custom Reply-To: Address Custom Field

Allows a custom field to provide the Reply-To address used in notifications

Custom Reply-To: Address

Allows a specified email address to be used as the Reply-To address in notifications

Custom Reply-To: Personal Custom Field

Allows a custom field to provide the Personal name of the Reply-To address in notifications

Custom Reply-To: Personal

Allows a specified name to be used as the Reply-To Personal name in notifications



Event Template Selection

This section is where the user can decide what events should result in notification, and what template should be used.  If custom templates have been created, here is where they would be selected.

Leaving a template selection blank for an event means that the event listener will not initiate notifications for that event type.  The below example shows the Issue Moved event having notifications disabled:

Example of Issue Moved event having notifications disabled

From version 1.7.0, most custom fields are set during the ISSUE_CREATED transition (before, custom fields were not present).  Two significant fields that are not set during this transition are Watchers and Attachments.  In order to allow the Event Listener to send to watchers or include attachments, an additional custom Issue Created event is required.  Therefore, a typical Event Listener template set up for Jira user notification may look something like this:

Configuration of Non-Jira User Notifications

This section will focus solely on the set up of the Event Listener to send issue event notifications to Non-Jira users.  For Jira user notification set up, see Jira User Configuration on this page.

  1. Click the Non-Jira notifications tab under Transports>Email





  2. If you have already created a mapping when setting up Jira User Notifications, click Edit 

    to the right of the mapping. Otherwise, click New Project Mapping to start setting up a new project specific configuration

Mapping Specific Settings

Setting

Details

Setting

Details

Project Keys

Common to both Jira and Non-Jira notifications this field identifies what Project issue events should be handled within the current notification mapping.

The format of this can be a mix of one or more (comma separated)

  • Project keys (e.g. AAA) to allow per-project specific notification mappings

  • Regular Expressions (e.g. .* ), this allows one expression to match all or a subset of projects

Notification Format

The format (text or HTML) of the notification to be sent to non-Jira users.  The relevant text or HTML entry on a template will be used.

Included Mail Headers

SMTP headers containing issue properties can be added to notifications.  This allows the recipients of the mail to sort by these properties

Exclude Subject Prefix

Allows you to remove the Subject Prefix (defined in - Outbound SMTP Mail Server) from outbound notifications

Event Selector and Filter script

Allows velocity script to be used to enable logic to be applied in order to change how a notification is handled.  Please see Change the EventID or Ignore an Event for more information

Treat Events with Comments As

When an issue event has a comment tied to it when it is fired, the event listener can be configured to notify of this event as if it were a different issue event (e.g. all events as ISSUE_COMMENTED)

Require a comment to notify

Enabling this prevents issue events from resulting in notifications unless a comment is also contained within the event

Assert Security

Enabling this prevents comments with group or role level restrictions from being being sent to non-Jira users in notifications

Include Attachments in Notifications

Attachments added in the last 10 seconds from event time can be chosen to be added to messages

Max Attachment Size

The maximum size of a single attachment to add to a notification

Max Attachment Total Size

The total maximum size of all attachments to add to a notification

Inline Images

Images referred through wiki mark-up in the content can be chosen to be displayed in-line

Filter Sender

Enabling this stops a non-Jira sender from getting notified of an event that they initiated

Store Notification History

If enabled, notifications sent by JEMH through the Event Listener will be tracked in the Notification History Issue Tab for issues in that project.  See Enable the Notification History Issue Tab for more information

CSV email Custom Fields

Custom fields specific to the project(s) listed in the mapping can be given here to supply non-Jira user email addresses.  If not used, the top-level Fallback email custom fields will be used

Bcc Addressees

Email addresses added here are added to outbound notifications as Bcc

Custom From: Custom Field

Allows a custom field to provide the From address used in notifications

Custom From: Address

Allows a specified email address to be used as the From address in notifications

Custom From: Personal Custom Field

Allows a custom field to provide the Personal name of the From address in notifications

Custom From: Personal

Allows a specified name to be used as the Personal name of the From address in notifications

Custom Reply-To: Address Custom Field

Allows a custom field to provide the Reply-To address used in notifications

Custom Reply-To: Address

Allows a specified email address to be used as the Reply-To address in notifications

Custom Reply-To: Personal Custom Field

Allows a custom field to provide the Personal name of the Reply-To address in notifications

Custom Reply-To: Personal

Allows a specified name to be used as the Reply-To Personal name in notifications

Event Template Selection

As previously mentioned in the last section, here is where the user decides what events are notified and what templates are used.

At the point that the Issue Created issue event is fired, the non-Jira address custom fields are not set.  This means that they will not be notified.  Therefore, if you want issue creation notifications to go to these users you must use a custom issue creation event, and configure JEMH to fire this event when Issue Created is fired.  Configuration of this was mentioned in the first section of this wiki, Prerequisite Steps.

A typical template selection for non-Jira users may look something like this.  Notice that the issue created event has no template, so it will not be used:

View current template selection for mapping

In order to see what notification templates are currently selected for an Event Listener mapping, either expand the project mapping using the expand/collapse icon  (in old versions) or as from https://thepluginpeople.atlassian.net/browse/JEMH-5146 click the "view active templates" icon  found to the right in the actions group for each mapping.

Testing Your Event Listener Configuration

After you have configured your Event Listener as you want, it is advised to test that notifications are being created as you would expect.  This could be done by sending an email from an email application to your JEMH address, or by using the built in test case functionality.  For more information on using JEMH test cases, please see our wiki article on how to Use a Test Case.

Limit Attachment Size

The attachment size and total attachment(s) added to a notification can be limited to prevent outbound notifications become to large. The field ‘Max Attachment Size' is used to limit the size of individual attachments addeded to notifications whereas 'Max Attachment Total Size' will prevent new attachments from being added to a notification if the additional Attachment would increase the total to above the 'Max Attachment Total Size'.

The example above would only allow Attachments 1MB or smaller from being added to a notification and a total limit of 10MB

Currently this configuration is only accessible through the Non-Jira Notification Mapping configuration, however this will affect both Jira and Non-Jira user notifications for the project. A current open improvement will address this issue: https://thepluginpeople.atlassian.net/browse/JEMH-7901

Issue Creation Event Template Selection Guide

This table details what event template selection settings you need in order to notify a particular person of issue creation.  Since JEMH-280 was fixed, non-Jira users can be notified by the standard Issue Created event, however certain things such as attachments and watchers would not be included in the notification, therefore it may be more beneficial to use the custom Issue Created event (see below table).

Issue Creation Method

Jira Users to receive notification?

Non-Jira Users to receive notification?

Required Event Template Selection

Issue Creation Method

Jira Users to receive notification?

Non-Jira Users to receive notification?

Required Event Template Selection

Interactive



  • Watchers are added to issues post-creation, therefore will not be notified.  Reporter and Assignee can still be notified if configured correctly however.

  • When creating an issue interactively, only the standard Issue Created event is fired.

Non-Jira User Event Template Selection:

  • Template selected for standard Issue Created event

  • No template selected for your Custom Issue Created event

Jira User Event Template Selection:

  • Template selected for standard Issue Created event

  • No template selected for your Custom Issue Created event



Interactive



  • When creating an issue interactively, only the standard Issue Created event is fired.

  • These settings are only applicable if the email sender email address custom field is populated at create time by the interactive user.

Non-Jira User Event Template Selection:

  • Template selected for standard Issue Created event

  • No template selected for your Custom Issue Created event (event not fired during interactive issue creation)

Jira User Event Template Selection: N/A

Email

Non-Jira User Event Template Selection:

  • No template selected for standard Issue Created event

  • Template selected for your Custom Issue Created event

Jira User Event Template Selection:

  • No template selected for standard Issue Created event

  • Template selected for your Custom Issue Created event

Watchers

Like custom fields, the watchers field is not set when the Issue Created event is fired.  In order for watchers set at creation to be notified, a custom Issue Creation Event is needed.



Email

Non-Jira User Event Template Selection: N/A

Jira User Event Template Selection:

  • No template selected for standard Issue Created event

  • Template selected for your Custom Issue Created event

Watchers

Like custom fields, the watchers field is not set when the Issue Created event is fired.  In order for watchers set at creation to be notified, a custom Issue Creation Event is needed.



Email

Non-Jira User Event Template Selection:

  • Template selected for your Custom Issue Created event

  • No template selected for standard Issue Created event

Jira User Event Template Selection: N/A

Include issue properties as email headers in Event Listener notifications

Jira sends a lot of email notifications, it may be desirable to filter these notifications in your email client based on properties of the issues that generated the notifications. JEMH's Event Listener is capable of appending headers to email notifications which contain certain issue properties, email clients can then filter Jira email notifications based on these headers.

Issue property mail headers can be configured within an Event Listener Project Mapping via the Included Mail Headers section, the selected issue properties will then be appended as headers in email notifications which will be prefixed with X-JEMH-DATA:

Event Listener Project Mapping Configuration

Event Listener Email Notification Header Example

Event Listener Project Mapping Configuration

Event Listener Email Notification Header Example



1 2 3 4 X-JEMH-DATA-ISSUETYPE: Bug X-JEMH-DATA-PROJECTKEY: TP X-JEMH-DATA-ISSUEEVENTID: 6 X-JEMH-DATA-STATUS: To Do





Issue property mail headers can be configured independently for both non-Jira and Jira recipients via the associated event listener project mapping tabs for each type of user.