Substitution Variables

On this page

Description

Substitution variables provide support similar to other Substitution variables support found in Create on Transition for Jira and Update on Transition for Jira.

Substitution variables provide powerful capabilities to customize the creation or updating of issues using values from issues or other Jira information. Variables provide text string representations of fields useful for inclusion in other fields.

The syntax for referencing substitution variables is: %<variable name>%.

Example: %parent_summary%


Substitution variables and variable replacements

Variable Replacements are different than substitution variables. Don't confuse them or their uniquely different syntax.

General support for all clients

Jira support extends general support provided for all clients. See Substitution Variables for more information.

Substitution support is available on specific actions and uses the following terminology.
TermDefinition
original
ActionsDefinitionParameter
updateIssueIssue being updated. Since 6.1.issue
cloneIssueIssue being cloned.issue
setFieldValueIssue who's field value is being set.issue
transitionIssueIssue being transitioned.issue
addCommentIssue for the comment.issue
setReplacementVariablesIssue parameter on action. Since 9.7.issue
parent
ActionsDefinitionParameter
createIssueParent of issue being created.parent
Any action where original is definedParent of original issue.

Variables

Note the terminology for the meaning of parent and original.

Custom fields

Custom fields are identified by name or id (like customfield_12345). By name is easier to know what it is referring to but by id will survive renaming a custom field.

Fields with ids

Some user fields like reporter, assignee, and lead and user custom fields returns the user's server user id or cloud display name by default. Similarly, some other fields like version fields, component, and some custom fields are internally based on option ids. In some cases, it is more desirable or even required to use the id for some operations. To enable getting id values instead of text values for a substitution field, we have a convention to use a _id postfix to the substitution variable.

Examples

  • ..._reporter_id - will return the reporter's unique id (user key for server, accountId for cloud)
  • ..._assignee_id - will return the assignees's unique id (user key for server, accountId for cloud)
  • group_jira-users_id - will return a list of group members unique ids (user key for server, accountId for cloud)
  • role_Developers_id - will return a list of group members unique ids (user key for server, accountId for cloud)
  • ..._voters_id - will return a list of unique id (user key for server, accountId for cloud) for voters


Configured date format

For date substitution variables, the format of the replacement variable can be specified if the default format is not desirable. The format is specified by a Simple Date Format string enclosed in parenthesis following the substitution variable name. For example: %created(yyyy-MM-dd)% will result in replacement like 2016-05-28.