Use workflow variables

Introduction

When designing a webcommander workflow, which consists of multiple individual commands, it's very likely that some commands share the same parameter values. Meanwhile, those values are likely changing when the workflow executes in different environments. It's obviously a better practice to define variables for those parameter values.

Besides, in certain cases, you may want to use the output of a former command as the input of a latter command. For instance, you use listVmHost command to retrieve all ESX hosts managed by a vCenter and then use listPortGroup command to list all port groups on the first ESX returned by the previous command. In this case, you could define a variable from the first command's output and then feed it into the second.

How to define workflow variables

To address the two aforementioned requirements, there are two methods to define variables for a workflow.

Use "Workflow > Define variables" command

Unlike other general commands, this one and the command of "Workflow - Sleep" are only available and meaningful within a workflow.

In this command, variables are defined in the following format

__variable1__=value1
__variable2__=value2
__variable3__=__variable1____variable2__
serverAddress=x.x.x.x

Each line is a "name=value" pair. If there are multiple "=" in a line, the first one is considered as the separator and all others are part of the variable value. And the string to the left of the first "=" is considered as the variable name.

The variable name could be any string. It's recommended to add prefix and suffix underscores, as showed in the example, to improve the readability of the workflow template file.

Please note that if a variable name is identical to a command parameter name, such as "serverAddress" in the example, it sets a default value for that parameter of all subsequent commands. And there is no need to explicitly input the variable name into those parameters.

Use "variableList" parameter of other commands

When variable values need to be determined by the output of a command, they could be defined in the format below in the variableList parameter of that command:

__variable1__=XPath expression
serverAddress=(//VmHost/Property[@Name='Name'])[1]

The only difference between this and the previous method is the usage of XPath expression, which could be used to retrieve the text of any XML element of the command output. For instance, (//VmHost/Property[@Name='Name'])[1] in the example refers to the first ESX host's name returned by command listVmHost.

<VmHosts>
    <VmHost>
       <Property Name="Name">x.x.x.x</Property>
    ...
</VmHosts>

Syntax of XPath expression could be found at http://www.w3schools.com/xpath/xpath_syntax.asp.

Please note that it's not supported to retrieve an attribute of XML element.

![Workflow variables] (https://github.com/vmware/webcommander/blob/master/www/images/wiki/workflow-variable-xpath.png)

Use JSON variable

When a command outputs information in JSON format, it could be saved in a JSON variable.

To define a JSON variable, simply use the expression below:

varJSON=//stdOutput

The variable name must end with "JSON". "stdOutput" is the XML tag which includes the JSON string the command outputs.

To refer to a specific value in the JSON variable, follow the instructions below: If the varJSON variable content is

{
	"vm" : {
		"name" : "myvm",
		"ip" : "192.168.1.100",
		"netmask" : "255.255.255.0",
		"portgroup" : "vm network",
		"cluster" : "mycluster"
	}
}

To refer to the VM IP, the expression is

['varJSON']['vm']['ip']