> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sengol.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Review workflows

> Route agent intakes to the teams that must review them before approval.

A review workflow sends an agent intake to the teams that must look at it
before it is approved. Each team is a **responsibility**. A **review policy**
says which responsibilities an intake needs. A policy is optional. Until one
is published, an intake has no review steps and approval follows only the
approver count and the same-person rule ([Set who approves
intakes](https://docs.sengol.io/journeys/platform-operator.md#7-set-who-approves-intakes)).

## Who does what

| Task | Needs | Roles |
| - | - | - |
| Create responsibilities, add people, write and test a policy | `review:configure` | `cro`, `admin` |
| Publish a policy | `review:publish`, interactive sign-in, and not the author | `approver`, `admin` |
| Clear a review step | `sod:approve`, interactive sign-in, and a seat in the responsibility | `approver`, `cro`, `validator`, `admin` |

> [!WARNING]
>
> The author of a policy cannot publish it. One administrator can do
> everything except publish, so a second person with `review:publish` is
> needed.

## Set it up

**1. Create the responsibilities**

In the Console, open **Govern → Review workflows → Responsibilities**.
In **New responsibility**, enter an identifier (lowercase, for example
`privacy`), a label, the remit and the evidence reviewers expect, then
select **Create responsibility**.

![Review workflows Responsibilities tab showing the privacy responsibility with two members](https://mintcdn.com/sengol/WAzD6pTFOjHwDiMz/images/console-review-responsibilities.png?fit=max\&auto=format\&n=WAzD6pTFOjHwDiMz\&q=85\&s=9d8e6505ee72a7d195598fa4dfb85273)

Responsibilities, with a responsibility's members shown.

**2. Give each one people**

Select **Show members** on a responsibility. Add people by principal id,
bind a group with **Bind group**, or let a member delegate their seat for
up to 30 days. Do this before publishing. Nothing checks that a
responsibility has members, and a mandatory step with nobody in it cannot
be cleared. If that happens, add a member. The intake does not need to be
revised.

**3. Draft a policy**

Open **Routing**, select **Start a draft**, edit the JSON and select
**Create draft**. The next section has an example, and the [policy
reference](https://docs.sengol.io/reference/review-policy.md) has the full format.

![Review workflows Routing tab showing published version 1 and its policy JSON](https://mintcdn.com/sengol/WAzD6pTFOjHwDiMz/images/console-review-routing.png?fit=max\&auto=format\&n=WAzD6pTFOjHwDiMz\&q=85\&s=66a5124dc1d89709913d5c8899ac1739)

Routing: a published version and its JSON.

**4. Validate it**

Select the draft, then **Validate**. Problems are listed as `path — code:
        message`. A draft is never edited, so fix problems in a new draft.

**5. Test it**

On **Test & publish**, **Simulate routing** shows which steps a sample
intake would get. **Preview impact on open intakes** shows what the
version would change. Neither changes anything.

![Test and publish tab simulating a personal data intake, which gets the privacy-review step](https://mintcdn.com/sengol/WAzD6pTFOjHwDiMz/images/console-review-publish.png?fit=max\&auto=format\&n=WAzD6pTFOjHwDiMz\&q=85\&s=67ae7a0447fa8b1d4a382d402707024d)

Test & publish: the Personal data sample routes to the Privacy review.

**6. Publish it**

A different user with `review:publish` selects **Publish version N** on
**Test & publish**. It applies to new submissions only.

## Example

This policy adds a mandatory Privacy review to every intake that lists `pii`
as a data class. It needs one person at most tiers and two at `HIGH`. It
needs an active responsibility named `privacy` with members.

```json theme={null}
{
  "baseline_steps": ["final"],
  "steps": [
    {
      "id": "privacy-review",
      "type": "mandatory",
      "responsibility_id": "privacy",
      "required_by_tier": { "HIGH": 2 }
    },
    { "id": "final", "type": "final", "responsibility_id": null }
  ],
  "rules": [
    {
      "id": "pii-data",
      "when": { "fact": "data_classes", "op": "contains", "value": "pii" },
      "add_steps": ["privacy-review"],
      "explain": "Personal data needs a Privacy review"
    }
  ],
  "constraints": []
}
```

## Review an intake

When an intake was routed by a policy, its page shows a **Review progress**
card. A reviewer with a seat selects **Clear this step** on a mandatory step,
or adds a note. On a mandatory step a note is **Advice**, **Changes requested**
or **Refusal**. An advisory step takes **Advice** only. The approver
acknowledges any advice and then approves. The submitter never clears a
mandatory step, and the final approver needs no seat.

These review conditions refuse approval. Other conditions can too, such as an
unconfirmed requester.

| Message | Fix |
| - | - |
| `step_unsatisfied` | A mandatory step needs more people to clear it. |
| `step_refused` | A reviewer refused this revision. Reject the intake, or revise it to start a new revision. |
| `step_changes_requested` | Revise the intake. |
| `advice_unacknowledged` | Acknowledge the advice, then approve. |
| `step_blocked` | A step it depends on is not cleared yet. |
| `distinct_actors` | This person already cleared a step the policy says they cannot also approve. |

## Good to know

* An intake keeps the policy version that was published when it was submitted. To move it to a newer policy, withdraw it and submit again.
* An intake submitted before any policy was published never gets review steps.
* Revising an intake routes it again and makes earlier approvals and notes stop counting.
* Review workflows are not available when the appliance is in evidence-only mode.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.