Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 19 Current »

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.

ThemeDescription
All DetailsAs the name implies, this theme may be used to add templates that are supposed to render all issue fields, including custom fields.
Issue CommentedThis theme is useful for notifications on events that contain comments. E.g. when an issue is commented or a transition is executed.
Issue UpdatedThis theme focuses on highlighting changes made to an issue.
Work LoggedThis theme gathers worklog information, it is useful for notifications on worklog related events.
EmptyTheme 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.

VariableDescriptionExampleType
currentUserThe current user object who's sending the email

$!currentUser.displayName

Renders the full name of the current user

User
mailSubjectEmail 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.


Add this variable to all templates where you want to render email body entered by the users.


String
issueThe 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
baseUrlBase 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
issueEventIssue event object if the email is being sent as an event notification
IssueEvent
commentThe comment the user enters during the operation. E.g. when editing an issue or executing a workflow transition.

#renderComment()

Renders the comment

Comment
changeLogChangelog 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
worklogWorklog object holding details of the worklog entered or edited.

#renderWorklog()

Renders the worklog details

Worklog
emailCommandEmail 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
stringUtilsString 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
templateSupportSupport 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 signatureParametersDescriptionExample
#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

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 text email this parameter is ignored and the full URL will be 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 text email this parameter is ignored and the full URL will be 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) comments#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)

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:

#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.

Template OperationDescription
TestOpens the Test Template Dialog, see below.
CopyOpens the template editor screen with a copy of the current template.
EditOpens the template editor
DeleteDeletes 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.



  • No labels