Customizing email templates

Theme

Description

All Details

This theme is used for adding templates that render all issue fields, including custom fields.

Issue Commented

This theme is useful for notifications on events that contain comments, e.g. when an issue is commented, or a transition is executed.

Issue Updated

This theme focuses on highlighting changes made to an issue.

Work Logged

This theme gathers worklog information. It is useful for notifications on worklog-related events.

Empty

An empty theme for starting a template from scratch.

Variable

Definition

Example

Type

currentUser

The current user sending the email

$!currentUser.displayName

Renders the full name of the current user.

User

mailSubject

The email subject entered manually in the subject field on the manual email screen, notifications or workflow post functions. In case of a Send auto reply action this will represent the subject of the original email.

String

mailBody

The email body entered manually in the Body field in the manual email screen, notifications or workflow post functions.

Add this variable to all templates to render an email body entered by users. In case of a Send auto reply action this will represent the body of the original email.

String

issue

The Issue object with all available fields. The email is being sent in relation to this issue.

$!issue.summary

Renders the issue summary in the template.

Issue

baseUrl

The base URL of the Jira Cloud site. Useful to add links to Jira screens or operations.

It is a simple String value you can use in building links.

String

issueEvent

The issue event if the email is being sent as an event notification.

IssueEvent

comment

The comment the user enters during the operation. E.g. when editing the issue or executing a workflow transition.

#renderComment()

Renders the comment.

Comment

changeLog

The changelog holding information about all fields changed during the operation. Old and new values are available.

#renderChanges()

Renders the changelog in a readable structure.

Changelog

worklog

The worklog object holding details of the worklog entered or edited.

#renderWorklog()

Renders the worklog details.

Worklog

emailCommand

The email definition object holding all recipients, the subject and body, the issue event and the comment details.

$!emailCommand.attachments

Returns the list of attachments being added to the email.

EmailCommand

sentDate

A formatted date representing when the original email was processed by Email This Issue.

Available only in Reply/Reply all/Forward for an email.

$!sentDate

Prints the when the email was processed by Email This Issue.

String

stringUtils

String helper methods

$!stringUtils.isBlank($!issue.summary)

returns true if the issue summary is empty or null.

$!stringUtils.join($!issue.labels, ", ")

prints the labels separated by comma.

org.apache.commons.lang3.StringUtils

templateSupport

The support object useful in templates. A constantly enhanced object, that will receive more and more methods.

TemplateSupport

Macro signature

Parameters

Description

Example

#renderDateTime($dateTimeValue $pattern $timezone)

• $dateTimeValue: the value to be formatted

• $pattern: the pattern describing the date and time format. You can find description about formatting and patterns here.

• $timezone: the time zone used for formatting. You can find a list of in the Supported Time Zones Appendix.

Formats a dateTime field based on the pattern and the timezone.

#renderDateTime($!issue.created "dd MMM yyyy hh:mm a" "Australia/West")

#renderIssueComments($order $num $restrictions)

• $order: "asc" or "desc"

• $num: an positive integer number or "all" to render all comments matching <restrictions>

• $restrictions: comment restrictions, values are:

  • empty: render all comments regardless of the restrictions

  • "none": render comments which are not limited to groups, roles or which are not internal in Service Management

  • "public": render Service Management public comments

  • "internal": render Service Management internal comments

A generic, multi-purpose comment rendering macro.

#renderIssueComments("desc" "all" "") prints all comments starting with the latest one.

#renderIssueComments("asc" "all" "")prints all comments starting with the first one.

#renderIssueComments("desc" "1" "") prints the latest comment.

#renderIssueComments("desc" "all" "none") prints all comments which are not restricted.

#renderIssueComments("desc" "all" "public") prints all public comments starting with the latest one.

#renderLinkToPortal($linkText)

• $linkText: text to show for the link in html mails.

  • Default value: "View portal"

  • In case of a text email this parameter is ignored, and the full URL is generated.

Renders a link to the portal with a custom text.

