Actions #

This section lists and documents most actions available in Varv.

Reference: A full list of actions can also be found in the Reference. The reference might also contain more actions, that are currently in development and which specification might change in the future.

Concept Actions #

"clone" Action #

An action that clones pies a concept instance including all its properties.

Parameters:

Properties:

Examples:

Clones the currently selected target concept instance deeply:

{
    "clone": {
        "of": "$target",
        "deep": true,
        "as": "myOutputVariableName"
    }
}

Clones a concept instance stored in a variable shallow (shorthand version):

{ "clone": "$myConceptVariable" }

"count" Action #

An action that counts how many instances of a given concept exist.

Parameters:

Properties:

Examples:

Counts how many "myConcept" that matches the given “where” filter, and saves the result as "myOutputVariableName":

{
    "count": {
        "concept": "myConcept",
        "where": {
            "property": "myProperty",
            "equals": "myTestValue"
        },
        "as": "myOutputVariableName"
    }
}

Counts how many "myConcept" there is, and saves the result as "count" (shorthand version):

{ "count": "myConcept" }

"exists" Action #

An action to check whether instances of a concept exist.

Parameters:

Properties:

Examples:

Sets a variable "myOutputVariableName" to true/false depending on if any "myConcept" that matches the where filter exists:

{
    "exists": {
        "concept": "myConcept",
        "where": {
            "property": "myProperty",
            "equals": "myTestValue"
        },
        "as": "myOutputVariableName"
    }
}

Sets a variable "exists" to true/false depending on if any "myConcept" exists (shorthand version):

{ "exists": "myConcept" }

"getType" Action #

An action to check the type of a concept instance, property, or variable.

Parameters:

Properties:

Examples:

Retrieves the type of a property:

{
    "getType": {
        "property": "myProperty",
        "as": "myPropertyType"
    }
}

Retrieves the type of a target concept instance with the given UUID:

{
    "getType": {
        "target": "someConceptUUID",
        "as": "myConceptType"
    }
}

Retrieves the type of a target concept instance and puts it in the variable getType (shorthand version). Looks up in the following order: ContextConcept, LocalConcept, GlobalConcept, Variable, UUID.

{ "getType": "somePropertyNameVariableNameOrConceptUUID" }

Shorthand that looks up the current event target’s concept type:

"getType"

"new" Action #

An action to create new instances of concepts.

Parameters:

Properties:

Examples:

Creates a new instance but does not change the current selection, which means that the newly created instance is only passed along as a variable:

{
    "new": {
        "concept": "myConcept",
        "with": {
            "myFirstProperty": "someValue",
            "mySecondProperty": false,
            "myThirdProperty": "$myVariableName"
        },
        "as": "myVariableName",
        "select": false
    }
}

"remove" Action #

Removes one or multiple concept instances.

Parameters:

Properties:

Examples:

Removes the current context target:

{ "remove" }

Remove the concept or concepts (if variable points to an array) that the variable holds:

{ "remove": "$someVariable" }

"select" Action #

An action to select concept instances. It is possible to select concept instances from a concept type, a property, a specific instance, or a variable.

Parameters:

Properties:

Examples:

Select all concept instances of a given concept type:

{ "select": { "concept": "myConceptType" }}

Select all concept instances of a given concept type (shorthand version):

{ "select": "myConceptType" }

Select all concept instances of a given concept type and save the selected UUIDs in a variable:

{
    "select": {
        "concept": "myConceptType",
        "as": "mySelection"
    }
}

Select a concept instance with given UUID:

{ "select": { "target": "concept57b18d140f8709bf4b74" }}

Select a concept instance saved in a variable (shorthand version):

{ "select": "$myConceptVariable" }

Select all concept instances of a given concept type, filtering for some property:

{
    "select": {
        "concept": "myConceptType",
        "where": {
            "property": "color",
            "equals": "yellow"
        }
    }
}

"sort" Action #

An action that sorts concept instances in a selection based on a property or variable in either ascending or descending order. Only properties and variables with primitive types (string, number, or boolean) can be used for sorting.

