Velocity Macro Scripting and Notifications

Owned by Former user (Deleted)
Last updated: Apr 15, 2019
7 min read

JEMHC uses Velocity Macros to allow you to create notifications that can dynamically vary their content.

This guide is geared towards email notifications but the Velocity macros for the other transport types (e.g. SMS) are configured in much the same way.

Table of contents

What can Velocity do for me?

You can use the features offered by the scripting language Velocity to control notification content. You can also vary the content of notifications by using the logic embedded within Java objects exposed by Velocity. We strictly use Velocity in this sense but it's capable of other things. If you're interested in looking further into the scripting language's capabilities then check out Apache's overview page on Velocity but, bear in mind that JEMHC uses it to dynamically control the content of notifications.

An example of how Velocity can be used is by calling methods on the String object. It has the equals method that can be used to see if two Strings have equal content which is useful for comparing, say, the time that a comment was created with the time that it was edited to see if it's a brand new comment or if it has been edited.

Check if comment is new, or has been edited.
// $comment has already been set to store a Jira comment that has been extracted from the webhook context. #if( $comment.created.equals($comment.updated) ) //Content related to a brand-new comment. #else //Content related to an edited comment. #end

Key terms and concepts

Macro - A Velocity macro. These allow you to write scripts with logic that alter the content of Notifications; an example of one is in the code block above.

System Macros - A collection of generic Velocity macros available within all other Velocity macro contexts due to an automatic import feature offered by JEMHC.

Theme Macros - Similar to system macros except all of the Velocity macros in Themes are automatically imported into the Template Sets that belong to the Theme.

Template Sets - A combination of HTML markup, CSS styling and Velocity macros. Template sets are specific to a Jira action (e.g. Issue Created, Issue Updated, Issue Deleted etc.).

Notification - An automated message sent out by JEMHC. The content and behaviour depends on the markup output by the Template Set and the configuration of the Notification Mapping.

Notification Mapping - A configuration that tells JEMHC how to respond to actions that occur within Jira. See our wiki page Notifications for more details about these configurations.

Official Velocity user guide

Velocity belongs to Apache and they have a very useful page that describes the fundamental syntax and semantics of the language. See their user guide for more information about the language itself.

Notification aggregation

There can be multiple recipients for a single notification. The Template Set is run once for each recipient and identical notifications are aggregated together so that a single email is sent out with all of the related recipients included as one, instead of lots of individual identical emails with one for each recipient.

The two methods in the code block below instruct JEMHC that the user under which this Template Set is being run does have a notification that contains useful content. They act as a flag telling JEMHC that the notification should be sent for the current user and they only need to be called once.

Call these to ensure your notification does not get ignored by JEMHC.
$jemhUtils.setCommentRendered() and/or $jemhUtils.setFieldRendered()

Macro import structure

We use a multi-tier system where the more general tiers are imported into the more specific tiers, thus making all of the macros in the general tier available in the more specific tiers.

The macro import hierarchy is like so: System macros → Theme macros → Template Set macros.

All macros on the left will be available on the right. For example, all of the system macros will be available within the context of the theme macros and the template set macros. This allows you to write 'helper' or convenience macros that can be used in any of the macros that are further along the hierarchy.

View existing macros

It's important that you've read the Macro import structure section on this page in order to understand why the macros are laid out as they are.

System Macros

To view the System macros, go to Notifications → System Macros → Content.

Theme Macros

To view the Theme macros, go to Notifications → Themes → and click the small pencil beside the Theme you want to read through.

If you want to investigate the contents of the default themes then you'll have to click 'Show Theme Defaults'.



Template Sets

To view the Template Set and its macros go to Notifications → Template Sets → and click the small pencil beside the Template Set you want to read through.

If you want to investigate the contents of the default Template Sets then you must click 'Show Template Set Defaults'.



Where's the best place to put my Velocity macros?

The best practice that we suggest is to create a new theme that's specific to the type of Notification that you want to construct, like a new Service Desk theme, or a new Jira theme. Inside of this new Theme you should then place macros that will be used by more than one of the Template Sets that belong to the Theme because, the Theme macros will be available within the context of its Template Sets.

You can place all of your custom macros directly in a Template Set but it will become very hard to read and manage.

Designing template sets

Template Set configurations consist of three sections and they are Subject, Text, and HTML. The Text and HTML sections both control the body of the email.

Subject

The subject box allows you to design the content of the subject field in emails sent out by JEMHC. The content can be static text or dynamic text by utilising Velocity macros.

Text

This section allows you to configure the content of the body of the email sent out by JEMHC. Both the Text and the HTML text boxes allow you to design the content of the notification email body with the difference being that the content of the Text box will be output raw text with no HTML or CSS markup taken into account.

HTML

This section is similar to the Text section except any HTML and CSS will be parsed and output in the resulting notification.

Text vs HTML

The difference between the 'Text' box and the 'HTML' box becomes apparent when the 'Format' of a Notification Mapping is switched between Text and HTML. If the Notification Mapping has its format set to Text then the content of the Template Set's Text box will create the resulting email body in the notification, and vice versa for HTML.

Inhibit or Suppress Notifications using Velocity

You might want to specifically suppress a notification based on the logic of your macro. We offer the following method to allow you to specifically inhibit a notification from being sent out. This is the method:

Use this to programmatically suppress your notification.
$jemhUtils.setInhibitSending(true)

An alternative to directly calling the jemhUtils method is to override a Velocity macro called inhibitSendingConditions provided in the system macros file. Once overridden it must be slightly adjusted in order for the 'if' statements to cause the notification to get inhibited. This is an example of the macro:

An example of inhibitSendingConditions

Common errors

Email hasn't been sent as no useful information was displayed based on the used template.

When a notification is rendered all Velocity macros are processed and their output is placed into the body of the notification. This will always result in static Macro content like the header and the footer of the notification being rendered which is fine unless there is no tangible or useful content to the notification. For example, you could find yourself receiving notifications that have a header, a footer and absolutely nothing else because the Macros that output the comments - for whatever reason - found no comments in the event.

To put a stop to wasteful notifications we provide a feature where the notification will be ignored if one of these two methods are not called anywhere within the macros in the Template Set used by the Notification Mapping.

The two methods are:

Call these to ensure your notification does not get ignored by JEMHC.

Note - these do not control whether to display the comment or fields themselves, instead these methods control whether to display the entire notification or not. The Template Set is run once for each recipient user and if neither of these methods is called for an individual user then that user won't get the notification. It's possible that a macro will call one of the methods for, say, a JSD agent but not for a JSD customer - such as when an internal comment is made.