In this page
Overview
This page contains the technical documentation of the variables you can use to configure the different stages of the automation rule execution.
Variables to configure automation actions
Several action parameters accept dynamic values in addition to static ones. For example, you can configure the automation to "send the exported Excel spreadsheet to the creator of the corresponding issue" instead of entering a concrete email address.
You can find the "Tip: use template variables." message on the configuration UI at each action parameter that accepts dynamic values.
Dynamic values can use the so-called template variables in Velocity syntax. The variables themselves are best explained through examples:
## ${issues} is a collection of issue objects.
## Note that starting from $issues, you can traverse the object graph:
## enclosing projects, priority objects, status objects, assignees, reporters, etc.
## You do it the same exact way as in any other Velocity template.
## See: https://docs.atlassian.com/software/jira/docs/api/latest/com/atlassian/jira/issue/Issue.html
## - basic ---------------------------------------------------------
## ${user} is the username string you specified as "Actor"
This Excel is rendered as user <${user}> ## for debugging purposes
## ${templateName} is the filename string you specified as "Template name"
This Excel is rendered from <${templateName}> ## for debugging purposes
## ${to}, ${cc} and ${bcc} are the email address strings you specified in the 3 action parameters
Primary recipients: ${to}
Secondary recipients: ${cc}
Blind carbon copy goes to: ${bcc}
## - standard fields -----------------------------------------------
## the number of issues passed (as size of the collection)
${issues.size()} pending bugs
## the key of the first issue (accessed by the item's index)
${issues.get(0).key} done!
## the summary of the first issue
NEW: ${issues.get(0).summary}
## the key of the first issue's project (accessed as embedded property)
Report for ${issues.get(0).projectObject.key}
## email address of the first issue's creator (typically used as a target email address)
${issues.get(0).creator.emailAddress}
## email address of the first issue's assignee (typically used as a target email address)
${issues.get(0).assignee.emailAddress}
## - custom fields -------------------------------------------------
## The #cfValue() macro displays nicely formatted values from custom fields,
## depending on the custom fields' types.
## formatted value of the custom field with the ID=10000 in the first issue, with line break
#cfValue(${issues.get(0)} 10000)
## formatted value, without line break
#cfValueInline(${issues.get(0)} 10001)
## - dates & times -------------------------------------------------
## The ${date} tool allows freely formatting date and time values using simple "pattern strings".
## See: https://velocity.apache.org/tools/devel/javadoc/org/apache/velocity/tools/generic/DateTool.html
## formatting current date and time as "20141107-1046"
${date.get('yyyyMMdd-HHmm')}
## formatting an existing date object in medium length (ex: "Oct 7, 2003 3:14:50 AM")
${date.format('medium', $someDateObject)}
## - rule and trigger configuration --------------------------------
## The variables below give convenient access to configuration of the automation rule.
## All values are strings.
## Not documented here in details, as they just hold the corresponding setting available in the UI.
${automationRuleId} ## ex: "1"
${automationRuleName} ## ex: "Archive closed bugs"
${automationTriggerProcessIssuesInBulk} ## ex: "true"
${automationTriggerOnlyUpdatedIssues} ## ex: "false"
${automationTriggerJiraJqlExpression} ## ex: "filter = 10123"
${automationTriggerJql} ## same (for backward compatibility)
${automationTriggerScheduleMethod} ## ex: "FIXED", "CRON"
${automationTriggerExecutionMode} ## ex: "jql"
${automationTriggerScheduleRate} ## ex: "10"
${automationTriggerScheduleRateInterval} ## ex: "86400"
${automationTriggerScheduleCronExpression} ## ex: "0 0 */2 * * ?"
${automationTriggerPropertyKeys}
${automationTriggerIssueEvent} ## ex: "issue_commented"
${automationTriggerEventKey} ## ex: "jira:issue_updated"
## ${automationTriggerRawParameters} is a string-keyed map of all trigger parameter objects.
## These give a lower-level access to the automation rule, also including 3rd party triggers.
## ex: {schedule={rate=10, rateInterval=86400}, jql=[project=DEMO], executionMode=[jql]}
${automationTriggerRawParameters}
Variables passed to the XLS API
Better Excel Automation for Jira Server relies on the XLS API to generate the Excel files. The XLS API is a lightweight, in-process API published by the Better Excel Exporter for Jira Server app.
Technically speaking, Better Excel Automation for Jira Server calls the XlsApi.getXls() method and passes a set of variables. The variables carry information about the enclosing automation rule, among others. And this is where it starts getting interesting!
As Excel templates can access these variables both in the template and in Groovy scripts, the automation rule can directly affect the generated Excel spreadsheet! For example, if the automation rule name contains the word "monthly", then the dates in the Excel spreadsheet could use the "2024 Feb" format, otherwise "2024/02/11".
The syntax is slightly different depending on where you access a variable:
- In Excel templates: prefix it with a dollar sign and wrap it in curly braces, like ${automationActionName}.
- In Groovy scripts: it is a "global variable", no need for any decoration, just automationActionName.
The variables themselves are best explained through examples (in Excel template syntax):
## - rule and trigger configuration --------------------------------
## The variables below give convenient access to configuration of the automation rule.
## All values are strings.
## Not documented here in details, as they just hold the corresponding setting available in the UI.
${automationRuleId} ## ex: "1"
${automationRuleName} ## ex: "Archive closed bugs"
${automationTriggerProcessIssuesInBulk} ## ex: "true"
${automationTriggerOnlyUpdatedIssues} ## ex: "false"
${automationTriggerJiraJqlExpression} ## ex: "filter = 10123"
${automationTriggerJql} ## same (for backward compatibility)
${automationTriggerScheduleMethod} ## ex: "FIXED", "CRON"
${automationTriggerExecutionMode} ## ex: "jql"
${automationTriggerScheduleRate} ## ex: "10"
${automationTriggerScheduleRateInterval} ## ex: "86400"
${automationTriggerScheduleCronExpression} ## ex: "0 0 */2 * * ?"
${automationTriggerPropertyKeys}
${automationTriggerIssueEvent} ## ex: "issue_commented"
${automationTriggerEventKey} ## ex: "jira:issue_updated"
## ${automationTriggerRawParameters} is a string-keyed map of all trigger parameter objects.
## These give a lower-level access to the automation rule, also including 3rd party triggers.
## ex: {schedule={rate=10, rateInterval=86400}, jql=[project=DEMO], executionMode=[jql]}
${automationTriggerRawParameters}
Questions?
Ask us any time.