Parameters:

Properties:

Examples:

A simple example of ordering the concept instances of a selection ascending by a property:

{
    "sort": {
        "property": "myProperty",
        "order": "asc"
    }
}

A simple example of ordering the concept instances of a selection descending by a variable in the context:

{
    "sort": {
        "variable": "myVariable",
        "order": "desc"
    }
}

Shorthand example that sorts ascending using a property:

{ "sort": "myProperty" }

"where" Action #

An action to filter the current selection to a set of conditions. Conditions can be nested and connected using and, or, and not.

Parameters:

In addition, the below value and composition operators can be used.

Value Operators:

Composition Operators:

Properties:

Examples:

Simple example of a single condition comparing a property with a value:

{
    "where": {
        "property": "myProperty",
        "equals": 5
    }
}

An example of comparing a variable in a negation:

{
    "where": {
        "not": {
            "variable": "myVariable",
            "startsWith": "Hello "
        }
    }
}

An example using a calculation and a variable:

{
    "where": {
        "calculate": "10 + $myVariable$",
        "lessThan": 17
    }
}

An example using an and composition:

{
    "where": {
        "and": [
            {
                "calculate": "10 + $myVariable$",
                "lessThan": 17
            },
            {
                "property": "myProperty",
                "endsWith": "!!!"
            }
        ]
    }
}

An example with multiple compositions and conditions:

{
    "where": {
        "or": [
            {
                "calculate": "10 + $myVariable$",
                "equals": 15
            },
            {
                "not": {
                    "variable": "myVariableName",
                    "equals": "myVariableValue"
                }
            },
            {
                "not": {
                    "property": "myProperty",
                    "equals": "myPropertyValue"
                }
            },
            {
                "and": [
                    {
                        "property": "myOtherProperty",
                        "unequals": "somethingelse"
                    },
                    {
                        "property": "myThirdProperty",
                        "lessThan": 10
                    }
                ]
            }
        ]
    }
}

Context Actions #

"limit" Action #

An action to limit the current selection to a given number of targets starting from first or last.

Parameters:

Properties:

Examples:

Limit targets to 1, starting from first:

{
    "limit": {
        "count": 1,
        "last": false
    }
}

Limit targets to 1, starting from first (shorthand version):

{ "limit": 1 }

Limit targets to 2, starting from last:

{
    "limit": {
        "count": 2,
        "last": true
    }
}

"storeSelection" Action #

An action that stores all targets in an event in an array variable.

Parameters:

Properties:

Examples:

Stores the current array of targets in a variable.

{ "storeSelection": { "as": "mySelectionVariableName" }}

Shorthand version:

{ "storeSelection": "mySelectionVariableName" }

Property Actions #

"eval" Action #

An action that takes a condition (like in the "where" action) and evaluates it to a Boolean variable.

Parameters:

Value and Composition Operators:

See "where" action.

Properties:

Examples:

A simple example:

{
    "eval": {
        "property": "myBooleanProperty",
        "equals": false
    }
}

A simple example using a composition:

{
    "eval": {
        "and": [
            { "property": "myBooleanProperty", "equals": false },
            { "property": "myNumberProperty", "lessThan": 10 }
        ]
    }
}

"get" Action #

An action that stores a property value in a variable.

Parameters:

Properties:

Examples:

Gets the given property and stores it in a variable.

{
    "get": {
        "property": "myProperty",
        "as": "myVariableName"
    }
}

Shorthand version:

{ "get": "myProperty" }

Get a property on a currently not selected concept:

{
    "get": {
        "property": "myConcept.myProperty",
        "as": "myVariableName"
    }
}

"set" Action #

An action to set a property or variable to a given value.

Parameters:

Properties:

Examples:

Set property to a given value:

{
    "set": {
        "property": "myProperty",
        "value": "myValueToSet"
    }
}

Set property to a given value (shorthand version):

{ "set": { "myProperty": "myValueToSet" }}

