Skip to main content
System StatusContact Support
VersionOne Community

Continuum Automate Task Command Reference

This feature is available in Ultimate edition only.

editions-u.png

Overview

There are many different Command Types that can be used on a Task. Commands are grouped together in Categories.

There are "internal" commands (responsible for flow control, system interactions, managing connections, etc.), "Cloud Provider API" commands (for interacting with a Cloud Provider's API), and "extension" commands (built by yourself, the community, or VersionOne).

Cloud Provider API documentation is beyond the scope of this document. Reference the published API documentation for the relevant Cloud Provider.

Extension commands are created by members of the Continuum community. Refer to the author for extension documentation.

Connect

New Connection

New Connection will create a named connection to an infrastructure asset such as a database, linux or Windows machine, etc. These connection persist, meaning that once you establish the connection it remains until either the Task finishes or the connection is explicitly dropped.

When connecting to a unix based system using ssh or telnet, this means that any environment variables created during previous steps will remain intact and be available for the life of the connection.

If the connection name alias was previously created by the same Task Instance, the original connection will be closed and a new one established.

Parameters

Connect via

Select the connection type. Valid choices are:

  • ssh - ec2 - ssh connection to an AWS Instance. Requires Username, Instance ID and a Private Key

  • ssh - a secure shell connection, typically used for Unix hosts

  • telnet - a telnet shell connection, typically for Unix hosts

  • mysql - MySQL database connection

  • oracle - an Oracle database connection

  • sqlserver - a Microsoft SQL Server database connection

  • sybase - A Sybase database connection

  • informix - an Informix database connection

  • winrm - a Windows Remote Management connection to a Microsoft Windows server

  • sqlanywhere - a Sybase SQL Anywhere database connection

Connection Name

The alias to give this connection. This will be the alias that is used in later steps. A Task can have more than one connection open as long as the connection's aliases are different.

to Asset or to Instance

Represents the connectivity options to the target. Can take one of three forms: an Asset name, AWS EC2 user id and Instance, or a list of key/value pairs to pass to the New Connection command.

Cloud

Only appears when ssh - ec2 connection type is used. Either select the cloud name from the drop down or use a variable. The Cloud name must be registered as a Cloud in the database.

Asset

To connect to an Asset with a fixed address with static credentials and possibly database name, create an Asset in the system and select it by clicking on the magnifying glass icon. A variable containing the asset name can also be used.

Ssh to an EC2 Instance

To connect to an EC2 Instance via ssh with private key authentication enabled, first import the private key into the applicable cloud. Select the cloud from the drop down "in Cloud" drop down, leave blank for AWS us-east-1 or use a variable.

Key/Value Pair Parameters

Pass a space delimited list of key value pairs. The following values are applicable:

  • address, server - IP address or fqdn of the target
  • userid, user, uid - user id or name required for authentication
  • password, pwd - password to use
  • port - optional port, defaults will be used if omitted
  • protocol - applicable to winrm, http or https. HTTP default
  • db_name, database - for database connections, the name of the 'database' or 'schema'
  • shared_cred, credential - a shared credential - (a uid/pwd or a private ssh key)
  • instance - only applicable for ssh - ec2 connections, the Instance ID

  • as - Provide a name for this connection. Other Commands will reference the connection by this name.

Debug - Options

Under the options button is the Debug checkbox. For an ssh connection type, this will turn on verbose ssh logging and print extra information in the filesystem log for the Task Instance. For winrm, this will print extra connection and debug information in the log.

ssh - ec2 example

The Following is an example of the "to Instance" syntax for connecting to an EC2 Instance.

username@instanceid

Key/Value Parameters example to database

address=10.20.10.23 userid=robert password=Mypassword port=1521 db_name=database1

Key/Value example to Microsoft using Winrm

address=10.20.10.24 userid=robert password=Mypassword protocol=https

Example using variables

userid=[[user]] address=[[address]] password=[[password]]

Drop Connection

Drop Connection will close a named connection made earlier in the execution of the Task.

Parameters

Connection Name

Define a connection name to drop. Click the search icon beside the field to select a connection or enter a for the connection if desired.

Control

End

The End Command halts the execution of the Task.

Parameters

Status

Choose the status with which the Task should end. Valid values: Completed, Error, Cancelled.

Log Message

Optional - specify a reason or message for the ending of the task.

Run Task

Run Task is used to launch a Task in a separate execution stream. The Task will be scheduled for immediate execution and will run independently from the calling Task. This is especially useful for running many tasks in parallel.

Parameters

Task

Select a Task. Click the Search icon beside the field to access a Task search dialog. Enter Search criteria and click the Search icon. Select a Task from the list.

Asset

Optional - select the Asset on which this Task will be executed. This Asset must be pre-defined in the system. Click the search icon beside the field to select an Asset or enter a for the Asset name if desired.

Task Handle

Enter a Task Handle name which will become the pointer to this Task Instance once started. This handle can be used to query the status and properties of the child task.

Time to Wait

Enter an integer value which defines how long, in seconds, the Task Engine should wait after running the defined Task before moving to the next Step. Valid values are:

  • Empty or 0 - do not wait... continue immediately to the next Step.

  • -1 - Wait indefinitely for the Task to complete. The Task will wait until the child Task completes.

  • Any value greater than 0 - Wait this number of seconds for the Task to complete. If it has not completed by this time, continue with the next Step.

Edit Parameters

If the child Task has parameters that are prompted for during it's initiation the values can be input here. Any parent Task variables that are used in the syntax will be dererefenced prior to passing to the child tasks.

Sleep

Sleep is used to pause Task execution for the number of seconds entered.

Parameters

Seconds to Sleep

Enter the desired number of seconds for the Task to wait.

Cancel Task

Cancel Task is used to force Task execution to stop on one or more running tasks using Task handles

Parameters

Task Instance ID(s)

Enter one or more Task Instance IDs separated by spaces. and pointers are permitted.

Wait For Tasks

Wait For Tasks will pause Task execution until one or more other Tasks have completed their work.

The Command Engine will monitor the provided Handles until they are all done. A Task will be considered finished when it arrives in any of the completion statuses - Error, Completed, or Canceled.

Parameters

Task Handles

Enter one or more Task Handles which are bound to running Tasks. Do not enter variable reference syntax or the # prefix for the handle in this field. Provide the handle name only.

Get Task Instance

Get Task Instance will get a "handle" on a currently active Task, exposing all the properties of that Task.

Parameters

Task Instance

Enter the Task Instance ID, or a variable which resolves to a Task Instance ID.

Handle

Enter a Task Handle name which will become the pointer to the Task Instance.

Set Logging Level

Sets the Task execution logging level to the specified value. Valid values: Debug, Info, Warning, Error, Critical. Debug is the most verbose log leve, Critical is the least. Critical will turn off all logging except for severe, Task ending errors. Critical logging level also turns off the Task logging into the database.

Parameters

Logging Level

Select one of Debug, Info, Warning, Error, Critical.

If

This Command performs conditional logic within a Task to change the flow of execution. Supports multiple "else if" conditionals and a final "else" Command.

Syntax Rules

All character string comparisons require quotes surrounding the values to be compared. Numeric comparisons do not require quotes.

For example to compare two strings to determine if they are equal:

"[[var1]]" == "YES"

or to compare two numbers:

[[var2]] < 10

Valid operator are as follows:

  • == - equal

  • != - not equal

  • < - less than

  • > - greater than

  • <= - less than or equal to

  • >= - greater than or equal to

  • and - multiple phrases must all evaluate 'true'

  • or - any phrase must evaluate 'true'

  • () - parens can group phrases together

Each If statement requires at least one If comparison and one Action Command.

Parameters

If

A comparison operation which will result in a true or false condition

Action

The step command to be executed in the case of a true condition from the If comparison. To set an Action:

  • Click in the Action placeholder (where it says "Click here to add a Command").

  • The Action placeholder will update with the message "Drag a Command from the toolbox and drop it here." To cancel the operation, click the x Cancel icon.

  • In the Task toolbox, click the Commands tab.

  • Click the Category, and identify the desired Command.

  • Drag the Command, and drop it in the Action placeholder.

  • The Action placeholder updates and now contains the Command.

  • Complete the Action Command properties as needed.

An Action placeholder can only contain one Command. If multiple Commands need to be processed it is best to consolidate these Commands within a Codeblock, and use a Codeblock Command in the Action placeholder.

Else If

Multiple Else If sections can be added as needed.

  • Click the + ( click to add another 'Else If' section ) link. Another section will appear containing another comparison and Action placeholder. Complete these two properties in the same manner as above.

  • To remove an Else If section, click the x icon in the upper right hand corner of the Else If section.

Else

A final Else section can be added if needed.

  • Click the + ( click to add a final 'Else' section ) link. Another section will appear containing another comparison and Action placeholder. Complete these two properties in the same manner as above.

  • To remove the "Else" section, click the x icon in the upper right hand corner of the "Else" section.

Loop

The Loop Command is similar to a 'for loop' in most programming languages. The Loop starts with a specific counter variable set to an integer and continues to execute the Command in the loop until the test is no longer true or a predefined number of iterations has occurred.

Parameters

Counter Variable

A new Variable that contains the loop number as the loop increments. This should not be an existing Variable, rather the name of a new Variable that will be created for this purpose. Enter a name directly, for example X. If you enter a Variable reference such as , it will be resolved before the Command is processed. Therefore, if X = "FOO", then the variable called FOO will be set, not X.

The Counter Variable has scope within the Loop Command. Any subsequent actions inside the loop will be able to reference the variable defined here.

For example, if you enter LOOP_NUM as the Counter Variable, will be available in the Action placeholder, and will increment for each iteration of the loop.

When a loop is finished, the Counter Variable remains available for the duration of the Task, containing the last value. If needed, it remains a useful indicator of the number of loops that were executed.

begins at

An integer representing the initial value of the Counter Variable, usually 1.

and increments by

An integer representing the value to increment the Counter variable at each iteration of the loop, usually 1.

Loop will continue until variable is

Select a comparison operator AND a value to which the Counter Variable will be compared. The value can be a literal string or number, or may also be a .

or n loops have occurred

An integer representing a maximum number of loops. A safety threshold: the loop will end when this number is reached.

Action

A Step Command to be executed on each iteration of the loop.

To set an Action:

  • Click in the Action placeholder (where it says "Click here to add a Command")

  • The Action placeholder will update with the message "Drag a Command from the toolbox and drop it here." To cancel the operation, click the [x] Cancel icon.

  • In the Task toolbox, click the Commands tab.

  • Click the Category, and identify the desired Command.

  • Drag the Command, and drop it in the Action placeholder.

  • The Action placeholder updates and now contains the Command.

  • Complete the Action Command properties as needed.

An Action placeholder can only contain one Command. If multiple Commands need to be processed it is best to consolidate these Commands within a Codeblock, and use a Codeblock Command in the Action placeholder.

Codeblock

Codeblocks are sections of a Task that can be created to encapsulate one or more Commands into a logical flow of execution. Codeblocks are usually created to run in a Loop Command or conditionally with the If Command. They can also be used to simplify management of the Task by separating the logic into sections.

Grab a Codeblock from the selector and drop it on the Step editor to create a Codeblock command!

Variable Scope

Variables in a Task have a global scope.

When a Codeblock is called during the execution of the Task, all variables created before the Codeblock is executed are available. Additionally, all variables created inside the Codeblock will remain available to subsequent Commands.

Parameters

Codeblock

Select or enter a Codeblock. Click the Search icon beside the field to access a Codeblock picker.

Recursion

There is no rule against a Codeblock calling itself, in fact this behavior is often used to create a long running or daemon Task.

When using recursive Codeblocks, take care to avoid infinite loops.

Subtask

Subtask runs a Task within the scope of the calling Task. Similar to a Codeblock, except that it enters the other Task at it's MAIN codeblock.

Unlike the Run Task Command which starts a new Task Instance in a separate ptoress, Subtask pulls another Task to run inside it's existing process.

Variable Scope

All variables available prior to Subtask execution are available within the Subtask and any variables set during the Subtask are available after it is finished. Subtasks are usually best for common execution logic that can be shared across multiple Tasks, such as a generic housekeeping Task.

Parameters

Task

Select a Task. Click the Search icon beside the field to access a Task search dialog. Enter Search criteria and click the Search button. Select a Task from the list.

Recursion

There is no rule against a Task calling itself as a Subtask.

When using recursive Subtasks, take care to avoid infinite loops.

Break Loop

The Break Loop command is used to interrupt the execution of a Loop or While command.

The Break Loop has no required properties. It will typically be placed in a If command within a Codeblock which is being called to perform logic inside a loop.

While

The While command is similar to a 'while loop' in many programming languages. The Test condition is evaluated at the top of each iteration.

In the following example the while loop will continue iterating until the runtime variable my_variable evaluates to something other than yes.

'[[my_variable]]' == 'yes'

Parameters

While

A test condition that will be evaluated for a True condition.

Valid operator are as follows:

  • == - equal

  • != - not equal

  • < - less than

  • > - greater than

  • <= - less than or equal to

  • >= - greater than or equal to

  • and - multiple phrases must all evaluate 'true'

  • or - any phrase must evaluate 'true'

  • () - parens can group phrases together

Action

A Step Command to be executed on each iteration of the loop.

To set an Action:

  • Click in the Action placeholder (where it says "Click here to add a Command")

  • The Action placeholder will update with the message "Drag a Command from the toolbox and drop it here." To cancel the operation, click the [x] Cancel icon.

  • In the Task toolbox, click the Commands tab.

  • Click the Category, and identify the desired Command.

  • Drag the Command, and drop it in the Action placeholder.

  • The Action placeholder updates and now contains the Command.

  • Complete the Action Command properties as needed.

An Action placeholder can only contain one Command. If multiple Commands need to be processed it is best to consolidate these Commands within a Codeblock, and use a Codeblock Command in the Action placeholder.

Comment

The comment command is simply a way to document a Task using a command. Comments should be added throughout a Task to document the Task logic. Comments are commonly added as the first step in a Codeblock.

Comments are not executed by the Task Engine.

Parameters

Comment

A descriptive comment.

Interact

Execute SQL

Execute SQL is used to run a SQL command against a remote database. The Execute SQL Command must be performed against an open connection to a database established by the New Connection Command.

Currently supported databases: Oracle, MS SQL Server, MySQL, Informix, SQL Anywhere

Commands can be the standard SQL 92 commands (select, update, insert, delete) or vendor specific SQL.

Parameters

Connection Name

A connection alias created with the New Connection command. Click the search icon beside the field to select a connection or enter a for the connection if desired.

Mode

The execution mode of the SQL command. One of the following:

  • SQL - a SQL statement to execute

  • BEGIN - begin a transaction

  • COMMIT - commit a transaction

  • ROLLBACK - rollback a transaction

  • EXEC - execute an Oracle procedure, only applicable with Oracle

  • PL/SQL - execute Oracle PL/SQL, only applicable with Oracle

  • PREPARE - prepare a SQL statement that contains placeholder bind arguments, only applicable with Oracle. Prepared statement is aliased with a Handle name.

  • RUN - run a prepared statement that is aliased with a Handle name. Bind value key / value pairs are passed in to the prepared statement.

SQL

The SQL statement or batch to be executed.

variables

Typically in a Task that runs SQL statements that return values (e.g. select) variables will need to be populated. Clicking on the Variables button will display a "Manage Variables" link and any variables that have already been set.

To populate variables, click on the Manage Variables link. This will display a dialog that can be used to setup the variables based on column number. After the SQL is run, all rows will be parsed into variable arrays.

Column numbers start at 1, not 0

Command Line

Used to communicate with an asset over ssh or telnet connection types. The Command Line command must be performed against an open connection to a suitable host established by the New Connection Command.

The Command Line Interface expects every command to return to the prompt. If a command does not return to the prompt, the Task will wait.

Take special care when executing commands that never return, such as starting a process. Make use of tools such as nohup in these cases to ensure the command returns to the prompt.

Parameters

Connection Name

Define a connection name identifying where the Commands will be executed. Click the search icon beside the field to select a connection or enter a for the connection if desired.

Command

The text of the Command to be executed. By their nature, Command Line commands can range from simple to complex. Since ssh or telnet connections are required, these Commands are most often Unix shell commands.

Command Line Interface is a very useful Command type. Placing many command line interface Commands in sequence is a powerful replacement for traditional shell scripting.

If a shell script is written in the traditional fashion, a) the script must exist on every host where it needs to be executed or b) every host must have a file system mounted where scripts are centrally stored. In either case, Unix administration is required for management of these scripts.

