Visual Workflow Builder

What it is

The Visual Workflow Builder is a drag-and-drop canvas (powered by React Flow) for designing automation workflows. You drag nodes from a searchable palette, wire their inputs and outputs with {{variable}} references, configure each node in a context-aware panel, and run the result manually or via a trigger — watching a step-by-step execution timeline.

Under the hood a workflow is an Activity (Strapi collection) whose workflow_definition is a JSON DAG of nodes and edges, paired with an input_schema and output_schema. The canvas is the authoring surface; the Processors are the runtime that walks the graph.

When to use it

Use the builder whenever the steps of an automation are known and orderable — upload → classify → route → email. It is the most auditable unit of automation. Drop agent or squad nodes into the graph for the steps that need open-ended judgement. See workflows vs. agents vs. squads.

How it works

Process flow — authoring and running a workflow:

Call flow — what happens on execution (DMS → Router → Processors, per communication-standard):

Execution status state machine — what the timeline reflects (a node-level lifecycle of pending → running → completed | failed; the execution rolls these up):

Sub-features

• Searchable node palette with 30+ task types across seven categories (see The node palette below, plus Node catalog and Task node types).
• Dynamic config panel — forms adapt to each node type from its config_schema.
• Real-time validation before execution; auto-layout of nodes.
• Execution timeline — per-node inputs/outputs, node status (active/running, skipped, failed, completed).
• Status lifecycle — draft, active, archived.
• Ownership / level — system (shared), user (private), internal (hidden transient); clone a system workflow via instantiation to get a private copy.
• Control flow — decision nodes (true/false branches, labelled edges), wait/poll, for-each loops (see Task node types).
• Human-in-the-loop — input/file-upload nodes pause the run as awaiting_user_input and resume with a correlation token (see Human in the loop).

The node palette

Everything you can drop on the canvas, grouped by the palette's categories. Each node's canvas node.type is the *_task identifier shown in the table; before execution the UI rewrites it to the generic type: "task" and moves the real type into data.task_type (see the callout above). The Key properties column lists the load-bearing config fields — the config panel renders the full schema from GET /api/workflows/task-types.

Triggers

How a run starts. The trigger node carries trigger_type; the actual binding (path, cron, event source) lives on the Event Bus. Trigger nodes shape the start of the graph rather than dispatching as a task.

AI Operations

Document

Knowledge / RAG

Integration

See Integration nodes below for full properties (auth, URL/method/body, output mapping). Summary:

Control Flow

Data Transform

Built-in context variables: {{user_id}}, {{execution_id}}, {{DMS_URL}}, plus all webhook form fields. File uploads produce {field}_document_id, {field}_file_url, {field}_mime_type.

Integration nodes

Integration nodes connect a workflow to the outside world. They share one pattern: the node config names the operation, the executor resolves {{variables}} and injects credentials, and the processor calls a DMS service that holds the OAuth tokens and makes the provider API call. Credentials are never stored in the workflow definition.

How credentials reach a node:

• Google (Drive / Gmail) — user-delegated OAuth2 (or service account); the DMS Google OAuth service injects the token. The user connects on the Integrations page first.
• Generic OAuth2 providers — set "oauth_integration": "<provider>" on the node (e.g. microsoft_365 for SharePoint). At execution time the executor looks up the user's user-integration, auto-refreshes an expiring token, and injects oauth_access_token into the node's input_mapping.
• SMTP email — server-side credentials from environment, no per-user OAuth.
• REST API — bring your own auth via headers (e.g. Authorization: Bearer {{api_token}}), or attach an oauth_integration for a managed token.

For the full integration architecture (OAuth flow, token injection, the generic adapter, and the roadmap of additional connectors) see Integrations.

Configuration parameters

The Activity (workflow_definition owner) carries these fields. Reconciled against the DMS activity schema — type and default included.

Inside workflow_definition, two further runtime keys may appear:

Examples

A minimal three-node DAG — classify → decision → extract — in canvas (frontend) format. Note the labelled decision edges and the always-present input_schema.

