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

# Approvals

> Require structured approval on tickets before work proceeds, with flexible policies, multi-stage rounds, and notifications across web and Slack.

Approvals let you gate ticket progress behind one or more approval decisions. Add approvers to a ticket, choose a policy that determines when the approval is satisfied, and track the outcome across web and Slack.

Approvals use a rounds-based system where each round has its own approvers and policy. Rounds run in sequence, so the next round only activates after the previous one completes. A single round covers simple use cases, while multiple rounds support multi-stage workflows like manager approval followed by security review.

<View title="Human" icon="user">
  ***

  ## How approvals work

  When you add approvers to a ticket, Ravenna creates an approval round and notifies each approver. The round stays active until the policy is satisfied or an approver declines.

  <AccordionGroup>
    <Accordion title="Approval policies" icon="scale" defaultOpen>
      Each round uses one of these policies to determine when it completes:

      * **Any can approve**: The round is approved as soon as any single approver approves. If any approver declines, the round is declined.
      * **All must approve**: Every approver must approve. If any approver declines, the round is declined.
      * **Threshold**: A specific number of approvers must approve (for example, 2 out of 5). The round is declined if it becomes mathematically impossible to reach the threshold.
    </Accordion>

    <Accordion title="Ticket approval status" icon="circle-check">
      The ticket itself tracks an overall approval status based on the progress of its rounds:

      * **In progress**: At least one round is active or pending
      * **Approved**: All rounds completed successfully
      * **Declined**: A round was declined by an approver
      * **Force approved**: An admin approved the ticket, bypassing remaining rounds
    </Accordion>

    <Accordion title="Round lifecycle" icon="arrow-right">
      Each round moves through these states:

      1. **Not started**: The round is created but waiting for a previous round to complete
      2. **In progress**: The round is active and awaiting approver decisions
      3. **Approved**: The round's policy was satisfied
      4. **Declined**: An approver declined the round

      When a round completes, the next round in the sequence automatically activates. When the final round is approved, the ticket's approval status changes to **Approved**.
    </Accordion>
  </AccordionGroup>

  ***

  ## Where to approve and decline

  Approvers can act on approval requests from multiple surfaces. When added as an approver, you receive notifications with action buttons.

  <AccordionGroup>
    <Accordion title="Web app" icon="globe" defaultOpen>
      Open the ticket detail page and use the **Approve** or **Decline** buttons in the approval rounds section. When declining, you can provide an optional reason.
    </Accordion>

    <Accordion title="Microsoft Teams" icon="https://mintcdn.com/ravenna/p_IKxz6RMCVu_6xg/icons/microsoft-teams.svg?fit=max&auto=format&n=p_IKxz6RMCVu_6xg&q=85&s=4a0fc016f40e81d619ccb663897b87f6" width="36" height="38" data-path="icons/microsoft-teams.svg">
      Approval requests are delivered as Adaptive Cards in the approver's Microsoft Teams chat. The card includes an **Approve** and **Decline** action. Approval updates are also posted into the ticket's connected Teams channel thread.

      <Callout icon="link" color="#6B7280">
        Learn more about [Microsoft Teams approvals](/integrations/microsoft-teams/approvals)
      </Callout>
    </Accordion>

    <Accordion title="Slack" icon="slack">
      Approvers receive a DM with the ticket details and approval buttons. You can approve or decline directly from the message. If your workspace requires biometric verification, the buttons redirect you to the Admin to verify your identity before completing the action.

      Approval updates are also posted to the ticket's Slack thread so the team stays informed.
    </Accordion>
  </AccordionGroup>

  ***

  ## Adding approvers

  Add approvers to tickets from several places:

  * **Ticket sidebar**: Use the Approvers field to search and add users or <Tooltip headline="User groups" tip="Collections of users for collaboration and access management" cta="Learn about user groups" href="/documentation/platform/groups">user groups</Tooltip>
  * **Approvals section**: Click **Add round** to create a new round with approvers and a policy
  * **<Tooltip headline="Workflows" tip="Automated actions triggered by ticket events" cta="Learn about workflows" href="/documentation/automate/workflows/overview">Workflows</Tooltip>**: Use the **Add Approvers** action to assign approvers automatically based on conditions
  * **<Tooltip headline="Approval templates" tip="Reusable multi-round approval configurations" cta="Learn about templates" href="/documentation/tickets/approvals/templates">Approval templates</Tooltip>**: Import a pre-configured set of rounds and approvers

  <Info>
    When you select a user group as an approver, the group is automatically expanded into individual users when saved. Only the individual users are stored as approvers on the round.
  </Info>

  ***

  ## Admin actions

  Workspace admins have additional controls for managing approvals on tickets.

  <AccordionGroup>
    <Accordion title="Force approve" icon="shield-check" defaultOpen>
      Approve a ticket immediately, bypassing any remaining rounds. All pending and active rounds are marked as approved. Use this when a ticket needs to proceed urgently regardless of the normal approval process.
    </Accordion>

    <Accordion title="Reset approval" icon="rotate-ccw">
      Restart the approval process. Existing rounds are archived and new rounds are created. Approvers are re-notified and must approve again. You can change the policy or approvers during a reset.

      You can reset individual rounds or the entire approval process.
    </Accordion>
  </AccordionGroup>

  ***

  ## Workspace settings

  Configure approval behavior for your workspace in **Settings** > **Workspace**.

  <AccordionGroup>
    <Accordion title="Admin approvals" icon="user-check" defaultOpen>
      Allow workspace admins to approve tickets on behalf of other users. Enabled by default.
    </Accordion>

    <Accordion title="Biometric approval verification" icon="fingerprint">
      Require approvers to verify their identity with a passkey (Touch ID, Face ID, or security key) before approving or declining. When enabled, Slack approval buttons redirect to the Admin for verification.

      Approvers register passkeys in **Settings** > **Account** > **Passkeys**.
    </Accordion>
  </AccordionGroup>

  ***

  ## Approval reminders

  Automatically nudge approvers who have not yet responded by configuring an organization-wide reminder cadence. When enabled, Ravenna posts a public ticket message that @mentions every pending approver on each interval until the round resolves or the maximum reminder count is reached.

  <Callout icon="link" color="#6B7280">
    Learn how to configure cadence, business-hours behavior, and escalation in [reminders](/documentation/tickets/reminders).
  </Callout>

  ***

  ## Approvals in workflows

  Use workflow actions to automate approval processes:

  * **Add Approvers**: Adds approvers to a ticket and creates an approval round. Supports assignment strategies (All, Round Robin, Auto).
  * **Wait for Approval**: Pauses the workflow until the approval round completes or the configured timeout expires (default 3 days). Continues down the On Approved, On Declined, or On Timeout path.
  * **Ticket Approval trigger**: Fires when a ticket's approval status changes, letting you trigger follow-up actions after approval or handle declined requests.

  <Callout icon="link" color="#6B7280">
    Learn more about [approval workflow actions](/documentation/automate/workflows/triggers-actions)
  </Callout>