Placing logic in one or more Command Line commands houses scripting in a central location so that scripts can be executed on any system without any special configuration on the host.

Options

The Command Line Interface Command has additional options available. Click on the Options button to view these properties.

Timeout

The number of seconds the Command Engine will wait for the command line prompt to return until it timeouts out the process. The Task will error if the command ends due to a timeout.

Positive Response

Overrides the set of characters that the Task Engine waits for to determine that the command is finished running. Accepts regular expressions. Useful for interacting with commands with their own prompts (other than the shell prompt).

Negative Response - a set of characters that the Task Engine tests for and will error out if they are returned by the Asset. Useful if a command does not return to the prompt, but generates an error message. (For example, "My Process can not connect...")

variables

Commands that are sent to a target host using the Command Line command usually produce output. Variable processing is a way to parse this data and get them into Task variables.

Buffers that are chopped into rows will populate variable arrays that can be processed in loops, etc.

Clicking on the Variables button will display a "Manage Variables" link and any variables that have already been set.

To populate variables, click on the Manage Variables link. This will display a dialog that can be used to setup the variables based on a number of options.

Row Break Indicator

Optional. The buffer can be chopped into rows by specifying a row delimiter or indicator. This will typically be LF (linefeed). If a row break is not used, the whole buffer will be considered to have 1 row.

