Skip to main content

Workflow Editor

The Workflow Editor is a visual designer for creating and editing workflows. It provides a drag-and-drop interface built on ReactFlow.

Opening the Editor​

import { WorkflowEditor } from "@xond/workflow";

function WorkflowEditPage({ workflowId }: { workflowId: string }) {
  return (
    <div className="h-screen w-screen">
      <WorkflowEditor id={workflowId} />
    </div>
  );
}

Editor Interface​

The editor consists of:

  1. Toolbar (left side) – Node types you can drag onto canvas
  2. Canvas (center) – Where you design your workflow
  3. Properties Panel (right side) – Configure selected node/edge
  4. Controls – Zoom, pan, minimap

Node Types​

Start Node​

Entry point of the workflow. Must have exactly one output handle.

Properties:

  • Code – Unique identifier
  • Name – Display name
  • Description – Workflow description

Usage:

  • Drag from toolbar
  • Connect output handle to first State or Decision node

State Node​

Regular step in the workflow. Can have UI forms and actions.

Properties:

  • Code – Unique identifier
  • Name – Step name
  • Label – Short label
  • Description – Step description
  • UI Type – Form type to display
  • Run Type – "0" for UI (manual), "1" for Exec (automatic)
  • Actions – Array of action buttons

Usage:

  • Drag from toolbar
  • Connect input handle from previous node
  • Connect output handle(s) to next node(s)
  • Configure UI and actions in properties panel

Decision Node​

Conditional branching based on workflow values.

Properties:

  • Code – Unique identifier
  • Name – Decision name
  • Conditions – Array of conditions to evaluate
  • Output Handles – Multiple handles for different outcomes

Usage:

  • Drag from toolbar
  • Add conditions (e.g., value.field === "value")
  • Connect output handles to different paths
  • Each handle represents a condition outcome

End Node​

Exit point of the workflow.

Properties:

  • Code – Unique identifier
  • Name – End point name
  • Description – Completion message

Usage:

  • Drag from toolbar
  • Connect input handle from final State node
  • Workflow completes when this node is reached

Adding Nodes​

  1. Drag node type from toolbar onto canvas
  2. Position node where you want it
  3. Click node to select and configure it

Connecting Nodes​

  1. Hover over output handle (right side of node)
  2. Drag to input handle (left side of target node)
  3. Release to create edge

Configuring Nodes​

Basic Configuration​

  1. Select node by clicking it
  2. Properties panel opens on right side
  3. Fill in properties:
    • Code (required)
    • Name (required)
    • Label
    • Description

UI Configuration​

For State nodes, configure the UI:

  1. Select UI Type:

    • MODEL_FORM – Auto-generated form from model
    • CUSTOM_FORM – Custom React component
    • OTP_FORM – OTP input form
    • PASSWORD_FORM – Password input
    • PIN_FORM – PIN code input
    • DISCLAIMER_PAGE – Terms and conditions
    • END_PAGE – Completion page

  2. For MODEL_FORM:

    • Select Model (e.g., "Person", "Product")
    • Form will be auto-generated

  3. For CUSTOM_FORM:

    • Enter Form Class name (must be registered in FormRegistryContext)
    • Component will be loaded dynamically

Actions Configuration​

Add action buttons below the UI form:

  1. Click "Add Action"
  2. Configure action:
    • Action Type:
      • NEXT – Proceed to next node
      • SKIP – Skip to specified handle
      • SUBMIT – Submit data to API endpoint
      • VERIFY – Verify data (e.g., OTP)
      • FUNCTION – Execute custom function
    • Handle – Output handle to follow (for NEXT/SKIP)
    • URL – API endpoint (for SUBMIT)
    • Label – Button label

Decision Node Configuration​

For Decision nodes:

  1. Add Conditions:

    • Field to compare
    • Comparison operator (equals, not equals, greater than, etc.)
    • Value to compare against

  2. Configure Output Handles:

    • Each handle represents a condition outcome
    • Connect handles to different paths

Configuring Edges​

Edges connect nodes and can have conditions:

  1. Select edge by clicking it
  2. Configure properties:
    • Label (optional)
    • Condition (for conditional edges)

Saving Workflows​

  1. Click "Save" button in toolbar
  2. Workflow is validated:
    • Start node must have exactly one output
    • Decision nodes must have at least two outputs
    • All nodes must be connected
  3. If valid, workflow is saved to database

Workflow Validation​

The editor validates workflows before saving:

  • ✅ Start node has exactly one output handle
  • ✅ Decision nodes have at least two output handles
  • ✅ State nodes have max one output handle
  • ✅ All nodes are connected
  • ✅ No circular references

Keyboard Shortcuts​

  • Delete – Delete selected nodes/edges
  • Ctrl/Cmd + Z – Undo
  • Ctrl/Cmd + Y – Redo
  • Ctrl/Cmd + S – Save workflow

Best Practices​

  1. Use descriptive codes – Make node codes meaningful (e.g., "personal-data", "otp-verification")
  2. Add descriptions – Help users understand each step
  3. Test workflows – Create test instances to verify flow
  4. Keep workflows simple – Avoid overly complex branching
  5. Document decisions – Add descriptions to decision nodes explaining conditions

Next Steps​