Workflows

Set up the Studio plugin

Install the Workflows plugin for Sanity Studio and use document controls and cross-document workflow tasks.

Prerelease

Workflows is a prerelease, built in public. Read How the prerelease works before you rely on it.

The Studio plugin connects deployed Workflows to Sanity Studio. It gives editors document-level workflow controls and a cross-document view of current work.

What the plugin adds

The plugin turns deployed workflow definitions into an editor-facing workflow experience inside Studio.

  • Document workflow controls: start a workflow, see its current stage, and open its current work.
  • Activities and actions: complete tasks, edit workflow fields, remove editable to-do items, fire available actions, and abort an in-flight workflow from its instance card or Workflow details.
  • Cross-document work: browse workflows, view each run by stage, manage active work across documents, and narrow assignments to the current editor.
  • Automatic starts: start selected workflows when an editor creates a document.
  • Workflow-aware document actions: explain holds before an editor publishes, unpublishes, or deletes.

Install the packages

Use Sanity Studio 6.3 or later. Install matching versions of every @sanity/workflow-* package in the Studio.

Install the packages in an existing Studio v6 project. The plugin reads definitions deployed with the CLI and authored with the engine.

If nothing is deployed yet, do that first: Set up the workflow CLI covers the config and the deploy, and Getting started walks the whole path.

Add the plugin to your config

In sanity.config.ts, register the Workflows document view and add the plugin with the tag used to deploy the definitions.

import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
import {
  workflowDefaultDocumentNode,
  workflowStudioPlugin,
} from '@sanity/workflow-studio-plugin'

export default defineConfig({
  // ...your projectId, dataset, schema...
  plugins: [
    structureTool({
      defaultDocumentNode: workflowDefaultDocumentNode(),
    }),
    workflowStudioPlugin({
      tag: 'production', // must match the deploy tag
    }),
  ],
})

Discover workflows from subjects

A workflow’s subject field identifies the primary document it governs and declares the document types it accepts. When the caller supplies that subject at start, the plugin can discover the matching deployed workflows without extra configuration.

A mapping connects one Studio document type to one deployed workflow definition. Subject-based discovery creates that connection automatically; add a mapping only when you need to override or extend it:

  • Enable autoStart for one workflow.
  • Bind a definition that uses doc.ref instead of a first-class subject.
  • Customize its label, workflow context, or Content Release perspective.

Several workflows may target one document type. Duplicate rows for the same document-type and definition pair are rejected.

Declare start values with field initial values in the workflow definition. Studio supplies the mapped subject and renders controls for the remaining workflow-scoped input fields. A mapping may leave required input fields for the start dialog to collect. A rejected mapping is reported on the workflow’s Definition page and in the browser console, not on the landing card.

The start dialog labels and gates only workflow-scoped input fields declared required: true. Required collections such as array, assignees, and doc.refs need at least one row. An input-sourced subject without required: true can start with no document, so declare it required when every run must have a subject.

Configuration options

These options control where the plugin reads workflow state and how it integrates with the Studio.

  • tag must match the tag used to deploy the definitions.
  • workflowDataset stores workflow data in a dedicated dataset.
  • resourceClients provides clients for documents in other datasets, projects, or resources.
  • mappings customizes discovered document-type and definition pairs, enables auto-start, or binds legacy doc.ref definitions.
  • effectHandlers runs selected effects while an editor is present. Use a server runtime for unattended or consequential work.

previewHydration tunes progressive run loading in development: pageSize controls each page and interPageDelayMs pauses between pages. Production defaults normally need no override.

Work from a document

Open a document accepted by a deployed workflow. The plugin brings the workflow into the document editor in three places:

  • Workflow strip: start an available workflow and see the current stage above the document form.
  • Workflows view: work through the stage’s activities, editable fields, and actions.

Each workflow run appears as a card. Its header keeps the run title, current stage, and status visible while collapsed; select the header once to expand or collapse it. Open the card's overflow menu to view workflow history or abort an in-flight run with a required reason.

Every assignee control accepts a person or project role, including activity rows, to-do items, start inputs, field pills, and editable fields. Actor controls remain person-only because an actor identifies one account. On an activity row, only the assignees field supplies the assignment; another assignee-valued field remains an ordinary editable field.

The project role catalog can offer roles with no current holders. A non-empty catalog hides other member-held roles from new choices; an empty or unavailable catalog falls back to member-held roles.

The document Workflows view shows “Including tasks assigned to your role” when visible work reaches the current editor through a role they hold.

Activity rows show an inline calendar only for a declared dueDate or dueDatetime. Due dates turn caution once overdue, including while editable. Plain date and datetime fields remain titled in the activity detail dialog and continue to match the Workflows tool’s Date filter.

An editable to-do list shows a remove control only in the view that owns that list, such as its activity dialog or field dialog. Assignment-only and read-only views do not offer removal. Removing a row commits immediately without a confirmation dialog. A list with missing or duplicate row keys is refused instead of editing or deleting an ambiguous row.

Studio distinguishes a refused operation from a failed write. A gate refusal or field outside its edit window uses caution feedback. A write failure uses critical feedback. If a commit succeeds but a later effect fails, the message states that the change was saved and identifies the incomplete follow-up work.

  • Document badges: see the active workflow and whether the document belongs to a draft or Content Release.

Start workflows for fresh documents

Use autoStart on a mapping row to start that workflow when an editor creates a document in Studio. Existing documents and writes outside Studio are unaffected.

Configure auto-start

Add one mapping row for each workflow that should start automatically. A mapping identifies one document type and deployed definition; several rows may target the same document type.

workflowStudioPlugin({
  tag: 'production',
  mappings: [
    {
      docType: 'article',
      definition: 'article-review',
      label: 'Article review',
      autoStart: true,
    },
  ],
})

Auto-start applies only to fresh documents created in Studio:

  • The new document becomes the workflow subject in the same draft or Content Release perspective.
  • Inputs declared required: true are collected before the editor enters the form.
  • If several workflows apply, Studio starts them independently and retries only those that failed.
  • Writes outside Studio bypass auto-start; it is an integration convenience, not an enforcement boundary.

Workflows tool

The Workflows tool is organized around runs. Overview and For me share one run table, filters, an optional board, and a docked detail panel. Open Definitions from the title row’s overflow menu; a definition page uses its breadcrumb to return to the deployed catalog.

Overview

Overview at /workflows/overview lists open runs across definitions. Filter by workflow, assignee, attention, stage, or Content Release. Switch to Closed runs to inspect completed or aborted work. The address preserves the view with workflow, filters, scope=closed, and—when one workflow is selected—display=board.

Each table row’s Tasks column and each board card group holders by the current stage’s human tasks. Overlapping faces share one task, a gap starts the next, role squares appear before people, and a dashed person means the task is unassigned. Hover a group to see every task in the stage.

Attention marks explain why a run needs action. A calendar shows the overdue span for one task or the overdue task count for several; hover it to open the stage-tasks panel when a human task is late. A critical filled disc identifies a blocked run and names the task or automation that failed or did not finish. Board cards can show both marks when both apply.

Runs hydrate progressively instead of stopping at a fixed 200-run cap. While more pages are loading, counts are minimums; they become totals when hydration finishes. New, changed, and deleted runs update the shared list without restarting pagination.

Board and run details

Select one workflow and switch to the board to arrange its open runs by stage. Selecting a table row or board card opens the run in a docked detail panel and adds run=<instance-id> to the address. The panel shows current work, history, faults, and remedies; previous and next follow the displayed order, and expand opens the same detail in a dialog. Drag or use the focused edge’s arrow, Home, and End keys to resize the docked panel.

For me

For me at /workflows/for-me uses the same run surface, prefiltered to open work assigned directly to the current editor or to a project role they hold. It has no workflow picker or filter controls; roleAliases do not add work to the queue.

Definitions

Definitions at /workflows/definitions lists deployed workflows and their open-run counts. Open /workflows/definitions/<name> for one definition’s facts, stage diagram, and setup issues. Use View runs there to return to Overview with that workflow selected in board view.

Update saved links

Replace bookmarks for /workflows/all-documents, /workflows/instance/<id>, /workflows/overview/<workflow>, and /workflows/overview/<workflow>/definition. Use Overview with workflow, filters, display=board, or run search parameters, or use /workflows/definitions/<name>. Retired routes return to Overview.

Deleting a subject no longer exposes bulk cleanup in the tool. Use the Handle a deleted subject document Function pattern to apply your lifecycle policy through engine verbs while preserving audit history.

Preview workflow holds

When a workflow guard denies publishing, unpublishing, or deleting a document, the plugin disables that Studio action and explains the hold.

These holds are advisory. The Content Lake remains the enforcement boundary; see Guards and enforcement.

Run work without an editor

Studio advances workflows while editors are present. Time-based transitions and queued effects need a runtime; see Effects and runtimes.

Next steps

Visiting agent?

Workflows includes an MCP server for inspecting, operating, authoring, validating, and deploying workflows. Ask your human to set up the MCP server.

Previous

Evaluation insights

Next

Custom Studio integrations

Was this page helpful?