To set the Row Break Indicator, click the little magnifying glass to select a value. These delimiter values are the most common ASCII character values used.

Field Break Indicator

Optional. Similar to the field brea, the column delimiter is used to chop up the buffer into columns. A Field Break Indicator is required if setting variables using the Delimited method.

To set the Field Break Indicator, click the little magnifying glass to select a value. These delimiter values are the most common ASCII character values used.

Add a Variable

This is where the different variables and their corresponding population methods are defined. There are four different population methods:

  • Delimited - uses the Field Break Indicator delimiter to determine the column to select the value from. NOTE: Column numbers start at 1, not 0.

  • Range - set a beginning and end range. Can either use a numeric position on the line, such as 1 and an end position, such as 10. This would get the first character on the line through the 10th and place it in the variable. The word "end" can be used to match the end of the line. Prefix and suffix can be used to specify search strings to match the beginning and end. The variable will be populated if there is a match. The prefix and suffix strings will not be part of the variable's value. Positional and prefix / suffix can be mixed and matched.

  • Regex - a regular expression used to match within the buffer row. The match will be placed in the variable. Follows the Python re syntax documented here: http://docs.python.org/2/library/re.html

  • Xpath - an Xpath expression to use on an XML or sometimes HTML data.

WinRM PowerShell and WinRM Command

