Customize Email Content

Customizing content can be required for many reasons, from adding a given custom field, to changing the look and feel, adding images etc.

1 Introduction
- 1.1 Creating a TemplateSet
- 1.2 Preview Context
- 1.3 Velocity Context
- 1.4 Useful things in the context
- 1.5 Editing the content
- 1.6 Macros
  - 1.6.1 Theme Macros
  - 1.6.2 System Macros
  - 1.6.3 Custom Macros
  - 1.6.4 How to change Macro behaviour
2 Related articles

Introduction

JEMHC allows customization of email subject and content (Text and HTML). These three templates are grouped together in a Template Set. JEMHC has Themes which are groups of TemplateSets, that's covered later. 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 TemplateSet

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:

Currently there are two Themes, JIRA and Generic. The JIRA theme is designed to look like current JIRA notifications, the Generic Theme is a reduced complexity theme, more suitable for Helpdesks. More themes will be added in the future. 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 incoming Webhook data from JIRA, this data can be converted into a Preview Context, such that data for an Create, Update and Delete may be used to drive design-time template previews. So, you wont be able to use this until you have actually saved a context, which is done via Auditing > Events > + action , when available and selected, it can be viewed in the Template edit page:

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.

Useful things in the context

See $jemhUtils (javadoc is https://jemhcloud.thepluginpeople.com/app/static/javadoc/com/thepluginpeople/jemhod/api/ITemplateUtils.html ), you can get a lot of useful info, like the Recipient Email Address $jemhUtils.getRecipient() , $jemhUtils.getRecipientType() will give you a RecipientType, calling .name() on that will give you the name of type match. Then you can conditionally add more content (or remove) for different types of user by Select fields to be shown in a Jira/Service Management/Transport issue update notification :

JSM template

By detecting the recipient type we can change the number of fields included in the current notification.

JEMHC uses BCC to deliver one mail to many recipients, varying the content will increase your plan consumption (msg and data).

#set ($recipientType = $jemhUtils.getRecipientType().name())
<p>recipientType: $recipientType</p>
#if ("$recipientType"=="REPORTER" || "$recipientType"=="REQUEST_PARTICIPANT" || "$recipientType"=="EMAIL_CUSTOM_FIELD" || "$recipientType"=="OTHER")
 #set ($serviceDeskUpdateFields = ['issuetype','summary'])
 <h3>Customer Notification</h3>
#else
 #set ($serviceDeskUpdateFields = ['issuetype','summary','description','customfield_10200', 'security', 'labels'])
 <h3>Jira Notification</h3>
#end

The HTML content above could also include the entirety of the macro call for further customization:

#set ($recipientType = $jemhUtils.getRecipientType().name())
<p>recipientType: $recipientType</p>
#if ("$recipientType"=="REPORTER" || "$recipientType"=="REQUEST_PARTICIPANT" || "$recipientType"=="EMAIL_CUSTOM_FIELD" || "$recipientType"=="OTHER")
 #set ($serviceDeskUpdateFields = ['issuetype','summary'])
 <h3>Customer Notification (less)</h3>
#jsdBodyDelimeter()
#jsdReplyMarkerHint()
#jsdIssueLinkAndDisableNotifications()
#renderParticipants()
#renderServiceDeskSignature()
#inhibitSendingConditions()
#else
 #set ($serviceDeskUpdateFields = ['issuetype','summary','description','customfield_10200', 'security', 'labels'])
 <h3>Jira Notification (more)</h3>
#jsdBodyDelimeter()
#jsdReplyMarkerHint()
#jsdMessageContentCreated()
#jsdMessageContentUpdated()
#jsdIssueLinkAndDisableNotifications()
#renderParticipants()
#renderServiceDeskSignature()
#inhibitSendingConditions()
#end

Remember that to preview a template in the context of a given user, use the JEMHC > Notifications > Preview (where a recipient can be selected) rather than the “Template Set Preview” (an improvement exists to make this possible on Template Set Preview).

Software project template

The above can also be done in a software project.

JEMHC uses BCC to deliver one mail to many recipients, varying the content will increase your plan consumption (msg and data).

#@issueNotification()
#set ($recipientType = $jemhUtils.getRecipientType().name())
<p>recipientType: $recipientType</p>
#if ("$recipientType"=="REPORTER" || "$recipientType"=="REQUEST_PARTICIPANT" || "$recipientType"=="EMAIL_CUSTOM_FIELD" || "$recipientType"=="OTHER")
 #set ($serviceJiraUpdateFields = ['issuetype','summary'])
 <h3>Customer Notification (less)</h3>
<table id="background-table" cellpadding="0" cellspacing="0" width="100%">
    <!-- header here -->
    #jemhIncludeStandardActionHeader()
    <tr>
        <td id="email-content-container">
            <table id="email-content-table" cellspacing="0" cellpadding="0" border="0" width="100%">
                #jemhIncludeIssueHeader()
                #jemhIncludeIssueDetail($serviceJiraFields)
                #jemhIncludeBody()
                #jemhIncludeDirectiveSetLinks()
                #renderCustomerSatisfaction()
                #jemhIncludeAddComment()
                #jemhIncludeFooter()
            </table>
        </td>
    </tr>
</table>
#inhibitSendingConditions()
#else
 #set ($serviceJiraUpdateFields = ['issuetype','summary','description','customfield_10200', 'security', 'labels'])
 <h3>Jira Notification (more)</h3
 <table id="background-table" cellpadding="0" cellspacing="0" width="100%">
    <!-- header here -->
    #jemhIncludeStandardActionHeader()
    <tr>
        <td id="email-content-container">
            <table id="email-content-table" cellspacing="0" cellpadding="0" border="0" width="100%">
                #jemhIncludeIssueHeader()
                #jemhIncludeIssueDetail($serviceJiraFields)
                #jemhIncludeChangeLogDetails()
                #jemhIncludeBody()
                #jemhIncludeDirectiveSetLinks()
                #renderCustomerSatisfaction()
                #jemhIncludeAddComment()
                #jemhIncludeFooter()
            </table>
        </td>
    </tr>
</table>
#inhibitSendingConditions()
 #end
#end

Editing the content

Editing a TemplateSet gives access to relevant content (sometimes html is not supported/appropriate)

Macros

Macros are reusable ‘methods’ that can be defined and 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). These themes have theme-specific macros, to see their definition, go to JEMHC > Notifications > Templates > Themes, there is a checkbox “show system defaults” that shows the system themes, from there you can access their macro and css definitions.

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.

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.

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!

Enterprise Mail Handler for Jira Cloud (JEMHC)