Scenario

JEMH exposes JIRA's notification templates and macros, allowing extensive customization of the content that your JIRA outputs.  This can mean anything from a small modification of an existing default template, to a complete overhaul of your entire template collection.

Templates are constructed using the Velocity Template Language.  If you plan on making use of custom templates, it is recommended that you have an understanding of Velocity by reading the Velocity User Guide.  It is also worth checking out Atlassian's documentation regarding Customising Email Content.

Customization pointers

Consulting the Velocity Context list

You can see what methods are available for use in your templates by referring to the Velocity Context List (JEMH>Template Sets>Velocity Context).  The list shows the key that represents a class.  The class is then referred to in the template by using a leading "$" followed by the key:

$issue

By consulting the class associated with that key, you can find the method that is needed.  Then, this method can be used by adding a method body to the end of the key in the template:

$issue.getKey()

Useful variables to remember

Macros

JIRA's default templates make extensive use of Macros.  These are located with JIRA_INSTALL/atlassian-jira/WEB-INF/classes/templates/email/macros.vm, but since JEMH 1.6.x these can be viewed via JEMH>Template Sets>Macros.  To customize content, it may be necessary to take existing macros and re-work them to suit your needs.  To assist with this, the User Macros tab allows you to define your own macros and test their functionality.  See How Do I Use Macros for more information.

Using Jira Macros in Template

As mentioned Jira’s default templates make extensive use of Macros, and since JEMH 1.6.x these can be viewed via JEMH>Template Sets>Macros. These Macros can be used as they are in your own Templates, for example:

Macro in JEMH

Using Macro in Template

Using Jira Macros as Template guidelines

In some cases, you might need to use something similar to an existing Jira Macro but cannot use the exact Macro. In this case, you can use JEMH to view existing Jira Macros as a guideline. For example, I might want to use the 'Fix Version' Macro from the last example, without putting the values in a table:

In this example we can take the heading, and value outside of the Table Row and use them independently.

#if ($issue.fixVersions && $issue.fixVersions.size() >0)
    #text("template.fix.versions"): 
    #foreach ($fixfor in $issue.fixVersions)
        $fixfor.name #if ($velocityCount != $issue.fixVersions.size()), #end 
    #end
#end

Value in template:

Custom Templates can result in IGNORED event status

When JEMHC processes a webhook Event, the default templates indicate when a comment or field is rendered. If you start with an EMPTY template and leave out the following, your event will likely end up with an IGNORED status as JEMHC believes that no ‘content’ was rendered.

Include the following as appropriate:

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

Specific Examples

Here there are some specific examples of velocity mark-up for extracting particular issue fields.  Sometime specific minimum versions of JEMH are required

Rendering user Avatars

since JEMH 3.1.15

#if ($!issue.getAssignee())
#rowWrapperNormalBegin('' 'wrapper-special-margin')
 #set ($assignee = $issue.getAssignee())
 #set ($avatarUrl = $jemhUtils.getUserAvatarURL($assignee, 24))
 <table style="border-radius: 10px;background:#FFEEFF;padding:10px;width: 600px;height: 50px;">
     <tr><th width="100">Your agent is:</th><td><img src="$avatarUrl" width="24" height="24" alt="alt text"></img> $assignee.getDisplayName()</td></tr>
     <tr><th>Email:</th><td>$assignee.getEmailAddress()</td></tr>
     <tr><th>Phone:</th><td>todo</td></tr>
 </table>
#rowWrapperNormalEnd()
#end

looks like:

Issue Watchers

since JEMH 1.6.22

#set ($allWatchers = $watcherManager.getCurrentWatcherUsernames($issue))
#foreach ($aWatcherUsername in $allWatchers)
#set ($applicationUser = $userManager.getUserByName($aWatcherUsername))
- watcher userName: $aWatcherUsername , email = $applicationUser.getEmailAddress(),displayName = $applicationUser.getDisplayName()
#end

Custom Fields

