Substitution variables

On this page

Description

Substitution variables provide powerful capabilities to customize.

The syntax for referencing substitution variables is: %<variable name>%. All text entry fields support replacement. 

Example: %parent_summary%

The functions use the following terminology. The terminology is also used in the substitution variables.

TermDefinition
original

The original issue that started the workflow transition. This could be an issue or subtask.

parentThe parent issue of the original issue. If the original issue is not a subtask, then parent is the same as original

Variables

Some variables are listed on the post function definition screen as an aid when creating definitions. This is a more complete and detailed list and represents the variables available with the most recent version (version 3.3) of the add-on. Create an issue if you need access to additional fields.

Note the terminology for the meaning of parent and original.

Starting with version 3.6.1, variables will be consistent with Create on Transition for Jira and Update on Transition for Jira. Variables with prefix issue will continue to be supported for compatibility, but the recommendation is to use the appropriate consistent prefix (original or parent) to avoid confusion.

Create issue transition

The Create issue transition is a unique transition. Some variables will not be available unless the post function is placed after the Creates the issue originally. post function. For example, original_key is not set.

VariableDescriptionNotes
projectProject key of the issue being transitioned
project_idProject id (numeric) of the issue being transitionedSince 3.9.
project_nameProject name of the issue being transitionedSince 4.3
project_categoryProject category name for the project of the issue being transitionedSince 3.6.1. Blank if the project does not have a category configured.

project_default_security

Default issue security level name for the project

project_default_security_id

Default issue security level id for the project
nowCurrent date/time in JIRA complete date/time format or a specific format Since 3.9.

user_id

User id (also known as username) of user that did the transition
user_keyUser key of user that did the transitionSince 7.9
user_nameDisplay name of user that did the transition
base_urlURL of this instanceSince 3.8

parent_key, original_key

Issue key
parent_summary, original_summarySummary
parent_description, original_descriptionDescription
parent_environment, original_environmentEnvironmentSince 3.6.1
parent_issuetype, original_issuetypeIssue typeSince 3.6.1
parent_status, original_statusIssue statusSince 3.6.1
parent_priority, original_priorityPrioritySince 3.6.1
parent_reporter, original_reporterReporter user id (also known as username)
parent_reporter_key, original_reporter_keyReport user key
parent_assignee, original_assigneeAssignee user id (also known as username)
parent_assignee_key, original_assignee_keyAssignee user keySince 7.9
parent_components, original_componentsComma separated list of componentsSince 3.6.1
parent_component_descriptions, original_component_descriptionsComma separated list of component descriptions. Some may be blank.Since 4.2
parent_affected_versions, original_affected_versionsComma separated list of affected version names
parent_fixed_versions, original_fixed_versionsComma separated list of fixed version names
parent_subtasks, original_subtasksComma separated list of subtask issue keysSince 3.6.1.
parent_duedate, original_duedateDue date in JIRA DMY date format or a specific formatSpecific format is available since 3.6.1.
parent_created, original_createdCreated date in JIRA complete date/time format or a specific format Specific format is available since 3.6.1.
parent_updated, original_updatedUpdate date in JIRA complete date/time format or a specific format Specific format is available since 3.6.1.
parent_resolution, original_resolutionResolutionSince 3.6.1.
parent_resolution_date, original_resolution_dateResolution date in JIRA complete date/time format or a specific format Specific format is available since 3.6.1.
parent_labels, original_labelsBlank separated list of labelsSince 3.6.1
parent_labels_comma_separated, original_labels_comma_separatedComma separated list of labelsSince 3.6.1.
parent_watchers, original_watchersComma separated list of watcher user idsSince 3.6.1.
parent_watches, original_watchesNumber of watchers of the issueSince 3.6.1.
parent_votes, original_votesNumber of votes for the issueSince 3.6.1.
parent_time_spent, original_time_spentTime spent on the issue in minutesSince 3.6.1. Note the JIRA timeSpent field returns seconds.
parent_estimate, original_estimateCurrent estimate for the issue in minutesSince 3.6.1.
parent_original_estimate, original_original_estimateTime spent on the issue in minutesSince 3.6.1. Note the 2 different meanings of the original word here (smile).
parent_security_level, original_security_levelSecurity level name
<field name>

Parent issue's JIRA issue field name

Deprecated but still active, recommend using specific replacements variables instead

Examples: components, resolution. See Jira issue field constants.

JIRA defines what information is returned by these fields.

<customfield name>

parent_<customfield name>

Parent issue's custom field value

Recommend using prefix qualified name for clarity. Unqualified name use is deprecated.

Must be an exact match including case and blanks.

JIRA defines what information is returned by these fields.

<customfield id>

parent_<customfield id>

Parent issue's custom field value

Recommend using prefix qualified name for clarity. Unqualified name use is deprecated.

Example: customfield_10010.

JIRA defines what information is returned by these fields.

