Workflow System

Workflows are how your Diagonal app gets things done.

A Workflow is a sequence of Steps that runs in response to something happening in your business: a button click, an HTTP request, a record being created or updated, a scheduled time, or another workflow finishing.

Workflows are where pages, data, security, and integrations come together. They handle requests, update Records, send notifications, charge payments, calculate values, control what users see, and route people to the right place.

Core idea

A Workflow is a Trigger plus a sequence of Steps.

The Trigger says when the workflow runs. The Steps say what it does.

Anatomy of a Workflow

Every Workflow shares the same set of pieces, no matter what triggers it.

Piece	Purpose
Title and description	Human-readable name and explanation of what the workflow does.
Type	Defines how the workflow is triggered (Manual, Page, Request, Record Event, Scheduled, or Workflow Event).
Trigger settings	Per-type configuration, such as a route, schedule, or Resource.
Steps	The individual units of work the workflow performs.
Transitions	Flow control rules that decide which step runs next.
Authorizer	Optional rules that control who can run the workflow or its steps.
Execution mode	Whether to run synchronously or asynchronously.
Status	Active or Paused.

Steps

A Step is one unit of work inside a workflow.

Each Step references a Task — for example, Find Record, Update Record, Send Email, Charge Payment, HTTP Request, Validate Input, or Redirect. Steps receive resolved input, run their task, and return output that later steps can use.

Diagonal ships with a large library of tasks for data, payments, HTTP, scheduling, math, dates, lists, dictionaries, frontend behavior, and assertions. Building a workflow is mostly a matter of choosing the right steps and connecting them.

Transitions

Transitions decide which Step runs next.

A Transition listens for an event — usually a Step succeeding or failing — and queues the next Step. Transitions can include conditions that decide whether to take a path. Together, they form the branching logic of your workflow: success paths, error paths, and conditional routing.

Authorizers

Authorizers control who can execute a Workflow or a specific Step.

They are useful for protecting page actions, gating an HTTP endpoint, or restricting an admin-level workflow to specific Roles or users. An Authorizer can apply at the workflow level for the whole run, or at the step level to gate a specific action.

Variables and Resolvers

Workflows pull dynamic values from the request, the signed-in user, the workflow input, the page, the record being edited, and the output of earlier Steps.

Resolvers are the syntax workflows use to grab those values without hardcoding them. They are how a Step says "use the email of the customer this workflow ran for" or "use the value of the form field named status". Combined with Variables, they let a single workflow handle many different inputs cleanly.

Workflow Types

A Workflow's Type sets its Trigger. The trigger decides how the workflow starts and what input it receives.

Type	Use it when...
Manual	A builder or admin runs the workflow on demand.
Page	A page event, such as a button click or form submission, runs the workflow.
Incoming HTTP Request	An external system calls a Diagonal-hosted endpoint.
Record Event	A record in a Resource is created, updated, saved, deleted, or restored.
Record Schedule	A workflow should fire relative to a date on each record — reminders, follow-ups, renewals.
Scheduled	A cron-like schedule runs the workflow on a recurring basis.
Workflow Event	Another workflow finishes successfully or fails.

Manual

Manual workflows run on demand.

They have no automatic trigger. Use them for one-off operations like running a backfill, generating a report, sending a test message, or kicking off a process that does not yet have a UI.

Setting	Required	Purpose
(none)	—	Manual workflows have no trigger settings.

Good first workflow

Manual workflows are a good way to learn Diagonal. You can build the steps you need without first having to design a UI or set up a schedule.

Page

Page workflows run from a Page event, like clicking a button, submitting a form, or completing a flow on a Page.

They are the connective tissue between your UI and the rest of the platform. A Page workflow can read form input, validate it, write to a Record, send a notification, redirect the user, and update the page in response.

Setting	Required	Purpose
Route	Yes	The route the page action is bound to.
Method	Yes	The HTTP method the page action uses.
Headers, query, params, body	No	Schema describing the inputs the page sends.

Page workflows usually run synchronously so the page can react to the result.

Incoming HTTP Request

Request workflows turn your Diagonal workspace into a hosted API endpoint.

Use them when an external system needs to call into your app — webhooks, integrations, partner systems, or third-party services that need a stable URL to send data to.

Setting	Required	Purpose
Route	Yes	The route the request workflow handles.
Method	Yes	One of GET, POST, PUT, DELETE, or PATCH.
Headers, query, params, body	No	Schema describing the request inputs the workflow expects.

Request and Page workflows share the same routing engine. The difference is the audience: Page workflows belong to a page in your app, Request workflows are public endpoints meant for outside systems.

Authorize HTTP endpoints

Request workflows are reachable from the internet. Add an Authorizer or validate a shared secret in an early step before doing anything sensitive.

Record Event

Record Event workflows run when a record changes inside a specific Resource.

Use them to keep your business logic close to your data. When a customer is created, send a welcome email. When an invoice updates and now has a paid status, push a confirmation. When a project is deleted, archive its tasks.

Setting	Required	Purpose
Resource	Yes	The Resource to listen to.
Event	Yes	One of created, updated, saved, deleted, or restored.

Event	Fires when...
Created	A new record is added to the Resource.
Updated	An existing record's fields change.
Saved	A record is created or updated.
Deleted	A record is removed.
Restored	A previously deleted record is restored.

Record Event workflows always run asynchronously so they do not block the action that triggered them.

Record Schedule