Here is an example of including a custom field that has the numeric ID 1481.  First, you need to locate the ID of a custom field. There are two ways to do this:

Once you have the custom fields ID, you can use the $issue to get the custom field value:

#if ($!issue.getCustomField("customfield_11300") && $!issue.getCustomFieldValue("customfield_11300")) 
  Some Custom Field : $issue.getCustomFieldValue("customfield_11300")
#end

#if ($!customFieldManager.getCustomFieldObject("customfield_11300") && $!issue.getCustomFieldValue("customfield_11300")) 
  Some Custom Field : $issue.getCustomFieldValue("customfield_11300")
#end

User Properties

This example script will list all user properties and show all text/string and boolean values.

#set ($targetUser = $issue.getReporter())
#set ($userProps = $userPropertyManager.getPropertySetForUserKey($targetUser.getKey()))
userPropertySet class: $userProps.getClass()
#set ($prpKeys = $userProps.getKeys())
Keys class: $prpKeys.getClass()
propertysSet size size: $prpKeys.size()
----------- user properties ---------------
#foreach ($aKey in $prpKeys)
#set ($propType = $userProps.getType($aKey))
$aKey[$propType] : #if ($propType==1) boolValue=$userProps.getBoolean($aKey) #elseif ($propType==5) stringValue=$userProps.getString($aKey) #elseif ($propType==6) textVal=$userProps.getText($aKey)#end]
#end
----------

Example extract:
"atl.jira.admin.current.project" = $userProps.getString("atl.jira.admin.current.project")

Rendering a Custom Field as Wiki mark-up

The velocity context contains $wikiRenderer for this purpose (see the API, its linked in the Velocity Context docs within the JEMH TemplateSet section):

HTML output

#if ($!issue.getCustomField("customfield_11300") && $!issue.getCustomFieldValue("customfield_11300")) 
   $wikiRenderer.render($issue.getCustomFieldValue("customfield_11300"),null)
#end

TEXT output

#if ($!issue.getCustomField("customfield_11300") && $!issue.getCustomFieldValue("customfield_11300")) 
  $wikiRenderer.renderAsText($issue.getCustomFieldValue("customfield_11300"),null)
#end

HTML output

#if ($!customFieldManager.getCustomFieldObject("customfield_11300") && $!issue.getCustomFieldValue("customfield_11300")) 
   $wikiRenderer.render($issue.getCustomFieldValue("customfield_11300").toString(),null)
#end

TEXT output

#if ($!customFieldManager.getCustomFieldObject("customfield_11300") && $!issue.getCustomFieldValue("customfield_11300")) 
  $wikiRenderer.renderAsText($issue.getCustomFieldValue("customfield_11300"),null)
#end

Access custom field values from a Parent Issue

The following velocity can be used to access the custom field values of a parent issue in a notification for a sub-task issue.

#set ($cfVal = $customFieldManager.getCustomFieldObject("customfield_11300") )
Custom field=$issue.getParentObject().getCustomFieldValue($cfVal)

Embedding a specific Attachment (Jira 8.0.0 + )

Prequisite
Ensure that Include Attachments in Notifications is enabled in your JEMH > Notification > Non-Jira/Jira Notification Project Mappings.

Script
The Script below will render an attachment link to the notification where “test.txt” is a placeholder additionally this will embed the file to the notification.

 $rendererManager.getRenderedContent("atlassian-wiki-renderer", "[^test.txt]", $issue.getIssueRenderContext())

how the link looks:

Rendering Customer request types

Status
colour Red title since 3.3.40

The script bellow can be used to retrieve information related to Customer Request Types. This only works in JSM projects that use Customer Request types.

#set($customField = $customFieldManager.getCustomFieldObjectByName("Customer Request Type"))

#if($!customField.getValue($issue))
#set($requestType = $jemhUtils.getRequestType($customField.getValue($issue).toString()))

$requestType.getName()
$requestType.getDesc()
$requestType.getIssueTypeId()
#else
No request type
#end

How it looks

Additional Examples

For Additional examples see the following pages