Logic Definition - A schema for defining orchestration for transformers

Introduction

Logic Definition is a JSON schema that defines the format for describing the orchestration of transformers, including what transformers should be used in a flow, how a particular transformer modifies an XMessage and how it triggers side-effects. This is an abstraction over the larger xstate specification that is uniquely tailored to work with the UCI system.

Overview

This document proposes a new specification on top of xstate, that works along with the UCI system to orchestrate the working of transformers. The document also goes about describing how to define a logic definition and what are its components.

The specification directly handles what transformers are used in a flow, how a transformer might modify an XMessage and what inputs are provided to a transformer. The specification also governs the exact order of execution of transformers in a flow.

Internally logic definition is transpiled to xstate, before feeding it to a state machine. The logic definition also restrics the usage of xstate, such that its components provide contextual information about the working of a flow.

Definitions

Transformer

Transformers are independent unit of proccessing that comprise of the logic that an XMessage flows through. The Orchestrator may chain together one or more transformers, by defining a logic definition, and converting it into a state machine.

Node

A node is a single independent component of the logic definiton. This component should a single transformer definition, and may contains additional input parameters and side effects along with state change rules.

Side-Effects

There are certain number of side-effects that you can attach to your flow, that execute parallely when a transformer executes like sending telemetry data or sending a discord alert when something goes wrong. These side-effects can also be added globally, which will make them run on every state change, or locally, which will make them run on specific nodes.

Logic Def Schema

A simple logic def schema is defined as follows:

"logicDef": {
    "id": string,
    "transformers": [ Nodes ],
    "sideEffects": object,
}

Below is a table describing all the fields

Field	Description	Type
id	Unique identifier for the logic def.	string
transformers	An array of transformer nodes that are used in the flow.	object
sideEffects	A JSON of all the global side effects that are triggered during execution. See Supported Side Effects for more details.	object

Node

A node is a single component in the transformers array. Here is how a simple node might be defined.

{
    "id": string,
    "type": string,
    "config": object,
    "states": object,
    "sideEffects": object,
}

Below is a table describing all the fields

Field	Description	Type
id	Unique identifier for the node.	string
type	The type of transformer being used. For a complete list of transformers see Supported Transformers	string
config	The input parameters for a transformer. This can vary based on the type of transformer being used. See Supported Transformers for exact config details.	object
states	Every transformer can switch to a different state based on how the execution of a transformer flows through. Allowed states may vary based on the class of transformer being used. See Transformer Classes for more details.	object
sideEffects	This field is used to define node level local side effects. The configuration may vary based on what side effect is being used. See Local Side Effects for more details.	object

Example

Here is a complete example of how different components can be knit together to create a complete logic definition.

"logicDef": {
    "id": "c7b25371-c8e3-476f-9904-e30b106ab256",
    "transformers": [
        {
            "id": "1",
            "type": "FIELD_SETTER",
            "config": {
                "setters": {
                    "payload.text": "hello there"
                }
            },
            "states": {
                "onSuccess": "2"
            }
        },
        {
            "id": "2",
            "type": "FIELD_SETTER",
            "config": {
                "setters": {
                    "payload.text": "hello hi",
                    "from.userID": "unknown"
                }
            },
            "states": {
                "onSuccess": "3"
            }
        },
        {
            "id": "3",
            "type": "HTTP_GET",
            "config": {
                "url": "https://my_url",
            }
        }
    ],
    "sideEffects": {
        "Telemetry": {
            "isGlobal": true,
            "host": "https://my_telemetry_host"
        }
    }
}