Record Schedule workflows fire relative to a date field on each record in a Resource. They are designed for per-record reminders, follow-ups, renewal notices, and similar time-relative automations.

Unlike Scheduled workflows (which run on a fixed clock for the whole workspace), Record Schedule workflows run independently for every qualifying record, anchored to that record's own date.

Setting	Required	Purpose
Resource	Yes	The Resource whose records are scheduled.
Date Field	Yes	A date or datetime field on the resource. All timing is relative to this value.
Offsets	Yes	One or more ISO 8601 durations with a + or - prefix, e.g. -P3D (3 days before), +P1D (1 day after), +P0D (same day).
Filters	No	Optional filter conditions that limit which records are eligible. Records that do not match are ignored.

How scheduling works

When a Record Schedule workflow is published, Diagonal evaluates every record in the resource and computes the next time each record's workflow should fire. This schedule state is stored on the record itself (in the __meta field) and includes a per-offset status map.

Each offset can be in one of three states:

State	Meaning
Pending	The offset has not yet reached its run time.
Sent	The offset fired and the workflow was dispatched.
Skipped	The offset was past due and was skipped because a more recent offset was also due.

A background process checks every minute for records whose next scheduled run is due. When it finds one, it dispatches the workflow and advances the schedule state.

Send time

All record schedule offsets resolve to 8:00 AM in the workspace's default timezone. For example, a record with a due_date of June 15 and an offset of -P3D would fire at 8:00 AM local time on June 12.

Stale offset handling

If multiple offsets are past due at the same time — for example, a record was imported with a date several days ago — Diagonal does not dispatch the workflow once per offset. Instead, it dispatches only the most recent past-due offset and marks the older ones as skipped. This prevents a flood of duplicate executions for historical data.

For example, given offsets [-P3D, -P1D, +P1D] where all three are past due, the -P3D and -P1D offsets are marked skipped and the workflow fires once for +P1D.

Recomputation

Schedule metadata is recomputed automatically when:

• A record is created, updated, or saved.
• The workflow is re-published with changed schedule settings (date field, offsets, or filters).
• A scheduled offset fires and the schedule state advances to the next pending offset.

Trigger context

When a Record Schedule workflow runs, the trigger context includes a record variable containing the full record that triggered it, including resolved relations. Use this in workflow steps to read the record's fields, send personalized messages, or update related data.

Record Schedule workflows always run asynchronously.

Common patterns

• Payment reminders: Set offsets at -P7D, -P1D, and +P1D relative to an invoice's due_date to remind before and after the deadline.
• Appointment prep: Send a preparation checklist -P1D before an appointment_date.
• Renewal notices: Notify customers -P30D before a contract_end_date.

Scheduled

Scheduled workflows run on a recurring schedule defined by a cron expression.

Use them for batch jobs, daily summaries, weekly reports, hourly polling against a third-party API, monthly invoice runs, or any operation that should happen on a clock instead of in response to a user action.

Setting	Required	Purpose
Cron expression	Yes	A cron expression in UTC that defines the schedule.

Common schedules:

Schedule	Cron expression
Every hour	0 * * * *
Daily at 9 AM UTC	0 9 * * *
Every Monday at 8 AM UTC	0 8 * * 1
First of the month at midnight UTC	0 0 1 * *

Cron times are UTC

Schedules are evaluated in UTC. If you want a workflow to run at a local business time, convert that time to UTC when you write the expression.

Workflow Event

Workflow Event workflows run when another workflow finishes.

Use them to chain related processes without baking the chain into a single large workflow. For example, when an Onboard Customer workflow succeeds, run a separate Send Welcome Pack workflow. When a Charge Payment workflow errors, run an Alert Finance workflow.

Setting	Required	Purpose
Workflow	Yes	The workflow to listen to.
Event	Yes	The lifecycle event to listen for.

Event	Fires when...
Execution success	The source workflow completes without error.
Execution error	The source workflow fails or is stopped.

Workflow Event workflows always run asynchronously, so they do not block the source workflow's completion.

Execution Modes

Each Workflow runs either synchronously or asynchronously.

Mode	When to use it
Synchronous	The caller — a user, page, or HTTP request — should wait for the result.
Asynchronous	The work should happen in the background and not block the caller.

Type	Typical mode
Manual	Synchronous
Page	Synchronous
Incoming HTTP Request	Synchronous
Record Event	Asynchronous
Record Schedule	Asynchronous
Workflow Event	Asynchronous
Scheduled	Asynchronous

Page and Request workflows are usually synchronous because the caller is waiting for a response. Background and event-driven workflows are asynchronous because the caller has already moved on.

Status

A Workflow is either Active or Paused.

Status	What it means
Active	Triggers fire normally and the workflow runs.
Paused	Triggers do not fire. No new executions start.

Pause a workflow during incident response, while you are editing destructive logic, or when an integration partner is offline. Activate it again when you are ready.

Choosing a Workflow Type

If you want to...	Use type
Trigger logic from a button click or form submission.	Page
Expose a public webhook or API endpoint.	Incoming HTTP Request
React to changes inside a Resource.	Record Event
Fire a workflow relative to a date on each record.	Record Schedule
Run something on a schedule.	Scheduled
Chain a workflow off the result of another workflow.	Workflow Event
Run something one-off from the admin panel.	Manual

Start small

Most apps grow their workflow library over time. Start with the workflows your users will hit on day one — Page workflows for the screens they touch, plus a small set of Record Event workflows to keep data consistent — and add Scheduled and Request workflows as integrations come online.