Send notifications for Issue Events
- Mike Harrison
- Ryan Clifton
- Andy Brook [Plugin People]
- 1 Introduction
- 2 Before starting
- 3 Initial configuration
- 4 Configuration of Jira User Notifications
- 5 Configuration of Non-Jira User Notifications
- 6 View current template selection for mapping
- 7 Testing Your Event Listener Configuration
- 8 Limit Attachment Size
- 9 Issue Creation Event Template Selection Guide
- 10 Include issue properties as email headers in Event Listener notifications
- 11 @Mention notifications
- 12 Related articles
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.
Go to Jira>Your Project>Project Settings
Click Notifications
Click on Actions and choose Use a different scheme
Select None from the drop-down menu and then click Associate to save the change
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
Go to JEMH>Profile>Configuration>Notifications and click Edit
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.
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.
Before starting (Disable JSM Customer Notifications)
Disable customer Notifications through your Jira Project Settings to prevent duplicate notifications to JSM Customers
Navigate to: Jira > Project > Project Settings > Customer Notifications
Edit each notification and de-select the ‘enabled’ checkbox and save your changes
Repeat for all Customer Notifications
Initial configuration
Some settings for the Event Listener are global and are not tied to specific projects/people.
Go to JEMH > Event Listener, located via the main JEMH navigation and edit the ISsue Event section:
Enable the event listener:
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
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
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.
Click the Jira notifications tab under Transports>Email
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 |
|---|---|
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)
|
Blocklist Project Keys | Defines Project Keys that should not use this Notification Mapping. Typically applies when using a Regular Expression to gather the Project Keys. |
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
|
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 |
Attach Inlined Images | If enabled, the Inlined images will also be attached to email. |
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 |
Disable local links | This will disable any links that reference locations that start with the Jira base URL. |
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 |
Filter Mentioned Users | If a comment is present that the notification recipient is mentioned within then JEMH will filter this notification to prevent duplicate notifications. |
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 |
Use System Defined personal | Gathers the rendered Email from value that is defined in “System > General Configuration > Email From” and will use this as the Personal. |
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 |
Use Request Participants | Notifies the Request Participants in addition to recipients in the Notification Scheme. No duplicate notifications will occur. Note: This will only send Comment notifications. |
Notify participants of events without comments | This will also notify Request Participants of events that do not contain a comment. |
Use Organizations | Notifies members of Organizations who have been involved on the issue and has enabled notifications within the Customer Portal for that particular issue, in addition to recipients in the Notification Scheme. No duplicate notifications will occur. |
Use Customer Notification Templates | Allows separate Notification Template selection for customer users. If enabled and no template is selected for an event, the customer will not be notified. |
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:
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.
Click the Non-Jira notifications tab under Transports>Email
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 |
|---|---|
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)
|
Blocklist Project Keys | Defines Project Keys that should not use this Notification Mapping. Typically applies when using a Regular Expression to gather the Project Keys. |
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 |
Attach Inlined Images | If enabled, the Inlined images will also be attached to email. |
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 |
Disable local links | This will disable any links that reference locations that start with the Jira base URL. |
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 |
Use System Defined personal | Gathers the rendered Email from value that is defined in “System > General Configuration > Email From” and will use this as the Personal. |
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 added 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 |
|---|---|---|---|
Interactive |
Non-Jira User Event Template Selection:
Jira User Event Template Selection:
| ||
Interactive |
Non-Jira User Event Template Selection:
Jira User Event Template Selection: N/A | ||
Non-Jira User Event Template Selection:
Jira User Event Template Selection:
| |||
Non-Jira User Event Template Selection: N/A Jira User Event Template Selection:
| |||
Non-Jira User Event Template Selection:
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 |
|---|---|
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.
@Mention notifications
JEMH deliberately ignores issue event notifications for users who are @mentioned in comment content. This is because Jira sends specific notifications for this outside the standard IssueEvent pattern - processing notifications for the user would create duplicates, and we would be forever answering support queries about ‘duplicates’.
Within the Notification Mapping you are able to stop JEMH from sending comment notifications when it contains a mention so that duplicate notifications are not sent. This requires Filter Mentioned Users to enabled within the Notification Mapping.
If you would like JEMH to still send comment notifications when they contain a mention, then you will need to ensure that Filter Mentioned Users is Disabled.