Set a variable to a given value:

{
    "set": {
        "variable": "myVariableName",
        "value": "myValueToSet"
    }
}

Set variable to a given value (shorthand version using the $-notation):

{ "set": { "$myVariableName": "myValueToSet" }}

Set a property on a currently not selected concept to a given value:

{
    "set": {
        "property": "myConcept.myProperty",
        "value": "myValueToSet"
    }
}

"length" Action #

An action that returns the length of a string or an array into a variable.

Parameters:

Properties:

Examples:

Get the length of a property:

{
    "length": {
        "of": { "property": "myArrayOrStringProperty" },
        "as": "myOutputVariableName"
    }
}

Get the length of a property on a not selected property:

{
    "length": {
        "of": { "property": "myConcept.myArrayOrStringProperty" },
        "as": "myOutputVariableName"
    }
}

Get the length of a property (shorthand version):

{ "length": "myProperty" }

Get the length of a variable:

{
    "length": {
        "of": {"variable": "myArrayOrStringVariable"},
        "as": "myOutputVariableName"
    }
}

Get the length of a variable (shorthand version):

{ "length": "$myVariable" }

Boolean Actions #

"toggle" Action #

An action to toggle a Boolean property or variable.

Parameters:

Properties:

Examples:

Toggle a Boolean property:

{ "toggle": {  "property": "myBooleanProperty" }}

Toggle a Boolean property on a non-selected concept:

{ "toggle": { "property": "myConcept.myBooleanProperty" }}

Toggle a Boolean property (shorthand version):

{ "toggle": "myBooleanProperty" }

Toggle a Boolean variable:

{ "toggle": { "variable": "myBooleanVariable" }}

Toggle a Boolean variable (shorthand version):

{ "toggle": "$myBooleanVariable" }

String Actions #

"concat" Action #

An action that concatenates an array of strings and stores the result in a variable. It is also possible to use properties and variables.

Parameters:

Properties:

Examples:

Simple example:

{
    "concat": {
         "strings": [ "How", "dy!" ],
         "as": "myOutputVariableName"
    }
}

Shorthand version:

{ "concat": [  "Hello",  " ", "World!" ] }

Using an string array variable:

{
    "concat": {
         "strings": "$myStringArrayVariable",
         "as": "myOutputVariableName"
    }
}

Using properties and variables in the array:

{
    "concat": {
         "strings": [
             "Variable: "
             {"variable": "myStringVariable"},
             " Property: ",
             {"property": "myStringProperty"}
         ],
         "as": "myOutputVariableName"
    }
}

Using a string variable shorthand inside the array:

{
    "concat": {
         "strings": [ "Hello, ", "$myStringVariable", " doing?" ],
         "as": "myOutputVariableName"
    }
}

"enums" Action #

An action that returns the possible enum options of a string property as an string array.

Parameters:

Properties:

Examples:

Simple example:

{
    "enums": {
        "property": "myEnumProperty",
        "as": "myVariableName"
    }
}

Example for using the dot notation to get properties of not selected concepts:

{ "enums": { "property": "myConcept.myEnumProperty" }}

Shorthand version:

{ "enums": "myEnumProperty" }

"split" Action #

An action to split up a string property or variable into an string array using a given delimiter.

Parameters:

Properties:

Examples:

Simple example with a property:

{
    "split": {
        "property": "myStringProperty",
        "delimiter": ";",
        "as": "myResultArrayVariable"
    }
}

Simple example with a variable:

{
    "split": {
        "variable": "myStringVariable",
        "delimiter": ";",
        "as": "myResultArrayVariable"
    }
}

Shorthand version with a property:

{ "split": "myStringProperty" }

Shorthand version with a variable:

{ "split": "$myStringVariable" }

"textTransform" Action #

An action to transform string to upper or lower case or to capitalization.

Parameters:

Properties:

Examples:

Uppercase a string in a property:

{
    "textTransform": {
        "property": "myStringProperty",
        "mode": "uppercase"
    }
}

Capitalize a string in a variable:

