Workflows
Model, run, and observe content workflows on the Content Lake: definitions, stages, activities, and effects, from editorial review to full automation.
Workflows
What Workflows is, the core concepts behind it, and which surface to build on.
Quick start: run your first workflow
Define your first workflow in TypeScript, deploy it, and move a Sanity document through its stages.
Run the engine from your own code
Create a Workflows engine from your deployment config, then start and advance an instance from a TypeScript script.
How early access works
What building on Workflows during early access commits you to: one fixed 0.x stack, a stricter contract for stored documents, what the Content Lake does not yet enforce, and the runtime you supply.
Definitions, stages, and instances
A definition describes a process. An instance is one run of it, pinned to the definition version it started under and sitting in exactly one stage.
Architecture, actors, and enforcement
Who the engine acts as, where a condition can read the caller, and which of the engine’s checks would stop a client that bypasses it.
Global document references
Why every document pointer in a workflow carries its location, and which resources a workflow may read and write.
Deployments, partitions, and resources
How a deployment binds definitions to a Sanity resource: name versus partition, the storage partition that keeps environments apart, and the aliases that point a definition at real content.
The reactive session
How a reactive session projects one workflow instance for a UI: what keeps it current, what each session state means, and when a preview becomes a commit.
Configure workflow fields
Declare workflow, stage, and activity fields, configure initial values and validation, and manage role-constrained assignments.
Define activities and actions
Add an activity to a workflow stage, record a decision with actions and operations, and route on it with a transition.
Let reviewers claim an assignment
Add a role-restricted reviewer assignment to a workflow activity, let an editor claim it with editField, and limit approval to the claimer.
Write GROQ conditions
Write GROQ conditions for workflow start filters, requirements, stage transitions, and activity gates.
Hold publishing and freeze fields with guards
Add stage guards that hold publishing and freeze fields on the subject document while a workflow instance is in a stage.
Spawn and coordinate subworkflows
Spawn child workflow cohorts from an action, pass input values, and wait for child instances to settle.
Run an external step with an effect
Declare effects on workflow actions, run effect drainers with leases and retries, and return typed outputs to conditions.
Add Workflows to Sanity Studio
Install the Workflows plugin in a Sanity Studio, bind it to your deployed definitions, and put workflows in front of editors.
Create a workflow-powered Document Action
Build a custom Submit for review Document Action in Sanity Studio with the @sanity/workflow-studio adapter: read the document's workflow, respect the evaluated verdict, and commit the action.
Workflows in Sanity Studio
See where your work stands, complete the tasks a workflow is waiting on, find work assigned to you, and understand a held publish.
Build a workflow interface with the App SDK
Render live workflow state and commit actions from your own App SDK application: mount a session, handle its states, render activities and fields from the evaluation, and list instances.
Explain waiting conditions and field insights
Use condition insights and field insights on WorkflowEvaluation to explain blocked actions, waiting transitions, and missing references.
Query instance history and audit trails
Query workflow instance history, resolve actor stamps, separate effect history, and record custom audit entries.
Configure and deploy workflow definitions
Install and authenticate the workflow CLI, write the sanity.workflow.ts config that binds your definitions to a Sanity resource, and deploy them to one environment or several.
Start a workflow instance
Start workflow instances from code and the CLI: build the subject reference, pre-flight start requirements, and retry a start safely.
Run Workflows with Sanity Functions
Use GROQ-triggered and scheduled Sanity Functions to start workflows, reevaluate conditions, and process queued effects.
Generate Functions from your workflow definitions
Generate the Sanity Functions your workflow definitions need, connect an effect handler, and deploy them with Blueprints. Experimental.
Coordinate content across projects and datasets
Run one workflow over content that lives in other projects, datasets, Media Libraries, or Canvas, and prove the routing before you rely on it.
Connect an agent over MCP
Install and authenticate the Workflows MCP server, register it with your agent, address a workflow environment, and see which tools change state.
Test your workflows
Run the real workflow engine in memory: drive every path of a workflow, control the clock, simulate guard enforcement, and assert on exactly what happens.
Upgrade Workflows packages
Take a new Workflows release without breaking in-flight instances: the lockstep set, what the reader-model literal claims, and the readers-first order.
Workflows reference
Index of every Workflows reference page: definition language, sanity.workflow.ts, engine, reactive session, Studio plugin, UI components, CLI, MCP tools, and TypeDoc.
Workflow authoring reference
Reference for Sanity Workflows authoring declarations, condition variables, decision sites, operations, guards, and subworkflow spawns.
Workflow configuration reference
Every key of a sanity.workflow.ts config: defineWorkflowConfig, deployments, partitions, resource aliases, reader-model acknowledgement, and runtime blocks.
Engine, effects, and insights reference
Reference for createEngine, WorkflowEvaluation, engine methods, effect handler contracts, evaluation insights, and HistoryEntry types.
Studio plugin configuration reference
Options, mapping rows, structure helpers, and embeddable tables of @sanity/workflow-studio-plugin, and how it differs from the @sanity/workflow-studio adapter.
Reusable UI components reference
Add assignment, date, member, and workflow-diagram controls to a custom Workflows interface.
Reactive session and adapter reference
Session states and commands, the useInstancePreviews contract, and the WorkflowObserver interface and builder kit for custom adapters.
Workflow CLI command reference
Every Workflows CLI command with its flags, selectors, JSON output, and exit behavior, for deploying definitions and driving instances.
Workflows MCP tools reference
Every tool the Workflows MCP server exposes, with inputs, results, and errors, generated from @sanity/workflow-mcp 0.37, plus the embedding API.
Limits
The engine’s operational caps and defaults: what each protects, and where to tune the ones you can.
Workflows release notes
Curated overviews of recent Workflows prerelease package waves.
Cookbook
Worked, runnable workflow examples for Sanity: editorial review, AI content pipelines, coordinated releases, and more, each a complete definition.
Cookbook: Editorial review
A four-stage editorial review workflow for Sanity: assignment, drafting, review, and published, driven by human actions in the Studio.
Cookbook: AI content pipeline
An AI content pipeline built on Workflows: effect handlers call generation APIs while editors approve results through workflow actions.
Cookbook: Coordinated release
A release workflow that coordinates approvals across many documents and hands the atomic go-live to a Content Release.
Cookbook: Client–server asset intake
Start an image-review workflow from an app, then let a server import or discard the staged file.
Cookbook: Handle workflows when referenced content is deleted
Apply an application-owned lifecycle policy when content watched by an Workflow is deleted.