Workflows: Triggers, Versions, Activation

A workflow is a graph with a stable key, a list of immutable versions, and at most one Active version. This page explains the lifecycle; the Visual Builder page explains the editing surface.

Triggers

Every workflow starts with exactly one trigger node. These trigger types exist:

Trigger	Starts a run when…	Notes
Trigger Manually (API)	You click Run in the builder, send a message in the Chat panel, call the CLI or SDK, or call the triggerWorkflow GraphQL mutation.	Works on any version, Active or not. Every new workflow starts with this trigger.
Webhook Trigger	An HTTP request hits the workflow's unique webhook URL.	The URL is shown on the node after the first save. Every delivery is logged and can be retried individually.
Schedule Trigger	A cron expression or interval fires.	Configure cron or interval and the days of the week. Runs on the Active version only.
Form Trigger	A hosted form is submitted.	The submission becomes the run's input.
Error Trigger	Another workflow's run fails.	Lets you build alerting and recovery as workflows.
When Executed by Another Workflow	A Sub-workflow node in another workflow calls this one.	Accepts whatever the caller sends, or declared fields.
RSS Feed Trigger	A check of an RSS or Atom feed finds items it has not seen.	Set the Feed URL. Each run carries the new items, newest first.
HTTP Poll Trigger	A check of an HTTP endpoint finds new items, or a changed response.	With an Items path (JSONPath such as $.data[*]) and optional Dedupe key it fires per new item; without one it fires whenever the response body changes. Headers are a JSON object.
Database Poll Trigger	A read-only PostgreSQL query returns rows with keys it has not seen, or a changed result.	Pick a PostgreSQL connection. Write a SELECT that returns the newest rows first and set Key column (for example id).
Email Trigger (IMAP)	New mail arrives in an IMAP mailbox.	Pick an IMAP Email connection (host, port, TLS or STARTTLS, username, app password). Optionally include the raw message source or mark delivered mail as read.

Only the manual trigger runs on a Draft. Every other trigger executes the Active version and does nothing until one exists.

Polling triggers

The RSS, HTTP, database and IMAP triggers poll: they check their source on the interval you choose (Check every, from one minute to one day).

• The first check only records what is already there. Activating a trigger never replays a feed's archive, a table's existing rows or an inbox's old mail. The first run comes from the first new item after that.
• One run per check that finds something new, carrying every new item (up to Max items per run, default 20). Anything beyond that is delivered by the next check, not dropped.
• Changing the source starts over. Pointing a trigger at a different feed, URL, headers, query or mailbox resets what it remembers, so the next check records the new source instead of firing.
• Safety limits. Database and mail hosts must be reachable on the public internet (private-network and cloud-metadata addresses are refused), the database query runs read-only as a single statement with a timeout, and responses are size-capped.
• When a trigger never fires, the pollTriggers(workflowKey) GraphQL query shows each trigger's status, whether it has recorded its source, the last check, items delivered and the last error. After ten consecutive errors a trigger switches itself off and you are notified; saving the workflow again turns it back on.

App-event triggers on store nodes. A few store nodes also offer trigger operations that watch the service for you: Gmail › On new email, Google Calendar › On event created / On event updated, and Google Sheets › On row added / On row updated. Add the node from the Node Store, pick the trigger operation, choose a connection, and the workflow subscribes to that provider when a version is Active.

For every other service there is no dedicated trigger: point the vendor's webhook at a Webhook Trigger, or watch its API with an HTTP Poll Trigger.

Versions

• Every save creates a new version. Versions are numbered and immutable; the graph you saved is exactly what a run of that version executes.
• Aliases are optional human-readable names for versions.
• Open Versions in the builder to see them, or History in the sidebar to see versions across every workflow.
• A run records the version it executed, so editing a workflow never changes the meaning of a past run.

Activation

Activation chooses which version is live.

1. Open the workflow in the builder. Click Activate in the toolbar to activate the version on the canvas, or click Versions and choose Activate this version on any earlier version. The confirmation reads It handles webhooks, schedules and other automatic triggers.

The workflow's status becomes Active and its automatic triggers are armed. Activating a different version later switches the triggers to that version atomically. Deactivating a workflow returns it to Draft and disables its schedules in the same step, so nothing fires from a parked workflow.

You can keep saving new drafts while a version is Active; the Active one keeps running until you activate a newer one.

Restore, duplicate, retire

Action	Where	Effect
Restore as new draft	Versions panel	Copies an old version's graph into a new version, ready to edit.
Duplicate workflow	My Workflows card menu	New workflow with its own key and history.
Delete version	Versions panel	Removes one version permanently; the rest are untouched.
Delete workflow	My Workflows card menu	Removes the workflow and every version.
Archive	API / SDK (archive)	Marks the workflow Archived.

Statuses at a glance

Status	Meaning
Draft	No Active version. Manual runs only.
Active	An Active version exists and its triggers are armed.
Deprecated	Superseded; kept for history.
Archived	Retired.

Sub-workflows

The Subworkflow node calls another workflow as a step: choose the target workflow (and optionally a version — leave it empty to use the target's latest Active version), map inputs and outputs, and decide whether to wait for completion and whether a failure fails the parent. The child run appears in Runs with a Sub-workflow of link to the parent.

Triggering from outside the app

• CLI — fluidgrids workflows trigger WORKFLOW_KEY
• GraphQL — the triggerWorkflow mutation on the workspace gateway
• Webhook — POST to the URL shown on the Webhook Trigger node
• SDKs — client.workflows.triggerByKey(...) in Node, sdk.workflows.trigger_by_key(...) in Python

See the API Reference and For Developers.

Next steps

• Runs — watching and controlling executions
• History — versions across all workflows