Variables

Variable Types

Variables are used throughout the platform script to manipulate data. Variables can be of any of the following types:

Data Type	Description	Example
Boolean	A boolean value, true or false	{ "SetItem" : { "Name" : "var", "Value" : true }}
Integer	Any valid integer value	{ "SetItem" : { "Name" : "var", "Value" : 999}}
Float	A floating-point value	{ "SetItem" : { "Name" : "var", "Value" : 9.99}}
String	A string of characters	{ "SetItem" : { "Name" : "var", "Value" : "a \"quoted\" string "}}
Array	An array of values, of any type	{ "SetItem" : { "Name" : "var", "Value" : [ "one", "two", "three" ] }}
Object	A complex object	{ "SetItem" : { "Name" : "var", "Value" : { "value1" : 1, "value2" : "str2", "value3" : true }}}

Variable scoping

Global: Each operation parameter defined for an operation is copied to a variable in RSMS and is global in scope. Any operation parameter can be accessed anywhere in the script.

Custom variables can be defined anywhere in a script, but the scope will depend on where the variable is defined. Any variable declared in the top level of an operation, such as CheckSystem, is global in scope, and can be accessed anywhere in the script. Variables that have the prefix Global: when created will also be global in scope, e.g.
{ "SetItem":{"Name":"Global:Connectobject","Value":null}}

Local: Unless created within the top level 'Do' block of an operation, a variable is local in scope. Scope is defined by what is contained in the 'Do' Blocks. Lower level 'Do' Blocks can see the variables defined in higher level 'Do' blocks back up to the function boundary. Higher level 'Do' Blocks cannot see the variables defined in lower level 'Do' blocks. An attempt to access a variable that is out of scope will result in an error when the operation is run.

Variable Naming

A variable name can only contain letters, numbers or underscore character. It cannot begin with a number.
{ "SetItem":{"Name":"Variable_123","Value":null}}

A variable can be made global in scope by prefixing its name with Global:
{ "SetItem":{"Name":"Global:Variable_123","Value":null}}

Resolving Variables

There are 2 methods available to resolve a variable to the corresponding value: String Variable Substitution and Inline Expressions.

Most command parameters that are of type Value will accept a hard-coded value: "a hard-coded \"string\" value", a variable substitution: "%Address%" or an inline expression "%{ Address }%"

A variable of a complex type (e.g a Json object) can only be accessed using an inline expression: "%{ MyObject.Name }%"

String Variable Substitution

The %identifier% pattern is called a "variable substitution pattern", and as the name suggests it is literally substituting the values of variables in to a string.
Since it is a string operation, it will always return a string.
Note: This pattern can only be used with variables of a simple type (e.g. string, int), and will always result in a string variable, regardless of the type of the variable substituted. Do not use this method when accesing a complex type.

Default Value:

By default, if a string variable substitution resolves to a null or empty string, RSMS will throw an error. This is intentional, to avoid running an unintentional command as a result of resolving a missing or mistyped variable name.

To change this behaviour, then the script must assign a default value when resolving the variable, using the syntax : %::$%, e.g. %DelegationPrefix::$sudo% will set DelegationPrefix variable to 'sudo' if the DelegationPrefix operation paramaeter is empty or null.

Example:

{
    "SetItem": {
        "Name": "FirstName",
        "Value": "Bubba"
    }
},
{
  "SetItem": {
    "Name": "CopyOfFirstName",
    "Value": "%FirstName::$empty%"
  }
}

This example will result in CopyOfFirstName having the string value "Bubba", or the string value "empty" if FirstName happens to be empty.

Example:

{
    "SetItem": {
        "Name": "Age",
        "Value": 100
    }
},
{
  "SetItem": {
    "Name": "CopyOfAge",
    "Value": "%Age::$0%"
  }
}

This example will result in CopyOfAge having the string value "100", or the string value "0" if Age happens to be empty.

Inline Expressions

The %{expr}% pattern marks an inline expression. This method of resolving variables is much more powerful and flexible than using variable substitution.

When the whole input is an expression the value resolves to the type and value of the expression result.

When the pattern appears in the middle of the string the expression is resolved, the result converted to a string and substituted in to the rest of the string, hence the result is a string.

Example:

{
    "SetItem": {
        "Name": "index",
        "Value": 0
    }
}
{
  "SetItem": {
    "Name": "index",
    "Value": "%{index + 1}%"
  }
}
{
  "Log": {
    "Text": "Index below limit %{index < 10}%"
  }
}

This example will result in index having the int value of 1 and the string "Index below limit True" will be logged.

Supported Inline Expressions

Inline expressions must be valid C# expressions, but not all C# expressions are accepted by the resolver. The following are supported:

Description	Namespace	Type
Primitive Types	System	bool, byte, char, decimal, double, int, float, long, object, sbyte, short, string, uint, ulong, ushort
Exceptions	System.Exceptions	Exception, OverflowException
Misc Types	System	Math, Convert, Array, DateTime, DateTimeOffset, Delegate, Enum, EventArgs, ExpandoObject, TimeZoneInfo, Type
Collections	System.Collections	ArrayList, Hashtable, IEnumerable
Generic Collections	System.Collections.Generic	IEnumerable<>, Dictionary<,>, HashSet<>, List<>,Queue<>,Stack<>
Linq Types	System.Linq.Expressions	Expression, Expression<>
Linq operations	System.Linq	Enumerable, Queryable, IQueryable<>
Text Operations	System.Text	Encoding, StringBuilder
Regular Expression support	System.Text.RegularExpressions	Regex, Match, RegexOptions, Capture
Tuples	System	Tuple, Tuple<>, Tuple<,>, Tuple<,,>, Tuple<,,,>, Tuple<,,,,>, Tuple<,,,,,>, Tuple<,,,,,,>, Tuple<,,,,,,,>