Workflow Canvas

The Workflow Canvas is a visual drag-and-drop editor for building event processing workflows. It uses React Diagrams to provide an intuitive node-based interface for connecting workflow entities.

Overview

Workflows define how incoming messages are processed. Each workflow consists of:

• Nodes — Visual representations of workflow entities
• Links — Connections that define execution flow
• Branches — Conditional paths based on logic evaluation

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Event     │────▶│   Prompt    │────▶│   Action    │
│  (Circle)   │     │   (Brain)   │     │   (Star)    │
└─────────────┘     └─────────────┘     └─────────────┘

Canvas Controls

Toolbar

Action	Description
Save	Persist the workflow to the database
Load	Load an existing workflow
New	Create a new empty canvas
Copy to Environment	Duplicate workflow to another environment
Zoom	Zoom controls and fit-to-view

Navigation

• Pan: Click and drag on empty canvas area
• Zoom: Mouse wheel or pinch gesture
• Select: Click on a node
• Multi-select: Shift + click or drag selection box

Node Operations

• Add Node: Right-click on canvas → Insert Node
• Delete Node: Select node → Delete key or context menu
• Edit Entity: Double-click on node or context menu → Edit

Node Types

Each node type has a distinctive shape that indicates its function:

Circle Node — Event

Shape: ⬤ Circle

Purpose: Entry point that evaluates conditions against incoming messages.

Branching Modes:

• Single Path: Continue if condition passes, exit if fails
• True/False: Branch based on condition result
• Multi: Branch based on a variable value

Visual Indicators:

• Contains the entity name
• Shows branch ports for True/False or Multi modes

Brain Node — Prompt

Shape: 🧠 Brain

Purpose: Execute AI/LLM prompts using configured models.

Features:

• Associated with a Model for credentials
• Prompt template with variable interpolation
• Auto-executes executePromptWithModel() function

Star Node — Action

Shape: ⭐ Star

Purpose: Execute custom JavaScript code for side effects.

Use Cases:

• Data transformation
• External API calls (via injected functions)
• Variable manipulation
• Logging and debugging
• Publishing results via PubSub

Logic Branch Node

Purpose: Represents a branch path from Event nodes in True/False or Multi mode.

Features:

• Contains a value that determines when this branch is taken
• Acts as a container for child nodes

Creating a Workflow

Step 1: Add an Event Node

1. Right-click on the canvas
2. Select Insert Node → Event
3. Choose an existing Event entity or create a new one
4. Configure the branching mode:
   • Single Path: Default, continues on condition pass
   • True/False: Creates two branch paths
   • Multi: Creates multiple named branches

Step 2: Connect Processing Nodes

1. Click and drag from the out port of the Event node
2. Release on the in port of the next node
3. Continue building the chain: Event → Prompt → Action

Step 3: Save the Workflow

1. Enter a Name for the workflow (required)
2. Add a Description (optional)
3. Click Save

Workflow Outcomes

Workflow outcomes are determined automatically:

Outcome	When it occurs
Success	All entities execute without errors
Error	A script throws an error or times out
Ignore	Event condition doesn't match

Branching Logic

Single Path Mode

The simplest flow — condition passes or workflow exits:

Event (Condition: message.type === 'signup')
  │
  ▼ (condition passes)
Prompt (Generate welcome message)
  │
  ▼
Action (Store result)

If condition fails, the workflow exits and the message is ignored.

True/False Mode

Create divergent paths based on a boolean condition:

Event (Condition: message.premium === true)
  │
  ├── true ──▶ Prompt (Premium welcome)
  │                   │
  │                   ▼
  │             Action (Send email)
  │
  └── false ─▶ Action (Log basic user)

Multi Mode

Branch based on variable values:

Event (Logic Field: userType)
  │
  ├── "admin" ──▶ Action (Admin flow)
  │
  ├── "user" ───▶ Prompt (User welcome)
  │
  └── "guest" ──▶ (no action - ignored)

The logicField specifies which variable to evaluate. The value is matched against branch values.

Connecting Nodes

Creating Links

1. Hover over a node to reveal ports
2. Click and drag from an out port (right side)
3. Release on an in port (left side) of another node

Port Types

Port	Position	Purpose
in	Left	Receives flow from parent node
out	Right	Sends flow to child nodes
true	Right	True branch (Event True/False mode)
false	Right	False branch (Event True/False mode)

Link Rules

• Each in port accepts one connection
• Each out port can have multiple connections
• Links cannot create cycles (detected and prevented)
• The first node in a workflow becomes the root

Context Menu

Node Context Menu (Right-click on node)

Option	Description
Edit Entity	Open the entity editor
Delete	Remove the node and its links
Duplicate	Create a copy of the node

Edge Context Menu (Right-click on link)

Option	Description
Insert Node	Add a node in the middle of this link
Delete	Remove the link

Canvas Context Menu (Right-click on empty area)

Option	Description
Insert Event	Add a new Event node
Insert Prompt	Add a new Prompt node
Insert Action	Add a new Action node
Paste	Paste copied nodes

Workflow Validation

Before saving, the canvas validates:

Rule	Description
Name required	Workflow must have a name
Entity required	Each node must have an associated entity
No orphans	Disconnected nodes are saved separately

Validation warnings are displayed but don't prevent saving.

Serialization

Workflows are stored as hierarchical JSON. See Workflow Data Schema for the complete specification.

Key points:

• Tree structure with root as entry point
• orphans array for disconnected nodes
• presentation stores viewport and positions
• Links are implicit through parent-child relationships

Keyboard Shortcuts

Shortcut	Action
Delete	Delete selected nodes
Ctrl+S / Cmd+S	Save workflow
Ctrl+Z / Cmd+Z	Undo
Ctrl+Y / Cmd+Y	Redo
Ctrl+A / Cmd+A	Select all
Escape	Deselect all

Related Topics

• Workflow Data Schema — JSON structure specification
• Workflow Entities — Entity types and configuration
• Consumer Evaluator — How workflows are executed