# Editorial approvals

Source: https://docs.qiick.io/externa/approvals

Optional **editorial approvals** for versioned collections: editor submits a draft → reviewer approves or rejects → publish (promote) only when approved.

> **Related**
> [Content versioning](https://docs.qiick.io/externa/content-versioning) · [Roles & permissions](https://docs.qiick.io/externa/roles-and-permissions) · [Outbound webhooks](https://docs.qiick.io/externa/webhooks)

## Enable

1. Turn on **Content versioning** on the collection.
2. Turn on **Approvals required** (same collection drawer). Approvals without versioning are rejected.

## States

```text
draft ──submit──► in_review ──approve──► approved ──Publish──► published (+ approval resets)
                    │
                    └──reject(+note)──► rejected ──(edit / resubmit)──► in_review
```

- Saving a draft while `in_review`, `approved`, or `rejected` **invalidates** approval and returns to `draft`.
- Discarding a draft resets approval state.
- Scheduled publish also requires `approved` when approvals are on.
- Editing an **approved** draft that still has `publish_at` set resets approval and flashes a warning. If the scheduler later cannot promote (approval missing or other promote error), the item stores `schedule_error` / `schedule_failed_at`, notifies editors/approvers, and emits webhook `item.publish_failed` ([core PR #303](https://github.com/qiick-io/externa-core/pull/303)) — [Content versioning](https://docs.qiick.io/externa/content-versioning#scheduled-publish-unpublish).

## Permissions

| Permission                | Who                                         |
| ------------------------- | ------------------------------------------- |
| `can-submit-collections`  | Submit draft for review                     |
| `can-approve-collections` | Approve or reject (note required on reject) |
| `can-edit-collections`    | Publish / discard / edit (unchanged)        |

Assign via **Roles & permissions**. Super Admin / Admin get both submit and approve after `permissions:sync` + role seed / upgrade.

## Review queue

On collections with approvals, the items list has an **In review** filter for the awaiting queue. Item form shows status badge + Submit / Approve / Reject actions.

## Webhooks

Reserved outbound events (same catalog as [Outbound webhooks](https://docs.qiick.io/externa/webhooks)):

| Type                  | When                                                               |
| --------------------- | ------------------------------------------------------------------ |
| `item.submitted`      | Draft submitted for review                                         |
| `item.approved`       | In-review item approved                                            |
| `item.rejected`       | In-review item rejected (`rejection_note` in payload)              |
| `item.publish_failed` | Scheduled promote failed after approval was reset or promote threw |

In-app notifications go to users with `can-approve-collections` on submit, and to the submitter on approve/reject.

## Out of scope

Multi-step BPM graphs, e-sign, and Slack/Telegram fan-out (see outbound notifiers) are separate.