Inhibit notifications based on run-time conditions

Owned by Andy Brook [Plugin People]
Last updated: Nov 11, 2024 by Andy Brook [Plugin People]
4 min read

Notifications can be conditionally prevented from being sent to Jira and Non-Jira user recipients. This is done by defining a Velocity macro (or “Velocimacro”) that is evaluated when an email template is being rendered.

The ‘render’ is attempted for all recipients, if all recipients are inhibited, the event will be marked as ‘ignored’

The key part of the macro that stops a notification being sent is the invocation of the method:

$jemhUtils.setInhibitSending(true)

The velocity macro inhibitSendingConditions defined in JEMHC > Notification > Custom Macros is already called in all built in templates, so if you are using such a template already there is no need for additional template modification.

Testing with Preview Context data

You can and should test your custom Macro to be sure it works as a syntax error in this macro will break all notifications.

In order to test the User Macro, we need a Preview Context, which represents a notification of change from Jira for the kind of issue event to be inhibited. You can create a preview context from JEMHC > Auditing > Events (via cog drop down at the end of each line. NOTE: JEMHC will not retain event data from Jira in JEMHC > Auditing > Events without a matching ‘notification project mapping’ (JEMHC > Notifications > Notification Mapping > Email).

Basic example

For demonstration, the following macro will prevent notifications when the issue type is “Support”.

#macro (inhibitSendingConditions) ## macros are defined using #macro #if ($context.issue.fields.issuetype.name.asText() == "Support") ## condition for $jemhUtils.setInhibitSending(true) ## this inhibits the notification inhibit ASOFT ## debug text only seen during preview #end ## ends the if block #end ## ends the macro definition
Previewing the basic example macro using previously encountered preview context data

If you use a different Preview Context, the scratchpad output will be updated, showing the different outcome.

Now we’ve shown how to inhibit ALL notifications for a given project, lets build that up, which involves you learning more about how to interact with the Preview Context, please read through:

If the configuration in Notification Mappings is not enough for your notification rules, you can define more complex conditions overriding a system macro. This macro has been included in all the templates.

  1. Enable Email users and JIRA users that you want to be notified in the project notification mapping: Notifications > Issue > Edit icon. Confirm the proper Target Audience has been selected.

  2. Add the inhibitSendingConditions custom macro in Notifications > Custom Macros > Edit. The following example uses the recipient type and the event data to only notify Bug issues to Email users (Jira users may receive any type of issues)

#macro (inhibitSendingConditions) #if ($jemhUtils.getRecipientType() == "EMAIL_CUSTOM_FIELD" && $context.issue.fields.issuetype.name.asText() != "Bug") $jemhUtils.setInhibitSending(true) #end #end

If a notification has been inhibited for sending, you should see the following line in the event's report:

Restrict notifications to particular issue field changes

If you add the following Custom Macro to JEMHC > Notifications > Custom Macros, it will check a list of fields that are passed to it, and only allows notification if one of the listed fields was changed.  It also allows comments to be notified:

To call the macro in your custom template, you need to add use something similar to the following example usages:

Checking 3 fields for changes: a custom field, the issues description field, and the issues status field:

Checking a single field for changes: the issues standard status field:

Note the lowercase name for the standard issue fields.  The field names can be determined through viewing the webhook data for a previous event.

Related articles