The WinRM commands are used to communicate with Microsoft servers using Winrm. WinRM Command will run commands at a DOS shell prompt and WinRM PowerShell will run Powershell scripts. The output can be placed into variables for further processing.

Winrm must be configured on the target server to accept Basic authentication. Kerberos is an option but requires further configuration on the Task Engine Linux host and beyond the scope of this document.

A valid connection created by the New Connection command must be established before issuing the Winrm command.

Parameters

Connection

Define a connection name identifying where the Commands will be executed. Click the search icon beside the field to select a connection or enter a for the connection if desired.

Command

The DOS command or Powershell script to send to the target server.

To send a Powershell script, the script must be Base64 UTF16 Encoded prior to sending. The Set Variable command provides a way to encode the script. The command will then be sent using the following command where is the variable containing the encoded script.

powershell -encodedcommand [[s]]

Options

Timeout

A number of seconds that the Task Engine waits for the command to complete. If the command times out, the Task errors.

Return Code

The Windows shell command return code as a result of running the command. Typically 0 mean success, 1 or greater is an error. However it has been found that this can vary based on the command and needs to be locally understood based on the commands used. For instance the Powershell command returns a 0 even on error.

Result Variable

The name of a variable to receive all the output from the command.  Newlines will be encoded.  Using Variables as described below gives more control over parsing the output.

Variables

Commands that are sent to a target host using the Command Line command usually produce output. Variable processing is a way to parse this data and get them into Task variables.

Buffers that are chopped into rows will populate variable arrays that can be processed in loops, etc.

Clicking on the Variables button will display a "Manage Variables" link and any variables that have already been set.

To populate variables, click on the Manage Variables link. This will display a dialog that can be used to setup the variables based on a number of options.

Row Break Indicator

Optional. The buffer can be chopped into rows by specifying a row delimiter or indicator. This will typically be LF (linefeed). If a row break is not used, the whole buffer will be considered to have 1 row.

To set the Row Break Indicator, click the little magnifying glass to select a value. These delimiter values are the most common ASCII character values used.

Field Break Indicator

Optional. Similar to the field break, the column delimiter is used to chop up the buffer into columns. A Field Break Indicator is required if setting variables using the Delimited method.

To set the Field Break Indicator, click the little magnifying glass to select a value. These delimiter values are the most common ASCII character values used.

Add a Variable

This is where the different variables and their corresponding population methods are defined. There are four different population methods:

  • Delimited - uses the Field Break Indicator delimiter to determine the column to select the value from. NOTE: Column numbers start at 1, not 0.

  • Range - set a beginning and end range. Can either use a numeric position on the line, such as 1 and an end position, such as 10. This would get the first character on the line through the 10th and place it in the variable. The word "end" can be used to match the end of the line. Prefix and suffix can be used to specify search strings to match the beginning and end. The variable will be populated if there is a match. The prefix and suffix strings will not be part of the variable's value. Positional and prefix / suffix can be mixed and matched.

  • Regex - a regular expression used to match within the buffer row. The match will be placed in the variable. Follows the Python re syntax documented here: http://docs.python.org/2/library/re.html

  • Xpath - an Xpath expression to use on an XML or sometimes HTML data.

Send Email

Send Email is used to send email messages from a Task. The fields of the Send Email Command may contain variable references, e.g. .

NOTE: the Messenger must be properly configured and running for the Send Email command to work.

Parameters

To

To, enter one or more email addresses, separated by commas.

Cc

Optional - carbon copy, enter one or more email addresses, separated by commas.

Bcc

Optional - blind carbon copy, enter one or more email addresses, separated by commas.

Subject

Enter a subject for the message.

Message

Enter message body. HTML formatting is allowed if desired to build a more user friendly email message. The resulting email will contain both a MIME encoded and plain text version that can be consumed by the recipient's email reader either way.

Add Summary Item

The Add Summary Item command is used to generate messages that will be accentuated at the top of the Task Log in a readable format. It may be used to display information that was dynamically generated during the Task, such as a virtual machine's address. Calling Add Summary Item multiple times during the Task execution will simply append values to the Summary line.

In the future this command may be used to return a result set to other Tasks or through API calls.

Parameters

Item Name

The item name is similar to a key name for the data.

Detail

The data that will be stored associated with the Item Name and displayed next to in the log.

Log Message

Use Log Message to place a message in the Task logging table. This can be informational, for debugging purposes, or for saving error messages.

Parameters

Log

Enter a message to be inserted into the Task log. This message may contain variable references, e.g. , which will be evaluated and then written into the log.

HTTP

The HTTP Command can either issue an http get call on a remote URL. It will retrieve the resulting HTML or XML which can be used to populate variables.

