Velocity Context in email templates
Email templates are velocity macro files. When email templates are used to render email body, the following Velocity context attributes are available.
Name | Type | Description |
---|---|---|
attachmentsManager | Manager component | |
baseurl | String | The base url of the Jira instance, set under General Configuration. |
buildutils | ||
customfieldManager | Support for adding custom fields to outgoing emails | |
dateformatter | Date format support | |
issue | Issue extended with support for processing in velocity templates | |
i18n | I18n support | |
jirakeyutils | ||
jirautils | ||
remoteUser | Current user running the action or null | |
rendererManager | ||
stringUtils | String helper methods | |
textutils | Jira's text util methods | |
userutils | ||
jetiFieldRenderer | Support for field rendering in templates | |
jetiFieldFormatter | Support for date/time formatting in templates | |
templateSupport | Support for email templates, rendering, formatting | |
number | ||
currentUserInfo | $!currentUserInfo.user : current user object
$!currentUserInfo.roles : current user's project roles
$!currentUserInfo.groups : current user's groups. | |
userPropertyManager | Access to Jira user properties. Usage: References to user properties by property name must be prefixed with " jira.meta ." due to the nature of the Jira API.E.g. If the user has a property, called "phone", the phone property may be rendered as $!userPropertyManager.getPropertySet(<user object>).getString("jira.meta.phone") | |
currentTimestamp | Date and time of rendering the template, this like "now". | |
jiraDurationUtils | Util class responsible for printing durations in various formats. | |
diffutils | Compares two string values and renders wiki markup diffs. | |
isJIRA610OrLater | boolean | Determines whenever the currently installed Jira version is at least 6.1.0 |
datetimeformatter | Date-time format support | |
timeSpentFieldId | String | The ID of the issue's time spent field |
padSize | Integer | Default padding size for templates (20) |
lfbean | Support for accessing Jira's look and feel parameters | |
menuTextHighlightColour | String | Jira's menu text highlight color |
textHighlightColour | String | Jira's text highlight color |
jiraLogoUrl | String | URL that points to Jira's logo image |
topBackgroundColour | String | Jira's top bar background-color |
topTxtColour | String | Jira's top bar text color |
topHighlightColor | String | Jira's top bar highlight color |
topTextHighlightColor | String | Jira's top bar text highlight color |
topSeparatorBackgroundColor | String | Jira's top bar separator background-color |
menuTxtColour | String | Jira's menu text color |
menuBackgroundColour | String | Jira's menu background-color |
menuSeparatorColour | String | Jira's menu separator color |
textHeadingColour | String | Jira's header text color |
textLinkColour | String | Jira's link text color |
textActiveLinkColour | String | Jira's active link text color |
textFontFamily | String | Jira's text font |
textSize | String | Jira's text size |
textColour | String | Jira's text color |
textSubtleColour | String | Jira's subtle text color |
borderColour | String | Jira's border color |
auiPanelBackgroundColour | String | Atlassian User Interface's panel background color |
auiPanelBorderColour | String | Atlassian User Interface's panel border color |
auiInfoBackgroundColour | String | Atlassian User Interface's info panel background color |
auiInfoBorderColour | String | Atlassian User Interface's info panel border color |
auiSuccessBackgroundColour | String | Atlassian User Interface's success panel background color |
auiSuccessBorderColour | String | Atlassian User Interface's success panel border color |
auiErrorBackgroundColour | String | Atlassian User Interface's error panel background color |
auiErrorBorderColour | String | Atlassian User Interface's error panel border color |
auiWarningBackgroundColour | String | Atlassian User Interface's warning panel background color |
auiWarningBorderColour | String | Atlassian User Interface's warning panel border color |
linkstyle | String | Comment author link style |
commentBackgroundl | String | Comment quotes color |
jetiFieldRenderer
provides the following methods to render issue fields:Method | Description | Usage |
---|---|---|
String renderCustomField(Issue issue, String fieldKey); | Renders a custom field value as a string value | $!jetiFieldRenderer.renderCustomField($!issue, "customfield_10011") |
Object renderCustomFieldAsObject(Issue issue, String fieldKey); | Returns the value of the custom field as Raw value. The Raw or Object value allows for further processing or access to methods, and attributes | $!jetiFieldRenderer.renderCustomFieldAsObject($!issue, "customfield_10011") E.g. render the Display name attribute of a user selected in a user picker field $!jetiFieldRenderer.renderCustomFieldAsObject($!issue, "customfield_10011").getDisplayName() |
String renderVersions(Collection<Version> versions); | Renders the given versions as a comma-separated list of version names. | E.g. $!jetiFieldRenderer.renderVersions($!issue.getFixVersions()) |
String renderComponents(Collection<ProjectComponent> components); | Renders the given components as a comma-separated list of component names. | E.g. $!jetiFieldRenderer.renderComponents($!issue.getComponents() ) |
String renderLabels(Collection<Label> labels); | Renders the given labels as a comma-separated list of label names. | E.g. $!jetiFieldRenderer.renderLabels($!issue.getLabels()) |
String renderSecurityLevel(GenericValue securityLevel); | Renders the name of the given Security Level object | $!jetiFieldRenderer.renderSecurityLevel($!issue.getSecurityLevel()) |
String re nderIssueConstant(IssueConstant issueConstant); | Renders the name of an Issue type, Resolution, Priority or Status | $!jetiFieldRenderer.renderIssueConstant($!issue.getPriority()) |
String renderUser(User user); | Renders the DisplayName attribute of a User or Application User object safely, if null, returns empty string | $!jetiFieldRenderer.renderUser($!issue.getAssignee()) |
String renderDateTime(Timestamp ts); | Renders a Timestamp object using Jira's default date format, DateTimeFormat.format( ) | E.g.
|
String renderEstimate(TemplateIssue ti, I18nHelper i18n); | Renders the issue's Original estimate in nicely readable format, like 3d 4h 5m | $!jetiFieldRenderer.renderEstimate($!issue, $i18n) |
String renderRemainingEstimate(TemplateIssue ti, I18nHelper i18n); | Renders the issue's Remaining estimate in nicely readable format, like 3d 4h 5m | $!jetiFieldRenderer.renderOriginalEstimate($!issue, $i18n) |
String renderWorklog(TemplateIssue ti, I18nHelper i18n); | Renders the issue's Logged Work Time in nicely readable format, like 3d 4h 5m | $!jetiFieldRenderer.renderWorklog($!issue, $i18n) |
I18nHelper getI18nBean(String locale); | E.g. get the language resources for French: $!jetiFieldRenderer.getI18nBean("fr") | |
String getLinkToCustomerPortal(Issue issue); | Returns an absolute link to the customer portal belonging to the service management project of the issue. If the issue is not from a Service Management project, it returns null | $!jetiFieldRenderer.getLinkToCustomerPortal($!issue) |
String getLinkToIssueInCustomerPortal(Issue issue); | Returns an absolute link to the issue in the customer portal belonging to the service management project of the issue. If the issue is not from a Service Management project, it returns null | $!jetiFieldRenderer.getLinkToIssueInCustomerPortal
($!issue) |
jetiFieldFormatter
is an object in the template context that may be used to format date or date time values.It provides the following methods:
Method | Description | Usage |
---|---|---|
DateTimeFormatter getJiraDateTimeFormatter() | #set ($formatter = $jetiFieldFormatter.getJiraDateTimeFormatter()) | |
DateTimeFormatter getJiraDateTimeFormatter(String style) | #set ($formatter = $jetiFieldFormatter.getJiraDateTimeFormatter("COMPLETE")) | |
DateFormat getJavaDateFormat() | #set ($formatter = $jetiFieldFormatter.getJavaDateFormat()) | |
DateFormat getJavaDateFormat(int style) | Returns a Java DateFormat object configured with the value of the style constants (see java documentation) | |
DateFormat getJavaDateFormat(int style, String locale) | Returns a Java DateFormat object configured with the value of the style constants (see java documentation) and a locale. | |
DateFormat getJavaDateTimeFormat() | | |
DateFormat getJavaDateTimeFormat(int dateStyle, int timeStyle) | Returns a Java DateFormat object for date time formatting configured with the value of the style constants (see java documentation) | |
DateFormat getJavaDateTimeFormat(int dateStyle, int timeStyle, String locale) | Returns a Java DateFormat object for date time formatting configured with the value of the style constants (see java documentation) and a locale. | |
DateFormat getJavaDateTimeFormat(String pattern) | #set($formatter = $jetiFieldFormatter.getJavaDateTimeFormat("dd/MM/yyyy HH:mm")) | |
String formatSafely(DateFormat formatter, Date value) | Formats a date value using the formatter created using either of the above methods | $!jetiFieldFormatter.formatSafely($!formatter, $issue.updated) or $!jetiFieldFormatter.formatSafely($!formatter, $issue.getCustomFieldValue("customfield_12345")) |
TimeZone getTimeZone(String tzID) | Returns the TimeZone matching the id. TimeZone can be set in the Java date time formatters created above | $!formatter.setTimeZone($jetiFieldFormatter.getTimeZone("America/Los_Angeles")) |
TimeZone getDefaultTimeZone() | | |
String[] getAvailableTimeZoneIDs() | Returns all time zone IDs available in Jira. | |
Method | Description | Usage |
---|---|---|
String encodeUrl(String url); | $!templateSupport.encodeUrl($urlVariable) | |
String encodeUrl(String url, String encoding); | Calls URLEncoder.encode(url, encoding) to encode rendered URLs in email templates using the encoding specified | $!templateSupport.encodeUrl($urlVariable, <desired encoding>) |
boolean issueMatchesJQL(String jqlQuery, Issue issue); | Checks if the given issue matches the JQL query | #if($!templateSupport.issueMatchesJQL("mycustomfield = somevalue AND component=ImportantComponent", $!issue) ## do something... #end |
I18nHelper getI18nHelper(String localeName); | Create an I18nHelper object for the locale Local name is composed of language code and country code. e.g. "fr" is for french language, while "fr_FR" is the french spoken in France. | #set($i18nFrench = $!templateSupport.getI18nHelper("fr_FR") |
I18nHelper getI18nHelper(Locale locale); | Create an I18nHelper object for the locale Local name is composed of language code and country code. e.g. "fr" is for french language, while "fr_FR" is the french spoken in France. | #set($frenchLocale = $!templateSupport.getLocale("fr_FR") #set($i18nFrench = $!templateSupport.getI18nHelper($frenchLocale) |
Locale getLocale(String localeName); | Creates a Java Locale object to be used in date / number formatting or language support. Local name is composed of language code and country code. e.g. "fr" is for the French language, while "fr_FR" is the French spoken in France. | #set($frenchLocale = $!templateSupport.getLocale("fr_FR") |
boolean isAgent(ApplicationUser applicationUser, Project project); | Determines if the given use is an Service Management Agent in the given project. | #if($!templateSupport.isAgent($!issue.reporter, $!issue.projectObject) ... #end |
boolean isInternalComment(Comment comment); | Determines if the give comment is an Service Management Internal comment in the current issue. | #if($!templateSupport.isInternalComment($!comment)) ... #end |
TemplateIssueSearchResults searchForIssuesByJQL(String jql); | Returns a list of issues matching the given JQL query. | #set($searchResults = $!templateSupport.searchForIssuesByJQL("project=IT AND resolution=Unresolved", 10)) #foreach($result in $searchResults.getResults()) $velocityCount - $!result.key (comments: $!result.comments.size()) #end |
String getCustomerVisibleStatus(Issue issue); | Returns the Customer Visible Status name of the issue in a Service Management project. | #set($!customerVisibleStatus = $!templateSupport.getCustomerVisibleStatus($!issue) |
Issue firstIssueMatchingJQL(String jql); | Returns the first issue that matches the given JQL query. | #set($firtstIssue = $!templateSupport.firstIssueMatchingJQL("project = $issue.projectObject.key AND assignee=$!currentUser.name AND priority = Highest")) $!firstIssue.summary |
String getParentValueFromCascadingSelectFieldValue(Map cascadeSelectFieldValue);
String getChildValueFromCascadingSelectFieldValue(Map cascadeSelectFieldValue); | Returns the parent or child value of a Cascade Select custom field. | #set($parentValue = $!templateSupport.getParentValueFromCascadingSelectFieldValue($!issue.getCustomFieldValue("customfield_12345")) #set($childValue = $!templateSupport.getChildValueFromCascadingSelectFieldValue($!issue.getCustomFieldValue("customfield_12345")) customfield_12345 is the key of a cascade select field |
String getCurrentUsersTimeZoneId() | Returns the time zone id set in the current user’s profile. | The issue was updated at #renderDateTime($!issue.updated "yyyy-MM-dd'T'HH:mmZ '['z']'" $!templateSupport.currentUsersTimeZoneId)
Please note that the capital letter T in the above code is just a placeholder, an example to mark that after the date, the time value comes next. |
TemplateIssueSearchResults searchForIssuesByJQL(String jql, int maxresults); | Same as above, but limits the results to the given number of issues. | |
Macro signature | Parameters | Description | Example |
#escapeHtml($value) |
| Escapes the HTML in a given value, therefore it will be displayed as text. | #escapeHtml("<p>Sample html</p>") |
#renderVersions($versions) |
| Renders the versions. | #renderVersions($!issue.fixVersions) |
#renderComments($issue) |
| Renders the public comments of the issue. | #renderComments($!issue) |
#renderCommentsInReverseOrder($issue) |
| Renders the public comments os the issue in reverse order. | #renderCommentsInReverseOrder($!issue) |
#renderCurrentCommentIfPublic() | Renders the current comment if it is public. | #renderCurrentCommentIfPublic() | |
#renderServiceDeskPublicComments($issue) |
| Renders the public comments of the issue. | #renderServiceDeskPublicComments($!issue) |
#renderServiceDeskInternalComments($issue) |
| Renders the internal comments of the issue. | #renderServiceDeskInternalComments($!issue) |
#renderAllComments($issue) |
| Renders both public and internal comments of the issue. | #renderAllComments($!issue) |
#renderLastComment($issue) |
| Renders the last comment of the issue. | #renderLastComment($!issue) |
#renderCurrentComment() | Renders the current comment. | #renderCurrentComment() | |
#renderComment() | Renders the current comment. | #renderComment() | |
#renderComponents($issue) |
| Renders the components of the issue. | #renderComponents($!issue) |
#renderDateTime($dateTimeValue $pattern $timezoneId) |
| Formats a date-time field based on the pattern and the timezone. | #renderDateTime($!issue.created "dd MMM yyyy hh:mm a" "Australia/West") |
#renderDate($dateValue $pattern $timezoneId) |
| Formats a date field based on the pattern and the timezone. | #renderDate($!issue.created "dd MMM yyyy" "Australia/West") |
#renderLabels($issue) |
| Renders the labels of the issue. | #renderLabels($!issue) |
#renderList($listitems) |
| Renders the items into a bullet list. | #renderList($!issue.affectedVersions) |
#renderFlatList($listitems) |
| Renders the items into a comma-separated list. | #renderFlatList($!issue.affectedVersions) |
#renderProject($issue) |
| Renders the project name of the issue. | #renderProject($!issue) |
#renderDescription($issue) |
| Renders the description of the issue. | #renderDescription($!issue) |
#renderEnvironment($issue) |
| Renders the value of the Environment field from the issue. | #renderEnvironment($!issue) |
#renderIssueType($issue) |
| Renders the type of the issue. | #renderIssueType($!issue) |
#renderCustomerVisibleStatus($issue) |
| Renders the status of the issue that is visible to the customer. | #renderCustomerVisibleStatus($!issue) |
#renderStatus($issue) |
| Renders the status of the issue. | #renderStatus($!issue) |
#renderPriority($issue) |
| Renders the priority of the issue. | #renderPriority($!issue) |
#renderResolution($issue) |
| Renders the resolution of the issue. | #renderResolution($!issue) |
#renderIssueConstant($issueConstant) |
| Renders the value of the issue system field. | #renderIssueConstant($!issue.status) |
#renderOriginalEstimate($issue) |
| Renders the original estimate of the issue. | #renderOriginalEstimate($!issue) |
#renderRemainingEstimate($issue) |
| Renders the remaining estimate of the issue. | #renderOriginalEstimate($!issue) |
#renderTimeSpent($issue) |
| Renders the time spent field value. | #renderOriginalEstimate($!issue) |
#renderSummary($issue) |
| Renders the summary of the issue. | #renderSummary($!issue) |
#renderUser($user) |
| Renders the user. | #renderUser($!issue.assignee) |
#renderCommentBody($commentObject) |
| Renders the body of a comment. | #renderCommentBody($!comment) |
#renderTextWithCommentRenderer($textToRender) |
| Renders the given text with the comment renderer. | #renderTextWithCommentRenderer($!worklog.comment) |
#renderCustomField($issue $customFieldKey) |
| Renders the value of a custom field. | #renderCustomField($!issue "customfield_10006") |
#renderAllCustomFields($issue) |
| Renders the value of all custom fields on an issue. | #renderAllCustomFields($!issue) |
#renderWorklog($worklog) |
| Renders a worklog entry. | #renderWorklog($!issue.worklogs.get(0)) |
#renderWorklogs($issue) |
| Renders all worklog entries of an issue. | #renderWorklogs($!issue) |
#renderUserProperty($user $propertyName) |
| Renders one of the user's property. | #renderUserProperty($!issue.assignee "phone") |
#footer() | Renders the Email This Issue footer. | #footer() | |
#renderLinkToCustomerPortal($issue $linkText) |
| Renders a link to the main page of the issue's customer portal. | #renderLinkToCustomerPortal($!issue "Customer Portal") |
#renderLinkToIssueCustomerPortal($issue $linkText) |
| Renders a link that points to the issue in its customer portal. | #renderLinkToIssueCustomerPortal($!issue "Customer Portal") |
#renderTemplate($templateId) |
| Renders a template. | #renderTemplate(1) |
#renderIssueComments($order $num $restriction) |
| Renders the comments of an issue. | #renderIssueComments("desc" 10 "all") |
#renderOptOutLink($linkText) |
| Renders a link that customers can use to unsubscribe from notifications. | #renderOptOutLink("Unsubscribe") |
Last modified 1yr ago