# Case Queue

> **Beta** — This feature is currently in beta and may change.

### Introduction

Case Queue is a queue-based work item system for assignments. It lets you feed individual work items — called **cases** — into a queue, where assignments automatically pick them up, process them, and report results.

This is useful when you have a stream of tasks that need to be handled one at a time (or in parallel), such as processing incoming requests, handling tickets, or working through a batch of items.

***

### Key Concepts

#### Queue

A queue is a container that holds cases waiting to be processed. Each team has one default queue, and cases flow through it to be claimed by assignments.

#### Case

A case is an individual work item with a title and associated data. Think of it as a task card — it carries the information an assignment needs to do its work.

#### Case Statuses

| Status          | Meaning                                                          |
| --------------- | ---------------------------------------------------------------- |
| **Pending**     | Waiting in the queue to be picked up                             |
| **In Progress** | An assignment has claimed the case and is working on it          |
| **Needs Input** | The assignment is waiting for a human response before continuing |
| **Postponed**   | Waiting until a scheduled time before being picked up again      |
| **Completed**   | The assignment finished processing the case successfully         |
| **Failed**      | The assignment could not process the case                        |

#### Agent Triggers

An agent trigger connects an assignment to a queue. When a new case arrives, the trigger automatically dispatches the assignment to claim and process it — no manual intervention needed.

***

### How It Works

1. **Cases are added to a queue** — either by another assignment or by an external system via the API.
2. **An assignment with a case trigger** automatically claims the next pending case.
3. **The assignment processes the case** using the case data as input.
4. **The case is resolved** — the assignment marks the case as completed or postponed, requests a handover, or the case is marked as failed if the Job ends without any of these actions.

#### Status Transitions

Case statuses follow a specific lifecycle. Understanding these transitions helps you write better SOPs and troubleshoot processing issues.

* **Pending → In Progress**: When an assignment picks up a case from the queue, the case moves to In Progress. This happens automatically through the case trigger — the assignment claims the next available case and begins working on it.
* **In Progress → Needs Input**: If the assignment requires human input while processing (via the Human-in-the-Loop feature), the case shows as Needs Input until the human responds.
* **In Progress → Completed**: The assignment explicitly marks the case as completed after it finishes processing successfully. Your SOP should instruct the assignment on when and how to mark a case as done.
* **In Progress → Failed**: If the assignment's Job ends without completing, postponing, or handing over the case, the system automatically marks it as Failed. This means your SOP should always instruct the assignment to explicitly resolve each case — otherwise it will be treated as a failure.
* **In Progress → Postponed**: The assignment can postpone a case to delay processing until a later time. This is useful when the assignment determines that a case needs to wait — for example, waiting for an external event, a cooling-off period, or a specific business hour. The assignment specifies when the case should be retried, either as a specific time or a relative duration (e.g., "2 hours", "1 day"). When the postponed time arrives, the case is automatically dispatched for processing again.

#### Writing SOPs for Case Processing

The assignment decides how to handle a case based on your SOP instructions. To get reliable results, your SOP should clearly tell the assignment:

* **When to complete a case** — define what "done" looks like. For example: "After sending the reply email, mark the case as completed."
* **When to fail a case** — define what counts as unprocessable. For example: "If the customer account cannot be found, update the case with the reason and mark it as failed." Note that if the Job ends without the assignment completing, postponing, or handing over the case, it is automatically marked as Failed — but explicitly failing with a reason is preferred so you can review what went wrong.
* **When to postpone a case** — define conditions for delaying. For example: "If the report data is not yet available, postpone the case for 2 hours."

Without clear instructions, the assignment may not resolve cases properly, and cases will be implicitly marked as Failed.

***

### Setting Up Case Queue in the Builder

Case Queue is configured directly from the assignment builder. A dedicated **Case Queue** section appears in the builder header, separate from Connections, where you link the assignment to the queues it should read from or write to.

To connect an assignment to one or more queues:

1. **Open your assignment** in the builder.
2. In the **Case Queue** section of the builder header, click the **plus button**. This opens the **Case Queue setup dialog**, where you can link queues to the assignment.
3. In the dialog, choose how the assignment should interact with each queue:
   * **Processes Cases (Consumer)** — the assignment picks up and processes cases from the selected queue.
   * **Adds Cases (Producer)** — the assignment adds new cases to the selected queue.