Parameters

Request Type

The Http request type to perform. The following types are supported:

  • GET

  • POST

  • DELETE

  • PUT

  • HEADER

URL

Enter a URL to retrieve. This would include the protocol prefix of http or https.

Data

POST or PUT payload data to send to the http server. The Task Engine performs variable processing prior to sending.

Header Fields

Key and value pairs that are attached to the http header. To add more than one key and value pair, click the + sign on the right.

Options

Timeout

A timeout value in seconds.

Retries

In the case of a timeout, the number of times to retry the request.

Status Code Variable

A variable name in which to place the http response code. Useful for testing for certain conditions.

Status Message Varaible

A variable name in which to place the http response message that corresponds to the code.

Response Info Object Variable

A variable name in which the reponse info object will be placed. Individual objects in the info variable can be accessed using the .getheader(name) function. For example if you set the info variable to INFO, a specific header can be referenced as such:

[$ INFO.getheader("Content-Length") $]

Response Header Variable

A variable name in which the full reponse header will be placed.

Response Body Variable

A variable name in which the full response body will be placed. This is typically the html code that is returned from a web page.

Response Time ms Variable

A variable name that in which the server response time will be placed. Milliseconds.

variables

Commands that are sent to a target host using the Command Line command usually produce output. Variable processing is a way to parse this data and get them into Task variables.

Buffers that are chopped into rows will populate variable arrays that can be processed in loops, etc.

Clicking on the Variables button will display a "Manage Variables" link and any variables that have already been set.

To populate variables, click on the Manage Variables link. This will display a dialog that can be used to setup the variables based on a number of options.

Row Break Indicator

Optional. The buffer can be chopped into rows by specifying a row delimiter or indicator. This will typically be LF (linefeed). If a row break is not used, the whole buffer will be considered to have 1 row.

To set the Row Break Indicator, click the little magnifying glass to select a value. These delimiter values are the most common ASCII character values used.

Field Break Indicator

Optional. Similar to the field break, the column delimiter is used to chop up the buffer into columns. A Field Break Indicator is required if setting variables using the Delimited method.

To set the Field Break Indicator, click the little magnifying glass to select a value. These delimiter values are the most common ASCII character values used.

Add a Variable

This is where the different variables and their corresponding population methods are defined. There are four different population methods:

  • Delimited - uses the Field Break Indicator delimiter to determine the column to select the value from. NOTE: Column numbers start at 1, not 0.

  • Range - set a beginning and end range. Can either use a numeric position on the line, such as 1 and an end position, such as 10. This would get the first character on the line through the 10th and place it in the variable. The word "end" can be used to match the end of the line. Prefix and suffix can be used to specify search strings to match the beginning and end. The variable will be populated if there is a match. The prefix and suffix strings will not be part of the variable's value. Positional and prefix / suffix can be mixed and matched.

  • Regex - a regular expression used to match within the buffer row. The match will be placed in the variable. Follows the Python re syntax documented here: http://docs.python.org/2/library/re.html

  • Xpath - an Xpath expression to use on an XML or sometimes HTML data.

Continuum API Call

The Continuum API Call command is used to interact with the REST API. The REST API provides an interface into the Continuum platform.

More information on the available API commands can be found here:

Parameters

Host

A URL address to the API endpoint. The port value is required and by default listens on port 8080.

Method

The web service method that will be called. See documentation links above.

UserId

A user id that has API permissions.

Password

The password for the user.

Result Variable

A variable name in which the result from the web service api call will be stored. This can either be in XML, Json or plain text format and is configurable based on parameters.

Error Variable

If an error is returned from the API, the error message will be placed in this variable.

Timeout

A timeout value in seconds

Parameters

Name / value pairs that will be sent to the API. See the API documentation links above.

Variable

There are several Commands for dealing specifically with variables. In addition to these Commands, other commands capable of retrieving data may also "set"-assign a value to-a variable.

Set Variable

Set Variable is used to manually populate a variable with alphanumeric data. It can be used to set multiple variables within the same Command.

Parameters

Variable

The name of the new variable to be created, or the existing variable to be set. Enter a name directly, for example X. This can be the name of an existing Variable. In this case, the variable will be updated with the new value. If a nonexistent name is used, a new variable will be created.

To set a specific element in a variable array, use a comma immediately followed by an integer. For example to set the fifth element in the variable array MYVAR: MYVAR,5. If the array does not exist, elements 1 through 4 will be created empty

Value

A value to assign to the variable.

Modifier (optional)

Optional directives that will transforms the value prior to storage in the variable.

  • None - the default, no modification of the value will occur.

  • UPPERCASE - change the value to uppercase.

  • lowercase - change to lowercase.

  • Base64 Encode - encode the value to base64.

  • Base64 UTF16 Encode - the value is utf16 little endian encoded before base64 encoding. This is required for sending Powershell scripts to Windows via Winrm.

  • Base64 Decode - Decodes a base64 encoded string.

  • Write JSON - Converts a Pyton data structure into a JSON string. The value should be the name of a variable to convert, not excaped with the square brackets [[ ]].

  • Read JSON - Loads a JSON formatted string into a Python data structure object as a variable. Useful for rereferencing values within the JSON.

  • Evaluate - Evaluate is used transform strings from one format to another. Currently this only applies to date strings but may include other uses in the future. The following Python functions are allowed for Evaluate:

Samples:

Get a formatted current date:
datetime.now().strftime("%Y%m%d%H%M%S")
-> 20130927090859

Parse a string into a date:
parsedate('20130927090859')
-> 2013-09-27 09:37:48

Compare a date in the past to now, True if older than 30 days:
(datetime.utcnow() - parsedate("2013-06-13 16:36:23")) > timedelta(days=30)
-> True
  • Math - allows for calculations to be performed with a limited set of math operators and the value stored in the variable. The following operators and their respective symbols are allowed at the moment. Order of operations precedence represented by parens (). It should be noted that some calculation (e.g. division) will return numeric values vs. integers.

    • Addition: +

    • Subtraction: -

    • Multiplication: *

    • Division: /

    • Exponentiation: **

    • Bitwise Exclusive Or: ^

    • Modulo: %

