> ## 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.

# Approval rounds

> Create and manage sequential approval rounds on tickets with configurable policies, threshold rules, approver management, and admin controls.

Approval rounds are the building blocks of ticket approvals. Each round defines a set of approvers and a policy that determines when the round is complete. Add a single round for simple approvals or chain multiple rounds for multi-stage workflows.

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

  ## Create approval rounds

  <Steps>
    <Step title="Open the ticket">
      Navigate to the ticket that needs approval.
    </Step>

    <Step title="Open the approval rounds section">
      Find the **Approvals** section in the ticket detail page. Click **Add round** to open the round editor.
    </Step>

    <Step title="Configure the round">
      For each round, set:

      * **Name**: A descriptive label (for example, "Manager approval" or "Security review")
      * **Policy**: Choose **Any can approve**, **All must approve**, or **Threshold**
      * **Threshold** (if using threshold policy): The number of approvers required
      * **Approvers**: Select 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> who can approve this round
    </Step>

    <Step title="Add more rounds (optional)">
      Click **Add round** again to add additional stages. Rounds run in the order you create them.
    </Step>

    <Step title="Save and start">
      Save your rounds. The first round activates immediately and approvers are notified.
    </Step>
  </Steps>

  <Info>
    You can add multiple rounds at once before saving. The round editor lets you configure all rounds in a single view.
  </Info>

  ***

  ## Edit approval rounds

  Edit rounds to change policies, add or remove approvers, or reorder stages.

  <Steps>
    <Step title="Open the round editor">
      Click the **Edit** button in the Approvals section to open the multi-round editor.
    </Step>

    <Step title="Make changes">
      Modify round names, policies, thresholds, or approver lists. You can also add new rounds or remove existing ones.
    </Step>

    <Step title="Save changes">
      Click **Save** to apply your changes. If you remove approvers from an active round, the policy is re-evaluated immediately.
    </Step>
  </Steps>

  <Warning>
    Removing approvers from an active round can trigger automatic completion. If the remaining approvers already satisfy the policy (for example, one approver already approved in an "any can approve" round), the round completes immediately.
  </Warning>

  ***

  ## Approve or decline

  When you are added as an approver, you receive notifications with action buttons.

  <AccordionGroup>
    <Accordion title="Approve" icon="check" defaultOpen>
      Click **Approve** from the ticket detail page or Slack DM. Your approval is recorded and the round policy is evaluated. If the policy is satisfied, the round completes and the next round activates.
    </Accordion>

    <Accordion title="Decline" icon="x">
      Click **Decline** and optionally provide a reason. Declining immediately completes the round with a declined status. The ticket's overall approval status changes to **Declined**.
    </Accordion>
  </AccordionGroup>

  ***

  ## Approval policies

  Choose the right policy for each round based on your requirements.

  | Policy               | How it works                                                  | Best for                                               |
  | -------------------- | ------------------------------------------------------------- | ------------------------------------------------------ |
  | **Any can approve**  | First approver to approve completes the round                 | Quick approvals where any authorized person can decide |
  | **All must approve** | Every approver must approve before the round completes        | Sensitive decisions requiring consensus                |
  | **Threshold**        | A specific number of approvals required (for example, 2 of 5) | Committee-style reviews with quorum requirements       |

  ***

  ## Multi-stage approvals

  Chain rounds for workflows that require multiple levels of approval.

  **Example: Software access request**

  | Round | Name             | Policy           | Approvers           |
  | ----- | ---------------- | ---------------- | ------------------- |
  | 1     | Manager approval | Any can approve  | Requester's manager |
  | 2     | Security review  | All must approve | Security team       |
  | 3     | IT provisioning  | Any can approve  | IT administrators   |

  Rounds activate in order. Round 2 only starts after Round 1 is approved. If any round is declined, the process stops and the ticket is marked as declined.

  ***

  ## Reset rounds

  Workspace admins can reset rounds when approvals need to be reconsidered.

  <AccordionGroup>
    <Accordion title="Reset a single round" icon="rotate-ccw" defaultOpen>
      Reset one round to restart it with the same or different configuration. The original round is archived and a new replacement round is created. You can change the policy and approvers during the reset.

      Existing approvers are re-notified and must approve again.
    </Accordion>

    <Accordion title="Reset all rounds" icon="rotate-ccw">
      Reset the entire approval process. All rounds are archived and recreated from scratch. The ticket's approval status returns to **In progress**.
    </Accordion>
  </AccordionGroup>

  ***

  ## Sidebar approver management

  The ticket sidebar provides a simplified view for managing approvers on the focused round (the currently active or most relevant round).

  * **Add approvers**: Search for users or groups in the sidebar Approvers field
  * **Remove approvers**: Click the remove button next to an approver's name
  * **Auto-creation**: If no rounds exist when you add approvers through the sidebar, a round is created automatically with the "Any can approve" policy

  <Info>
    The sidebar always shows the most relevant round: the active round if one exists, the most recently declined round, or the first pending round.
  </Info>
