Since JEMH v1.8.18
Summary
JEMH provides the ability to control the events that its Event Listener detects. Events can be ignored, replaced or added to in addition. This config happens at the Project Mapping level, so no per-template changes are needed. If per-event changes are required, the templates must be updated, see:
Approach
The Event Listener Project Mappings have a Velocity script field which allows logic to be coded that could drive a change in how the event is handled.
The script is evaluated like any other template in JEMH, the difference is that the output of the render process goes nowhere except into the JEMH LOG, so is the perfect place for debugging:
Velocity context
The context available to the script is the generic one, shown on the JEMH > TemplateSet page. In addition there are some new values available:
Reference | Description | Link for API methods |
|---|---|---|
$issueEvent | The issue event that has been fired by Jira. | |
$issue | The Jira issue that the event is related to. Note that this is not the same $issue reference used in Template Sets, this the real Issue object. | |
$comment | If a comment was made as part of the event this reference represents that comment. | |
$result | The JEMH result object that is used to instruct JEMH on what to do with the event. | See below |
Result Bean methods
Method | Parameters | Example usage |
|---|---|---|
setIgnoreEvent(boolean ignore) | ignore - whether or not the event should be ignored. Set to true to ignore, false otherwise. |
|
setReason(String reason) | reason - a text string containing the reason for the event change or ignore. This is optional and is for providing information in log files. |
|
setTargetEventId(int targetEventId) | targetEventId - the integer ID of the event to set as the target event. The target is event is for use with the |
|
setEventBroadcastMethod(String method) | method - a String representing the broadcast method to use:
A method must be set in order for a different event type ID to be used. |
|
setIgnoreUnsentAttachments(boolean ignoreAtts) | ignoreAtts - whether or not attachments that have already been sent should be ignored or not for the event. Set to true to ignore, false otherwise. |
|
Ignoring an event
In this contrived example, an issue is commented on, and that issue has a priority of 'Lowest', the script for JIRA users will cause those events to be filtered.
Running script
#if ($issue.getPriority().getName().equalsIgnoreCase("lowest"))
Trivial Issue
$result.setIgnoreEvent(true)
$result.setReason("Its a trivial issue")
#else
Its normal, leave alone
#end
This is the content of the JIRA user notification part of an Event Listener Project mapping for the 'TEST' project:
Script being edited in Event Listener | Script being viewed in Event Listener |
|---|---|
 |  |
