Template configuration (Custom templates)
- Ryan Clifton
Summary
Templates Sets are applicable to email as well as other Transports if installed and configured. All TemplateSets have access to the JEMH global and user macro definitions, and may access $issue if appropriate.
Template Sets allow you to customise the content and format of Notifications using VTL (Velocity Template Language). Here you are able to customise the templates that are used for Email, Slack and SMS. See Template Types for more info about the types of templates that can be configured.
Creating a new Template
Select the Relevant Template type (Listed below in Template Types)
Press Create or the “+” icon to create a new template. Ensure to select the relevant additional information. e.g. Transport, Theme and EventType.
Editing a Template
This section shows how to access the Template editor. For additional information and Template example see: Customize Email Templates
Press Edit (Pen Icon) to edit the name of the Template and the content that would be shown when the template will be rendered. Note: The template can be modified at any time.
Once the template has been modified, Press Save so that the new template can be used.
This section covers all of the configurations options there are when editing a Template. Note: Some templates may not contain all of the configuration Option.
Edit Configuration Options
Name
The name of the template.
Css
The Css Styling that the Template will use.
Issue Event
Defines the Issue Event that the Template can be used with. Note: Only applies to Issue Event Templates.
Subject
This is the information that will be added to the Subject of the Email. This uses a Text format.
Text
This is the information that will be added to the Text part of the email. This section is used when the notification format is Text.
HTML
This is the information that will be added to the HTML part of the email. This section is used when the notification format is HTML.
Previewing Templates
You can preview Velocity Template sections such Subject/Text/HTML by configuring the Preview Context as shown below.
Preview Context Configuration
Preview Context Issue Key - An existing issue which you wish to preview the Template Set against.
Action User - The recipient of the notifications
Actioner User - User who triggers the Notification to be sent. e.g. The User who adds a Comment.
Velocity Preview Icon - Once the previous Configuration is set up clicking the preview Icon will render the related velocity section as a preview.
Exporting and Importing a Template
All TemplateSets can be copied within JEMH or exported/imported to allow migration between environments.
Export
Importing
Select Import Template Set.
Select the relevant Export file and press Import Template Set.
Once imported you will see the new template within the list.
Example Template Customisations
To view example templates configurations see the following page: Customize Email Templates
Template Actions
For each Template there are a couple of actions that can be triggered.
Edit
This opens the Template Editor which will allow you to change the Name, Subject, Text and HTML sections of the Template. (Configuration Options depend on the Template Type).
Copy
This will create a duplicate copy of the template. Copied templates has “Copy of” at the start of their name.
Export
Creates an XML file that allows you to create a backup copy which can be imported later.
Template History
This shows the change history of the template allowing you to compare between versions and to restore a specific version. Note: Only two templates can be selected at a time.
Delete
This removes the Template from the instance.
Template Types
Template Sets are groupings of TEXT, HTML and Subject templates that can be customized. The templates are scripted using VTL (Velocity Template Language). There are several varieties of TemplateSets:
Issue Event
These templates are used to render notifications when an issue has been updated. These templates allow you to customise how the notifications will look for each type of Issue event.
These templates are selected within JEMH > Notifications > Notification Mapping > Relevant Issue event. For more info about Sending Issue Event notification see: Send notifications for Issue Events
Comment Header
The Comment Header template allows the customization of the message that can be prefixed to comments/descriptions when coming from email.
This is selected within Profile > Email > Templates > Comment Header TemplateSet.
Hint Notification
These templates are used to send a notification to the email sender when their email did not Create/Comment on a Issue.
These templates are defined within Profile > Email > Templates > Hint Notification TemplateSet
Forward
This section allows you to create Custom Forward notification templates. When configured and selected these templates will be used to render Forward notifications to Admin Users.
These templates are defined within Profile > Email > Templates > Forward Email TemplateSet.
User Event
These templates are used to send notifications when user events are triggered. You select the relevant template within JEMH > Notifications > User Events.
These templates can be sent when:
A User is created.
A User has signed up.
A User states they Forgot their Username when signing in.
A User states they Forgot their Password when signing in.
A User cannot change their password
Signup
These templates are used when a Jira user has been created. This notification is used to notify the sender that a Jira user was created, the details that was used when creating the user and to allow the user to set a password for their new account.
The template used can be selected within Profile > Email > Template > User Sign-up TemplateSet.
Status Notifications
These are Templates that can be used for System Notifications. System Notifications are used to notify reporters that they have issues still open.
Defined within JEMH > Status Notifications > Configuration > Status Notification Template Set
Thread Match Rejection
These are templates that are used to send Thread Match Rejection notifications to email senders. These notifications typically occur when a email does not relate to an existing issue and when the Profile used is set to Comment Only Operating Mode.
These templates are selected within Profile > Email > Templates > Thread Match Reject TemplateSet
Directive Set Response
When DirectiveSets are used, they can refer to one of these templates, that are shown post-execution.
These templates are defined within JEMH > Notifications > Relevant Directive Set > Response TemplateSet.
Ad hoc
These are templates that can be used within Ad Hoc notification and Post Function notifications.
For more info see:
Ad Hoc Notifications: Use Adhoc Notifications
Post Functions: Use the JEMH Notification Post Function
Scriptlets for Ad hoc
These templates inject content within the Ad Hoc notification editor.
Ad hoc/ Workflow auto-comment
These templates are used to add comments to the issue when a workflow postfunction and adhoc notifications are sent. Enabling customization of the storage for 'sent' messages on the issue (usually with limited visibility) for traceability.
Selection of Templates
Forward, Hint-O-gram and Comment Header templates are selected via the Profile > Email > Templates. Issue Event templates will be selected via JEMH > Notifications.
JEMH Profile
For Forward, Hint Notifications and Comment Header templates you select these through the Profile. This found within Profile > Email > Templates section, this allows per-profile selection.
Event Listener/Notifications
The Event Listener allows JEMH to create per-project mappings that allow JIRA and non-JIRA user notifications to be sent. Each Issue Event can be set to the DEFAULT template, or can refer to a specific custom template. For more information on its configuration, please see How Do I Use Event Listener
Removing Notification Scheme from Project at JIRA level
When a Notification Scheme is associated with a project, JIRA will automatically receive Issue Event's and generate email. JEMH's Event Listener is just another listener - if enabled, will produce appropriate emails, but JIRA will still do the same, creating a second notification for JIRA users.
If JIRA user notification needs customization, the JIRA-User section of the JEMH Notification project mapping needs to have the appropriate Notification Scheme selected. The same Notification Scheme also needs to be deselected from the actual Project (this is required because of JRA-19957 that prevents the disablement of the internal Mail Event Listener).
JEMH is then able to take over all notifications for JIRA users, using exactly the same Notification Scheme that you have configured.
Go to JEMH > Event Listener/Notifications
Scroll down to the Transports > Email section and choose either the Non-JIRA notifications or JIRA notifications tab
Click Edit (Pen Icon) on the project of your choice
Scroll down to the Event Template Selection section
Find the event type for which you have created a custom template, and open the drop down menu on the right. You should see your custom template:
Press Submit to save your changes
Press View Active Templates on the Mapping to see the Templates that have been selected:
Ensuring Templates will be used
Some custom issue templates work automatically, such as Issue Created or Issue Commented. However for others, such as Issue Resolved or Issue Updated, the Jira Workflow Transitions must be edited in order to ensure that the correct issue event is fired which will tell JEMH to use your custom template. Once you have created your template and selected it in the Event Handler/Notifications section for the related event, you need to modify the Workflow for your project.
In your project, go to Project Settings>Workflows and click edit
Click on a transition that you want your template set to be used on (For example, for ‘Issue Resolved’ you might want the ‘In Progress → Done’ transition)
Go to the ‘Post Functions’ tab
If a ‘Generic Event’ is being fired (Or Event ID:13) then edit this and select ‘Issue Resolved’. If there is no Issue Event being fired, click ‘Add post function’ and choose ‘Fire Event’
Repeat steps 2-4 for each transition that you want your custom issue event templates to be used on
Save these changes to the workflow.