# Customizing email templates Email templates define the content and layout of the emails that are sent using [The Email Button and the Email Screen](https://docs.meta-inf.hu/email-this-issue/outgoing-emails/manual-emails/email-this-issue-for-jira-cloud-the-email-button-and-the-email-screen), as [Email Notification Schemes](https://docs.meta-inf.hu/email-this-issue/outgoing-emails/email-this-issue-for-jira-cloud-email-notification-schemes) or as [Workflow Post Function](https://docs.meta-inf.hu/email-this-issue/outgoing-emails/email-this-issue-for-jira-cloud-workflow-post-function), all of which you can configure with your custom templates. To manage templates, do the following: 1\. Go to **Templates** under the **EMAIL CONTENT** menu item of the **Outgoing Mails** configuration tab. 2\. Click on **Add** to create a new template or click on the three dots and choose **Edit** to modify an already existing template.

Templates may contain static and dynamic content related to issues, projects and users, such as: * Issue fields * Custom fields * Comments * Worklog details It is possible to build templates from scratch, and there are predefined template themes that help to get started with custom templates. ### Themes Themes help you to build your own templates for various goals. Click the **Add** button to add new templates from themes.

| 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. | ## Building email templates Email Templates may be built using using Apache Velocity Markup. Aspects to consider: * **Basic Settings** * **HTML Template** * **Text Template** ### **Setting up Basic Settings**

**Category:** Emails are grouped into categories. Enter any text, and a category will be automatically created if doesn't already exist. There are special categories for special uses, for instance the responses. By default, templates in this category can be selected as a canned response on the [Email Screen](https://docs.meta-inf.hu/email-this-issue/manual-emails/email-this-issue-for-jira-cloud-the-email-button-and-the-email-screen#TheEmailButtonandtheEmailScreen-EmailScreen). ### **Setting up the** Subject Template Subject templates are part of an Email template. They are used for generating the final subject of the emails sent using this template. The Subject template can contain static text and dynamic content, such as issue fields and custom fields.

The **$!mailSubject** variable is replaced by the subject you enter in the [Email Notification Schemes](https://docs.meta-inf.hu/email-this-issue/outgoing-emails/email-this-issue-for-jira-cloud-email-notification-schemes) or [Workflow Post Function](https://docs.meta-inf.hu/email-this-issue/outgoing-emails/email-this-issue-for-jira-cloud-workflow-post-function). When you send a manual email, the Subject Template is used for generating the subject in the [The Email Button and the Email Screen](https://docs.meta-inf.hu/email-this-issue/outgoing-emails/manual-emails/email-this-issue-for-jira-cloud-the-email-button-and-the-email-screen). The subject you enter in the email screen is not modified further by the email templates when the email is sent. ### **Setting up the** HTML Template HTML Template is used when an HTML email is sent using this email template. The HTML body may be combined with HTML and Apache Velocity Markup to give templates a customizable look and layout. The HTML template may be developed using a WYSIWYG editor. With this editor everyone can develop templates without HTML coding experience.

The Rich Text editor allows users to apply formatting, add tables, images, links, preview the template and edit content in full screen. HTML can include issue fields and custom fields, and complex structures such as: * Comments * Issue link information * Change history To edit HTML directly, open the HTML Editor and make changes to the source code of the template.

### Embedding images Email This Issue can embed an image targeted by a URL on an `` tag level. This way you can send out attachments of the issue, and the recipient does not need to connect and create a Jira user account to see the attachment. To allow this feature, add the `data-embed="true"` attribute to the `` element. Example: ```markup

``` ### **Setting up the** Text Template The Text Template is used for sending pure text emails with this email template.

The Text Body part can also contain issue fields, custom fields and the same set of complex structures as the HTML Body. ### Using the Field Picker Field Picker is a dropdown list of all issue fields and custom fields. When a field is selected, a tiny popup dialog opens with the template code fragment needed to render the value of the field in the email. Click the button in the dialog to add the code to the cursor position. The Field Picker is available for Subject Template, HTML and Text Body templates.

## Velocity Context for Templates The following is a list of variables that are available in the email templates. | Variable | Definition | Example | Type | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `currentUser` | The current user sending the email |

$!currentUser.displayName

Renders the full name of the current user.

| [User](https://metainf.atlassian.net/wiki/display/JETIC/API+for+Velocity+Context+Objects#APIforVelocityContextObjects-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.

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.

$!issue.summary

Renders the issue summary in the template.

| [Issue](https://metainf.atlassian.net/wiki/display/JETIC/API+for+Velocity+Context+Objects#APIforVelocityContextObjects-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](https://metainf.atlassian.net/wiki/display/JETIC/API+for+Velocity+Context+Objects#APIforVelocityContextObjects-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](https://metainf.atlassian.net/wiki/display/JETIC/API+for+Velocity+Context+Objects#APIforVelocityContextObjects-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](https://metainf.atlassian.net/wiki/display/JETIC/API+for+Velocity+Context+Objects#APIforVelocityContextObjects-Changelog) | | `worklog` | The worklog object holding details of the worklog entered or edited. |

#renderWorklog()

Renders the worklog details.

| [Worklog](https://metainf.atlassian.net/wiki/display/JETIC/API+for+Velocity+Context+Objects#APIforVelocityContextObjects-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](https://metainf.atlassian.net/wiki/display/JETIC/API+for+Velocity+Context+Objects#APIforVelocityContextObjects-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.

$!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](https://commons.apache.org/proper/commons-lang/javadocs/api-3.5/index.html?org/apache/commons/lang3/StringUtils.html) | | `templateSupport` | The support object useful in templates. A constantly enhanced object, that will receive more and more methods. | | [TemplateSupport](https://metainf.atlassian.net/wiki/display/JETIC/API+for+Velocity+Context+Objects#APIforVelocityContextObjects-TemplateSupport) | ## Velocity Macros The following is the list of macros that are available in the email templates. {% hint style="warning" %} According to [Atlassian's announcement](https://community.developer.atlassian.com/t/deprecation-of-the-epic-link-parent-link-and-other-related-fields-in-rest-apis-and-webhooks/54048), the 'Epic Link' custom field will be deprecated as of 31th May 2022. As a consequence, exisiting macros utilizing the 'Epic Link' value (usually in a form of `#renderCustomField($!issue 'customfield_10014'` - however, the custom field ID can vary per site) won't work after this deadline. Please, review and consider replacing your old macros with any of our new offerings (`#renderParent` or `#renderParentEpic`). {% endhint %} {% hint style="info" %} Due to some known limitations in hierarchy level retrieval for custom issue types introduced in *Advanced Roadmaps* (verified by Atlassian in [this community announcement](https://community.atlassian.com/t5/Jira-articles/Rename-epics-in-your-company-managed-projects/ba-p/1874726)), the `#renderParent` macro currently does not work as expected for higher hierarhy levels than that of Epic (1).\ E.g. `#renderParent($!issue, 2)` will not render a parent having 'Initiative' issue type (hierarchy level 2). {% endhint %} | 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: 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

$comments: The comments to render

$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

$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

#renderParent($!issue, 0) => renders Story/Task or higher level (e.g. Epic) parent issue
#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)` | ### Assets related macros {% hint style="danger" %} Please note that the following macros display Assets Objects with **all (including hidden)** of their attributes by default. Use the $attributes parameter to customize this behavior. {% endhint %} | Macro signature | Parameters | Description | Example | | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

#renderAssetsCustomField($issue $customFieldKey $attributes

$runAsUserName

)

