Continuum Automate Task Variable Reference

Last updated
Save as PDF

This feature is available in Ultimate edition only.

Overview

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.

Setting Variables

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 Script or extension commands) can set variables from within their own code
Explicitly by a Developer using the Set Variables command

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.

Referencing Variables

To reference a variable, use the following bracket-dollar escape syntax:

[$variablename$]

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 $]

Newlines

Variable expressions must be on one line. Use of newlines inside the brackets is disallowed and will raise an error.

Datatypes

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$]

Arrays (Lists)

If a variable is an Array, use the following syntax:

[$arrayvar[2]$]

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.

If var = "Now is the time for all good men to come to the aid of their country."

[$ var[14] $] will be `e`
[$ var(str) $] will be `69`
[$ str[4:11] $] will be `is the time`

String indexing is extremely cool and powerful!

Objects (Dictionaries)

Python dictionaries follow the same format as Javascript Objects and JSON objects.

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.

Functions

Using Set Variable to set bar =:

[$ var.split() $]

will set bar to:

['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', 'int', 'isinstance', 'len', 'list', 'long', 'max', 'min', 'oct', 'ord', 'pow', 'range', 'repr',
'round', 'set', 'sorted', 'str', 'sum', 'tuple', 'unichr', 'unicode', 'zip'

Comprehensions

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]

Conversions

And finally, for a little mind-blower. We've included access to some common conversion libraries as well, such as json and 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.

Nested Variables

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[3] $]

Another example of nested variable substitution. Assume that 'var2' = 'name'.

[$variable[$var2$]$]

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 HTTP.

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.

So, use Set Variable (or some external method) to create a string such as:

["apple","orange","pear"]

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:

'["apple","orange","pear"]'

Changing sub-elements

The 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[2] Value: foo

In the case of a hierarchical object:

Variable: @dictvar['root']['status'] Value: pending

See the documentation for Set Variable for full details.

Unsetting Variables

To unset one or more variables, use the Clear Variables command under the Variable category.

Global Variables

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:

[$_TASK_INSTANCE$]

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

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.

Scope

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.

Naming Convention

Variable names should be restricted to alphanumeric characters "A-z", "0-9" and the underscore "_" character.
Commas ,, square braces [] and parens () 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 //node//subnode.

For more information on XPath, see w3school's Xpath Tutorial and the Python Elementtree Xpath syntax page