The result of a comment on an issue with 'Lowest' priority' can be seen, First the NON-JIRA User Notifier runs, showing the velocity pos-processing of the non-JIRA script (which here was just static text and didn't affect the $result: "Non JIRA script here".
2015-12-17 15:10:49,196 http-nio-8080-exec-22 DEBUG [emh.service.listener.JEMHIssueEventListener] Direct match target project key [TEST] 2015-12-17 15:10:49,196 http-nio-8080-exec-22 INFO [emh.service.listener.JEMHIssueEventListener] Handling Email Notifications 2015-12-17 15:10:49,272 http-nio-8080-exec-22 INFO [emh.service.listener.JEMHIssueEventListener] Running notification handler: NON JIRA User Notifier 2015-12-17 15:10:49,274 http-nio-8080-exec-22 DEBUG [jira.emh.service.DefaultJEMHMessageManager] EventSelectorScript result - issue: TEST-129 and event: 6, Result: ignoreEvent: false, eventOut: 0, reason: none given, velocity debug output: ---------------- Non JIRA script here ---------------- 2015-12-17 15:10:49,274 http-nio-8080-exec-22 DEBUG [emh.service.listener.NonJiraUserNotifier] NonJiraEventSelectorScript The script completed without setting a valid eventId through: $result.setTargetEventId(12000) 2015-12-17 15:10:49,274 http-nio-8080-exec-22 INFO [emh.service.listener.NonJiraUserNotifier] No valid default customField value set global or in project [TEST] mapping, ignoring this event.
The JIRA User notifications are where the above script is run, it refers the issue Key, the Event#, ind indicates that after evaluation, the $result is to ignoreEvent. The post rendered output from the script shows the static text embedded in the template, which can be used for debug:
2015-12-17 15:10:49,274 http-nio-8080-exec-22 INFO [emh.service.listener.JEMHIssueEventListener] Running notification handler: JIRA User Notifier 2015-12-17 15:10:49,277 http-nio-8080-exec-22 DEBUG [jira.emh.service.DefaultJEMHMessageManager] EventSelectorScript result - issue: TEST-129 and event: 6, Result: ignoreEvent: true, eventOut: 0, reason: Its a trivial issue, velocity debug output: ---------------- Running script Trivial Issue ---------------- 2015-12-17 15:10:49,277 http-nio-8080-exec-22 DEBUG [emh.service.listener.JiraUserNotifier] JiraEventSelectorScript ignored eventID [6], reason: Its a trivial issue
Blocking all JSM Internal Comment notifications
#if ($comment)
comment present
#if ($jemhUtils.isPrivateJSDComment($comment.getAuthorApplicationUser(), $comment))
Comment is INTERNAL
$result.setIgnoreEvent(true)
$result.setReason("JSM internal comment detected, blocking ALL")
#else
Comment is PUBLIC
#end
#else
no comment present
#end
Log output:
2022-01-24 13:55:14,180 http-nio-8080-exec-3 DEBUG [jira.emh.service.DefaultJEMHMessageManager] EventSelectorScript result - issue: JSDDEFAULT-12 and event: 6, Result: ignoreEvent: true, eventOut: 0, reason: JSM internal comment detected, blocking ALL, velocity debug output: ---------------- comment present Comment is INTERNAL ----------------
Replacing an event with another
Now, a slight change in the script:
Running script
#if ($issue.getPriority().getName().equalsIgnoreCase("lowest"))
Retargetting to a Generic Event (13)
$result.setTargetEventId(13)
$result.setEventBroadcastMethod('useDerivedEventInstead')
$result.setReason("Its a generic thing")
#else
Its normal, leave alone
#end
Log output, showing how system default templates are located for event 13, rather than the input event 6.
2015-12-17 15:35:44,716 http-nio-8080-exec-20 DEBUG [jira.emh.service.DefaultJEMHMessageManager] EventSelectorScript result - issue: TEST-129 and event: 6, Result: ignoreEvent: false, eventOut: 13, outcome: useDerviedEventInstead, reason: Its a generic thing, velocity debug output: ---------------- Running script Retargetting to a Generic Event (13) ---------------- 2015-12-17 15:35:44,716 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] JiraEventSelectorScript selected [TEST-129] eventID [13] INSTEAD of the current one [6], reason: Its a generic thing 2015-12-17 15:35:44,716 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] JiraUserNotifier: Got event [13] for issue: TEST-129, has notification scheme: 10000 2015-12-17 15:35:44,716 http-nio-8080-exec-20 INFO [emh.service.listener.JiraUserNotifier] given LsnProjMapping: id=1, mapping for project: TEST 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=1 with DEFAULT template for issueEvent: 1 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=2 with DEFAULT template for issueEvent: 2 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=3 with DEFAULT template for issueEvent: 3 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=4 with DEFAULT template for issueEvent: 4 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=5 with DEFAULT template for issueEvent: 5 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=6 with DEFAULT template for issueEvent: 6 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=7 with DEFAULT template for issueEvent: 7 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=8 with DEFAULT template for issueEvent: 8 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=9 with DEFAULT template for issueEvent: 9 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=10 with DEFAULT template for issueEvent: 10 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=11 with DEFAULT template for issueEvent: 11 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=12 with DEFAULT template for issueEvent: 12 2015-12-17 15:35:44,717 http-nio-8080-exec-20 DEBUG [emh.service.listener.JiraUserNotifier] Looking for eventId=13, found: mappingId=13 with DEFAULT template for issueEvent: 13 2015-12-17 15:35:44,717 http-nio-8080-exec-20 INFO [emh.service.listener.JiraUserNotifier] Matched for DEFAULT templateSet 2015-12-17 15:35:44,717 http-nio-8080-exec-20 INFO [emh.service.listener.JiraUserNotifier] looking up notification scheme: 10000 2015-12-17 15:35:44,717 http-nio-8080-exec-20 INFO [emh.service.listener.JiraUserNotifier] notification scheme found?: true 2015-12-17 15:35:44,717 http-nio-8080-exec-20 INFO [emh.service.listener.JiraUserNotifier] no restricted group, triggering notification.
Adding an event in addition to the original
A minor variation of the above to cause notifications to be sent based on BOTH event types:
Running script
#if ($issue.getPriority().getName().equalsIgnoreCase("lowest"))
Retargetting to a Generic Event (13)
$result.setTargetEventId(13)
$result.setEventBroadcastMethod('useDerivedEventAsWell')
$result.setReason("Its a generic thing")
#else
Its normal, leave alone
#end
Log output shows:
2015-12-17 15:41:26,340 http-nio-8080-exec-7 DEBUG [jira.emh.service.DefaultJEMHMessageManager] Enqueing JIRA user mail SUCCESS for event [13] on issue TEST-129 for admin / meeeee@thepluginpeople.com ... 2015-12-17 15:41:26,466 http-nio-8080-exec-7 DEBUG [jira.emh.service.DefaultJEMHMessageManager] Enqueing JIRA user mail SUCCESS for event [6] on issue TEST-129 for admin / meeeee@thepluginpeople.com
Checking if an attachment was added
Events don't refer attachments, but JEMH can provide support for determining some things through a script helper utility:
Running script #if ($scriptUtil.isAnyAttachmentAddedWithin($issue, 5000)) Attachment added #else No attachment added #end
Log output, for an attachment added
2015-12-17 16:53:09,933 http-nio-8080-exec-22 DEBUG [jira.emh.service.DefaultJEMHMessageManager] EventSelectorScript result - issue: TEST-128 and event: 2, Result: ignoreEvent: false, eventOut: 0, reason: none given, velocity debug output: ---------------- Running script Attachment added ----------------
Checking the value of a custom field
You want to ignore an event if a custom field has a certain value.
The following example script checks to see if an event is an Issue Created event and whether or not a custom field has the value Email. If both checks are true then the event will be ignored else an notification will be sent.
Running script
#set($cf = $customFieldManager.getCustomFieldObject("customfield_10600"))
#set ($cfValue = $issue.getCustomFieldValue($cf))
#if ($issueEvent.getEventTypeId() == "1" && $cfValue == "Email")
$result.setIgnoreEvent(true)
$result.setReason("Stop duplicate")
Event ignored, issue created via email with JEMH.
Will notify with custom event.
#else
Issue created interactively. Will send notification.
#end
Log output
2016-10-21 14:00:31,461 http-nio-8080-exec-12 DEBUG [jira.emh.service.DefaultJEMHMessageManager] EventSelectorScript result - issue: INROLL-37 and event: 1, Result: ignoreEvent: true, eventOut: 0, reason: Stop duplicate, velocity debug output: ---------------- Running script Ignoring event, issue was created via email. Will notify user with during custom event. ----------------