This feature is available in Ultimate edition only.
There are three types of variables used in Task Steps: runtime variables, input variables and global variables.
Runtime variables are variables that are defined within a task and can be referenced at any time. Runtime variables are actually global in scope meaning that they are settable and able to be referenced at any time during the task run, even when used in a codeblock or subtask.
Input variables are referenced exactly the same as Runtime variables. They're only mentioned separately as they are passed in to a Task when it's executed, as parameters.
Global variables are a set of reserved keywords unique to and available within a specific Task run. See below for more details.
Variables in a Task are set in a multitude of ways:
- The Command has a specific property that defines a Variable which will be populated by the command
- The Command has built-in advanced output parsing which can populate many variables
- Some Commands (such as
Utility - Python Scriptor extension commands) can set variables from within their own code
- Explicitly by a Developer using the
The Command Reference identifies which specific commands have built-in advanced parsing.
Cloud Provider API Results
All Cloud Providers APIs currently supported by Automate return data in the XML format. Any Cloud API commands will include a single property called Result Name. This property is the name of a single variable that will contain the XML response from the API call.
See the XPath portion of Referencing Variables for a description of how to interpret these results.
To reference a variable, use the following bracket-dollar escape syntax:
The square-bracket-dollar-sign wrapper tells the Task Engine to perform variable substitution in-place. If the variable has not been defined, the task will not error but will replace the token with nothing.
Careful use of Spaces
Careful use of spaces for readability inside the brackets is allowed. However invalid spaces inside an expression may cause errors.
[$ variablename $]
Variable expressions must be on one line. Use of newlines inside the brackets is disallowed and will raise an error.
The Task Engine stores variable in standard Python data types: string, number, list (array) and dictionary (object). The 'variablename' inside the brackets follows the standard Python syntax for accessing these types of variables.
Most Python keywords for dealing with variables, such as len and .get() are also supported.
Strings and Numbers
In regards to referencing, strings and numbers are referenced identically, simply by name.
[$stringvar$] or [$numvar$]
If a variable is an Array, use the following syntax:
This would retrieve the third item in the array, as all indexes are zero-based.
To determine the length of an array:
[$ len(arrayvar) $]
Strings are actually Arrays
An interesting capability is available regarding string versus array variables. Technically speaking, a string is just an array of characters. Therefore, index referencing will actually work on a string value too.
var = "Now is the time for all good men to come to the aid of their country."
[$ var $] will be `e` [$ var(str) $] will be `69` [$ str[4:11] $] will be `is the time`
String indexing is extremely cool and powerful!
Functions, Comprehensions and Conversions
Once you really get your head around how variable expressions work, especially given they are powered by Python, some truly creative solutions can be realized. Certain Python functions, list comprehensions and lambda functions can be used to scrunch down logic into a few steps.
For example, using the following in a
Set Variable command will split our previous sentence into a new list variable.
Set Variable to set
[$ var.split() $]
['Now', 'is', 'the', 'time', 'for', 'all', 'good', 'men', 'to', 'come', 'to', 'the', 'aid', 'of', 'their', 'country.']
Not all Python functions are included, only the 'safe' functions that apply to direct variable manipulation. Here's a list of all the Python functions at your disposal. See Python Built-In Functions for more details about each function.
'abs', 'all', 'any', 'bin', 'bool', 'bytearray', 'chr', 'cmp', 'divmod', 'enumerate', 'float', 'format', 'hex', 'i
nt', 'isinstance', 'len', 'list', 'long', 'max', 'min', 'oct', 'ord', 'pow', 'range', 'repr', 'round', 'set', 'sorted', 'str', 'sum', 'tuple', 'unichr', 'unicode', 'zip'
Sometimes, you'll want only a subset of a list, or to apply another type of basic filter to a set. List Comprehensions are perfect for this:
Given an array variable called 'varlist':
[1, 2, 3, 4]
The following variable format would return a portion of that list:
[$ [x for x in varlist if x > 2] $] will be [3, 4]
And finally, for a little mind-blower. We've included access to some common conversion libraries as well, such as
base64. Therefore, this statement is valid:
[$ base64.b64encode(str) $]
Here's a list of all the conversion libraries we've included. Some are full implementation of the Python feature, others are limited in scope and capability.
'datetime', 'timedelta', 'ObjectId', 'b64encode', 'b64decode', 'parsedate', 'asjson', 'fromjson'
These are powerful features of variable replacement, but take care. Don't try to overdo logic inside the variable replacement syntax. If you need more capability, use the Utility - Python Script Command.
When the Task Engine encounters a variable token, it works from the inside out. It will determine if there are other variables within the variable, and evaluate them from the inside out. This is called a Nested Variable.
[$ variablename[[$index$]] $]
In this example, if 'index' is '3', the first replacement would result in:
[$ variablename $]
Another example of nested variable substitution. Assume that 'var2' = 'name'.
In this example 'var2' will first get substituted with the value 'name', then the variable 'variablename' will get substituted. This type of use is rare, but can be used to create multi-dimensional variable arrays of almost endless complexity.
Setting Arrays and Objects
Several commands can set variable arrays automatically, such as
Execute SQL and
You need not worry with details for creating an array or object variable from a string - the proper datatype conversion happens automatically.
When a variable is set from a raw input, be it a string, an array or an object, it is always evaluated to see if it represents a valid object. If the evaluation is successful, the variable will be created as that object type.
If an input cannot be evaluated as an array or an object, it will by default be set to a string.
Set Variable (or some external method) to create a string such as:
That's it. The Task Engine will evaluate that string into an Array variable.
If you actually need an input that would be interpreted as an object to be a literal string, enclose it in quotations, for example:
Set Variable command has another powerful ability - it can access a specific index (or path) into a variable and set just that sub-element.
When specifying the Variable name in the
Set Variable command, prefix the variable with the
@ sign. This indicates to the command that the variable is
at a certain index or path in the target variable.
If you do not use the @ prefix, Set Variable will replace the entire variable with the new value!
So, to set index #3 of an array variable 'listvar' to a new value 'foo':
Variable: @listvar Value: foo
In the case of a hierarchical object:
Variable: @dictvar['root']['status'] Value: pending
See the documentation for
Set Variable for full details.
To unset one or more variables, use the
Clear Variables command under the
Global variables are a set of reserved keywords unique to and available within a specific Task run.
Global Variable Naming Convention
Global variables use the same bracket notation as Runtime variables. The difference is Global variables have an underscore "_" prefix at the beginning of the variable name.
For example, to get the Task Instance number of the currently running Task, use the following:
Available Global Variables
The following is a list of the available global variables.
_TASK_INSTANCE- current Task Instance number
_TASK_INSTANCE_URL- URL to the log of the current Task Instance
_CLOUD_NAME- current Cloud in default scope (e.g. us-east-1)
_CLOUD_LOGIN_ID- current Cloud Account user id (e.g. access key)
_CLOUD_LOGIN_PASS- current Cloud Account password (e.g. secret key)
_TASK_NAME- task name for this Task Instance
_TASK_VERSION- task version for this Task Instance
_SUBMITTED_BY_EMAIL- the email address of the user that submitted the Task
_SUBMITTED_BY- the full name of the user that submitted the Task
_ASSET- the asset uuid that is associated with the Task Instance
_HTTP_RESPONSE- this is set by the HTTP command and represents response milliseconds
_SUMMARY- the XML document created by occurences of the Set Result Summary command
_OPTIONS- the extension options document associated with this Task Instance
_DEBUG- will output the full configuration of the Task Instance for troubleshooting purposes
_UUID- not actually a global variable, but a convenience substitution of a new uuid value
_UUID2- like _UUID, but without the dash "-" separators
Global variables cannot be set by the developer. They are set automatically by the Task Engine.
Task Handles are a special variable that contains all the relevant properties of a running Task Instance. To aid the user in identifying these special variables in the Task editor, they are differentiated by a leading hash (#) in the reference.
Several commands require the user to provide a Handle name. When providing the name, do not explicitly enter the hash mark. This syntax is used when referencing Handles, not when defining them.
Additionally, enter Handle names as text, such as MYHANDLE, not in variable reference syntax [$MYHANDLE$].
The following properties will be available. Assuming “ZZZ” was entered as the Handle name.
[$ #ZZZ.STATUS $]– The status of the Task.
[$ #ZZZ.STARTED_DT $]– The timestamp when the Task was started.
[$ #ZZZ.COMPLETED_DT $]– The timestamp when the Task completed.
[$ #ZZZ.CENODE $]– The Command Engine where the Task was processed.
[$ #ZZZ.PID $]– The PID (process ID) of the Command Engine process.
[$ #ZZZ.ASSET $]– The Asset ID (if any) where the Task was set to run.
[$ #ZZZ.ASSET_NAME $]– The Asset Name where the Task was set to run.
[$ #ZZZ.TASK_ID $]– The GUID ID of the Task.
[$ #ZZZ.TASK_NAME $]– The Name of the Task.
[$ #ZZZ.TASK_VERSION $]– The Version of the Task.
[$ #ZZZ.IS_DEFAULT $]– A flag indicating whether or not this is the ‘default’ version of the Task.
[$ #ZZZ.SUBMITTED_BY $]– The name of the user who submitted the Task.
[$ #ZZZ.SUBMITTED_DT $]– The timestamp when the Task was submitted.
Other Variables Notes
Here are some additional commonalities of variables.
Use in the Task Editor
In many of the step command input boxes, you can right click inside of the box to see a list of input, runtime and global variables. Not all commands provide this feature. Also though many commands set runtime variables, not all of them register them for use in the right click menu.
All variables are global in scope during the task execution. By their very nature, sub-elements of a dictionary or list variable are scoped within their parent container.
- Variable names should be restricted to alphanumeric characters "A-z", "0-9" and the underscore "_" character.
,, square braces
()in variable names are expressly forbidden.
- Use of dots
.is allowed but frowned upon, as it can lead to confusion.
- Do not use an underscore
_at the beginning of a variable name - this is reserved for Global Variables.
Other reserved characters should be avoided when choosing a variable name:
- At sign "@"
- Pound "#"
- Carat "^"
- Comma ","
- Period "."
- Star "*"
Since text inside the [$ $] escape syntax is evaluated by the Task Engine, Variable names are case sensitive. Ex: MyVar ~= MYVAR. A best practice recommendation is to use [$ UPPERCASE $] variable names, however it is completely up to the task developer to adopt whatever naming convention they like, following the aforementioned rules of course.
XPath Queries Within Variables
A special syntax can be used to perform XPath queries on data stored within a variable. The Carat
^ character serves as a delimiter between a variable name and an XPath expression.
If a carat ^ is found anywhere inside the variable brackets, the Task Engine will attempt XML parsing and XPath lookup.
Consider the following variable syntax:
[$ xmlstring^//node//subnode $]
The Task Engine will look for the variable named
xmlstring, and attempt to look up the XPath