Template Sets

Summary

JEMHC allows you to create and customise templates that are used to render the outbound email content. These templates allow you to modify the Subject and the content (Text and HTML). Templates use a markup language called Velocity, to learn more about this, new users should read the Velocity User Guide.

JEMHC Templates are NOT JIRA Templates! Atlassian documentation is not applicable here, all 'data' is remote, exposed as a RenderContext, see Manipulate Webhook data in a Template for how to do things like refer to a custom field value that may be present.

Creating a Template Set

Click Create on the Notifications > Templates > Template Sets page:

This shows the new Template Set dialog which needs a Name, a Template Set Type and a Theme to be created.

There are lots of types of template, select an appropriate type, eg Issue Created:

There are many different themes to choose from. The JIRA theme is designed to look like current JIRA notifications, the Generic Theme is a reduced complexity theme and the Service Desk themes are designed to look like current JSM notifications. Once submitted, the template is created and available for editing:

Preview Context

The Preview Context is the 'data' that drives the Template, in actual fact it is the JIRA Webhook data. JEMHC stores all incoming Webhook data from Jira within Auditing > Events, this data can be converted into a Preview Context, such that the data can be used to drive design-time template previews. A Preview Context can be created via Auditing > Events > + Action > Create Preview Context, once completed it can then be viewed in the Template edit page:

Gathering User Avatars

When attempting to gather a Users avatar (profile Picture) you will need to ensure that it is visible to anyone. If it is set to Only You then it means your initials will be used instead.

Velocity Context

This expandable section gives access to velocity variables that are defined and available to templates at render time. They are hyperlinked where possible to the related online documentation to enable you to understand what methods may be available.

Editing a Template

When you edit a Template you see there are couple of options. These options would change depending on the Transport type that is used. This is outlined below.

Editing a Email Template

When editing the content of a Email Template you will see three sections, Subject, Text and HTML.

Subject is used to define the content that will be displayed within the Subject of the email.
Text is used to define the content that will be displayed within a Text format notification
HTML is used to define the content that will be displayed within a HTML format notification

Each section is independent of each other meaning that a change to one section will not affect the other sections allowing for different content to be viewed for each section (mainly applies to the Text and HTML sections).

Editing a Slack Template

When you edit a Slack Template you will see one section which is Card. This section is used to customise the content that is displayed within the Slack Notification.

Editing a SMS Template

When you edit a SMS Template you will see one section which is Subject. This section is used to customise the content that is displayed within the SMS message.

Editing a Telegram Template

When you edit a Telegram Template you will see one section which is Text. This is used to customise the content that is displayed within the Telegram message.

Editing a Mattermost Template

When you edit a Mattermost Template you will see one section which is Card. This is used to customise the content that is displayed within the Mattermost notification.

Slack, SMS, Telegram and Mattermost Template Configuration Options

Name

This is the name that the Template will be known as.

Transport Type

This defines the Transport type that the Template can be used with.

Theme

This is the Theme that is used for this template. Themes contains the styling information and macros that can be used within that template.

Template Set Type

Determines where and when the template can be used. Current options are:

Issue Created
Issue Updated
Issue Deleted

Preview Context

The Preview Context that is used to test and drive the design of the template.

Email Template Configuration Options

Name

This is the name that the Template will be known as.

Transport Type

This defines the Transport type that the Template can be used with.

Theme

This is the Theme that is used for this template. Themes contains the styling information and macros that can be used within that template.

Template Set Type

Determines where and when the template can be used. Current options are:

Issue Created
Issue Updated
Issue Deleted
User Registration
Blacklist Forward
Non Catch Email Forward
Limit Exceeded Forward
Message Rejected
Precedence Bulk

Ad Hoc Notifications
Comment Header
Customer Satisfaction Response

Preview Context

The Preview Context that is used to test and drive the design of the template.

Macros

Macros are reusable ‘methods’ that can be called from templates to reduce the complexity of those templates.

Theme Macros

JEMHC Templates for Issue Created /Update etc. are defined within a Theme (eg Jira, Service Desk, Generic). Themes have theme-specific macros, these macros are scoped to only be used by templates that have this specific theme selected. You can view the System themes macros by going to JEMHC > Notifications > Templates > Themes and press “show system defaults” to show the system themes, from there you can access their macro and css definitions.

For more info about Theme Macros see: Themes | Macros

System Themes are read-only, you can create your own template versions based on a Theme or create an entirely new Theme.

System Macros

All Theme macro content include the JEMHC Global script, see JEMHC > Notifications > Templates > System Macros. Its possible to evaluate macro calls in the context of the webhook data from Jira ( How Jira events turn into emails ) when saved as a Preview Context.

For more info about System Macros see: System Macros

Custom Macros

You can define your own custom macro content for use in your own templates through Custom Macros, see JEMHC > Notifications > Templates > Custom Macros. Again you can invoke Velocity macros through the scratchpad interface in the context of a Preview Context.

For more info about Custom Macros see: Custom Macros

How to change Macro behaviour

A common requirement is to provide a ‘slightly different' macro used by a Template, there are two paths:

a) Create a new template, code the logic and/or refer to a new macro defined in your Custom Macros. The advantage of this path is that you can test changes in isolation and even, just apply them on a per project basis.

b) Override a System/Theme macro in your Custom Macros, which then that then avoids having to customize templates.

If your Custom Macros contain broken syntax it will cause all notifications to be broken. Test every change!

Template Actions

Once a Template has been created, there will be some actions that can be performed.

View

This will show you the content that has been added to each section. The sections are: Subject, Text and HTML.

Edit

This will open the relevant edit screen for the template

Copy

This will create a duplicate of this template.

Auditing

This is used to identify when changes have been made and who they were made by.

Export

This will create an export of the template content allowing you to create a backup or to import within another instance.

Delete

This will delete the template from JEMHCloud. This will impact any notification mappings if in use.

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 Template or the macros used in the Template Set used by the Notification Mapping.

The two methods are:

$jemhUtils.setCommentRendered()
	and/or
$jemhUtils.setFieldRendered()

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.

Previewing Templates

When a template is edited, a previously created Preview Context can be used to drive the template, selected in (1) below:

The template content can be previewed in TEXT or HTML (2):

The HTML preview is a restricted view to avoid common CSS injection problems that content within the Preview Context can cause. After the user clicks through a warning, the user can see the fully rendered content:

Fully rendered HTML:

Enterprise Mail Handler for Jira Cloud (JEMHC)