</View>

<View title="Agent" icon="bot">
  ## Mental model

  Approvals are a structured gate on ticket progress. A ticket can have zero or more approval rounds, each with its own policy and set of approvers. Rounds execute sequentially in a linked-list order. The ticket tracks an overall approval status derived from the state of its rounds.

  Key entities:

  | Entity                     | Purpose                                                                       | Cardinality               |
  | -------------------------- | ----------------------------------------------------------------------------- | ------------------------- |
  | **Ticket approval status** | Overall ticket-level status (In Progress, Approved, Declined, Force Approved) | One per ticket (nullable) |
  | **Approval round**         | A single stage with a policy and approvers                                    | Zero or many per ticket   |
  | **Round approver**         | A user assigned to approve within a round                                     | One or many per round     |

  ***

  ## Approval policies

  | Policy        | Approved when                      | Declined when                   |
  | ------------- | ---------------------------------- | ------------------------------- |
  | **ANY**       | Any single approver approves       | Any approver declines           |
  | **ALL**       | Every approver approves            | Any approver declines           |
  | **THRESHOLD** | N approvers approve (configurable) | Impossible to reach N approvals |

  ***

  ## Round status flow

  ```text theme={"system"}
  PENDING → ACTIVE → APPROVED → (next round activates or ticket approved)
                   → DECLINED → (ticket declined)
                   → RESET    → (new replacement round created)
  ```

  * **PENDING**: Waiting for a previous round to complete
  * **ACTIVE**: Awaiting approver decisions
  * **APPROVED**: Policy satisfied
  * **DECLINED**: Approver declined
  * **RESET**: Admin reset the round (archived, replaced by a new round)
  * **SKIPPED**: Round was bypassed

  ***

  ## Ticket approval status

  | Status              | Meaning                        |
  | ------------------- | ------------------------------ |
  | **IN\_PROGRESS**    | Active or pending rounds exist |
  | **APPROVED**        | All rounds approved            |
  | **DECLINED**        | A round was declined           |
  | **FORCE\_APPROVED** | Admin bypassed all rounds      |

  ***

  ## Round sequencing

  Rounds form a singly-linked list via `nextRoundId`. The first round (head of list) has no previous round. When a round is approved, the system activates `nextRound` automatically. When the final round is approved, the ticket's `approvalStatus` is set to APPROVED.

  ***

  ## Adding approvers

  Approvers can be added through:

  * Ticket sidebar (creates/updates the focused round)
  * Approval rounds UI (explicit round management)
  * Workflow "Add Approvers" action (creates round at head of chain)
  * Approval templates (creates full round chain from template)
  * Forms (adds approvers to active round or creates new one)

  When user groups are selected, they are expanded to individual users server-side. Only concrete users are stored as round approvers.

  ***

  ## Admin operations

  * **Force approve**: Sets all non-approved rounds to APPROVED, sets ticket status to FORCE\_APPROVED. Requires workspace admin.
  * **Reset round**: Archives the round (status = RESET), creates a new replacement round with `resetFromRoundId` link. Can change policy and approvers.
  * **Reset approval**: Resets all rounds, restarts the process from the beginning.

  ***

  ## Notifications

  Approvers are notified through:

  * **Slack DM**: Always sent, bypasses notification preferences. Includes approval action buttons.
  * **Microsoft Teams Adaptive Card**: Always delivered to the approver's chat, bypasses notification preferences. Includes **Approve** and **Decline** actions.
  * **Slack thread**: Batched @mentions posted to the ticket thread (5-second batching window).
  * **Microsoft Teams channel thread**: Approval updates posted into the ticket's connected Teams channel.
  * **Email**: Configurable notification for pending approvals.

  Events dispatched: `APPROVAL_ROUND_APPROVER_ADDED`, `APPROVAL_ROUND_APPROVER_REMOVED`, `APPROVAL_ROUND_APPROVER_APPROVED`, `APPROVAL_ROUND_APPROVER_DECLINED`, `TICKET_APPROVAL_COMPLETED`, `TICKET_APPROVAL_RESET`, `APPROVAL_ROUND_STARTED`.

  ***

  ## Constraints and gotchas

  * A ticket can have multiple rounds, but only one round is ACTIVE at a time.
  * Removing approvers from an active round triggers immediate policy re-evaluation. If remaining approvers already satisfy the policy, the round auto-completes.
  * User groups are expanded to individual users at save time, not at evaluation time.
  * Force approve requires workspace admin privileges.
  * Reset preserves history by archiving the old round (RESET status) rather than deleting it.
  * Biometric verification (when enabled) forces Slack approval buttons to redirect to the Admin.
  * Approval DMs in Slack always send regardless of user notification preferences.
</View>