You can assign variables in a workflow by using an assign step or by assigning them as the result of a call step. Assigning a variable creates a variable in the current scope (in this document, see Variable scope). You can also access HTTP response information stored in a variable using the built-in parser.
For more information about invoking an HTTP endpoint or accessing HTTP response data, see Make an HTTP request.
Variable names
Variable names must start with a letter or underscore, and must consist of only letters, digits, and underscores.
Variable scope
A variable created inside a for loop
belongs to the local scope of that loop, and is accessible only in that scope.
For example, the variable is cleared after exiting the loop, and accessing it
outside of the loop will raise an error when deploying the workflow. This local
scoping also applies to any variable created inside an
except block.
This sample demonstrates how any variable created in a loop does not exist outside of that loop:
YAML
JSON
Variables assigned in a parent scope are accessible in any child scopes. For
example, a variable created inside the main block of a workflow is accessible
in any child for loop.
Subworkflows do not have access to any variables from the main block of a
workflow or other subworkflows. A subworkflow receives values passed in a call,
and assigns those values to new variables in the subworkflow scope. Note that
all step names in a subworkflow must be unique, even if they are in a scope.
Using nested steps
does not create a new variable scope. Variables declared in a steps block
have workflow-level scope and can be accessed outside of the block.
Share a variable before an except block
If you are assigning a variable inside an except block and want to access the
variable outside of the block, assign the variable before the block to place
it in the surrounding scope. For example, the following workflow generates a
deployment error:
YAML
main:
steps:
- fail:
try:
call: http.get
args:
url: https://foo.bar
result: nope
except:
as: e
- returnError:
return: ${e}
JSON
{
"main": {
"steps": [
{
"fail": {
"try": {
"call": "http.get",
"args": {
"url": "https://foo.bar"
},
"result": "nope"
},
"except": {
"as": "e"
}
}
},
{
"returnError": {
"return": "${e}"
}
}
]
}
}
The deployment error will be similar to the following:
Could not deploy workflow: failed to build: error in step returnError: error evaluating return value: symbol 'e' is neither a variable nor a sub-workflow name (Code: 3)
To fix this issue, assign the exception variable e outside the except
block so that it is a shared variable in the outer scope. For example:
YAML
main:
steps:
- init:
assign:
- e: null
- fail:
try:
call: http.get
args:
url: https://foo.bar
result: nope
except:
as: e
- returnError:
return: ${e}
JSON
{
"main": {
"steps": [
{
"init": {
"assign": [
{
"e": null
}
]
}
},
{
"fail": {
"try": {
"call": "http.get",
"args": {
"url": "https://foo.bar"
},
"result": "nope"
},
"except": {
"as": "e"
}
}
},
{
"returnError": {
"return": "${e}"
}
}
]
}
}
Memory usage
The memory usage for local variables is computed as follows:
| Data type | Size |
|---|---|
| Integer, double, boolean | 8 bytes |
| String, byte, array | 8 bytes + size of EACH_ELEMENT * |
| Map (dict) | 8 bytes + size of EACH_KEY + size of EACH_VALUE |
* Applied recursively to each substructure.
For the maximum amount of memory that you can use for all variables defined in a single execution of a workflow, see Quotas and limits.
Assign variables
To initialize variables or update existing variables, use a variable assignment step.
YAML
- STEP_NAME:
assign:
- VARIABLE_NAME: VALUE
JSON
[
{
"STEP_NAME": {
"assign": [
{
"VARIABLE_NAME": "VALUE"
}
]
}
}
]
You can perform up to 50 assignments in a single step. Variables can be assigned to a particular value or to the result of an expression. For example:
YAML
- assign_vars:
assign:
- number: 5
- number_plus_one: ${number+1}
- other_number: 10
- string: "hello"
JSON
[
{
"assign_vars": {
"assign": [
{
"number": 5
},
{
"number_plus_one": "${number+1}"
},
{
"other_number": 10
},
{
"string": "hello"
}
]
}
}
]
Since each assignment is processed sequentially, you can concatenate a string over multiple lines by repeating the variable and splitting the assignment. For example:
YAML
- assign_vars:
assign:
- string: "say"
- string: ${string+" "+"hello"}
- string: ${string+" "+"to the world"}
JSON
[
{
"assign_vars": {
"assign": [
{
"string": "say"
},
{
"string": "${string+" "+"hello"}"
},
{
"string": "${string+" "+"to the world"}"
}
]
}
}
]
Clear variables
You can clear a variable by assigning null. In YAML, you can also assign an
empty value or ~ to a variable. This identifies memory that
can be safely reclaimed; for example, you might want to free up memory that is
needed for subsequent steps. For example:
YAML
- step:
assign:
- bigVar:
JSON
[
{
"step": {
"assign": [
{
"bigVar": null
}
]
}
}
]
Store result from a call in a variable
You can store the result of a call step to a variable.
YAML
- STEP_NAME:
call: ...
args:
...
result: VARIABLE
JSON
[
{
"STEP_NAME": {
"call": ...,
"args":
...,
"result": "VARIABLE"
}
}
]
Samples
These samples demonstrate the syntax.
Assign variables
This sample assigns string and number values to variables. Variable assignments are executed sequentially.
YAML
JSON
Evaluate an expression with type casting
This sample uses an expression to assign the value of a variable. The full_name
variable uses the name and last_name variables previously defined.