Prevent /inhibit sending of a notification (Issue Event or Postfunction)
- Andy Brook [Plugin People] (Unlicensed)
- Andy Brook [Plugin People]
- Phil Evans
- Finn Gale
- 1 Summary
- 2 Example
- 3 Preventing certain recipients from notification
- 4 Inhibiting the ISSUE_CREATED notification when the issue was created by email
- 5 Inhibiting a notification for specific issue changes
- 6 Inhibit Issue Created event notifications to stop duplicates
- 7 Inhibiting duplicates due to @Mention notifications (as mentions are done by Jira and cannot be intercepted)
- 8 Related articles
Summary
From version 1.7.2, JEMH has the ability to allow scripted decision logic at the Template level on whether or not a given notification should be sent by using the $jemhUtils.setInhibitSending(boolean) method. The script itself can be as simple or complex as you need.
Template Sets are the raw Velocity mark-up content for email notifications. For more information on what Velocity is and how it is used, see the official user guide here.
Project Mapping Solution
If you do not want to customize templates, it is possible to add inhibition logic at the ProjectMapping config level, see:
The Velocity Context
The usual velocity context references are available to help you script your decision logic, there is also a helper class available $jemhUtils , see the API link below for additional methods available:
Example
Before using the setInhibitSending(boolean) method, you will want to set up the overlying conditions for when this should happen. Lets imagine I don't like SIMPLE-11 as an issue key, and want to prevent all notifications about that issue. Note that your condition does not have to be based on the issue key - it could be based on almost anything (e.g. priority, custom field values, statuses, day of the week).
Basic Logic
#if ($issue.getKey()=="SIMPLE-11")
##inhibit
#end
#if ($issueEvent.getEventTypeId().longValue()==1)
##inhibit for ISSUE_CREATED
#endInhibiting the notification
$jemhUtils.setInhibitSending(true)The above line will set the boolean isInhibitSending to true. If after the template rendering is complete, this boolean is found to be true then the notification will not be queued for sending. If needed, you could potentially want to reset the boolean back to false in the template also - however if your logic is set out efficiently this may not be needed.
Setting a reason for inhibition
The below line would set the reason for preventing sending of the notification to JEMH's jemh.log file (if logging is enabled).
$jemhUtils.setInhibitSendingReason("I dont like number 11")Implementing in your template
You may wish to consult the built-in Velocity context list in order to know what classes and variables are available for you out-of-the-box. This can be found by going to JEMH>Template Sets and expanding the Velocity Context section. Here is our example in its full glory:
Resulting jemh.log output
The jemh.log (see Enabling JEMH logging) contains a wealth of info, understanding why a given recipient did not get a notification should be obvious if a reason is set!
2015-03-20 16:59:18,710 http-bio-8080-exec-12 INFO [jira.emh.service.DefaultJEMHMessageManager] Mail for [SIMPLE-11] sending was INHIBITED (reason: I dont like number 11) for [javahollic@gmail.com]
Preventing certain recipients from notification
The previous example inhibition script would prevent notification for all recipients as it was non-selective. What if you only want to stop certain recipients from getting the notification? Here are just a few ways it can be done.
Inhibiting by recipient email address
Inhibiting by user group
JIRA 7+ | JIRA 6.4 |
|---|---|
Inhibiting by user picker custom field
Inhibiting the ISSUE_CREATED notification when the issue was created by email
JEMH cannot yet use Entity Properties to indicate the issue was created by email, this can be inferred by setting the JEMH > Custom Field Defaults. For example, a Custom Field select field called 'Issue Source' with a default value of 'Interactive'. JEMH could set a Custom Field Default value of 'Email', custom fields are set in Phase 1 of issue creation, and are set at the point events fire. Labels, still, are not. Then, in a custom copy of the ISSUE_CREATED TemplateSet, for the ISSUE_CREATED event, it can be 'inhibited' when the source was email, to stop duplication notifications. The remain _Profile > Notifications > On Create Custom Event_ will only be driven by JEMH so will allow ONE notification to recipients to be made, and for JIRA recipients specifically, a 'different set' of recipients as the notifications are driven from a Notification Scheme entry.
The Custom Field
Create a Single select custom field:
Once you've created the custom field, make a note of the ID on the Cog > Configure link, (hover, look at URL), it will be something like:
http://dev-jira:8080/secure/admin/ConfigureCustomField!default.jspa?customFieldId=11104 |
The Custom Field default value for interactive users:
The ISSUE_CREATED inhibit notification script
The script then looks for the custom field value, and if its 'Email' (set by JEMH) then the message (for ISSUE_CREATED) is inhibited, and only the custom event driven by the Profile will result in a notification.
Inhibiting a notification for specific issue changes
Lets say that you do not want notifications to be sent for "Issue Updated" events, when the only change is a label addition/removal. Note that a comment does not count as a change log item, therefore simply adding a label and a comment will still result in the notification being stopped:
Inhibit Issue Created event notifications to stop duplicates
When a projects issues are being created interactively and via email, and the Event Listener has templates selected for both "Issue Created" and a custom issue created event, this can result in the sending of duplicate notifications when the issue is created interactively. A solution to this is to add a custom field (e.g. a Select List (single choice)) through the Issues section of the JIRA administration panel which indicates how the issue was created (e.g Interactively/Email). The default value is set to "Interactive".
Following this, navigate to the Profile section of the JEMH Configuration Panel. Proceed to the Profile tab and expand the Custom Field Defaults section. Here we set the default value of the previously defined custom field to be "Email". This means that when JEMH is responsible for issue creation its default will be used over JIRA's.
Once this has been done, the following velocity script can be inserted into a custom Template Set. This script will inhibit the sending of the notification when the issue is submitted via email but allow the notification through if it was created interactively.
The method $!issue.getCustomField has been removed since Jira 8.19.0. Please use the following if using a later version. For more info see:
Hintogram templates, and (as of 1.8.23) Forward templates can also take advantage of this notification inhibition script. This could be useful if for example, you wanted to stop being notified of a certain error message.
Inhibiting duplicates due to @Mention notifications (as mentions are done by Jira and cannot be intercepted)
As per https://thepluginpeople.atlassian.net/browse/SUPPORT-2311 the following can be embedded in a custom IssueEvent TemplateSet so that every Issue Commented / Issue Updated event (for the most part...) can be inhibited when the current recipient identified by JEMH via NotificationScheme can be detected, and inhibited when mentioned, so that they get only one notification