Workflows & Triggers

Workflows are the bridge between the outside world and the graphs you design in Swirls. They let you react to form submissions, execute AI pipelines, and observe every run without wiring up custom infrastructure.

Why a Workflow Layer?

Graphs focus on how data is processed. Triggers focus on when that processing should start. The workflow abstraction keeps these concerns separate:

• Reuse the same graph behind multiple triggers (e.g., different intake forms).
• Turn triggers on and off without touching graph topology.
• Store trigger configuration in its own table for auditability.

This separation mirrors the underlying data model—triggers and workflows are peers to graphs rather than just another node, which keeps execution logic decoupled from the events that kick it off.

Trigger Types

The current release supports form triggers. Each one points to a form definition so every submission arrives with the fields and validation your graph expects.

Future trigger types—webhooks, scheduled jobs, AI agents—fit naturally into the same model: they capture configuration alongside the workflow and feed a normalized payload into graph execution.

Creating a Workflow

1. Create a form that describes the fields you need.
2. Create (or reuse) a trigger with that form.
3. Create a workflow that links the trigger and graph. You can reuse an existing trigger or create one on the fly—either way, Swirls stores the configuration with the workflow so it’s easy to audit later.

Executing a Workflow

• Automatically: When the trigger fires (e.g., a form submission), Swirls resolves the workflow and invokes the linked graph.
• Programmatically: Use the public API or SDK to fire a workflow with custom data—the payload is validated against the stored trigger configuration before execution begins.
• Direct graph runs: You can still invoke a graph manually, but workflows add governance and observability on top.

Each execution records:

• graphExecutions row with the payload, timestamps, and final status.
• nodeExecutions rows for each node, including errors and outputs.

You can retrieve this information through Swirls’ execution APIs or dashboards.

Handling Failures

• Trigger failures (e.g., invalid payloads) are surfaced immediately with validation errors.
• Node-level failures are captured in nodeExecutions.error; the overall graphExecution.status reflects success or failure.
• Because workflows keep trigger configuration in the database, auditing changes and rolling back is straightforward.

Embedding Workflows in Your App

Use the headless SDK or HTTP API to:

• Render the same form from your app UI.
• Trigger workflows when users take action.
• Stream execution updates for real-time feedback.

With workflows and triggers, Swirls gives you a robust, transparent mechanism to connect user intent to automated AI-driven processing—no custom glue code required.