Workflows¶

Workflows automate business logic in your workspace. Each Workflow has a Trigger—what starts it—and a graph of Steps—what happens next.

Use Workflows to validate or change Records, respond to API calls, send email, take payments, call third-party services, schedule follow-up, and reuse logic from another Workflow.

Create a Workflow¶

Open Workflows and select New Workflow.
Choose what should start it.
Enter a unique Title and optional Description.
Complete the Trigger settings.
Select Create Workflow, then add and connect Steps in the Workflow Editor.

The trigger picker uses these labels:

Trigger	Use it for
When a record changes	React after a Record is created, updated, saved, deleted, or restored.
Before a record is saved	Validate or adjust a Record synchronously before the write completes.
On a record's date	Run before, on, or after a Date/Datetime Field on each qualifying Record.
On a schedule	Run from a recurring UTC cron schedule.
When a request comes in	Expose an HTTP endpoint for a webhook, integration, or API client.
When another workflow runs	React to another Workflow succeeding or failing.
On demand	Run manually or from another Workflow.

New Request Workflows default to GET, Include in API docs enabled, and Synchronous execution. New Scheduled Workflows start with */15 * * * * (every 15 minutes) until you change it. Event and scheduled triggers always run asynchronously.

Build the Step graph¶

A Step runs one Task. Tasks cover Records, files, email, payments, HTTP, AI, dates, lists, dictionaries, validation, branching, and other platform operations.

Connect Steps with transitions. A transition can follow success or error and may include a condition. A Workflow can branch, loop, or converge; publishing rejects transitions that point to missing Steps or leave invalid graph state.

Step inputs can use Workflow inputs, trigger data, state, and the output of earlier Steps. Pick values through the variable picker instead of hardcoding IDs where a reference is available. See Resolvers for the dynamic value model.

Save and publish timing¶

The Workflow Editor autosaves draft changes after a short pause. Saved means the draft is stored; it does not mean users or triggers are running the new graph.

Select Publish to make the draft live. Publish first flushes pending autosaves, then checks the graph, required Step inputs, linked variables, and routes. Workflow Scenarios are temporarily disabled and do not block publication. Validation failures leave the existing published version live.

Publishing creates an immutable version and sets the Workflow to Active. Editing it afterward creates Unpublished changes. Select the Active status badge to pause a published Workflow; pausing stops new trigger runs but keeps the published version. Publishing a paused Workflow resumes it.

Use Run to execute from the editor. The menu beside it offers Debug Workflow. Existing Run Scenarios controls skip execution while Scenarios are disabled. An editor run is not a substitute for publishing.

Configure each Trigger¶

When a request comes in¶

Set the Route, HTTP Method, optional domain, and the fields accepted under Route Parameters, Query Parameters, Request Headers, and Request Body.

Methods: GET, POST, PUT, DELETE, and PATCH.
Routes may include placeholders such as /webhooks/orders/{order}.
Route parameters can bind to a Resource and lookup Field. The resolved Record becomes Workflow input.
Declared query, header, and body fields appear in the variable picker and can carry validation rules.
Field references remain stable when you rename the public request key.
Include in API docs is on by default. Its published value controls generated workspace API docs.

Request routes do not become live until publication. A route must not conflict with a published Page or another Request Workflow on the same domain. Drafts may temporarily share a route.

Protect public endpoints

When a request comes in is reachable from the internet. In Who can access this endpoint?, require authentication and optional Permissions when the caller is a workspace user. For third-party webhooks, validate the provider signature or a secret before any sensitive Step.

Choose Synchronous when the caller needs the Workflow's response. Choose Asynchronous only when an immediate accepted response is enough and the remaining work can continue in the background.

Before a record is saved¶

Choose a Resource and Hook (Creating, Saving, Updating, Deleting, or Restoring). Only one Workflow can own the same Resource/Hook pair.

This Trigger runs inside the Record operation. It can reject the write or return adjusted values before persistence, so keep the graph short and deterministic. It is not a replacement for When a record changes, which reacts after the event and runs asynchronously.