Samples:

2 ** 3 / 2 * (1 + 1)
-> 8.0

5432 + 1
-> 5433

Adding and Removing Variables

To add another Variable click the + ( click to add another ) link. A new row will appear.

To remove a variable click the x icon at the right side of the row.

Clear Variables

Clear Variables is used to delete one or more variables from memory. If the variable is an array the whole array will be cleared.

To clear a specific element in an array, enter the array variable name, a comma and the index number. The element will be popped off the array and any elements that follow that index will be shifted down one. For example, given a variable array of var1,1 var1,2 var1,3 if var1,2 is cleared, var1,3 will shift to var1,2.

To add another Variable click the + ( click to add another ) link. A new row will appear.

To remove a variable click the x icon at the right side of the row.

Parse Text

Parse Text is used when data or variables need to be further processed into variables or arrays of variables. For example, an Execute SQL Command may return a single text field which needs to further be parsed using Range or Regular Expression methods.

Parameters

Text

A literal block of text or a to be processed

variables

Variable processing is a way to parse this data and get them into Task variables.

Buffers that are chopped into rows will populate variable arrays that can be processed in loops, etc.

Clicking on the Variables button will display a "Manage Variables" link and any variables that have already been set.

To populate variables, click on the Manage Variables link. This will display a dialog that can be used to setup the variables based on a number of options.

Row Break Indicator

Optional. The buffer can be chopped into rows by specifying a row delimiter or indicator. This will typically be LF (linefeed). If a row break is not used, the whole buffer will be considered to have 1 row.

To set the Row Break Indicator, click the little magnifying glass to select a value. These delimiter values are the most common ASCII character values used.

Field Break Indicator

Optional. Similar to the field break, the column delimiter is used to chop up the buffer into columns. A Field Break Indicator is required if setting variables using the Delimited method.

To set the Field Break Indicator, click the little magnifying glass to select a value. These delimiter values are the most common ASCII character values used.

Add a Variable

This is where the different variables and their corresponding population methods are defined. There are four different population methods:

  • Delimited - uses the Field Break Indicator delimiter to determine the column to select the value from. NOTE: Column numbers start at 1, not 0.

  • Range - set a beginning and end range. Can either use a numeric position on the line, such as 1 and an end position, such as 10. This would get the first character on the line through the 10th and place it in the variable. The word "end" can be used to match the end of the line. Prefix and suffix can be used to specify search strings to match the beginning and end. The variable will be populated if there is a match. The prefix and suffix strings will not be part of the variable's value. Positional and prefix / suffix can be mixed and matched.

  • Regex - a regular expression used to match within the buffer row. The match will be placed in the variable. Follows the Python re syntax documented here: http://docs.python.org/2/library/re.html

  • Xpath - an Xpath expression to use on an XML or sometimes HTML data.

Substring

Substring is used to populate a variable with part of a string.

Parameters

Variable

The name of the variable that will be populated with a portion of the source string. Enter a name directly, for example X or a variable. If you eJnter a Variable reference such as , it will be resolved before the Command is processed. Therefore, if X = "FOO", then the variable called FOO will be set, not X. This can be the name of an existing Variable. In this case, the variable will be updated with the new value. If a nonexistent name is used, a new variable will be created.

To set a specific element in a variable array, use a comma immediately followed by an integer. For example to set the fifth element in the variable array MYVAR: MYVAR,5

Start

An integer indicating the position in the source string to start. The first character in the string is 1, not 0 like many programming languages.

End

An indicator of the end position of the value extracted. This can be an integer, a plus sign and number of characters past the start index (for example +5 to get the start index plus five more characters) or the word "end" to indicate the last character in the string. To go from the end of the string back a certain number of characters, end-n where n is the number of characters is supported.

Text

The set of characters to be extracted from. Can be a literal value, or a .

Exists

The Exists command will check one or more variables to ensure they have values. Each Exists statement requires at least one Variable and one Action Command.

Parameters

Variables To Test

One or more Variables which will be tested to see if they are defined. Variables are considered defined even if they have a blank value (zero length string).

Is True

If checked, will additionally consider the value of the variable for typical values that indicate a true condition, such as "1", "yes", or "true".

Has Data

If checked, will check to see if the variable contains at least 1 byte.

Positive and Negative Actions

Step commands to be executed based on the results of the test. The Positive action will occur if the Exists evaluates to true, visa versa for the Negative action.

To set an Action:

  • Click in the Action placeholder (where it says "Click here to add a Command").

  • The Action placeholder will update with the message "Drag a Command from the toolbox and drop it here." To cancel the operation, click the [x] Cancel icon.

    • In the Task toolbox, click the Commands tab.

    • Click the Category, and identify the desired Command.

    • Drag the Command, and drop it in the Action placeholder.

    • The Action placeholder updates and now contains the Command.

    • Complete the Action Command properties as needed.

Security

Get Shared Credentials

Retrieves a shared credential from the database and places the user id, password and domain values (if applicable) into variables that can be referenced in a Task.

Parameters

Alias

The shared credential name to look up.

User ID Variable

A variable name in which to store the user id.

Password Variable

A variable name in which to store the password.

Domain Variable

A variable name in which to store the domain value. The domain value would typically be an Active Directory domain and may not apply.

Store Private Key

The Store Private Key command takes a ssh private key value and stores it encrypted in the database associated with a cloud endpoint. This private key can then be used to login to linux machines via ssh.

Parameters

Keypair Name

The name of the keypair. In Amazon Web Services this would be the equivilent to the keypair name in EC2.

Cloud Name

The name of the Cloud endpoint to associate the private key with.

Private Key

The private key data.

Generate Password

Generates a random string based on a number of characters and places the string in a variable. Characters used will be a-Z and 0-9.

Parameters

Length

The number of random characters to generate.

Variable Name

The variable name in which to store the password.

Datastore

