| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
| Info |
|---|
JEMHC Templates are NOT JIRA Templates! Atlassian documentation is not applicable here, all 'data' is remote, exposed as a RenderContext, see It is important to note that JEMHC templates differ from Jira templates. The documentation provided by Jira is not relevant in this context. For guidance on how to reference a custom field value, please refer to the article on 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:
...
There are lots of types of template, select an appropriate type, eg e.g. Issue Created:
...
There are many different themes to choose from. The JIRA theme :
Jira is designed to look like current
...
Jira notifications
...
Generic
...
is a
...
basic theme
...
Service Desk
...
is designed to look like current JSM notifications.
Once submitted, the template is created and available for editing:
...
The Preview Context is the 'data' that drives the Template, in actual fact it is the JIRA Webhook Jira webhook data. JEMHC stores all incoming Webhook 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:
...
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.
...
...
Templates
When editing the content of a Email Template you will see three sections, Subject, Text and HTML.
...
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).
...
...
Slack
...
Templates
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.
...
...
SMS
...
Templates
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.
...
...
Telegram
...
Templates
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.
...
...
Mattermost
...
Templates
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.
...
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.
...
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 e.g. 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 CSS definitions.
For more info about Theme Macros see: https://thepluginpeople.atlassian.net/wiki/spaces/JEMHC/pages/3765895264/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.
...
| Code Block |
|---|
#set ($serviceJiraFields = ['issuetype','assignee','created','updated','priority','reporter', 'security']) |
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.
...
Email hasn't been sent as no useful information was displayed based on the used template.
When a notification is rendered generated, all Velocity macros are processed and their output is placed , incorporating their HTML/CSS outputs into the notification's 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.
. To avoid receiving “empty” notifications, we offer a feature that disregards notifications if neither of the two specified methods is invoked within the Template itself (or the macros it uses). The two methods are:
...
$jemhUtils.setCommentRendered()
...
$jemhUtils.setFieldRendered()
...
Note - that these do not methods control whether to display the comment or fields themselves, instead these methods control whether to display the visibility of the entire notification, not the comment or notfields. The Template Set is run once runs for each recipient user , and if neither of these methods method is called invoked for an individual user then that user a user, they won't get receive the notification. It's possible that For example, a macro will call one of the methods for, say, a JSD may call a method for an agent but not for a JSD customer - such as , like when an internal comment is made.
...
When a template is edited, a previously created Preview Context can be used to drive the template, selected in (figure 1) below:
...
The template content can be previewed in TEXT or HTML (figure 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:
...