Understanding Workflows
A workflow is a directed graph: nodes connected by edges, starting at a trigger. FluidGrids stores it as a series of immutable versions under a stable workflow key, and executes it as runs.
Key, versions, alias, status
- The key identifies the workflow for its whole life. Duplicating a workflow creates a new key.
- Every save in the builder creates a new version — a complete snapshot of nodes, edges, and node configuration. Versions are never edited in place.
- An alias is an optional label on a version.
- A workflow's status is Draft, Active, Deprecated, or Archived. It is Active when one of its versions has been activated.
Activation
At most one version of a workflow is Active. The Active version is the one automatic triggers — webhook, schedule, form, error — execute. Manual runs (the builder's Run, the Chat panel, the API) can execute any version. Activating a different version switches the triggers atomically; deactivating disables the workflow's schedules in the same step. Restoring an old version copies it into a new draft rather than rewriting history.
Triggers
The trigger node types are Trigger Manually (API), Webhook, Schedule (cron or interval), Form, Error, When Executed by Another Workflow, and four polling triggers that check a source on an interval and fire only for new data: RSS Feed, HTTP Poll, Database Poll (PostgreSQL) and Email (IMAP). A trigger is registered per workflow; webhook deliveries are logged and individually retryable. A few store nodes add app-event trigger operations on top (Gmail new email, Google Calendar event created/updated, Google Sheets row added/updated) that subscribe to the provider; every other vendor reaches FluidGrids through the generic Webhook trigger or an HTTP Poll trigger on its API.
Data flow
Data moves along edges as items. Each node receives the output of the node(s) before it and produces output for the node(s) after it. A node parameter is either a fixed value or an expression such as ${output.customer.email} referencing upstream output. Edges can carry a mapping (the GraphQL Mapper: direct, expression, transform, cast, array, object, context) and a condition.
Branching, looping, and joining are built-in nodes: IF and Switch route, Loop iterates, Merge joins branches with Append, Combine, Multiplex, Keep Separate, or Choose Branch semantics, Wait pauses, and Subworkflow calls another workflow.
Runs
A run is one execution of one version. It records the trigger payload, the version executed, per-node state (Pending, Running, Completed, Failed, Skipped, Waiting, Timeout, and more), each node's input and output, a structured log, and a run-level status: Pending, Running, Waiting, Completed, Failed, Cancelled, or Terminated.
Runs are asynchronous and durable. Triggering enqueues a job on a Redis Streams queue; a pool of stateless workers consumes it and walks the graph node by node, fanning out parallel branches and reconverging at Merge nodes. If a worker dies mid-run the job is redelivered rather than lost. Built-in nodes execute inside the worker; store nodes execute in isolated per-node sandboxes with credentials injected at call time; Code nodes run in a hardened JavaScript or Python sandbox.
Error handling and recovery
Failures are typed — a bad credential, a validation error, a downstream 500, a timeout, a sandbox violation — so the UI and retry logic can react differently. Recovery is surgical: Retry Node re-executes one node with its original inputs; Resume continues a paused or waiting run; Cancel stops one cleanly. A workflow that begins with an Error Trigger runs whenever another workflow fails, so alerting and remediation are themselves workflows.
Where a workflow's output can go
Anywhere a node can send it: a Slack message, a database row, an HTTP call, an email. The BigConsole DataSink node is a special case — it turns any workflow into a data pipeline feeding live BigConsole dashboards, keyed by a DataSink key.