The datastore is a built-in MongoDB NoSQL database which can hold any data that a Task developer may require to share data with other tasks or reports. NoSQL databases are schema-less which means the data structures can be dynamic and free form. To learn more about MongoDB, see the link below.

Datastore Insert

Inserts a a json data document into a named MongoDB datastore collection. Creates the collection if it does not exist.

Parameters

Collection

The name of the collection in which to store the data. A collection in MongoDB is similar to a table.

ObjectId Variable

Optional. When a new document (similar to a row) is inserted into MongoDB, a unique identifier is returned. If desired, name a variable in which this identifier is to be stored.

Pairs

Key / value pairs to add to the document. Click the + button on the right to add more key value pairs.

Name

A key name for which to associate the value in the document. This is similar to a column name.

Value

The data value to insert.

Datastore Query

Queries the MongoDB datastore collection given a query to use. Extracts data and places the data in variables.

Parameters

Collection

The name of the collection in which to query for the data. A collection in MongoDB is similar to a table.

Query

The query to use to find the result set. Uses the MongoDB "find" directive. See the MongDB find documentation here:

Automate uses a Python interface to MongoDB. The Mongo documentation and examples are all written assuming the reader is interfacing with the Mongo console. As such, certain features may have different syntaxes.

Columns

One or more columns or key values to extract from the result set. To add additional columns, click the + button on the right. If more than one datastore document matches, multiple variable array values will be set.

Column Name

The key name in the result set from which to extract the value.

Variable Name

The variable name in which to store the value.

Datastore Update

Updates an existing document in a named MongoDB datastore document. If the query criteria does not match and existing document and upsert is checked, the a document (row) will get inserted.

Parameters

Collection

The name of the collection in which to query for the data and update. A collection in MongoDB is similar to a table.

Upsert

If checked, a new document will get created in the collection if the query does not match any existing documents.

Query

The query to use to find the document to update. Uses the MongoDB "update" directive. See the MongDB update documentation here:

Columns

Key / value pairs to either update or insert.

Name

Key name for the value.

Value

Value data to update or insert associated with the key.

Datastore Find and Modify

Performs a datastore query and update in a single atomic transaction. MongoDB does not support transactions in a traditional RMDB sense. However the find and modify command will find a document(s) and will perform the update on the document while locking it. Therefore during the execution only this command will be able to update the documents.

Once the documents have been updated, values can be pulled out of the updated documents and placed into variables. Optionally documents can be upserted if the query doesn't match at least one document. The document can also be removed instead of updated.

The Find and Modify command is related to the MongoDB findandmodify command:

Parameters

Collection

The name of the collection in which to query for the data and update. A collection in MongoDB is similar to a table.

Upsert

If checked, a new document will get created in the collection if the query does not match any existing documents.

Remove

If checked, the matching document will be removed. Out Column values will still be returned and placed into variables.

Columns

The columns to be updated. Consists of a Name which resembles the key to update and a Value which is the value to assign to the key.

Out Columns

The columns to retrieve from the document after the update. Consists of a Name for the key and a Variable in which the value is stored. If more than one datastore document matches, multiple variable array values will be set.

Datastore Delete

Delete datastore documents based on matching query criteria. Related to the MongoDB remove command:

Parameters

Collection

The name of the collection in which to query for the data and update. A collection in MongoDB is similar to a table.

Query

The query to use to find the document to delete.

Datastore Create Collection

Creates a collection in the MongoDB datastore. A collection is similar to a table in a relational database.

Parameters

Collection

The name of the collection to create.

Datastore Drop Collection

Drops a collection in the MongoDB datastore. A collection is similar to a table in a relational database.

Parameters

Collection

The name of the collection to drop.

Datastore Create Index

Creates an index on a datastore collection to speed up lookups and queries.

Parameters

Collection

The name of the collection on which to create the index.

Unique

Either yes or no (default). If yes, a unique index will be created on the combination of columns in the index.

Columns

One or more columns (keys) can be specified to create a composite key. It does not matter if the column names exist or not in the collection.

AWS

The AWS command set is closely aligned with the Amazon Web Services API documentation found on the AWS website. Refer to the individual product categories on the AWS documentation website, specifically the API Reference documents.

Examples

Under the Examples category, Task extension command examples can be found. Extensions are a way to create custom step commands for use within your tasks. More to come on building custom extension Task commands.

vCloud

vCloud API Call and Parse

Issues a vCloud API call against the vCloud web service, retrieves the response XML and parses the response into variables in a single command. This is a single command that encompasses the activities of both the vCloud API Call and vCloud Parse XML commands. See the VMware vCloud API programming guide for more information on API methods, parameters, responses, etc.

Parameters

Cloud Endpoint Name

Optional. A Cloud endpoint defined for the vCloud Director web service. This named cloud endpoint must be defined in the database. If not defined the endpoint will be the default for the cloud account in current scope when the Task is run.

Url or Method

Either method or href. For href the full url will be used to make the API call. Typically this is used when a vCloud XML response contains an href value that is extracted, put into a variable and then used to make further API calls. Method is used as a shortcut, the API url is constructed using the vCloud API endpoint and the method.

Action

Either GET, POST, DELETE or PUT. This correspond to the http action that is required for a particular API call.

Data

Required for a POST or PUT operation. This data takes a form of XML and is specific based on the API call that needs to be made. Variable substitution is performed prior to sending to the web service.

Content Type

Required when sending POST or PUT data and is specific to the API call being made.

Xpath

This is an Xpath query that will be performed on the result set in order to extract data into variables.

Values to Extract

Based on the Xpath query, either XML attributes or elements can be extracted from the XML. The Attribute or Element Name is the name of the value to extract (case sensitive), Variable is the variable name in which to place the data. Type determines whether the data is an XML attribute or element to find.

Output Variable

Optional. Used to place the full XML response in a variable. Can be used to further process later.

Options

Timeout

Optional. The http timeout value in seconds. Default is 30 seconds.

vCloud API Call

Issues a vCloud API call against the vCloud web service and retrieves the response XML. See the VMware vCloud API programming guide for more information on API methods, parameters, responses, etc.

