5.VarStrings

Overview
Functions
Definitions

1.Knowledge Item Structure
2.Variables
3.Scope
4.Data types
5.VarStrings
6.Matching variables and values
7.Data Manipulation
8.All About lists
9.KI examples

Automation Issue Lifecycle
KI Best Practices
KI Debugging

Table of Contents

Mathematical operations
String Modifiers
JSON handling with VarStrings

At almost every location in a Knowledge Item where strings could be entered, the engine also processes "VarStrings". VarStrings are strings that can be dynamically expanded during the runtime with specific variable values. This works as follows:

It is possible to construct strings using string interpolation:

on
  Foo
  Bar == "Hello, ${Foo}"

Mathematical operations

It is possible to use math expressions on the right side of a match:

on
  Foo
  Bar == Foo + 1

log("This is the ID of the current node: ${NodeID}")

In addition to this simple string replacement, we can perform some mathematical operations:

# Addition
LOCAL::result = number1 + number2
log("${number1} + ${number2} = ${LOCAL::result}")

# Subtraction
LOCAL::result = number1 - number2
log("${number1} - ${number2} = ${LOCAL::result}")

# Division
LOCAL::result = number1 / number2
log("${number1} / ${number2} = ${LOCAL::result}")

When the result of a division is about to be assigned to a variable, if division by 0 was attempted, the value of the variable will be set to 'MathError'. It’s important to note that using 'MathError' in subsequent operations can lead to further arithmetic errors in the following KIs

# Multiplication
LOCAL::result = number1 * number2
log("${number1} * ${number2} = ${LOCAL::result}")

# Mod
LOCAL::result = number1 % number2
log("${number1} % ${number2} = ${LOCAL::result}")

There is also a mathematical library integrated into the engine which allows the evaluation of mathematical formulas. For this purpose, the corresponding expression is enclosed in $[ ]:

# Multiplication
log("Calculated Value: $[${number1} * ${number2}]")

The engine also integrates a mathematical library (https://github.com/Rob-bie/expr) that enables the evaluation of mathematical formulas. To use this funcionality, the relevant expression must be enclosed in $[ ]. When including a variable in the mathematical formula, the variable should be enclosed in ${}

# Absolute value
Value = "$[abs(-20)]"

# Absolute value using variables
TS1 = "1732542005189"
TS2 = "1732539624000"

TS3 = "$[abs(${TS1} - ${TS2})]"

String Modifiers

Also, various modifiers can be used in variable strings to convert the output. Let’s assume we have a variable "data" with a string as value. We can modify the value "hello world" in the following ways:

Modifiers must be put before scope declaration, not before variable: ${+LOCAL::test}

Table 1. Modifiers
	Description	Sample from "Hello world"
+	Convert to uppercase	"HELLO WORLD"
-	Convert to lowercase	"hello world"
^	Convert to upper camelcase	"Hello World"
\	Shell encoding (extra backslash for " and \ )	\"Hello world\"
&	HTML encoding	"Hello world"
_	Convert non alphanumerical chars to underscore	Hello_world

Syntax

upper =  "${+data}"
lower =  "${-data}"
camel =  "${^data}"
shell = "${\data}"
html = "${&data}"
under =  "${_data}"

These can also be combined as required, so if the value is "hello world" as above, you can combine uppercase and underscore conversion ${+_HELLOWORLD} for a result like: HELLO_WORLD.

JSON handling with VarStrings

VarStrings allow simple parsing of JSON structures.

Handling of JSON structures is initialized by adding # to a variable name inside the VarString followed by operators to address Key:Value pairs inside the structure.

Table 2. JSON Operators
Operator	Function
`key`	Name of "key" in the root JSON object
`['subkey']`	Name of "subkey" in a JSON sub-object
`[0…n]`	n-th element of a JSON (sub-)array item (first element is 0).
`[-n…-1]`	n-th element of a JSON (sub-)array item counted from the end of the array (-1 is the last item).

The following structure shows a minimalist example. We assume the data is stored in the variable "JSONData"

{
  "UserInfo": {
    "User": "Jane Doe",
    "Location": {
      "Country": "Germany",
      "City": "Frankfurt"
    },
    "Pets": [
      {
        "Name": "Daisy",
        "Type": "Cat",
        "Age": "3"
      },
      {
        "Name": "Duke",
        "Type": "Dog",
        "Age": "1"
      },
      {
        "Name": "Felix",
        "Type": "Cat",
        "Age": "97",
        "Color": "Black"
      }
    ]
  }
}

Extract the value for "Country"

${JSONData#UserInfo['Location']['Country']} → "Germany"

Extract a full entry from the "Pets" array

${JSONData#UserInfo['Pets'][1]} → "{"Name":"Duke","Type":"Dog","Age":"1"}"

Extract the name for the second entry in the "Pets" array

${JSONData#UserInfo['Pets'][1]['Name']} → "Duke"

You can only extract single values or objects using this syntax, you can not extract arrays.

If you need to perform more complex operations on JSON structures, please refer to the JavaScript element.