#renderLinkToPortal("View Customer Portal")

#renderLinkToPortalRequest($linkText)

• $linkText: text to show for the link in html mails

  • Default value: "View request"

  • In case of a text email this parameter is ignored, and the full URL is generated.

Renders a link to the request with a custom text.

#renderLinkToPortalRequest("Open request")

#renderAllComments($comments)

• $comments: The comments to render

Renders all comments (both public and internal).

#renderAllComments($!issue.comments)

#renderChanges()

Renders the changelog in a readable structure.

#renderChanges()

#renderComments($comments)

• $comments: The comments to render

Renders the public comments.

#renderComments($!issue.comments)

#renderCommentsInReverseOrder($comments)

• $comments: The comments to render

Renders the public comments in reverse order.

#renderCommentsInReverseOrder($!issue.comments)

#renderCustomField($issue $customFieldKey)

• $issue: the issue in the context

• $customFieldKey

  • key of the custom field(eg. customfield_10001)

Renders the value of the custom field as displayed in Jira.

#renderCustomField($!issue, 'customfield_10603')

#renderLastComment($issue)

• $issue: The issue

Renders the last comment of the issue.

#renderLastComment($!issue)

#renderParent($issue, hierarchyLevel)

• $issue: The issue, whose parent issue shall be rendered

• $hierarchyLevel: the minimal hierarchy level of the parent issue to be rendered

Renders the parent issue of the issue passed as parameter, only if the hierarchy level of the parent issue is higher than or equal to the specified hierarchy level.

Hierarchy levels of some known issue types:

• sub-task: -1

• task/story: 0

• epic: 1

1. #renderParent($!issue, 0) => renders Story/Task or higher level (e.g. Epic) parent issue

2. #renderParent($!issue, 1) => renders Epic or higher level (e.g. Initiative) parent issue

#renderParentEpic($issue)

$issue: The issue, whose parent issue shall be rendered

Renders the parent issue of the issue passed as parameter, only if the parent issue is an Epic.

In this regard, it can be considered as a replacement for the former 'Epic Link' custom field renderer.

#renderParentEpic($!issue)

#renderAssetsCustomField($issue $customFieldKey $attributes)

• $issue: the issue in the context

• $customFieldKey

  • key of the custom field(eg. customfield_10001)

  • The type of the field must be Assets Object

• $attributes Optional: the name of the attributes you want to include

Renders all assets objects in the field with their labels and all of their attributes or selected attributes. Please note that if you do not specify an attribute list all attributes (not visible, hidden, etc.) will be included in the email.

Render asset all attributes:

#renderAssetsCustomField($!issue, 'customfield_10093') Render asset with the created date and the status:

#renderAssetsCustomField($!issue, 'customfield_10093', ['Created', 'Asset Status'])

#renderAssets($aql $attributes $limit)

• $aql: search query in Assets Query Language

• $attributes: Optional the attributes to display (used the same way as in the #renderAssetsCustomField macro).

• $limit: Optional the maximum number of Assets Objects to display. Default: 10 Maximum: 100

Renders the labels and attributes of Assets Objects returned by the given AQL query.

Render assets with the default limit and all attributes: #renderAssets('objectId IN (1, 2, 3)') Render assets with custom limit and all attributes: #renderAssets('objectId IN (1, 2, 3)', $null, 25)

Render assets with their Created date and Status within a custom limit of maximum 25 asset objects: #renderAssets('objectId IN (1, 2, 3)', ['Created', 'Asset Status'], 25)

#renderAssetsLabel($aql $limit)

• $aql: search query in Assets Query Language

• $limit: Optional the maximum number of Assets object to display. Default: 10 Maximum: 100

Renders the labels of Assets Objects returned by the given AQL query.

#renderAssetsLabel('objectId IN (1, 2, 3)', 5)

Template operation

Definition

Test

Opens the Test Template dialog.

Copy

Opens the template editor screen with a copy of the current template.

Edit

Opens the template editor.

Delete

Deletes the template from the system