| Redirect | ||||||
|---|---|---|---|---|---|---|
|
| Note | ||
|---|---|---|
| ||
Thank you for visiting our old product documentation site. Note that weare in the process of migrating our product documentation and soon we will notno longer store or update our documentation here.Please navigate to our new documentation site and update your bookmarks accordingly. If you're looking for the former content of this page, click here. |
| Table of Contents |
|---|
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.
...
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.
...
$!currentUser.displayName
Renders the full name of the current user
...
Email body entered manually in the Body field in the manual email screen, notifications or workflow post functions.
...
$!issue.summary
Renders the issue summary in the template
...
It is a simple String value you can use in building links.
...
#renderComment()
Renders the comment
...
#renderChanges()
Renders the changelog in a readable structure
...
#renderWorklog()
Renders the worklog details
...
$!emailCommand.attachments
Returns the list of attachments being added to the email
...
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
...
triggerType
...
Provides information about what type of event triggered the email sending.
Possible values:
OPERATION: The email is being sent manually
EVENT: The email is triggered by an issue event (created, commented... etc)
WORKFLOW: The email is triggered by a workflow transition
HANDLER: The email is triggered by a mail handler action
...
#if("$!triggerType" == "OPERATION")
<p>This is a manual email</p>
#end
prints 'This is a manual email' when the email was sent manually
...
Velocity Macros
Below is the list of macros that are available in the email templates.
...
here |
...
#renderDateTime($!issue.created "dd MMM yyyy hh:mm a" "Australia/West")
...
- $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
...
Generic, multi-purpose comment rendering macro.
...
...
- $linkText: text to show for the link in html mails.
- Default value: "View portal"
- in case of text email this parameter is ignored and the full URL will be generated
...
- $linkText: text to show for the link in html mails
- Default value: "View request"
- in case of text email this parameter is ignored and the full URL will be generated
...
- $comments: The comments to render
...
#renderChanges()
...
- $comments: The comments to render
...
- $comments: The comments to render
...
- $issue: the issue in the context
- $customFieldKey
- key of the custom field(eg. customfield_10001)
...
- $issue: The issue
...
- $versions: the list of versions to render
...
#set($comment = $!issue.lastComment)
#renderComment()
...
#renderComponents($components)
...
- $components: the list of components to render
...
#renderComponents($!issue.components)
...
- $dateValue: 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
...
#renderLabels($labels)
...
- $labels: the list of labels to render
...
#renderLabels($!issue.labels)
...
- $listitems: the list of items to be rendered
...
- $issue: the issue whose type is to be rendered
...
- $issue: the issue whose status is to be rendered
...
- $issue: the issue whose priority is to be rendered
...
- $user: the user to be rendered
...
#renderAllCustomFields($issue)
...
- $issue: the issue whose custom fields are to be rendered
...
#renderCustomFieldValue($fieldValue)
...
- $fieldValue: the value of a custom field to be rendered
...
Concatenate text to URLs
It is possible to add certain text to a URL link in a template.
For this, open the template in its raw HTML editor form and use the following code:
| Code Block |
|---|
#set($url = $issue.getCustomFieldValue('customfield_12345').value) <a href="$url/go" target="_blank">$url/go</a> |
Make sure to use the correct customfield ID as per the below example:
Template Operations
Templates offer a handful of operations under the ... actions menu.
...
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.
...
. |