Email templates define the content and layout of the emails that may be sent using Email This Issue.
Templates come to life when they are used sending The Email Button and the Email Screen, as Email Notification Schemes or from Workflow Post Function. You can configure Manual Emails, Email Notifications and Email This Issue workflow post functions with your custom templates.
Build Templates
Templates may contain static and dynamic content such as issue fields, custom fields, comments, worklog details - practically anything related to issues, projects and users.
It is possible to build templates from scratch, but there are predefined template themes that help get started with custom templates.
Themes
Themes help you build your own templates for various goals. Click the Add button to add new templates from themes.
| Theme | Description |
|---|---|
| All Details | As the name implies, this theme may be used to add templates that are supposed to 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 | Theme to start a template from scratch |
How an Email Template is Built
Email Templates may be developed using using Apache Velocity Markup. Email templates are built from three major parts:
- Subject Template
- HTML Body Template
- Text Body Template
Category: Emails can be grouped by categories. You can enter any text for here, a category will be automatically created if not exists. There are special categories for special uses:
- Response: by default templates in this category are selectable as canned response on the Email Screen
Subject Template
Subject template part of an Email Template is used to generate the final subject of the emails sent using this template. The Subject Template may contain static text and dynamic content such as issue fields and custom fields.
The variable $!mailSubject is replaced by the Subject you enter in the Email Notification Schemes or Workflow Post Function.
When you send The Email Button and the Email Screen, the Subject Template is used to pregenerate the Subject for your in the The Email Button and the Email Screen. The subject you enter in the email screen, will not be further modified by the email templates when the email is sent.
HTML Body Template
HTML Body Template part 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 your templates customizable look and layout.
The HTML Body template may be developed using a WYSIWYG editor. With this editor everyone can develop templates without HTML coding experience.
The Rich Text editor provides lots of features. It allows you to easily apply formatting, add tables, images, links, preview the template and edit content in full screen.
HTML Body may include issue fields and custom fields. Furthermore complex structures like all comments, issue link information, change history etc.
In case the Rich Text Editor would not be sufficient or you prefer tweak HTML directly, just open the HTML Editor and make changes directly to the source code of the template.
Embedding images
You can tell JETI to embed an image targeted by a URL on <img> tag level. This way you can send out attachments of the issue, and the recipient does not need to connect (hence don't need to create a Jira user account) to see the attachment.
To achieve this, just add the data-embed="true" attribute to the <img> element.
Eg:
<img src="https://www.meta-inf.hu/download/attachments/35749899/icon_product_jeti.png?version=1&modificationDate=1524212907169&api=v2" data-embed="true">
This will cause that the image will be downloaded and attached to the email.
Text Body Template
Text Body Template part is used to send pure text emails with this email template.
Obviously, the Text Body part may also contain issue fields, custom fields and the same set of complex structures as the HTML Body.
Field Picker
Field Picker is a handy dropdown 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
Below is the list of variables that are available in the email templates.
| Variable | Description | Example | Type |
|---|---|---|---|
| currentUser | The current user object who's sending the email | $!currentUser.displayName Renders the full name of the current user | User |
| mailSubject | Email subject entered manually in the Subject field in the manual email screen, notifications or workflow post functions. | String | |
| mailBody | Email body entered manually in the Body field in the manual email screen, notifications or workflow post functions.
| 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 | 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 | Issue event object if the email is being sent as an event notification | IssueEvent | |
| comment | The comment the user enters during the operation. E.g. when editing an issue or executing a workflow transition. | #renderComment() Renders the comment | Comment |
| changeLog | Changelog object 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 | Worklog object holding details of the worklog entered or edited. | #renderWorklog() Renders the worklog details | Worklog |
| emailCommand | Email definition object holding all recipients, subject and body, issue event and 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 | Support object useful in templates. Constantly enhanced object, it will receive more and more methods. | TemplateSupport |
Velocity Macros
Below is the list of macros that are available in the email templates.
| Macro signature | Parameters | Description | Example |
|---|---|---|---|
| #renderDateTime($dateTimeValue $pattern $timezone) |
| 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) |
| 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 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) |
| renders a link to the portal with a custom text. | #renderLinkToPortal("View Customer Portal") |
| #renderLinkToPortalRequest($linkText) |
| renders a link to the request with a custom text. | #renderLinkToPortalRequest("Open request") |
| #renderAllComments($comments) |
| Renders all comments (both public and internal) comments | #renderAllComments($!issue.comments) |
#renderChanges() | Renders the changelog in a readable structure | #renderChanges() | |
| #renderComments($comments) |
| Renders the public comments | #renderComments($!issue.comments) |
| #renderCommentsInReverseOrder($comments) |
| Renders the public comments in reverse order | #renderCommentsInReverseOrder($!issue.comments) |
| #renderCustomField($issue $customFieldKey) |
| Renders the value of the custom field as displayed in jira | #renderCustomField($!issue, 'customfield_10603') |
| #renderLastComment($issue) |
| Renders the last comment of the issue | #renderLastComment($!issue) |
Template Operations
Templates offer a handful of operations under the ... actions menu.
| Template Operation | Description |
|---|---|
| Test | Opens the Test Template Dialog, see below. |
| 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 |
Test Template
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.
However, the ultimate and best way to validate the correctness of a template is to use 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, look into your email app and verify the content and layout was according your expectations.