A single assignment can act as both a producer and a consumer if needed — just link the relevant queues under each role in the dialog.

### Enabling the Case Trigger

Linking a queue as a consumer lets the assignment access that queue, but it will not start processing cases until the **case trigger** is enabled. The case trigger lives in the assignment's **Schedule & Trigger** tab.

To enable the case trigger:

1. Open the assignment's **Schedule & Trigger** tab.
2. **Enable the case trigger.**
3. **Set the concurrency** — this controls how many cases the assignment can process at the same time.

Once the trigger is enabled, the assignment will start claiming and processing cases as they arrive in the linked queue.

***

### Producer and Consumer Pattern

A common pattern is to have one assignment create cases and another process them:

* **Producer assignment**: Runs on a schedule or trigger, identifies work items, and adds them as cases to the queue.
* **Consumer assignment**: Has a case trigger enabled and automatically picks up and processes each case.

This separation keeps your workflows modular — the producer focuses on identifying work, while the consumer focuses on doing it.

***

### Case Labels

Cases can be tagged with labels to organize and categorize your work. Labels appear as **Key: Value** pills in the case detail header, making it easy to see how a case has been classified at a glance.

Labels are scoped to the queue — when adding a label, an autocomplete popover shows labels already used in that queue, making it easy to apply consistent classifications across cases.

#### Managing Labels

* **Assign a label** — Open the case detail and click **Add label**. Select an existing label from the searchable list, or create a new one by entering a key and value.
* **Remove a label** — Click the × on a label pill to remove it from the case.
* **Rename a label** — Click the label text to enter inline edit mode. Update the key or value and press Enter to save, or Escape to cancel.

Assignments can also assign labels automatically using the `assign_labels` tool in their SOP. This lets cases be categorized as part of automated processing — for example, tagging a case with `Priority: High` or `Type: Escalation` before completing or handing it over.

***

### Retrying Cases

You can manually retry cases from the **Cases** page. Cases in Completed or Failed status can be retried, which resets them to Pending so they are picked up and processed again. This is useful when a case failed due to a temporary issue or when you want to reprocess a case after updating your assignment's SOP.

***

### Human-in-the-Loop with Cases

Cases work with the Human-in-the-Loop feature. If a consumer assignment needs human input while processing a case, it will pause and send a notification to the Activity Inbox. The case shows as **Needs Input** until the human responds and the assignment completes its work.

***

### Viewing Cases

You can monitor your queue from the **Cases** page in your team space:

* **Filter by status** — Show only cases in a specific status: Pending, In Progress, Needs Input, Postponed, Completed, or Failed.
* **Filter by labels** — Click the **Filters** button to open the filter dropdown and select one or more label values. Only cases carrying all selected labels are shown. Active filters appear as chips above the table; click the × on any chip to remove it.
* **Filter by date** — Narrow the list to cases created within a specific date range.
* **Search cases** by title keyword to find specific items in a large queue.
* **Sort cases** by date created, last updated, or postponed time — newest first by default.
* **Browse pages** of results when your queue has many cases (20 per page by default, up to 100).
* **View case details** including title, data, and processing history.
* **Track queue stats** to understand throughput and failure rates.

Filter state is reflected in the page URL, so you can copy and share a filtered view with teammates.

Assignments that list cases via the `list_cases` tool can also filter by label values and a created date range, making it easier to process only a specific subset of cases.

***

### Case Handover

An assignment can hand a case off to another assignment during processing. When the assignment determines that a different specialist should handle the case, it requests a handover instead of completing or failing the case. The case is released and routed to the target assignment, which picks it up and continues processing.

This is useful for triage workflows where a general assignment routes cases to specialists, or for escalation paths where routine cases are handled by one assignment and complex ones are escalated to another. The case timeline in the case details view shows which assignment handled each stage.

For setup instructions and setup details, see [Assignment Handover](https://docs.duvo.ai/assignment-features/assignment-handover).

***

### Key Takeaway

Case Queue gives your assignments a structured way to receive and process work items. Pair it with agent triggers for fully automated processing, or use the producer-consumer pattern to build modular, scalable workflows.