> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt). # 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. > [!WARNING] > Early access > Workflows is in early access, built in public. Read [How early access works](https://www.sanity.io/docs/workflows/prerelease) before you rely on it. 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. ## Start a workflow on a 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. ## See where your work stands 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](https://www.sanity.io/docs/user-guides/content-releases). 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](https://www.sanity.io/docs/workflows/effects-and-runtimes): 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. ## Complete a task, edit fields, and fire an action 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](https://www.sanity.io/docs/workflows/fields). 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. ### Resolve a deleted or inaccessible document 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](https://www.sanity.io/docs/workflows/studio-user-guide) when the work is no longer needed. ## Workflows tool 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 **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. ### Board and run details 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 **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 **Definitions** at `/workflows/definitions` lists deployed workflows and their open-run counts. Open `/workflows/definitions/` 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. ### Update saved links Some saved Workflows tool addresses open **Overview** instead of the page they named. Replace bookmarks that use these addresses: - `/workflows/all-documents`, `/workflows/instance/`, and `/workflows/overview/`: use **Overview** with the `workflow`, `filters`, `display=board`, or `run` parameters. - `/workflows/overview//definition`: use `/workflows/definitions/`. - Addresses with `scope=concluded`: these open **Open runs**, the opposite of what they saved, with no warning. Save them again with `scope=closed`. ## Understand a held publish When a [workflow guard](https://www.sanity.io/docs/workflows/guards) 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. ## Cancel a workflow 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: 1. Open the run card’s overflow menu and select **Cancel workflow**, or select **Manage** in the run’s detail panel. 2. Enter a reason. 3. Select **Cancel workflow** to confirm, or **Keep workflow** to leave it running. A canceled run shows the status **Aborted**. ## Next steps - [Workflows](https://www.sanity.io/docs/workflows/introduction): what a workflow is made of, and the words the rest of these pages use. - [Add Workflows to Sanity Studio](https://www.sanity.io/docs/workflows/studio-plugin): the setup a developer does before any of this appears.