Variables in KurocoEdge

Overview

KurocoEdge includes an in-memory data storage which persists for each request individually. Since there are 2 hooks sfor actions processing - the request phase and the response phase - the variables created during request phase persist all the way through the response phase. After the response is sent back to the user, the associated memory storage is freed.

Some specific rules may create special variables, but in most cases they are user-defined.

Variables types

Variables are typed, and may be of any of the following type (mirroring JSON types) :

Type	Description	Example
Null	Represents a JSON null value	null
Bool	Represents a JSON boolean	true
Number	Represents a JSON number, whether integer or floating point	12.5
String	Represents a JSON string	"a string"
Array	Represents a JSON array	["an", "array"]
Object	Represents a JSON object	{"an": "object"}

String representation and nesting

Most actions with an input allow to use a string representation of a variable using the notation `{$my_variable}. If a variable is not a String, then it will JSON stringified.

For example, you can use them in Header Rule's value, or HTML Edit Rule's content.

Furthermore, the variables are stored in a tree structure, and therefore can be accessed using dot . notation. For example, an Object variable parent_var might have two children parent_var.child1 and parent_var.child2, and each child may be stringified like this : {$parent_var.child1}. Or an array variable parent_arr allows accessing its children using integer index : {$parent_arr.0}.

If an accessed nested variable does not exist (for example {$parent_arr.9}), then the resulting stringified result will not be replaced, and be used as-is : {$parent_arr.9}. This decision was made to minimise any potential collision with user data.

Creating variables

As you might have noticed, an Action has a "Condition / Variable" part - indeed, in most cases variables are created there along with conditions, except few special rules.

There are 4 main ways to define the variables :

• Static Variables
• Captured Variables
• API Variables
• Variable Transformations

Below is a brief overview of each type of variable, with basic guidance and best practices for usage.

Each of the variable types can be created and managed within the 'Conditions / Variables' section of any Action within a Rule.

Static Variables

Static variables can be explicitly assigned within the 'Conditions / Variables' section of an Action, by creating a new 'Static variable' in the Field select/dropdown menu.

This is the most basic form of variable that can be used in KurocoEdge.

info

Static Variables are always a valid "condition"

Why Use Static Variables?

As in any programming language, it is useful to be able to define variables to store a value that can be easily called later (without having to repeat the value).

Static variables can be used in the fields of an Action's 'Execution' section, for a cleaner and more efficient way of entering in values.

info

For a tutorial on how to create and use Static Variables, refer to the following document:
Using Variables in KurocoEdge – Static Variables

Captured Variables

Unlike 'Static' or 'API' variables, which are explicitly defined in the 'Conditions / Variables' section of an Action, KurocoEdge also allows you to define special 'Captured' variables within a Rule's Action. This type of variable is created as a captured 'Field settings' value.

For example, in 'Conditions / Variables' you can choose a 'Header', 'Body prefix', or 'Match variable value' field, and capture its current value using the regular expression syntax for Named Capture Groups : (?P<name>…). Note that variables captured inside unnamed groups are not registered.

Why Use Captured Variables?

This is a convenient, and highly versatile way to create variables 'on-the-fly' in KurocoEdge. These captured variables can then be reused like other KurocoEdge variables within the Action's 'Execution' section, with the {$variable} syntax.

A common use case is to capture a value and insert it as a parameter in a URL (ex. when making an API call to fetch data).

info

For a tutorial on how to create and use Captured Variables, refer to the following document: Using Variables in KurocoEdge – Captured Variables

API Variables

The most advanced form of variable in KurocoEdge is the API variable. This allows you to assign a value fetched from an API endpoint to a variable. API variables can be used within an Action's 'Execute' section, the same way a Static Variable can be. However, it can be more complicated to assign a value to an API variable, as the API data is often an object with nested values.

In order to access nested values, it is necessary to use dot notation.

For example, if an API variable (object) called address contains a nested value of street the correct syntax to use in the 'Execution' section is:

{$address.street}

Generally, when using an API variable, it is a best practice to either return a top-level string value (from a top-level key/value pair within an object), or use dot notation to return a nested string value.

info

API Variable condition returns true only if the API call succeeds, has a proper JSON response body, and all the specified Expected Variables are found in that JSON.

Why Use API Variables?

Working with API response objects can be complicated and unwieldy. Assigning a value (or nested value) to a variable can make it easier to work with - for example, when you need to insert a value as a parameter in a URL or when fetching dynamic data from an API endpoint.

info

For a more advanced tutorial on how to create and use API Variables, refer to the following document:
Using Variables in KurocoEdge – API Variables

Variable Transformations

This feature allows to apply one or more functions to any existing variable, effectively transforming them. Functions are applied in order, and new variable is created - without affecting the original one if variable pointer is used.

Why use Variable Transformations

While regular expressions allow rich substring extractions from string variables, sometimes it is useful and more convenient to apply specific functions - or transform Objects or Arrays in a form more suitable for your business logic.

info

For an in-depth tutorial on Variable Transformations and the explanation of features, refer to the following tutorial : Using Variables in KurocoEdge – Variable Transformations