WBSKT Engine / Reference / Core Concepts

Core Concepts

The authoritative vocabulary for the WBSKT workflow builder. Covers both the visual canvas UI and the underlying engine runtime — from the elements you drag and drop to the objects the engine creates and manages at runtime.

Spec v1.2 Unified Glossary

Canvas & UI Layer

The visual objects and interactive surfaces that make up the workflow builder interface. Everything visible in the editor maps to a concept defined here.

Canvas UI Surface
The infinite, pannable and zoomable workspace where a workflow is visually assembled by placing nodes and drawing connections between them.

The canvas is the primary editing surface of the WBSKT workflow builder. It provides an infinite 2D plane on which users drag nodes from the node palette, position them spatially, and wire them together. The canvas has no functional meaning at runtime — it is purely a design-time representation. When a workflow is deployed, the engine reads the saved topology and discards all positional metadata.

Multiple canvases can exist within a tenant — each one corresponds to exactly one Workflow Definition.

Canvas vs. Workflow Definition The canvas is the editor view. A Workflow Definition is what gets serialized and saved to the platform when you publish. The canvas is your working surface; the definition is the artifact.
Node Building Block
A single, self-contained processing unit placed on the canvas. Every action, decision, trigger, loop, and data operation in a workflow is represented as a node.

Nodes are the atomic building blocks of every workflow. Each node has a defined type (e.g. HttpWebhookTrigger, LogicGate, StaticForLoop), a set of configurable properties edited in the Properties Panel, and one or more ports through which it connects to other nodes.

At runtime, the engine executes nodes in sequence based on the signals flowing through connections. Each node type defines its own execution semantics — from routing a signal through a conditional branch to iterating over a list.

Node Categories

Category Role
Trigger Entry points that initiate workflow execution in response to an external event. No input ports.
Logic & Control Conditional routing, branching, looping, and parallel join nodes. Shape the execution path.
Data Read, transform, and write values in the WorkflowContext.
Action Perform side-effects: send commands, call external APIs, dispatch notifications.
Nodes are Stateless Individual nodes do not store data between executions. All persistent state lives in the WorkflowContext. A node reads from context, acts, and optionally writes results back to context before emitting a signal.
Connection · Wire Edge
A directed line drawn from one node's output port to another node's input port. The route a Signal travels to activate the next node in the workflow.

Connections are the edges of the workflow graph. Every connection has a source (an output port) and a target (an input port). The direction is always source → target; signals cannot travel backwards along a connection.

In the builder UI, a connection is drawn by clicking and dragging from an output port dot to an input port dot. The only constraint is direction — an output port connects to an input port. There is no type-based port compatibility check; all ports carry signals.

A single output port can fan-out to multiple connections, emitting the same signal to several downstream nodes simultaneously. A single input port can receive connections from multiple sources, but fires independently for each arriving signal.

Connections carry no data A connection is purely a routing path. All data exchange between nodes happens through the shared WorkflowContext, not through the connection itself. The signal that travels along the wire is a zero-payload notification pulse.
Port Connector Point
A typed attachment point rendered as a colored dot on a node's edge. Every port emits or receives a signal — the color indicates the kind of signal, not a different data carrier. Ports are the anchors for connections.

Every node exposes one or more named ports. Input ports appear on the left of the node block; output ports appear on the right. Port names are unique within a node and are surfaced in the Properties Panel and in the port diagram on each node's specification page.

All ports carry signals. The port color indicates the role of that signal within the workflow — not a distinct data type. The only rule governing connections is direction: an output port must connect to an input port.

Signal Role Legend