{
  "nodes": [
    {
      "id": "classify-1",
      "type": "classification_task",
      "position": { "x": 80, "y": 120 },
      "data": {
        "label": "Classify document",
        "task_type": "classification_task",
        "config": { "document_types": ["invoice", "receipt", "other"] }
      }
    },
    {
      "id": "decide-1",
      "type": "decision_task",
      "position": { "x": 360, "y": 120 },
      "data": {
        "label": "Is it an invoice?",
        "task_type": "decision_task",
        "config": {
          "left": "{{classify-1.category}}",
          "operator": "==",
          "right": "invoice"
        }
      }
    },
    {
      "id": "extract-1",
      "type": "extraction_task",
      "position": { "x": 640, "y": 40 },
      "data": {
        "label": "Extract invoice fields",
        "task_type": "extraction_task",
        "config": { "output_format": "json" }
      }
    }
  ],
  "edges": [
    { "id": "e1", "source": "classify-1", "target": "decide-1" },
    { "id": "e2", "source": "decide-1", "target": "extract-1", "sourceHandle": "true", "label": "true" }
  ],
  "input_schema": {
    "type": "object",
    "properties": { "file_url": { "type": "string" } },
    "required": ["file_url"]
  }
}

Variable / data-flow example. A downstream node config pulls a field off an upstream result. {{variable}} substitution is literal string replacement against the resolved context; JSONPath (e.g. on a REST API node's output_mapping) lifts a nested field into a named variable:

{
  "subject": "Invoice {{extract-1.invoice_number}} received",
  "body": "Total due: {{extract-1.total_amount}} on {{extract-1.due_date}}"
}

Dependencies

• DMS (Strapi) — the API, the Activity store, and the job submitter the UI talks to.
• Router (Redis-backed) — enqueues jobs onto workflow_queue; forwards the DMS payload unchanged.
• Processors — walk the DAG in topological order and execute individual node tasks.
• Per-node services — LLM service, RAG query service, integrations, as the nodes require.

Limitations

• A workflow is only as adaptive as its nodes; for open-ended steps you must add agents/squads.
• Draft workflows skip strict validation (used by the Composer); active workflows are validated.
• The processor runs only nodes with type: "task"; input/output/decision-only nodes shape flow but aren't dispatched as tasks.
• A node config that references {{vars}} that never resolve does not fail — it emits the literal template (see Troubleshooting).
• Coming soon: version history / undo-redo on the canvas is planned, not yet shipped; treat version as a manual label and clone before risky edits.

Tips & best practices

• Naming — give workflows and nodes verb-first, human-readable names ("Classify document", not "node-3"). The label is what the timeline shows.
• Lifecycle discipline — author in draft, promote to active only after validation and a manual test run, archive instead of deleting so executions keep their definition.
• Clone, don't edit, system workflows — a system/template workflow is shared. Use instantiate to get a private user copy; edit that.
• Keep nodes small — one responsibility per node makes the timeline and retries meaningful. Split a do-everything LLM node into classify → extract.
• Variable hygiene — name inputs in input_schema, reference them exactly, and prefer explicit output mapping (JSONPath) over deep {{a.b.c}} chains.
• Set deadlines and quotas deliberately — tune execution_deadline_seconds to the slowest realistic run; set monthly_*_quota on costly LLM workflows.
• Anti-patterns to avoid: strings where arrays are required; one giant node; editing a live active workflow other users depend on; leaving data_shield_policy unset on workflows that process PII.

Troubleshooting

How to test

A repeatable checklist for a positive then a negative run:

1. Build — drag a Webhook trigger and an Email Send node onto the canvas; wire the edge.
2. Map a variable — put a webhook field into the email body with {{field_name}}; set to as an array and fill subject.
3. Validate — confirm real-time validation is green (no missing input_schema, no required fields empty).
4. Save as active.
5. Trigger manually — copy the generated curl sample and POST a payload (or run with custom JSON inputs from the UI).
6. Watch the timeline — poll status; confirm each node goes pending → running → completed and the per-node inputs/outputs are what you expect.
7. Confirm outputs — the final node's result appears under the execution's outputs.
8. Negative test — remove a required field (e.g. clear subject, or delete input_schema) and confirm validation blocks save/execution with a specific error.

Cross-links

• Task node types · Node catalog
• Event Bus — webhook / schedule / event triggers
• Data Shield — data_shield_policy enforcement
• Human in the loop · Agentic automation · Governance
• Workflows vs. agents vs. squads

APIs used