{
    "textTransform": {
        "variable": "myStringVariable",
        "mode": "capitalize"
    }
}

Number Actions #

"calculate" Action #

An Action that calculates a given math expression and stores the result in a number variable. The calculate action uses math.js to calculate, see its documentation for detailed use. Variables can be used within expressions using the $-notation.

Like in math.js, it is possible to use multi-line expressions either using the ; in a single expression or by splitting lines into elements of an array (see examples). Multi-line expressions in Varv, however, can only return a single value, not an array.

Parameters:

Properties:

Examples:

Simple example:

{
    "calculate": {
        "expression": "sqrt(2) * sqrt(2)",
        "as": "myOutputVariableName"
    }
}

Shorthand version with using a variable in the expression:

{ "calculate": "42 + 60 + $myVariableName$ + 10" }

A multi-line expression example:

{ "calculate": "a = 3; b = 4; a + b" }

A multi-line expression as an array of expressions (results in the same expression as the previous example):

{
    "calculate": [
        "a = 3",
        "b = 4",
        "a + b"
    ]
}

"decrement" Action #

An action to decrement number properties or variables.

Parameters:

Properties:

Examples:

Decrement a property by 1:

{ "decrement": { "property": "myNumberProperty" }}

Decrement a property by 2:

{
    "decrement": {
        "property": "myNumberProperty",
        "by": 2
    }
}

Decrement a property by 1 (shorthand version):

{ "decrement": "myNumberProperty" }

Decrement a variable by 2:

{
    "decrement": {
        "variable": "myNumberVariable",
        "by": 2
    }
}

"increment" Action #

An action to increment number properties or variables.

Parameters:

Properties:

Examples:

Increment a property by 1:

{ "increment": { "property": "myNumberProperty" }}

Increment a property by 2:

{
    "increment": {
        "property": "myNumberProperty",
        "by": 2
    }
}

Increment a property by 1 (shorthand version):

{ "increment": "myNumberProperty" }

Increment a variable by 2:

{
    "increment": {
        "variable": "myNumberVariable",
        "by": 2
    }
}

"random" Action #

An action to generate random numbers in a given range. The range is inclusive. If no range is specified 0 to Number.MAX_SAFE_INTEGER (2^53 - 1) is used as range.

Parameters:

Properties:

Examples:

Generate a random integer between 0 and 10::

{
    "random": {
        "range": [0, 10],
        "as": "myOutputVariableName"
    }
}

Shorthand version:

{ "random": [0, 10] }

Generate a random float number between 0 and 10:

{
    "random": {
        "range": [0, 10],
        "float": true,
        "as": "myOutputVariableName"
    }
}

Array Actions #

"append" Action #

An action that appends an item to an array.

Parameters:

Properties:

Examples:

Append a string item to an array inside a property:

{
    "append": {
        "to": { "property": "myStringArrayProperty" },
        "item": "Hello World"
    }
}

Append a string variable to an array inside a property on a non-selected concept:

{
    "append": {
        "to": { "property": "myConcept.myStringArrayProperty" },
        "item": "$myStringVariable"
    }
}

Append a string to an array inside a variable:

{
    "append": {
        "to": { "variable": "myStringArrayVariable" },
        "item": "Hello Varv"
    }
}

"index" Action #

An action that gets the index of an item in an array.

Parameters:

Properties:

Examples:

A full example of finding the index of an item in an array property:

{
    "index": {
        "of": { "property": "myArrayProperty" },
        "item": "myLookupItem",
        "as": "myResultVariableName"
    }
}

Shorthand example that looks up the item myLookupItem inside the property myArrayProperty, and saves the index in the variable index:

{ "index": { "myArrayProperty": "myLookupItem" }}

Shorthand example with a variable myArrayVariable:

{ "index": { "$myArrayVariable": "myLookupItem" }}

"insert" Action #

An action that inserts an item into an array at a given index position.

Parameters:

Properties:

Examples:

Insert a string item into an array inside a property:

