Template Sets
- 1 Summary
- 1.1 Creating a Template Set
- 1.2 Preview Context
- 1.2.1 Gathering User Avatars
- 1.3 Velocity Context
- 1.4 Editing a Template
- 1.5 Macros
- 1.5.1 Theme Macros
- 1.5.2 System Macros
- 1.5.3 Custom Macros
- 1.5.4 How to change Macro behaviour
- 2 Template Actions
- 3 Email hasn't been sent as no useful information was displayed based on the used template.
- 4 Previewing Templates
- 5 Related articles
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:
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: