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.

A workflow is your team’s review process, set up in Sanity Studio. It shows where each document stands and what it needs next. This page covers what you see and do as an editor after a developer installs the Workflows plugin.

Two surfaces carry the whole experience. The document editor shows the workflows a single document is in. The Workflows tool shows work across every document.

Open the document and look at the workflow strip above the form. It has one button for each workflow you can start on this document type. Each button reads Start followed by the workflow’s name. Select one to start it.

If a workflow needs information first, a start dialog opens. Fill in every required field, then confirm. Some workflows start on their own when you create a document, so a new document may already be in one.

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.
• Document badges: see the active workflow and whether the document belongs to a draft or Content Release.

Each workflow run appears as a card that shows the workflow title and the current stage. Select the card’s header to expand or collapse it. To start another workflow on the document, select + beside Active Workflows. To see what has happened in a run, open the card’s overflow menu and select Workflow history.

Workflow history is written as plain sentences, such as “Alex Kim moved this workflow from Draft to In review”. Each entry names who acted:

• A project member: their name and avatar.
• A robot token: its token label.
• A robot token without a label, or the workflow’s own automation: Automation.
• Someone who is no longer in the project: Unknown user.

Names show a placeholder while the member list loads. If the list fails to load, people show as Couldn’t load. Hover a name to see details.

Some history rows record an effect: a step the workflow runs on its own, such as posting to another service. Select a completed or failed effect’s row to open its details:

• Completed: who completed it and its note, with each output the effect declares in the workflow’s order. An output the effect didn’t return reads Not returned.
• Failed: who resolved it. When the failure recorded a reason, the reason shows first.

Press Escape or select outside the details to close them. A row with nothing to show doesn’t open.

The Workflows view lists the work the current stage is waiting on. Complete a to-do, fill in the fields the stage asks for, and fire an action when the work is done. An action records what happened. The workflow moves to the next stage only when the conditions for moving are met.

You can edit a field only if the workflow makes it editable. The activity dialog, the run card, and the run’s detail panel all use the same editor for a field:

• Single assignee: holds one person. Picking another person replaces the first.
• Multiple assignees: picking a person adds them to the list.
• Choice: offers the workflow’s options.
• Single document reference: opens the document picker.
• Notes log: takes a new entry.

Multiple document references, release references, objects, and other lists are read-only in Studio.

When you open a field’s value, in the activity dialog, a field on a run card, or an effect’s details, an object reads as a grid of labeled rows that use the field titles from the workflow. A list of objects stacks one grid per item. A long list shows its first five items and a Show N more button. A notes log shows its newest five entries and a Show N earlier button. On the run card itself, an object field shows its title, name, label, or headline, or else how many of its fields have a value. A list field shows how many items it has. Yes-or-no values read Yes or No.

You can assign a task to a person or send it to a project role:

• Assigned to a person: the task appears in that person’s task list.
• Sent to a role: the task is offered to everyone with that role. Once someone is assigned, it no longer appears for the others. If you remove the last assigned person, the task is offered to the role again.

In the assignment picker, select a person under Assign to, or a role under Send to role group. Your own name is listed first. You can search by name, email, or role. The number beside each role shows how many people have that role. The workflow may also let people with other roles take the task.

In the document’s For me view, Tasks assigned to you lists your own work. Tasks sent to your roles lists unassigned work offered to a role you have. Your personal task badges and counts don’t include role tasks. Open a task to see the actions and assignment changes the workflow allows.

Opening a task from the document view shows the same activity view in a modal, without the Studio document row and document link.

An activity shows a calendar only for a due date field (dueDate or dueDatetime). The due date turns to a warning color after it passes, but only while the activity or to-do is open and the workflow is running. Finished, failed, or skipped work, and work in a completed or canceled run, shows its due date as a plain date. Studio checks due dates every minute, so an item turns overdue while you have the list open. Other date fields (date and datetime) appear with their titles in the activity dialog, and you can filter on them with the Workflows tool’s Date filter.

You can remove a to-do only in the view that owns its list, such as its activity or field dialog. Views that only show or assign to-dos don’t offer removal. Removing a to-do saves at once, without asking you to confirm. If the list’s rows are damaged (rows missing an ID, or two rows with the same ID), Studio refuses the change, so it never removes the wrong row.

Studio shows different messages for a refused change and a failed save:

• Refused, for example because the workflow doesn’t allow it now, or a field can’t be edited in this stage: a warning message.
• The save failed: an error message.
• The change saved, but follow-up work failed: a message that says the change was saved and names the work that didn’t finish.

If a workflow can’t find a document it refers to, a notice names the field. If that document is required, the workflow can’t move on until the document is back. If it’s optional, the workflow waits only when a condition needs the document’s content.

If the document still exists, check your access and the version used by the workflow: draft, published, or Content Release.

To continue, restore the deleted document or your access to it. If the affected field offers a document picker, you can select a replacement you can access. Ask your project administrator for help if you cannot make the change.

Completed workflows stay completed. A blocked workflow is not canceled automatically; you can still cancel it when the work is no longer needed.

The Workflows tool has two views:

• Overview: tracks workflow runs across documents.
• For me: lists tasks assigned to you or sent to your roles.

To see the deployed workflows, open Definitions from the More menu in the title row.

Overview at /workflows/overview lists open runs for all workflows. To work with the list:

• To filter, select the Add filter icon and choose Assignee, Stage, Needs attention, or Release. Each value you pick adds a chip to the filter bar. Select a chip to add or remove values. Select Clear filters to remove them all.
• Without filters, a count line shows how many runs are blocked, overdue, or unassigned. Select a count to filter to those runs.
• To show one workflow, select it from the All workflows menu.
• To see completed or canceled runs, select Closed runs.

The page address keeps your view, so you can bookmark or share it. It uses the workflow, filters, and scope=closed parameters, and display=board when one workflow is selected.

The Tasks column and board cards show the people working on the current stage’s tasks:

• Faces that overlap share one task. A gap starts another task.
• A dashed person means nobody has the task.
• A group icon means the task is sent to roles.
• An amber dot marks an overdue task: an open task whose due date has passed. Failed tasks have no dot.

Hover a group to see its tasks, who has them, and their due dates.

A calendar mark shows how late the run is, such as 4d, when all its overdue tasks are equally late. If they differ, it shows overdue. Hover the mark for details. A filled red dot beside the stage name means the run is blocked. It names the task or automation that failed or didn’t finish.

Runs load page by page, so every run appears. While pages are still loading, counts are minimums. They become totals when loading finishes. The list updates on its own when runs start, change, or are deleted.

To see one workflow’s open runs by stage, select the workflow and switch to Board. Select a table row or board card to open the run’s detail panel. The panel header names the workflow and the current stage. The panel has Workflow subject, Workflow, History, and Manage sections. Select Expand for a larger view of the same run, with previous and next buttons and a position count.

On a board card, the blocked mark sits in the top corner. Overdue dots remain on the individual task groups. A card can show both when a run is blocked and has late tasks.

With a workflow row or board card selected, press Up Arrow or Down Arrow to open the previous or next workflow. Drag the edge of a docked panel to resize it.

When the board is wider than the window, use the navigator to jump to a stage. Select Endings to show the ending stages. For keyboard navigation, focus the navigator, use Left Arrow or Right Arrow to choose a stage, then press Enter or Space.

For me shows one row per task, including failed tasks that need attention. A workflow with two tasks appears in two rows. Tasks assigned to you lists your personal assignments. Tasks sent to your roles lists tasks offered to your role groups that have not been assigned to a person. Empty sections are hidden.

The tables show Workflow subject, Task, Opened, Workflow, Due, and Assignee, plus a column that flags tasks that need attention:

• Opened: how long ago the task’s stage started.
• Assignee: every person and role on the task.
• Due: hover it to see the exact deadline.

Due dates follow these rules:

• A date-only due date (dueDate) has no time of day. It becomes overdue after that date has passed in your own time zone. A workflow uses dueDatetime when everyone must share one exact deadline.
• A task with several due dates is late once any of them passes. How late it is counts from that date.
• A failed task shows its past due date as a plain date.

Select a task row to open its activity view. The view shows:

• The activity’s description.
• Its status, and who an open task waits on, such as Active · with you or Active · with your role.
• The Studio document, and a Target row when the task links to work elsewhere. A web link target shows its host and opens in a new tab.
• The activity’s fields.
• A footer with every action you can take, in the workflow’s order, and an Open linked document link. Actions that don’t fit are in the More actions menu.

Opening an activity from a run in Overview shows the same view in a modal.

Select Expand to give the same task more room. The expanded view includes previous and next task controls and a position count. Back to the panel returns to the same task. On a selected table row, Down Arrow and Up Arrow step through tasks in displayed order. To inspect the whole run’s history, open the run from Overview.

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. Select View runs there to return to Overview with that workflow selected in board view.

Some saved Workflows tool addresses open Overview instead of the page they named. Replace bookmarks that use these addresses:

• /workflows/all-documents, /workflows/instance/<id>, and /workflows/overview/<workflow>: use Overview with the workflow, filters, display=board, or run parameters.
• /workflows/overview/<workflow>/definition: use /workflows/definitions/<name>.
• Addresses with scope=concluded: these open Open runs, the opposite of what they saved, with no warning. Save them again with scope=closed.

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

A hold isn’t an error, so retrying doesn’t help. The document is waiting for the workflow. To continue, finish the work the current stage asks for. The message on the disabled action says what is holding it.

Canceling ends a run. It doesn’t delete the document or its history, and your reason is saved in the run’s history. A workflow can allow only some roles to cancel. If you don’t have one of those roles, you don’t see the cancel options. To cancel a run:

• Open the run card’s overflow menu and select Cancel workflow, or select Manage in the run’s detail panel.
• Enter a reason.
• Select Cancel workflow to confirm, or Keep workflow to leave it running.

A canceled run shows the status Aborted.

• Workflows: what a workflow is made of, and the words the rest of these pages use.
• Add Workflows to Sanity Studio: the setup a developer does before any of this appears.