Guide to Variables used in STU

How “Variables” work in STU and PAM

1. Format
   1.       {{GroupName.VariableName}}
   2.       {{GroupName.VariableName(index, function, and another variable)}}
      
      
2. Data Types
   a. Omnipotent (String-base)
   Variable data types get automatically converted into an appropriate type such as Integer, Float, and Date, when the data has been fed into an Operation.   

3. Data Store Types

1. 1.   Simple    Stores as one data and retrieves plainly with {{GroupName.VariableName}}
   2.   Array      Stores as a series of data and retrieves with index {{GroupName.VariableName(5)}}
   3.   CSV       Stores as a table of data and retrieves with column/row coordinates where the VariableName represents column and index represents row like {{GroupName.A(5)}} --- see more about CSV variable in the section right below.

4. CSV type variables

1. 1. This type of variables can only be generated by the Plugin operations as one of the three Return Value options

When you want to use the column headers as Column names leave the check box checked just like in the example given above. Otherwise, columns are uppercase alphabets like A, B, C --- AA, AB and so on just like the notation in MS Excel.

5. Array type

1. 1. You can create and define array variables in the Variable section in STU (lower left corner). 
      In the example given below, {{family.brothers}} and {{family.sisters}} are the array variables as they have the check boxes under array column checked.

6. Index

1. 1. Index is integer (you can use variable) starting with 1

Examples

((family.brother(1))) or {{family.brother({{loop.count}})}}

7. Functions like COUNT, APPEND, and LAST are available.

1. 1. They must be all uppercase letters.
   2. COUNT shows you how many data exist in array or in a column of a CSV variable.
   3. APPEND add a new data at the end of an existing array variable.
   4. LAST      retrieves the data at the end of the array variable.

Example

{{family.brothers(COUNT)}}

{{family.sisters(APPEND)}}

{{family.sisters(LAST)}}

8. The User Params operation in the Interactive group will generate its own variable.

9. Repeat counter variable.

1. 1. The Repeat operation manages a local (Repeat specific) variable.
   2. It is shown as {{rp.index}}

There are 3 types of Variables used in STU.

1. User defined variables
2. Plugin generated variables
3. Special variables

1. User defined variables

User Defined Variables are the ones that are defined in the Variable section of STU.

2. Plugin generated variables

Plugin/Operation generated variables are the variables specific to the Plugin when the Return Value of CSV has been selected.

One example is the User Param operation in the Interactive tool-group.

For most of plugin generated variables, Users get to define group name but the variable names are defined by the plugin itself.

In below example Folder_C becomes the group name of the variable.

Then in this example of File Monitor plugin, the variable names are Index, filepath, and filesize like described in its help document.

3. Special variables

 Special Variables are fixed in the STU system such as {{rp.index}} in the Repeat operation which holds the counter data.

VARIABLES

1. Notation

{{group_name.variable_name}}

Double curly brackets in both front and the back and there is a . (period) in between group_name (your choice) and variable_name (your choice)

2. Examples

Define a "grp1" variable group like below in the 'User variables in Scenario'.

• "grp1" including 3 variables, "var1","var2",and "var3".

{
	# Group variable name: "grp1"
	"grp1": {
		# simple variable (number)
		"var1": 100,

		# simple variable (string)
		"var2": "Hello World, Thank you for using ARGOS"

		# array 
		"var3": [ 1, "Hello", "World", "Thank you for choosing ARGOS" ]
	}
}

• "grp2" including 3 variables, "var4","var5",and "var6".

{ 
	# Group variable name: "grp2"
	"grp2": {
		# simple variable (number)
		"var4": 30,

		# simple variable (string)
		"var5": "I am a Bot"

		# array
		"var6": { 2, "ARGOS" }
}

Below are the variable notation examples and the actual value of the variable.

FUNCTIONS

1. COUNT

How to use "COUNT" in "Repeat"

'COUNT' can be used as an index in "Repeat".

See below.

When repeating same operations for all items in array, you have to know the total number of items in array variable. You can obtain it by using 'COUNT'.
For examples, "{{grp1.var3(COUNT)}}" means the total number of items of "{{grp1.var3}}" array variable.
The value of {{grp1.var3(COUNT)}} is "4".

2. APPEND

How to use "APPEND"

 Use case

• 'Excel Basic' action
• Result value of plugins

How to use "APPEND" in "Excel Basic"

Suppose you have a array variable that already has a values. 

In this example, I'll show you how to append "{{grp2.var2}}" (simple variable) and "{{grp2.var3}}" (array) to another array variable "{{grp1.var3}}".

Sample Excel Data for "grp2":

Ex1. Append "{{grp2.var2}}" (simple variable) to "{{grp1.var3}}" (array)

1. Add "Excel Basic" action
2. Choose "Read" in 'Read/Write'
3. Select an excel file to read in STU
4. (Option) Set 'Sheet name' (default: sheet1)
5. Click "Add Item" 
6. Set "Cell range" to "**B2**"
7. Write "{{grp1.var3(APPEND)}}" in "Select variable" input box

※ To check out the result value of "{{grp1.var3}}", print on 'Notepad' by using 'Repeat" and 'TextInput' actions

Ex2. Append "**grp2.var6**" (array) to "grp1.var3" (array)

1. Add "Excel Basic" action
2. Choose "Read" in 'Read/Write'
3. Select an excel file to read in STU
4. (Option) Set 'Sheet name' (default: sheet1)
5. Click "Add Item" 
6. Set "Cell range" to "**B3:C3**"
7. Write "**{{grp1.var3(APPEND)}}**" in "Select variable" input box

How to use "APPEND" with return value of plugin

There are 3 types in the result type of plugins. Only 'string' can be used with 'APPEND'.

1. Select the result type of plugin to 'string'
2. Select 'Variable name' in variable table drop down menu. (ex) {{grp1.var3}}
3. Edit variable name like "{{grp1.var3(APPEND)}}". <br>The returned value is appended to {{grp1.var3}}.

Global Variables

• Global Variables are pre-defined variables that will store more commonly used environment specific information.
• Below is the list of the ARGOS Global Variables
• These variables are especially useful when you want to run a site-survey in advance for the production environment for your new “bot” – they capture all you need to know to prepare the bot for the production environment.

View Variable output sample

Global Variables to help your “logs” 

• In Jan 2023, total 9 new Global Variables were added (see below)
• They are designed to provide a better “debug” experiences when used in conjunction with the Citizen Log plugin
  • Just by adding them in the “Event Message” field will make your log much more intuitive and powerful in case you need to track down what really happened with your bot.
• Special Function
  {Global.allUserVarJsonPath(groupname)}

• This will give you a full path to the JSON file that contains ONLY the list of User Variables with a specific “groupname”