original_<customfield name>

Original issue's custom field value

Since 3.6.1. Similar to above.

original_<customfield id>

Original issue's custom field value

Since 3.4. Similar to above.

Example: original_customfield_10010.

parent_value_id_<customfield name>

parent_value_id_<customfield id>

Parent issue's custom field value id (or key) for custom fields who's value is derived from an unique identifier like an option id or keySince 7.9

original_value_id_<customfield id>

original_value_id_<customfield name>

Original issue's custom field value id (or key) for custom fields who's value is derived from an unique identifier like an option id or keySince 7.9
transition_commentComment entered on the transition screen
jql_result_countNumber of issues returned by the querySince 3.6.1.
jql_result_listComma separated list of issue keys returned from the querySince 3.6.1.
jql_result_nThe issue key for the nth issue returned from the query where n is a numberSince 3.6.1. Blank if n is not in range for the issue list.
pattern1_nnth capture group from condition pattern 1

Since 3.6.1. Blank if n is not in the range of valid capture groups. Example: pattern1_1.

If you used this on releases previous to 3.6.1, update to use cli_pattern1_n instead. This incompatibility was introduced due to the introduction of the the conditioning patterns.

pattern2_nnth capture group from condition pattern 2

Since 3.6.1. Blank if n is not in the range of valid capture groups. Example: pattern2_1.

If you used this on releases previous to 3.6.1, update to use cli_pattern1_n instead. This incompatibility was introduced due to the introduction of the the conditioning patterns.

cli_pattern1_nnth capture group from cli find pattern 1Since 3.6.1.
cli_pattern2_nnth capture group from cli find pattern 2Since 3.6.1.
property_<property name>

Transition property. Other transition functions can add transition properties that can be referenced. This provides a way to access those transition properties. You must know the property name.

Since 3.8.0.

Examples:

  • org.swift.jira.cot.last_created_key
  • org.swift.jira.cot.last_created_non_subtask_key
  • org.swift.jira.acli.validator_message - result message from last CLI action validator
  • org.swift.jira.acli.function_message - result message from last CLI action post function
  • org.swift.jira.acli.validator_exit_code - string representation of the exit code from the last CLI action validator (since 6.2)
  • org.swift.jira.acli.function_exit_code - string representation of the exit code from the last CLI action post function (since 6.2)
group_<group name>Comma separated list of user ids for members in the groupSince 3.6.1. Example: group_jira-users.
role_<role name>Comma separated list of user ids for users that are role actors for the project of the original issueSince 3.6.1. Example: role_developers.

values_<customfield name>

values_<customfield id>

Comma separated list of custom field option values in the context of the original issueSince 3.6.1. Custom field should be of a type that has option value like multi-select or cascade select. For cascade select fields, it is a list of parent option values.

values_<customfield name>(<value or sub variable>)

values_<customfield id>(<value or sub variable>)

Comma separated list of cascade select child option values for the specific parent value provided

Since 3.6.1. Primarily used for advanced scenarios for multi-issue creation scenarios using entry substitution variable. See CSOT-103.

Examples: values_custom-cascade-select(entry), values_custom-cascade-select(1)

function_<function name>(<parameters>)

Functions that derive useful text values that can be used as substitution variables. Some are similar to their equivalent JQL function (follow link). The project key may be a substitution value.


Make sure you use the correct syntax!

Set custom field: field: My custom field, value: %function_earliestUnreleasedVersion(%project%)%



Since 3.6.1. Open an improvement request if you have similar needs.

  • Version id is since 3.9
  • Field value is since 4.0
  • List since 4.0
  • FindReplace since 4.0
  • UserName since 4.0
  • VersionInfo since 4.0
  • GroupMemberList since 4.1
  • ComponentLead since 4.2
  • LinkedIssues since 5.6

Example: function_earliestUnreleasedVersion(%project%)

function_message

Message created by the last cli post function.

This provides a way to communicate between cli workflow functions.
validator_messageMessage created by the last cli validator.This provides a way to communicate between workflow functions.
cli_replace_<name>Many Atlassian CLI products support setting replacement variables during the running of actions in order to facilitate use in a subsequent actions. Run CLI Actions in Jira workflow functions will take these replacement variables from the running of a CLI action and populate the transition properties so they can be available in subsequent functions as substitution variables. Use the prefix and the replacement name from the lists shown on the replacement variables page after running a CLI action function that produces replacement variables.

Since 3.6.1.

Example: cli_replace_issue will be replaced with the issue key of the last created issue after the createIssue action is run by a CLI action function.

variable_<user defined variable name>

User defined variables can be configured on the Configuration screen. See User Defined Substitution Variables for more information.

Example configuration:

NameValue
credentials--user automation --password automation
jira-local--server http://example.com %variable_credentials%

Since 4.2.

Example usage:

--action getServerInfo %variable_jira-local%


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 2013-05-28.