</View>

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

  Approval rounds are a linked list of approval stages on a ticket. Each round has a policy, a set of approvers, and a status. The system evaluates the policy after each approver action and advances through the chain automatically.

  ***

  ## Round data model

  | Field              | Type                                                | Description                                    |
  | ------------------ | --------------------------------------------------- | ---------------------------------------------- |
  | `name`             | String (nullable)                                   | Display name for the round                     |
  | `policy`           | ANY, ALL, THRESHOLD                                 | Determines completion criteria                 |
  | `status`           | PENDING, ACTIVE, APPROVED, DECLINED, RESET, SKIPPED | Current round state                            |
  | `threshold`        | Integer (nullable)                                  | Required approval count for THRESHOLD policy   |
  | `nextRoundId`      | String (nullable)                                   | Links to the next round in sequence            |
  | `resetFromRoundId` | String (nullable)                                   | Links to the round this replaced (after reset) |
  | `openedAt`         | DateTime (nullable)                                 | When the round was activated                   |
  | `closedAt`         | DateTime (nullable)                                 | When the round completed                       |

  ***

  ## Approver data model

  | Field         | Type                        | Description                |
  | ------------- | --------------------------- | -------------------------- |
  | `userId`      | String                      | The approver's user ID     |
  | `status`      | PENDING, APPROVED, DECLINED | Approver's decision status |
  | `reason`      | String (nullable)           | Decline reason             |
  | `completedAt` | DateTime (nullable)         | When the decision was made |
  | `deletedAt`   | DateTime (nullable)         | Soft delete timestamp      |

  ***

  ## Policy evaluation logic

  Policy evaluation happens after each approver action (approve, decline, or remove):

  **ANY policy:**

  * At least one APPROVED approver → round APPROVED
  * Any DECLINED approver → round DECLINED

  **ALL policy:**

  * All approvers APPROVED → round APPROVED
  * Any DECLINED approver → round DECLINED

  **THRESHOLD policy:**

  * N or more APPROVED approvers → round APPROVED
  * Impossible to reach N (remaining pending + already approved \< threshold) → round DECLINED

  After round completion:

  * If `nextRound` exists → activate it (set status to ACTIVE, set `openedAt`)
  * If no next round → set ticket `approvalStatus` to APPROVED or DECLINED

  ***

  ## Sidebar focus logic

  The sidebar shows the "focused" round, determined by priority:

  1. Active round (status = ACTIVE)
  2. Most recently declined round
  3. Last round if all are approved
  4. First pending round

  When approvers are added via the sidebar with no existing rounds, the system auto-creates a round with ANY policy.

  ***

  ## Reset behavior

  **Single round reset:**

  1. Original round status set to RESET
  2. New round created with `resetFromRoundId` pointing to the original
  3. New round is inserted into the linked list at the same position
  4. New round is set to ACTIVE
  5. Carried-over approvers are re-notified

  **Full approval reset:**

  1. All non-reset rounds are archived (status = RESET)
  2. New rounds created matching the original chain
  3. First round activated, ticket status set to IN\_PROGRESS

  ***

  ## Workflow integration

  The "Add Approvers" workflow action creates a round at the **head** of the linked list:

  * If rounds already exist: new round becomes the first round, ticket status resets to IN\_PROGRESS
  * If no rounds: creates round and kicks off approval
  * Supports assignment strategies: All (all users), Round Robin (one user), Auto (system bot auto-approves)

  The "Wait for Approval" action pauses until the ticket's approval status changes from IN\_PROGRESS or the configured timeout (default 3 days) expires. The action branches into three outcome paths — On Approved, On Declined, and On Timeout — so workflows can escalate or auto-close stalled approvals.

  ***

  ## Constraints and gotchas

  * Only one round can be ACTIVE at a time.
  * Rounds require at least one approver.
  * Removing the last approver from a round deletes the round (via sidebar).
  * Removing approvers triggers immediate policy re-evaluation, which can auto-complete the round.
  * Reset preserves audit history. Reset rounds (status = RESET) are hidden from the UI but remain in the database.
  * The linked-list structure means round ordering is stored via `nextRoundId` references, not an `order` column.
  * `sourceTemplateRoundId` tracks which template round generated each ticket round (for lineage).
</View>