When a record changes¶

Choose a Resource, an event, and optional Relations to include with the trigger Record. Supported events are created, updated, saved, deleted, and restored.

The Workflow runs asynchronously. Use the trigger Record variable for the changed Record and select only Relations the Workflow actually needs. A background Run As identity is required and defaults to the builder creating the Workflow. Choose Run as system to run with no user instead.

On a record's date¶

Choose a Resource, Date Field, at least one offset, and optional filters. The Date Field can be a Date, Datetime, or Event Schedule field. An Event Schedule field uses its start. Offsets use ISO 8601 durations with a sign: -P3D is three days before, +P0D is the same day, and +P1D is one day after.

Each qualifying Record keeps its own schedule state. Diagonal checks due Records every minute. By default, each offset runs at 8:00 AM in the workspace timezone on the offset day. If several offsets are already overdue, it sends only the most recent due occurrence and marks older ones skipped.

For an Event Schedule field, Send time can also be Exact time before or after. Each offset then runs at the event start plus the offset, for example -PT1H (one hour before) or -PT15M (15 minutes before). An all-day event starts at midnight in the workspace timezone. When an event moves, its reminder moves with it. A reminder that already ran or was skipped runs again when the new time is still in the future. When you switch back to 8:00 AM on the day, or choose a Date or Datetime field, each offset keeps only its whole days, so -PT2H becomes the day of the event.

Publishing the first version or changing the Date Field, offsets, or filters queues a participant recomputation. The Resource cannot be changed after the first publication; create another Workflow for a different Resource.

On a schedule¶

Enter a five-part Cron Expression in UTC. For example, 0 9 * * 1 runs every Monday at 09:00 UTC.

Scheduled Workflows run asynchronously as their configured Run As identity. There is no signed-in request user.

Run as system runs every step with no user. Record policies do not apply, so steps can read and change every Record. Use it for Workflows that must keep working when a user is deleted. Steps that need a user, such as AI: Run Prompt, fail in a system run.

When another workflow runs¶

Choose the source Workflow and whether to react to execution success or execution error. The follow-up runs asynchronously.

Diagonal prevents direct and indirect event cycles and caps chain depth. Use On demand with a run-workflow Step when the caller should explicitly invoke shared logic and optionally wait for it.

On demand¶

On-demand Workflows have no automatic Trigger. They can run from the editor or from a Workflow Step. Choose Synchronous when the caller needs output immediately; otherwise use Asynchronous.

Email, notifications, and integrations¶

Email Steps use a selected Email Layout for the Liquid body. The Step owns the subject, recipients, Layout values, and attachments. Layout edits save immediately; Workflow Step edits require publishing before live runs use them. Review delivery in Settings → Email Messages. If outbound email is disabled for the workspace, Diagonal records the message as suppressed and does not send it.

Provider-backed Tasks—payments, HTTP, web search/extraction, screenshots, AI, and messaging—use the workspace/provider configuration available to that Task. Publishing validates the Workflow shape, not third-party availability. Inspect the execution trace when a provider rejects a live request. Scenario execution is temporarily disabled.

Notification type variable names must differ from the selected Layout’s field names and the template’s content field names. For example, name the type variable renewal_url and set the Layout field action_url to {{ renewal_url }}. Using action_url for both prevents the template from saving. The name record is reserved for the recipient. Without a Layout, content is reserved for the email body.

Verify before publishing¶

Select Run with representative inputs.
Use Debug Workflow to inspect resolved input and output one Step at a time.
Verify important success, error, request, and Record cases in a disposable workspace. Publication does not prove runtime behavior.
Confirm background Workflows have the intended Run As identity.
For Request Workflows, preview the URL/request contract and test authorization.
After publishing, check Executions for the published run and its Step trace.

Testing external Steps

Debugger replays can roll back supported Diagonal data changes, but third-party calls cannot be rolled back. The debugger records root-level external Step output to avoid repeating calls while you step backward. Use mocks when a provider action must not run at all.