{
    "insert": {
        "to": { "property": "myStringArrayProperty" },
        "index": 7,
        "item": "Hello World"
    }
}

Insert a string variable into an array inside a property on a non-selected concept:

{
    "insert": {
        "to": { "property": "myConcept.myStringArrayProperty" },
        "index": 3,
        "item": "$myStringVariable"
    }
}

Insert a string into an array inside a variable:

{
    "insert": {
        "to": { "variable": "myStringArrayVariable" },
        "index": 2,
        "item": "Hello Varv"
    }
}

"items" Action #

An action that stores the items of an array property or variable in a variable. It allows also for filtering items.

Parameters:

Properties:

Examples:

Simple example on a property:

{
    "items": {
        "property": "myArrayProperty",
        "where": { "equals": "my-specific-value" },
        "as": "myOutputVariableName"
    }
}

Property example, on non selected concept:

{
    "items": {
        "property": "myConcept.myArrayProperty",
        "as": "myOutputVariableName"
    }
}

Simple example (shorthand version):

{ "items": "myArrayProperty" }

Variable example:

{
    "items": {
        "variable": "myArrayVariable",
        "where": { "equals": "my-specific-value" },
        "as": "myOutputVariableName"
    }
}

Variable example (shorthand version):

{ "items": "$myArrayVariable" }

"join" Action #

An action that can join the items of an array into a string using a given separator.

Parameters:

Properties:

Examples:

A simple example:

{
    "join": {
        "property": "myArrayProperty",
        "separator": ";",
        "as": "myOutputVariableName"
    }
}

A simple example (shorthand version):

{ "join": "myArrayProperty" }

An example using a variable:

{
    "join": {
        "variable": "myArrayVariable",
        "separator": " ",
        "as": "myOutputVariableName"
    }
}

An example using a variable (shorthand version):

{ "join": "$myArrayVariable" }

"prepend" Action #

An action that prepends an item to an array.

Parameters:

Properties:

Examples:

Prepend a string item to an array inside a property:

{
    "prepend": {
        "to": { "property": "myStringArrayProperty" },
        "item": "Hello World"
    }
}

Prepend a string variable to an array inside a property on a non-selected concept:

{
    "prepend": {
        "to": { "property": "myConcept.myStringArrayProperty" },
        "item": "$myStringVariable"
    }
}

Prepend a string to an array inside a variable:

{
    "prepend": {
        "to": { "variable": "myStringArrayVariable" },
        "item": "Hello Varv"
    }
}

"slice" Action #

An action to create a clone of an array or a part of it. Cloned slices of arrays of type concept are always shallow, i.e., the referenced concept instances remain the same.

Parameters:

Properties:

Examples:

Creates a cloned slice of an array property:

{
    "slice": {
        "of": { "property": "myArrayProperty" },
        "start": 3,
        "end": 10,
        "as": "myOutputVariableName"
    }
}

Creates a complete clone of an array property on a non-selected concept:

{
    "slice": {
        "of": { "property": "myConcept.myArrayProperty" },
        "as": "myOutputVariableName"
    }
}

Creates a complete clone of an array property (shorthand version):

{ "slice": "myArrayProperty" }

Creates a cloned slice of an array variable from a start index until the end of the array:

{
    "slice": {
        "of": { "variable": "myArrayVariable" },
        "start": 3,
        "as": "myOutputVariableName"
    }
}

Creates a complete clone of an array variable (shorthand version):

{ "slice": "$myArrayVariable" }

"removeFirst" Action #

An action that removes the first item from an array and outputs it as a variable.

Parameters:

Properties:

Examples:

Remove the first item from an array property:

{
    "removeFirst": {
        "of": { "property": "myArrayProperty" },
        "as": "myOutputVariableName"
    }
}

Remove the first item from an array property on a non-selected concept:

{
    "removeFirst": {
        "of": { "property": "myConcept.myArrayProperty" },
        "as": "myOutputVariableName"
    }
}

Remove the first item from an array property (shorthand version):

