Substitution Variables
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.
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.
Variable | Description | Notes |
|---|---|---|
base_url | Base URL | |
user_id | User id of user that is considered to be doing the action | |
user_key | User key of user that is considered to be doing the action | |
user_name | Display name of user that is considered to be doing the action | |
now | Current date/time on the Jira server in Jira complete date/time format or a specific format | |
parent_project, original_project | Project key of the issue | |
parent_project_id, original_project_id | Project id (numeric) of the issue | |
project_name, parent_project_name, original_project_name | Project name for the issue | |
project_category, parent_project_category, original_project_category | Project category name for the project of the issue | Blank if the project does not have a category configured. |
project_lead, parent_project_lead, original_project_lead | User id of the project lead. | |
parent_key, original_key | Issue key | |
parent_id, original_id | Issue numeric id | |
parent_summary, original_summary | Summary | |
parent_description, original_description | Description | |
parent_environment, original_environment | Environment | |
parent_issuetype, original_issuetype | Issue type | |
parent_status, original_status | Issue status | |
parent_priority, original_priority | Priority | |
parent_reporter, original_reporter | Reporter user id | |
parent_assignee, original_assignee | Assignee user id | |
parent_components, original_components | Comma separated list of components | |
parent_component_descriptions, original_component_descriptions | Comma separated list of component descriptions. Some may be blank. | |
parent_affected_versions, original_affected_versions, parent_affects_versions, original_affects_versions | Comma separated list of affected version names | |
parent_fixed_versions, original_fixed_versions, parent_fix_versions, original_fix_versions | Comma separated list of fixed version names | |
parent_subtasks, original_subtasks | Comma separated list of subtask issue keys | |
parent_issuelinks, original_issuelinks | Comma separated list of issue keys for links (not subtasks) to/from the issue | |
parent_duedate, original_duedate | Due date in JIRA DMY date format or a specific format | |
parent_created, original_created | Created date in JIRA complete date/time format or a specific format | |
parent_updated, original_updated | Update date in JIRA complete date/time format or a specific format | |
parent_resolution, original_resolution | Resolution | |
parent_resolution_date, original_resolution_date | Resolution date in JIRA complete date/time format or a specific format | |
parent_labels, original_labels | Blank separated list of labels | |
parent_labels_comma_separated, original_labels_comma_separated | Comma separated list of labels | |
parent_watchers, original_watchers | Comma separated list of watcher user ids | |
parent_watches, original_watches | Number of watchers of the issue | |
parent_voters, original_voters | Comma separated list of voter user ids | |
parent_votes, original_votes | Number of votes for the issue | |
parent_time_spent, original_time_spent | Time spent on the issue in minutes | Note the JIRA timeSpent field returns seconds. Since 9.3. |
parent_estimate, original_estimate | Current estimate for the issue in minutes | Since 9.3. |
parent_original_estimate, original_original_estimate | Time spent on the issue in minutes | Note the 2 different meanings of the original word here |
parent_security_level, original_security_level | Security level name | |
parent_issue_restriction, orginal_issue_restriction | Issue restriction for nextgen (simplified) project issues | Since 9.4. |
parent_<customfield name> | Parent issue's custom field value | Must be an exact match including case and blanks. |
parent_<customfield id> | Parent issue's custom field value | Example: parent_customfield_10010. |
original_<customfield name> | Original issue's custom field value | Similar to above. |
original_<customfield id> | Original issue's custom field value | Similar to above. Example: original_customfield_10010. |
jql_result_count | Number of issues returned by the last getIssueList action using '–options cacheJqlResult' | Since 9.4. |
jql_result_list | Comma separated list of issue keys returned by the last getIssueList action using '–options cacheJqlResult' | Since 9.4. |
jql_result_n | The issue key for the nth issue returned by the last getIssueList action using '–options cacheJqlResult' where n is a number | Since 9.4. |
group_<group name> | Comma separated list of user ids (account ids for Cloud) for members in the group | Example: group_jira-users. Since 9.3. |
role_<role name> | Comma separated list of user ids (account ids for Cloud) for users that are role actors or members of group role actors for the project of the original issue | Example: role_developers. Since 9.3. |
function_<function name>(<parameters>)
| Functions that derive useful text values that can be used as substitution variables. The parameter(s) may be a substitution variable. Make sure you use the correct syntax! Set custom field: field: My custom field, value: %function_earliestUnreleasedVersion(%project%)% Notes
| Open an improvement request if you have similar needs. Example: function_earliestUnreleasedVersion(%project%) Since 9.6 |
. Since 9.3.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.