$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
$runAsUserName: Optional: a custom user name used to run AQL queries. If not provided, the query runs with the permissions of the action's initiator. Can be displayname or email address. Account id can also be specified with the following syntax: accountId:\

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'])

With runAsUserName, without custom attributes:
#renderAssetsCustomField($!issue "customfield\_10006", $null, "assetsViewUser")

| | #renderAssetsCustomFieldAttribute($issue $customFieldKey $attributeName $runAsUserName) |

$issue: the issue in the context
$customFieldKey
- key of the custom field(eg. customfield\_10001)
- The type of the field must be Assets Object
$attributeName: the name of the attribute
$runAsUserName: Optional: a custom user name used to run AQL queries. If not provided, the query runs with the permissions of the action's initiator. Can be displayname or email address. Account id can also be specified with the following syntax: accountId:\

| Renders only the value of the attribute, which name was given |

Render asset attribute:
#renderAssetsCustomFieldAttribute($!issue, 'customfield\_10093', 'Name')

With runAsUserName:
#renderAssetsCustomFieldAttribute($!issue, 'customfield\_10093', 'Name', 'assetsViewUser')

| |

#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)` | It is possible to render only the object names from an Assets field by using the `#renderCustomField($issue $customFieldKey)` macro. ## Concatenating text to URLs It is possible to add certain text to a URL link in a template. Open the template in its raw HTML editor form and use the following code: ```java #set($url = $issue.getCustomFieldValue('customfield_12345').value) $url/go ``` Make sure to use the correct `customfield` ID as shown in the following example: ![](https://880912854-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Mf8H-oTE_fhOrUtfYrN%2F-MjTB0TRUCTl_NQSL6SD%2F-MjTME7N-n07GdGtieW7%2Foutgoing_22.jpg?alt=media\&token=51115346-92cb-4662-b5e2-fb2f8df19b24) ## Template operations Templates offer a handful of operations under the three dots. | 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 | ### Testing templates While developing a template it is necessary to validate the look, layout and content the template renders. For the HTML Body you can use the rich text editor's *Preview* function to check the layout and content, but the best way to validate whether a template is correct is using the *Test* operation. It allows you to enter an issue key and send yourself an HTML or Text formatted email.

Once the email was sent, verify in your email app whether the content and layout was according your expectations.