Role Semantics
signal Standard execution pulse. Notifies the target node to evaluate and run its logic.
control Internal flow-control signal — used for loop boundary events (e.g. onComplete, onIteration).
error Fault signal. Fires when the node encounters an error; routes execution to a recovery branch.
Dynamic Ports Some node types (Logic Gate, Switch Gate) generate output ports dynamically at configuration time. Each rule or case label defined in the Properties Panel becomes a named output port on the canvas. These are shown in documentation as [ruleLabel] or [caseLabel].
Properties Panel · Inspector UI Panel
The configuration sidebar that opens when a node is selected on the canvas. Exposes all editable properties for that node type, organized by group.

The Properties Panel (also called the Inspector) is a context-sensitive panel that renders the configuration form for whichever node is currently selected. Its contents change entirely depending on the node type — selecting an HttpWebhookTrigger exposes HTTP routing and auth settings, while selecting a LogicGate exposes the rule editor.

All property values edited here are serialized into the Workflow Definition when the workflow is saved. They are also the parameters documented in the "Node Properties" section of each node's specification page in this reference.

Properties vs. Runtime State Properties set in the Inspector are static configuration — they are fixed at design time. Runtime values (the data a node reads or writes during execution) live in the WorkflowContext, not in the node's properties.

Workflow Fundamentals

The core objects the engine creates, manages, and executes. Understanding the distinction between a Definition and an Instance is central to working with WBSKT.

Workflow Definition Blueprint
The versioned, saved blueprint that captures the complete canvas topology — every node, connection, port binding, and property value. The definition is the template; it is never itself "running".

A Workflow Definition is the immutable artifact you author in the builder UI and publish to the engine. It describes what should happen — which nodes exist, how they are connected, what each node is configured to do, and how incoming triggers are correlated to instances.

Each definition has a stable definitionId (UUID) and a version. When you edit and republish a definition, the engine creates a new version. Any Workflow Instances that are already running continue on the version they were started with; only new arrivals pick up the updated definition.

The formal schema for Workflow Definitions — including triggers, execution physics, error handling, and governance — is documented in Workflow Definitions.

Versioning Policy Active instances are pinned to the definition version they were created under. Changing the definition mid-execution does not affect in-flight instances. Publish changes only when existing instances can safely complete or be terminated.
Workflow Instance Runtime Object
A live, in-progress execution spawned from a Workflow Definition. Each instance is isolated — it has its own WorkflowContext, its own execution pointer, and its own lifecycle.

When a trigger fires and the engine resolves a matching or new CorrelationKey, it creates (or resumes) a Workflow Instance. The instance is the running incarnation of the definition's blueprint. It tracks:

  • correlationKey — The unique identifier that distinguishes this instance from all others.
  • executionPointer — Which node(s) are currently active.
  • WorkflowContext — The shared key-value state accumulated during execution.
  • status — Running, Waiting, Completed, Failed, or Terminated.

Multiple instances of the same definition can exist simultaneously — each identified by a different correlationKey and maintaining fully independent state. The maximum concurrent count is capped by maxActiveInstances in the definition.

Persistent vs. Ephemeral Instances Persistent instances write their state to durable storage at every checkpoint — allowing crash recovery and audit. Ephemeral instances run entirely in memory for maximum throughput, with no recovery guarantee. Set via instanceMode in the Workflow Definition.
Trigger Node Entry Point
A specialised class of node that listens to an external event source and initiates workflow execution. Trigger nodes have no input ports — they are always the starting point of a signal chain.

Every workflow must have at least one trigger. A trigger monitors an external system (an HTTP endpoint, an MQTT topic, a cron schedule, a connected client, etc.) and fires when its configured conditions are met. When a trigger fires, it:

  1. Receives the raw external payload.
  2. Extracts the CorrelationKey from the payload using correlationExpression.
  3. Applies the onMatch strategy to create, resume, replace, or discard a workflow instance.
  4. Normalizes the payload into the WorkflowContext.
  5. Emits a signal on its onTrigger output port to start the execution chain.

A single Workflow Definition can have multiple triggers of different types (e.g. both an HTTP webhook and an MQTT subscription). This is the multi-trigger pattern — any configured trigger can initiate or update the same instance.

