Variables

Variables are very useful to store an information to be replaced on command lines, REST API calls, or compare values on control flows (more details about control flow can be found at Control Flow). Variable instructions have the following syntax:

VARIABLE_IDENTIFIER = VARIABLE_VALUE

Variable identifiers must be unique and start with a letter. The other characters of variable identifiers can be numbers and underscores.

Example of valid variable identifiers:

var command1 cmd_var

Example of invalid variable identifiers:

_var 1command #those won’t work.

Variables can contain 2 kinds of value: strings or lists.

Strings are like statements and can contain pretty much any kind of character, as being letters, numbers, spaces, etc.

Lists are a group of strings stored in a variable.

There are two types of variables: static and dynamic.

Static Variables

Static variables have their values defined before automation. Example of a static variable value containing letters, space and numbers:

var = "abc 123"

Notice that with static variable, strings must be enclosed within double quotes.

An example of a static variable list would be:

var = ("abc", "def", "ghi")

To define a list, you require to have the string between double quotes, with strings separated by comma, all enclosed within parentheses.

To use variables, you simply specify where in the script you want to replace the variable by the actual value using {{VARIABLE_IDENTIFIER}}. For example:

newFileName = "logFile1.log"
IMPC: touch {{newFileName}}

The implementation-command line will become:

IMPC: touch logFile1.log

Notice that double quotes are not part of the replacement. If you require double quotes as part of the replacement, you have to escape it, by using (backslash). For example:

stringToFile = "\"string with quotes\""
IMPC: echo {{stringToFile}} > textFile

After evaluation:

IMPC: echo "string with quotes" > textFile

For lists, you have to indicate the position, or index or the value you want to use for replacement, first position being index 0. For example:

listOfFiles = ("file1", "file2", "file3")
IMPC: rm -f {{listOfFiles[0]}}

After evaluation:

IMPC: rm-f file1

Reference Number

Before I explain dynamic variables, you need to know what is a reference number.

X. can be prefixed to an implementation instruction as reference. It is optional, but essential with dynamic variables. Replace X by a number. An example:

1.PREC:
2.IMPC:
3.POSTC:
4.BACKC:
5.FINC:
6.RESTU:

Notice that for CLI command instructions, the only relevant reference number for variables is the -COMMAND: (or ending with C:). In the case of REST instruction, the only relevant reference number is the one used with REST-URL: (or RESTU:).

To be used as reference, the number and respective implementation instruction has to be unique within the script.

If you are not using variables within your script. There is no real need to use the reference number.

Dynamic Variables

Dynamic variables change during implementation and can have values based on the results of the commands.

The syntax for dynamic variables is:

VARIABLE_IDENTIFIER = {[EXTRACT_INSTRUCTION] [REFERENCE]}

Items in square brackets are optional, and items on curly braces are required.

Clarifying each item of dynamic variables:

  • We begin with VARIABLE_IDENTIFIER as usual.

  • The value assigned to the variable will depend on 2 items: EXTRACT_INSTRUCTION and REFERENCE. Both are optional, but at least one is required. Both can be used as well.

The purpose for the EXTRACT_INSTRUCTION is to define what part of the results of a command we want to assign to the variable, and there are two ways that this can be done:

  1. Using a JSON(“VALUE_QUERY”) extact

  2. Using an XML(“FULL_XPATH_ELEMENT_QUERY”, “OPTIONAL_ATTRIBUTE”, “OPTIONAL_NS_REG”) extract

Before giving the first example, let me explain the REFERENCE part of the line. It refers to the results of one of the commands previously applied. Let me show some examples:

OBJECT: AWS
1.IMPC: aws ec2 run-instances...
ec2InstanceId = JSON("Instances[0].InstanceId") $1.IMPC

If the results of the command aws ec2 run-instances... returns the JSON data: {“Instances”: [{“InstanceId”: “abc123456”}]}, the variable ec2InstanceId will have the value “abc123456”, and if it uses that in another command, it would work similar to the constant variables:

IMPC: echo {{ec2InstanceId}} >> ec2InstanceIds.txt

Which will evaluate to:

IMPC: echo abc123456 >> ec2InstanceIds.txt

For XML extraction, only the paramenter “XPATH_ELEMENT_QUERY” is required. If “OPTIONAL_ATTRIBUTE” is provided, the value of the attribute is fetched instead of the value of the element. “OPTIONAL_NS_REG” can be used to register a list of known namespaces in the format: “<prefix1>=<href1> <prefix2>=href2> …”. Usually only “XPATH_ELEMENT_QUERY” is necessary. An example of XML extraction is:

VAR = XML("/xml/data/object[1]/id", "", "") $1.REST

Variable reference for REST responses are $X.REST for enclosed-body data, and $X.RESTH("PARAMETER") for returned headers (it does not require extract instruction), with the same sequence number used by the respective RESTU: instruction. An example of variable assignment using returned header value:

VAR_HEADER_CONTENT_TYPE = $1.RESTH("Content-Type")

IMPORTANT: During automation runtime, OBJECT: & ADDOBJ: instructions must have variables with values. If the variables on those lines do not have value, the automation will be interrupted and backed out (if applicable).

IMPORTANT: You can use dynamic variables with instruction OBJECT:, but be sure to have the respective object already part of the objects.csv file and already have the credentials persisted for the object. If the new object is not on objects.csv file, you can still use ADDOBJ: to insert the new object, but you must have the credentials on the ADDOBJ: instruction. If the credentials are not found during implementation, the automation will be interrupted, and backed out (if applicable).

IMPORTANT: Variables and line ANSWER: cannot have variable replacements.

An instruction that proves to be very useful to check variables is PRINT:. An example of how PRINT: works with variables:

var = "VALUE1"
list = ("VALUE2", "VALUE3", "VALUE4")

PRINT: The var value is "{{var}}"
#This will print: The var value is "VALUE1"

PRINT: The second element of list is {{list[1]}}
#This will print: The second element of list is VALUE3

PRINT: instruction will also print to log file.