Parameters

Cloud Endpoint Name

Optional. A Cloud endpoint defined for the vCloud Director web service. This named cloud endpoint must be defined in the database. If not defined the endpoint will be the default for the cloud account in current scope when the Task is run.

Url or Method

Either method or href. For href the full url will be used to make the API call. Typically this is used when a vCloud XML response contains an href value that is extracted, put into a variable and then used to make further API calls. Method is used as a shortcut, the API url is constructed using the vCloud API endpoint and the method.

Action

Either GET, POST, DELETE or PUT. This correspond to the http action that is required for a particular API call.

Data

Required for a POST or PUT operation. This data takes a form of XML and is specific based on the API call that needs to be made. Variable substitution is performed prior to sending to the web service.

Content Type

Required when sending POST or PUT data and is specific to the API call being made.

Output Variable

Optional. Used to place the full XML response in a variable. Can be used to further process later.

Options

Timeout

Optional. The http timeout value in seconds. Default is 30 seconds.

vCloud Parse XML

Parses the vCloud XML response into variables. See the VMware vCloud API programming guide for more information on API methods, parameters, responses, etc.

Parameters

XML Data

Enter a variable containing the vCloud XML response data.

Xpath

This is an Xpath query that will be performed on the result set in order to extract data into variables.

Values to Extract

Based on the Xpath query, either XML attributes or elements can be extracted from the XML. The Attribute or Element Name is the name of the value to extract (case sensitive), Variable is the variable name in which to place the data. Type determines whether the data is an XML attribute or element to find.

vSphere

The vSphere Task command set can be used to manage VMware vSphere virtual machines either directly with the ESX host or through the vCenter management interface. The vSphere command set is a front end for the VMware SOAP web service. Therefore proper VMware credentials are required to establish an authenticated connection and perform the commands.

VMware List VMs

Returns a list of VMware virtual machines. The list can be filtered with the image unique identifier or several other key / value pair filters. If no filters are used, all virtual machines will be returned.

The columns returned for each vm is as follows in order:

  • config.instanceUuid

  • name

  • overallStatus

  • config.guestFullName

  • config.template

  • config.hardware.numCPU

  • config.hardware.numCoresPerSocket

  • config.hardware.memoryMB

  • runtime.powerState

  • runtime.host

  • guest.ipAddress

  • guest.net

  • datacenter

Specific information on each of these column values can be found on the VMware vSphere SDK API documentation site:

Parameters

vCenter Endpoint

The named Cloud endpoint that represents either the vCenter endpoint or an ESX server. If unspecified the default cloud endpoint for the cloud account under which the Task is run will be used.

InstanceUUID

Optional - A virtual machine unique identifier. This will be in UUID format.

Filters

Filters consist of name and value pairs. Multiple values per name are allowed. Every named filter is considered an AND and is inclusive (vm must match all named criteria. Each value within a named filter is considered an OR, must match at least one value.

For more information on vm properties that can be filtered on, see the VMware vSphere SDK API documentation site:

variables

The result set from vSphere is turned into a rows and columns format for easy variable processing. Variables are defined by specifying an index value that corresponds to the column number.

VMware Power Off

Powers off a virtual machine given the virtual machine unique identifier.

Parameters

vCenter Endpoint

The named Cloud endpoint that represents either the vCenter endpoint or an ESX server. If unspecified the default cloud endpoint for the cloud account under which the Task is run will be used.

InstanceUUID

Optional - A virtual machine unique identifier. This will be in UUID format.

VMware Power On

Powers on a virtual machine given the virtual machine unique identifier.

Parameters

vCenter Endpoint

The named Cloud endpoint that represents either the vCenter endpoint or an ESX server. If unspecified the default cloud endpoint for the cloud account under which the Task is run will be used.

InstanceUUID

Optional - A virtual machine unique identifier. This will be in UUID format.

VMware Clone Image

Will clone a virtual machine within a vCenter datacenter. Essentially makes a copy of the virtual disk and registers it as a new virtual machine.

Parameters

vCenter Endpoint

The named Cloud endpoint that represents either the vCenter endpoint or an ESX server. If unspecified the default cloud endpoint for the cloud account under which the Task is run will be used.

InstanceUUID

Optional. The virtual machine unique identifier to be cloned. This will be in UUID format.

New Name

A new name for the virtual machine. Must be unique within an ESX server or vCenter datacenter.

Folder

Optional. The vCenter virtual machine folder in which to place the new virtual machine.

Resource Pool

Optional. The vCenter resource pool in which to place the new virtual machine.

Power On (yes/no)

Determines whether the new virtual machine should be powered on after cloning or not.

Utility

Python Script

Using this command, you can write Python scripts that are run in a memory space that is sandboxed from the task instance runtime. Three of the Task Engine internal functions are exposed in this Python sandbox:

  • logger (log file)
  • audit (log in the database and presented in the task instance log in the user interface)
  • vars (the variable dictionary at the moment this step was entered)

Some additional notes about using Python Script... If the exit() command is used in the script or even if there is an error in the script the task will stop immediately with the status of Completed. If the intention is to pass information back to the task and then perform additional logic or notifications, see the Variables section below and set some sort of status indicator using a try/except section.

Also, to preserve the "sandboxed" space within which the script will run, the following Python methods are not allowed:

  • open
  • file
  • execfile
  • compile
  • reload
  • input
  • __import__
  • eval

LOG

Writes to the task engine log file based on the Debug level set in the task. "critical" will always write, whereas "debug" will write only if the task is set to write informational messages. The five levels are critical, error, warning, info and debug. Task instances run by default at the "warning" level.

AUDIT

Writes to the task instance log in the database and is presented in the web page version of the task log. The command takes two arguments, a command name (deprecated) and the log message.

variables

Allows variables to be passed back and forth between the Python script and the task engine.

To Read:

VARS.get("foo")
VARS["foo"] (will raise exception if key doesn't exist)

To Set:

VARS["key"] = "value"

  • Was this article helpful?