Email templates are velocity macro files. When email templates are used to render email body, the following Velocity context attributes are available.
Template Context Objects
Name | Type | Description |
---|---|---|
attachmentsManager | com.atlassian.jira.mail.util.MailAttachmentsManager | Manager component |
baseurl | String | Base url of the Jira instance, set under General Configuration |
buildutils | com.atlassian.jira.util.BuildUtils | |
customfieldManager | com.atlassian.jira.issue.CustomFieldManager | Support for adding custom fields to outgoing emails |
dateformatter | com.atlassian.jira.web.util.OutlookDate | Date format support |
issue | com.atlassian.jira.mail.TemplateIssue | Issue extended with support for processing in velocity templates |
i18n | com.atlassian.jira.util.I18nHelper | I18n support |
jirakeyutils | com.atlassian.jira.util.JiraKeyUtils | |
jirautils | com.atlassian.jira.util.JiraUtils | |
remoteUser | com.atlassian.jira.user.ApplicationUser | Current user running the action or null |
rendererManager | com.atlassian.jira.issue.RendererManager | |
stringUtils | org.apache.commons.lang.StringUtils | String helper methods |
textutils | com.opensymphony.util.TextUtils | Jira's text util methods |
userutils | com.atlassian.core.user.UserUtils | |
jetiFieldRenderer | See below | Support for field rendering in templates. See details below. |
jetiFieldFormatter | See below | Support for date/time formatting in templates. See details below |
templateSupport | See below | Support for email templates, rendering, formatting. See details below. |
number | com.atlassian.jira.util.velocity.Numbertool | Support for Number formatting in templates. See API documentation |
currentUserInfo | $!currentUserInfo.user: current user object | |
userPropertyManager | com.atlassian.jira.user.UserPropertyManager | Access to Jira user properties. . Usage: Refernces 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 | java.util.Date | Date and time of rendering the template, this like "now". |
jiraDurationUtils | com.atlassian.jira.util.JiraDurationUtils | Util class responsible for printing durations in various formats. |
diffUtils | com.atlassian.jira.mail.DiffUtils | Compares two string values and renders wiki markup diffs. |
jetiFieldRenderer
jetiFieldRenderer provides a lot of useful 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 attribues | $!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 renderIssueConstant(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); | Returns a I18nBean for the given locale, locale string follows java syntax | 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
jetiFieldFormatter is an object in the template context that may be used to format date or date time values.
It provides the below methods:
Method | Description | Usage |
---|---|---|
DateTimeFormatter getJiraDateTimeFormatter() | Returns a native Jira DateTimeFormatter object | #set ($formatter = $jetiFieldFormatter.getJiraDateTimeFormatter()) |
DateTimeFormatter getJiraDateTimeFormatter(String style) | Returns a native Jira DateTimeFormatter object configured with DateTimeStyle provided | #set ($formatter = $jetiFieldFormatter.getJiraDateTimeFormatter("COMPLETE")) |
DateFormat getJavaDateFormat() | Returns a Java DateFormat object for date formatting | #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. | Example for locales: en, en_US, fr, de, see more examples in the documentation |
DateFormat getJavaDateTimeFormat() | Returns a Java DateFormat object for date time formatting | |
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) | Returns a Java SimpleDateFormat object for date time formatting configured with a 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() | Returns the default TimeZone in Jira. | |
String[] getAvailableTimeZoneIDs() | Returns all time zone IDs available in Jira. |
- DateTimeFormatter is part of the Jira API
- DateFormat is a standard way to format dates in Java
templateSupport
Method | Description | Usage |
---|---|---|
String encodeUrl(String url); | Calls URLEncoder.encode(url) to encode rendered URLs in email templates using UTF-8 encoding | $!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>) |
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 |
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 |
TemplateIssueSearchResults searchForIssuesByJQL(String jql, int maxresults); | Same as above but limits the results to the given number of issues | |
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 |
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 french language, while "fr_FR" is the french spoken in France. | #set($frenchLocale = $!templateSupport.getLocale("fr_FR") |
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) |
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 |
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 |
boolean isInternalComment(Comment comment); | Determins if the give comment is an Service Management Internal comment in the current issue. | #if($!templateSupport.isInternalComment($!comment)) ... #end |
String getCustomerVisibleStatus(Issue issue); | Returns the Customer Visible Status name of the issue in a Service Management project | #set($!customerVisibleStatus = $!templateSupport.getCustomerVisibleStatus($!issue) |
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. |