Template Values
Introduction
Template values allow you to dynamically populate templates with contextual data when being used.
The contextual data are mainly the issue for which a template is being used as well as the user using the template.
Template values therefore make it possible to create templates that are flexible, especially when adding logic via Template Functions.
How to access and use
You can simply access any value by wrapping it within {{ }}.
So if you wanted to show an issue’s summary you can do so by writing {{issue.summary}}.
When using a value as an argument in a Template Function, you must not wrap it. e.g. {{capitalize issue.summary}}.
When accessing a field that doesn’t exist it will return an empty string.
Fields
Simplified structure
The following shows the outline of the available fields. Please see the following sections for more details.
{
issue: {
id: string,
key: string,
url: { // can be accesses directly to print browse url
browseUrl: string, // prints the browse url
customer: string, // prints the portal url if available
smart: string // prints the portal url if available, otherwise it will fallback to the browse url
}
// ... the issue's fields
}
issues: Issue[],
baseUrl: string,
label: {
<fieldname>: string
},
currentUser: User,
userTimezone: string,
userLocale: string,
now: ISO-Date,
customData: { any }
}Issue
You have access to all fields/renderdFields values of an issue.
By default we prioritize populating a field with the renderedField’s value.
For some field types this might not always satisfy all your needs which is why we add Additional processing for those.
Here are some examples for often used fields:
issue.id the issue's technical id
issue.key the issue's key (e.g. "TEST-123")
issue.assignee the displayname of the assignee (e.g. "Jane Doe")
issue.duedate the duedate formatted in the user locale (e.g. "Jan 18, 2024, 3:00 PM")
Additionally we provide the following non-standard fields:
issue.url the browse url to this issue (e.g. "https://<your instance>.atlassian.net/browse/<issue key>")
issue.url.browseUrl direct access to the browse url to this issue (e.g. "https://<your instance>.atlassian.net/browse/<issue key>")
issue.url.customer the servicedesk url for issues in a JSM project (e.g. "https://<your instance>.atlassian.net/servicedesk/customer/portal/<issue key>")
issue.url.smart either the browse or servicedesk url depending on the issue's type
issue.comment comments have a different structure for easier access
issue.watchers array of users watching this issue
Assets
issue.customfield_xxxxx (e.g. customfield_10001) array of assets
issue.customfield_xxxxx.[n].label the label of the selected assets
issue.customfield_xxxxx.[n].attributes data of the asset
issue.customfield_xxxxx.[n].attributes.attributeName the value of one of the asset’s attributes. Please make sure the attributes are visible on the issue view within the asset object when trying to pull information from them.
You can access all custom fields.
We are working on an UI to show available data live and specific to your issues.
In the meantime, if you are looking for information how an field looks like, you can use the following Jira API: (make sure to replace Issue key and instance url )https://<your instance>.atlassian.net/rest/api/2/issue/<issue key>?fields=*all&expand=renderedFields
Issues
issues
In automation this may be populated by passing issueIds via custom data. See the Custom data example below.
Outside of automation this will remain unused.
Current user
currentUser The current Atlassian Jira user. In automation context the actor of an action.
Label
label key-value list of all fields to access a field's name in the users current locale.
Using this ensures your template adjust to the correct naming if you change a label in Jira.
It also takes different, context-sensitive configurations into account (e.g. the duedate could be renamed to Escalation Date for a specific project)
Custom data
customData Only present when used in automation. 1:1 representation of what has been configured to be passed on as custom data to an action.
Always empty when used outside automation.
Other values
baseUrl e.g. "https://<your instance>.atlassian.net"
userTimezone Time zone to be used for dates. If present, it will contain a currentUser's time zone based on their Atlassian settings - else it defaults to "Europe/Berlin".
userLocale Locale to be used for dates. If present, it will contain a currentUser's locale based on their Atlassian settings - else it defaults to "en-US".
now A full ISO-Date of the current date and time. It will be converted automatically to the time zone in timezone (e.g. "2022-11-15T14:15:42.000+01:00").
Additional processing
For all fields that contain one or multiple users you can simply write issue.myUserField instead of issue.myUserField.displayName to print out the user’s name.
This also applies for any option field, for which it will print out the value.
We enrich string and date(time) with additional properties.
This is necessary as Atlassian renders these fields to contain a readable value which may make them unusable in Template Functions.
For date(time) fields we add
isoStringcontaining the ISO-Daterenderedcontaining the formatted date in the user locale (e.g. Jan 18, 2024, 3:00 PM)
When simply accessing the date(time) field it will print the rendered value.
For string fields we add
renderedcontaining the field's value
When simply accessing the string field it will print the rendered value.
Be aware that when using such a field in Template Functions, it will still access the entire object, even if it prints a specific value.