Case Queue

Documentation Index

Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

Introduction

​

Key Concepts

​

Queue

​

Case

​

Case Statuses

​

Agent Triggers

​

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

• 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

• 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.”

​

Setting Up Case Queue in the Builder

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.
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.
   If your team has more than 20 queues, a search box appears at the top of the dialog so you can filter by name.
4. On a live revision, after selecting a consumer queue, trigger controls appear inside the dialog. You can enable the case trigger and set concurrency here alongside your queue selection. Changes are saved together when you click Save.

​

Enabling the Case Trigger

1. Open the Case Queue Setup dialog from the builder header.
2. Select a queue under Processes Cases (Consumer).
3. Enable Runs on new cases to start automatic processing.
4. Optionally enable Process cases one at a time to restrict the assignment to processing one case at a time instead of in parallel.
5. Click Save — queue setup and trigger settings are saved together.

duvo agents case-triggers update <agent-id> <trigger-id> --enable
duvo agents case-triggers update <agent-id> <trigger-id> --disable

​

Producer and Consumer Pattern

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

​

Case Labels

​

Managing Labels

• Assign a label — Open the case detail and click the attributes area. Select an existing attribute and one of its values to apply a label. To create a new label type, enter a new attribute name to add it as a draft, then add values to it — the first saved value promotes the attribute from draft to active.
• 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.

​

Retrying and Updating Cases

• Retry — Cases in Completed, Failed, In Progress, or Needs Input status can be retried. This resets them to Pending — any active Job is stopped first — so they are picked up and processed again. This is useful when a case failed due to a temporary issue, when you want to reprocess a case after updating your assignment’s SOP, or when you need to restart a Job that is stuck or waiting for input.
• Mark as Completed — Manually mark any non-completed case as Completed. Useful when a case was resolved outside the assignment workflow.
• Mark as Failed — Manually mark any non-failed case as Failed. Use this to close out cases that are no longer relevant or cannot be processed.

​

Delegating Cases to Specific Assignments

​

Delegating a single case

​

Delegating multiple cases

​

Human-in-the-Loop with Cases

​

Organizing Queues

​

Creating folders

​

Moving queues into folders

​

Queue Statistics

​

Viewing Cases

• Label columns — Each label group appears as its own column in the cases table, showing the assigned value as a colored chip for every case that has it. This lets you scan and compare label values across cases at a glance without opening each one.
• 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.

​

Case Handover

​

Managing Queues and Cases via API

​

Queue operations

• List queues — retrieve all queues for your team
• Create a queue — provision a new queue with a name and description
• Get a queue — fetch details for a specific queue
• Update a queue — rename or update a queue
• Delete a queue — remove a queue

​

Creating cases via API

{
  "case": {
    "title": "Invoice #12345",
    "data": { "invoice_id": "12345", "amount": 1500 }
  }
}

{
  "cases": [
    { "title": "Invoice #12345", "data": { "invoice_id": "12345" } },
    { "title": "Invoice #12346", "data": { "invoice_id": "12346" } }
  ]
}

​

Key Takeaway