Trigger Categories Light Triggers — React to protocol-level events: HTTP Webhook, MQTT Telemetry, Scheduled, Polling / Watcher, Manual Event.

Identity Triggers — Scope execution to registered clients or groups: Single Client, Group / Folder, Policy-Based.
Signal Execution Pulse
The zero-payload notification pulse that travels along a connection from one node's output port to the next node's input port. A signal carries no data — it is a pure "proceed" instruction.

Signals are the mechanism of execution in WBSKT. When a node finishes its work, it emits a signal on one or more of its output ports. That signal travels along the connection(s) attached to those ports and activates the receiving nodes at the other end.

Because signals carry no data, the architecture avoids data coupling between nodes. A node that needs data from a previous step reads it directly from the WorkflowContext rather than receiving it on a wire. This shared-state model makes the graph topology independent of data shape.

Signal Flow Example

HTTP Trigger fires → writes payload to context → emits signal on onTrigger → travels connection → Logic Gate receives signal on eval → reads context → evaluates rules → emits signal on matching output port(s)
Signals are not queued by default If a node receives a signal while it is already executing, the behavior depends on the node type and the instance's concurrency configuration. For loop nodes, incoming signals during iteration can be queued or discarded per the ackStrategy setting.
WorkflowContext Shared State
The mutable, shared key-value store that lives inside a Workflow Instance. It is the sole data bus — all nodes read inputs from it and write outputs back to it rather than passing data through connections.

The WorkflowContext is created when an instance is spawned and destroyed when the instance completes or is terminated. It is scoped strictly to one instance — no two instances share a context, even if they were created from the same definition.

The context is populated in layers as execution progresses:

  1. The triggering payload is written in at instance creation (e.g. the HTTP request body, the MQTT message).
  2. Data nodes (Set Context, Data Mapper) add or transform values during execution.
  3. Action and logic nodes may read values from context to parameterize their behavior.

Nodes reference context values using JSONPath expressions — for example $.sensor.temperature to read a nested field, or $.client.id to access a top-level key.

Context is the data layer — Signals are the control layer Think of it as two separate planes: signals control which node runs next; the context holds what data that node operates on. This separation keeps the graph topology clean and makes each node independently testable.

Identity & Routing

How the engine maps incoming trigger events to the correct workflow instance — or decides to create a new one.

CorrelationKey · Identity Instance Identifier
The resolved string identifier extracted from an incoming trigger payload that determines which Workflow Instance should receive the event — or whether a new instance should be created.

Each trigger can be configured with a correlationExpression — a JSONPath or regex applied to the incoming payload. The value it extracts becomes the CorrelationKey. The engine then looks up all active instances for this definition and checks whether any instance was already created with that key.

Resolution Outcomes — onMatch Strategies

Strategy Behavior
MapOrCreate If a matching instance is found, the signal is routed to it. If not, a new instance is created. Default.
MapOrDiscard Only routes to an existing instance. If no match is found, the incoming event is silently dropped.
AlwaysCreate Ignores the resolved key entirely and always spawns a new parallel instance. Useful for stateless, fire-and-forget event logs.
MapOrReplace If a match is found, the existing instance is terminated and a fresh instance starts with the new payload. Use when the latest event must always win.

When a workflow has multiple triggers (multi-trigger pattern), each trigger defines its own correlationExpression independently. Different triggers may extract the key from different fields of their respective payloads, but they all resolve to the same logical identity space within the definition.

No Expression → AlwaysCreate If correlationExpression is left empty (null), the engine cannot extract a key and therefore cannot match an existing instance. In practice this behaves like AlwaysCreate — every trigger arrival spawns a new independent instance.

The full correlation specification — including multi-trigger strategy and per-trigger overrides — is defined in Workflow Definitions → Identity & Routing.

WBSKT Core Concepts · Unified Glossary · Spec v1.2