{ "removeFirst": "myArrayProperty" }

Remove the first item from an array variable:

{
    "removeFirst": {
        "of": { "variable": "myArrayVariable" },
        "as": "myOutputVariableName"
    }
}

Remove the first item from an array variable (shorthand version):

{ "removeFirst": "$myArrayVariable" }

"removeItem" Action #

An action that removes an item at a given index from an array and outputs it as a variable.

Parameters:

Properties:

Examples:

Remove two items at the given index from an array property:

{
    "removeItem": {
        "of": { "property": "myArrayProperty" },
        "index": 7,
        "removeCount": 2,
        "as": "myOutputVariableName"
    }
}

Remove the item at the given index from an array property on a non-selected concept:

{
    "removeItem": {
        "of": { "property": "myConcept.myArrayProperty" },
        "index": 3,
        "as": "myOutputVariableName"
    }
}

Remove the item at the given index from an array variable:

{
    "removeItem": {
        "of": { "variable": "myArrayVariable" },
        "index": 4,
        "as": "myOutputVariableName"
    }
}

"removeLast" Action #

An action that removes the last item from an array and outputs it as a variable.

Parameters:

Properties:

Examples:

Remove the last item from an array property:

{
    "removeLast": {
        "of": { "property": "myArrayProperty" },
        "as": "myOutputVariableName"
    }
}

Remove the last item from an array property on a non-selected concept:

{
    "removeLast": {
        "of": { "property": "myConcept.myArrayProperty" },
        "as": "myOutputVariableName"
    }
}

Remove the last item from an array property (shorthand version):

{ "removeLast": "myArrayProperty" }

Remove the last item from an array variable:

{
    "removeLast": {
        "of": { "variable": "myArrayVariable" },
        "as": "myOutputVariableName"
    }
}

Remove the last item from an array variable (shorthand version):

{ "removeLast": "$myArrayVariable" }

Flow Actions #

"exit" Action #

An action that stops the action chain and does not forward an event.

Parameters:

This action has no parameters.

Properties:

Examples:

Simple example:

{ "exit" }

"run" Action #

An action that runs another action and, after running it, continues with the action chain passing on the event from before the "run" action independently of the outcome of the ran action (e.g., if the other actions contains an "exit" or modifies the event).

Parameters:

Properties:

Examples:

Simple example:

{ "run": { "action": "myActionName" }}

Shorthand version:

{ "run": "myActionName" }

"switch" Action #

An action that can execute several branches of actions chains. Each branch can contain a condition using the same filtering to the "where" action.

Parameters:

Branch Parameters:

Properties:

Examples:

A simple example using three branches. Two with conditions and one as a default option:

{
    "switch": [
        {
            "where": { "property": "myProperty", "equals": "myValue" },
            "then": [ "myAction", "myOtherAction" ],
            "break": false
        },
        {
            "where": { "property": "myProperty", "equals": "myOtherValue" },
            "then": [ "myAction", "myOtherAction" ]
        },
        { "then": [ "myDefaultAction" ] }
    ]
}

Timing Actions #

"wait" Action #

An action that waits for a given duration of time before continuing in the action chain.

Parameters:

Properties:

Examples:

Simple example of waiting for 100 milliseconds:

{ "wait": { "duration": 100 }}

Shorthand version:

{ "wait": 100 }

Debug Actions #

"debugConcept" Action #

An action that prints the ID of the current target of a context.

Parameters:

This action has no parameters.

Properties:

Examples:

Simple example:

{ "debugConcept" }

"debugContext" Action #

An action that prints the current event including all contexts to the console.

Parameters:

This action has no parameters.

Properties:

Examples:

Simple example:

{ "debugContext" }

"debugMessage" Action #

An action that prints a message to the console. The message can include variables.

Parameters:

Properties:

Examples:

Simple example:

{ "debugMessage": { "message": "The message to debug" }}

Shorthand version:

{ "debugMessage": "The message to debug" }

Example with a variable:

{ "debugMessage": "My value is $myVariable$" }