# Introduction to Maestro Case

> | | Maestro Case | Maestro BPMN |
|---|---|---|
| Content applies to | ✅ | ❌ |

| | Maestro Case | Maestro BPMN |
|---|---|---|
| Content applies to | ✅ | ❌ |

## Overview

**Maestro Case** orchestrates long-lived, goal-driven work about a specific situation — a case. A case holds data, rules, tasks, and history to drive an auditable outcome such as a refund, a claim decision, or an investigation closure. Where Maestro BPMN excels at structured, sequential orchestration, Maestro Case addresses scenarios that are exception-heavy, non-linear, and dependent on human and AI agent judgment at key decision points.

This document **introduces Maestro Case** as a distinct capability in Maestro, walks through the **business use cases** it solves and when to choose it over Maestro BPMN, gives you a tour of the **toolset** you will work in, and lays out the **fundamental concepts** you need to understand before building your first agentic case.

**Audience:** Beginner to Intermediate — solution architects, business analysts, and developers evaluating or starting with Maestro Case.

## Why case management

Traditional process automation works best when the flow of work is predictable and repeatable. However, many business scenarios are not like this. They may span days or weeks, involve multiple teams, and require decisions that cannot be fully automated. In these situations, **exceptions are not rare — they are expected**.

Case management addresses this challenge by providing structure without rigidity. It allows automation and AI to handle routine or repeatable work, while enabling humans to step in when judgment or policy decisions are required.

### Pain points that case management solves

| Pain Point | How Case Management Addresses It |
|---|---|
| No persistent case construct or lifecycle tracking |  Introduces a **case entity** **[Coming Soon]**  with full lifecycle, state, and history |
| No native stage modeling | Adds a **visual stage canvas** to define sequential stages and transitions |
| No design-time transition or targeted re-entry | Enables **rule-based stage transitions and re-entry** to the exact task within a previous stage |
| Limited SLA and escalation control | Supports **SLA tracking at case, stage and task levels**, with escalation rules and pause/resume |
| No unified experience for case workers and managers | Delivers **Case App** for collaboration, task management, and visibility |
| No flexibility for ad-hoc work | Allows **runtime ad-hoc task creation** for exceptions or additional reviews |

## When to use case management

Case management is most effective when work **cannot be fully defined upfront**. These scenarios often involve multiple stages, frequent decision points, and collaboration between different user groups or systems. Progress depends not just on completing tasks, but on evaluating outcomes and deciding what should happen next.

## Business scenarios

| Scenario | Why Case Management |
|---|---|
| **Insurance claims** | Long-running, multi-party (claimant, adjuster, inspector), frequent exceptions (missing documents, disputes), SLA-driven |
| **Disputes and chargebacks** | Back-and-forth between parties, evidence gathering, escalation paths, non-linear progression |
| **Loan origination and underwriting** | Multiple review stages (credit, compliance, underwriting), conditional paths based on risk scores, regulatory requirements |
| **KYC/AML remediation** | Document collection across stages, regulatory decision points, audit trail requirements |
| **Customer escalations and complaints** | Tiered resolution, re-entry when a fix does not hold, SLA commitments, multi-team handoffs |
| **Order fulfillment exceptions** | Backorders, partial shipments, returns — multi-system coordination with SLA tracking |
| **Public sector investigations and referrals** | Ad-hoc approvals, cross-department coordination, policy-dependent routing |
| **Vendor onboarding** | Multi-stage vetting (legal, compliance, finance), conditional stages based on vendor type, document collection |

### Case management adds value when

- Work is **long-running** — spanning hours, days, or weeks rather than seconds.
- The process is **exception-heavy** — the next step depends on what just happened, and no single flowchart captures every path.
- Multiple **roles and systems** are involved — case workers, managers, AI agents, and external integrations all contribute.
- **SLA tracking and escalation** are critical — deadlines matter, and breaches must trigger specific actions.
- **Audit trails** are required — every decision, data change, and transition must be recorded.
- **Re-entry and rework loops** are common — cases frequently return to earlier stages for corrections or additional investigation.

### Case management is not required when

Not every process needs case management. If a process is short-lived, predictable, and follows the same sequence every time, a Maestro BPMN is often simpler and more efficient.

:::note
**Quick test:** If the next step depends on what just happened and no single flowchart can capture every path, consider case management. If the process follows the same path every time, use Maestro BPMN.
:::

### Shared foundations

Both project types reuse the same UiPath Platform services and task types:

- **RPA workflows** for UI automation in legacy systems.
- **API workflows and integrations** for system-to-system operations.
- **AI Agents** (UiPath or external) for non-deterministic tasks.
- **Human tasks via Action apps** for forms, approvals, and reviews.
- **Data Fabric** for business data management and data connectivity.
- **Studio Web** as the design environment.

### Key differences

| Dimension | Maestro BPMN | Maestro Case |
|---|---|---|
| **Work structure** | Defined sequence of steps modeled in BPMN notation | Named stages with rule-based transitions; the runtime path is determined dynamically |
| **Lifecycle** | Typically short- to medium-lived; follows a predetermined flow | Long-lived and goal-driven; evolves as new information becomes available |
| **Non-linear flow** | Possible through BPMN gateways and loops, but complex to model for highly variable scenarios | Built-in support for re-entry, secondary stages, skip rules, and ad-hoc tasks |
| **Data model** | Process variables scoped to the instance | Case variables scoped to the instance + Persistent **case entity** **[Coming Soon]**  — a central, typed business record that all stages, tasks, and conditions read from and write to |
| **SLAs and escalations** | Not natively modeled at the process level | First-class constructs at both **case level** and **stage level**, with at-risk and breach escalation rules |
| **User experience** | Monitored via the Maestro Monitoring tab for operators | Dedicated **Case App** for business users (case list, detail view, task inbox) and **Case Instance Management** for operators |
| **Role-based access** | Standard platform permissions | **Stage-aware personas** — define who can view and act within each stage |
| **Ad-hoc work** | Not supported; all steps are defined at design time | Supported — the Case Manager or a human user can create tasks at runtime |

A case can invoke a Maestro BPMN as one of its task types, and a Maestro BPMN can invoke a case as one of its task types — making the two project types complementary rather than competing. Use Maestro BPMN for well-defined sub-processes and Maestro Case as the outer orchestration layer when the overall flow is dynamic.

## Agentic-first by design

Case management is the right shape for exception-heavy, long-running work — but on its own, it still relies on human knowledge workers to make most routing and judgment calls. Maestro Case is **agentic-first** and **AI-native**: AI agents are first-class participants in the case and operate at two distinct levels:

- **As task workers within stages** — categorizing data, flagging anomalies, extracting fields from documents, drafting responses, verifying policies. Each agent runs inside a task, reads what it needs from the Case Entity **[Coming Soon]** , does its work, and writes its results back.
- **As the orchestrator of the case itself** — the **Case Manager agent** drives the case from creation to closure, making decisions at both the stage and task level: which stage to activate next, which tasks to run within that stage, when a task or stage is complete or should exit early, and when to escalate. It works alongside deterministic rules where they exist, and reasons over case data and policies where they don't.

This collapses the traditional bottleneck of relying solely on human knowledge workers to make routing decisions, handle exceptions, and push cases forward. Humans step in when policy, judgment, or accountability requires it — not because the case cannot move without them.

## Maestro Case toolset

Maestro Case spans the end-to-end case lifecycle through three complementary surfaces:

![Maestro end-to-end case lifecycle diagram](https://dev-assets.cms.uipath.com/assets/images/maestro/lifecycle-diag_8a63dad7_image-4817b067.png)

### Case plan designer (Studio Web)

**Who it is for:** Automation developers and business architects.

Use it to build or update a case plan — stages, transitions, SLAs, escalations, and stage-level access. Attach implementations to tasks (Human, RPA, API, AI Agent, Agentic Process, Child Case). Map inputs and outputs and set re-entry behavior. The output is a versioned case plan ready to **publish and deploy**.

### Case instance management (Maestro)

**Who it is for:** Process operators, incident managers, and process owners.

Use it to operate running cases with lifecycle controls (**Pause**, **Resume**, **Cancel**, **Migrate**) and full audit. Resolve incidents by retrying failed tasks or migrating instances to newer case plan versions. Use live insights, heatmaps, and **Process Mining** to spot bottlenecks and feed improvements back to design.

### Case app (Maestro)

**Who it is for:** Case workers and case managers.

Use it to view all cases, case details (timeline, case data, human tasks), and take quick actions such as **Complete** and **Reopen**. The Case App is an opinionated, case-centric workspace — lists, details, tasks, and SLA views. Human task forms continue to be built with **Action apps** and referenced by case tasks.

The Case App comes in two options:

| Option | Description | When to use |
|---|---|---|
| **Out-of-the-box Case App** | A pre-built, no-code case workspace that ships with Maestro Case. Lists, detail views, task inbox, and SLA views are configured automatically from your case plan and entity. | The default — use it for rapid case operations without writing any code. |
| **Custom coded Case App** | A bespoke case app you build using the **pro-code TypeScript SDK**. Lets you author custom views, layouts, and workflows on top of the same case runtime. | When you need a UI beyond what the out-of-the-box app exposes — branded workspaces, custom dashboards, or domain-specific case experiences. |

:::note
The Case App is distinct from UiPath Apps. The Case App is purpose-built for case operations. UiPath Apps is a general-purpose low-code builder for fully custom or composite business apps. Use the Case App for rapid case operations; use UiPath Apps when you need a bespoke UI beyond case operations.
:::

## Core concepts

Understanding the following concepts is essential before designing an Agentic case.

### Case and case key

A **case** represents a real-world business situation that needs to be resolved — a claim, a dispute, an investigation. Unlike a traditional process instance, a case evolves over time as new information becomes available and decisions are made.

Each case is uniquely identified by a **case key**:

| Key Type | Description | Example |
|---|---|---|
| **System key** | Auto-generated by Maestro on case creation | `HC-1234`, `CLM-00891` |
| **External (customer-defined) key** | An upstream ID passed at creation so the same real-world case is recognized across tools | CRM case number, policy number, ERP order ID |

Use external keys when the case originates in another system (CRM, ERP, ticketing tool) so that humans and integrations can correlate the case across tools without maintaining a separate mapping table.

### Case entity

The **case entity** **[Coming Soon]**  is the persistent, typed business record at the center of every case. It is the single source of truth that stages, tasks, and transition conditions read from and write to throughout the case lifecycle.

Every case project also includes two additional out-of-the-box data objects:

- **Case Documents** — attachments and files associated with the case (receipts, photos, contracts).
- **Case Comments** — notes, annotations, and communications added by case workers and managers during run-time.

All three objects share an immutable `caseID` system field generated at case creation.

You can bring the case entity into Maestro Case in three ways:

| Source | Description | When to Use |
|---|---|---|
| **Native Data Fabric object** | Enable the case entity toggle in your case project, which automatically creates and links a native Data Fabric case entity to your case | New processes where you own the data model |
| **System of record via VDO** | Register an external source as a Virtual Data Object (VDO) in Data Fabric, enable the case entity toggle, and establish a relationship between the VDO and the case entity in Data Fabric | Entity data lives in an external system and you want to reference it without duplicating |
| **System of record via case trigger** | Pass existing data in the case creation trigger (for example, via an API connector); the fields become case fields available throughout the case | Lightweight integrations where you hydrate the case at creation time |

### Stages

**Stages** are the named phases of a case — for example, *Intake*, *Review*, *Settlement*, *Closure*. A stage is, in effect, a **collection of tasks** that move the case forward toward the stage's complete condition.

#### Primary vs. secondary stages

Maestro Case supports two kinds of stages:

| Stage Kind | Purpose | How it is reached | Visibility in Case App |
|---|---|---|---|
| **Primary stage** | The expected progression of the case (for example, *Intake* → *Review* → *Settlement* → *Closure*). | Can be entered through **edges** from a preceding stage on the canvas, **or** by its configured **entry condition** — both are valid. | Shown as **core stage nodes** in the Case App timeline — these are the stages case workers see as the main lifecycle. |
| **Secondary stage** | Exception or alternative paths that can occur at any time during the case (for example, *Request Info*, *Denied*, *Withdrawn*, *Cancelled*). | **No incoming edges** — toggling a stage as *secondary* removes them. The stage is reached only when its entry condition evaluates true, and can activate whenever that happens, regardless of where the case currently is. | Not part of the core stage timeline. Surfaced separately when active (for example, as an exception path indicator), since they can fire at any point. |

In other words, marking a stage as secondary means: *don't wire me into the main lifecycle — I'll activate myself whenever my entry condition is met.* This is what lets a case jump into *Request Info* mid-Review, or into *Withdrawn* from anywhere, without the designer having to draw edges from every possible source.

#### Stage attributes

Each stage defines:

- **Entry condition** — when this stage begins.
- **Complete condition** — what must be true to mark the stage as done and advance.
- **Exit condition** — when to leave the stage early (for example, bailout, or rerouting scenarios).
- **Re-entry condition** — how rework or return-to-origin routes back here.
- **Stage SLA and escalations** — due time, warning thresholds, and escalation notification & email recipients.

Stages can be marked as **required** or **optional**. A case cannot complete until every required stage has been completed. Optional stages activate only when their entry conditions are met and can be skipped without blocking the case.

#### Parallel stages

**Multiple stages can be active in the same case at the same time.** For example, a *Customer Communication* stage can run alongside *Underwriting* while *Settlement* prepares in the background. Whether stages run in parallel or in sequence is controlled by entry rules.

### Tasks

A **task** is a unit of work inside a stage.

#### Task types

Maestro Case supports the following task types:

| Task Type | Description |
|---|---|
| **Human action** | Forms, approvals, and clarifications assigned to a person |
| **RPA Workflow** | UI automation for legacy systems, extraction, and reconciliation |
| **API Workflow** | System-to-system operations via workflow |
| **Execute Connector** | Invoke a connector activity (for example, send notification, create record in external system) |
| **AI Agent (UiPath)** | Autonomous reasoning over data for judgment-based work |
| **External Agent** | Third-party AI agent invoked via API |
| **Maestro Agentic Process** | A multi-step BPMN process invoked as a task |
| **Child Case** | Another case is spawned as a child with its own lifecycle |
| **Wait for Timer** | Pause until a duration elapses or a target date is reached |
| **Wait for Connector Event** | Pause until an external event arrives via a connector |

#### Execution modes

Independent of its type, every task runs in one of three execution modes that determine **when** it starts:

| Execution Mode | Behavior | Example |
|---|---|---|
| **Sequential** | The task executes in a defined order within the stage. A sequence can also include **parallel branches** that fan out and rejoin before the next step. | In an *Underwriting* stage: `Verify income` → (`Run credit check` ∥ `Pull employment history`) → `Calculate DTI` → `Generate decision` |
| **Event-driven** | The task has an **entry rule** and fires whenever the event makes the rule evaluate true — even if the stage is mid-flight or the sequence has already moved past that point. It can fire more than once if the event recurs. | In a *Claims Processing* stage: `Request additional documents` fires **WHEN** a verification task flags a missing document **IF** `Documents.Missing == true` — no matter where the stage currently is in its sequence |
| **Ad-hoc** | The task is defined in the case plan but only starts when a user manually triggers it at runtime. Ad-hoc tasks can be of any task type listed above. | In a *Customer Escalation* stage: `Escalate to supervisor` or `Add fraud review` — kicked off by the case worker on judgment |

**Multiple tasks can be active in the same stage at the same time.** Sequential branches can fan out into parallel paths and rejoin before the next step. **Event-driven tasks fire independently of the sequence** and frequently run in parallel with whatever else is in flight — including multiple instances of the same event-driven task firing concurrently if its triggering event recurs. Ad-hoc tasks can be launched at any time alongside running tasks.

#### Run only once

When a stage is re-entered, you control which tasks should re-execute using the **run only once** flag on each task:

- **Run only once = true** — the task is skipped on re-entry. Its previous output is retained, and the task does not execute again.
- **Run only once = false** *(default)* — the task resets and runs again every time the stage is re-entered, producing fresh output.

**Example:** In a *Document Collection* stage, the `Send document checklist to customer` task is marked **run only once** — you don't want to re-email the customer every time the stage reopens for a different reason. The `Validate documents` task is left with the default so each new submission gets freshly validated.

#### Other task configuration

Each task also supports **inputs and outputs** mapped to the case entity.

### Rules

**Rules** control lifecycle movement and are the mechanism that makes case management non-linear. They follow the **CMMN (Case Management Model and Notation)** pattern and are **event-driven** — a rule fires only when a relevant event occurs on the case, not on a polling schedule or fixed sequence.

Every rule has three parts:

- **WHEN** — the event that triggers evaluation. Events come in two kinds:
  - **Internal events** emitted by the case lifecycle itself — `CaseCreated`, `StageEntered`, `StageCompleted`, `StageExited`, `TaskCompleted`, `CaseSlaAtRisk`, `CaseSlaBreached`, `StageSlaAtRisk`, `StageSlaBreached`, and changes to case entity fields written back by tasks.
  - **External events** arriving from outside the case — Integration Service connector events (webhooks, queue messages), timer firings, child case completion or exit, and direct API calls to the case.
- **IF** *(optional)* — the condition over the case entity that must also be true for the rule to take effect. If omitted, the rule fires on every matching WHEN event.
- **ACTION** — what the rule does when it fires (start a stage, complete a stage, exit a stage, complete the case, etc.).

Rules are scoped to one of three levels: **case**, **stage**, or **task**.

#### Case-level rules

| Rule | Purpose | Example |
|---|---|---|
| **Case complete** | Mark the entire case as completed (successful outcome). | **WHEN** all required stages complete **IF** `Outcome == "Approved"` |
| **Case exit** | Terminate the case before it reaches normal completion (cancel, withdrawal, fraud). | **WHEN** `Application.Status` changes **IF** `Application.Status == "Withdrawn"` |

#### Stage-level rules

| Rule | Purpose | Example |
|---|---|---|
| **Entry** | Gate when the stage begins. | **WHEN** `Application.Submitted` event arrives **IF** `Application.Type == "Mortgage" && Documents.Count > 0` |
| **Complete** | Decide when the stage finishes normally. | **WHEN** any task in the stage completes **IF** all required tasks are `Done` and `UnderwritingDecision != null` |
| **Exit** | Bail out of the stage early, even if it is incomplete. | **WHEN** `UnderwritingDecision` changes **IF** `UnderwritingDecision == "Reject"` |
| **Re-entry** | Return to a previously completed stage for controlled rework. | **WHEN** `Verification.Result` changes **IF** `Verification.Result == "Failed" && DocsComplete == false` |

**Entry** rules carry an **interrupting** toggle that controls what happens to other active stages when the entry rule evaluates true:

- **Interrupting = true** — all currently active stages are automatically exited and the case is forced into the newly entering stage. Use this for hard exception paths like *Withdrawn* or *Fraud Hold* that must take over the case immediately.
- **Interrupting = false** — the new stage activates alongside any existing active stages. The case can have multiple stages running in parallel.

**Defaults differ by stage kind:** primary stages default to **interrupting = false** (join in parallel — the normal progression of work). Secondary stages default to **interrupting = true** (take over the case — since secondary stages represent exception or alternative paths). Both defaults can be overridden per stage.

**Complete** and **Exit** rules also carry an **action** that determines what happens to the case after the stage ends:

- **Complete the case** / **Exit the case** — finish or terminate the case from here.
- **Wait for manual selection** — pause and let a user choose the next stage.
- **Return-to-origin** — route the case back to the stage that originally activated this one.

#### Task-level rules

| Rule | Purpose | Example |
|---|---|---|
| **Entry** | Gate when a task starts within a stage. Used by event-driven tasks to fire on a triggering event, and optionally by sequential or ad-hoc tasks to guard execution. | **WHEN** a verification task flags a missing document **IF** `Documents.Missing == true` |

Because rules are event-driven, the case does not run a fixed sequence — stages and tasks activate, complete, exit, or reopen whenever their **WHEN** event arrives and **IF** condition (if present) evaluates true against the current case entity. Re-execution of tasks on stage re-entry is controlled by the **run only once** flag described in the **Tasks** section above.

### Case Manager

The **Case Manager** is the orchestrator of a case — the agent that drives lifecycle decisions based on events. It decides which stage to activate next, which tasks to start, when a stage should complete or exit early, and when to escalate.

It orchestrates using two complementary methods:

1. **Rules (primary)** — for every decision point, the Case Manager first evaluates the deterministic CMMN rules defined in the case plan. Where a rule resolves the decision, it is taken. This keeps the high-volume happy paths predictable, auditable, and cheap.
2. **Agent (fallback)** — when no rule covers the situation (a gap, an exception, or a judgment call), the Case Manager reasons over the case entity, the case plan, and available policies and knowledge to pick the next action. This is what lets a case keep moving without escalating to a human for every uncovered branch.

To drive a case, the **Case Manager Agent** must conform to a defined **input/output contract** that specifies what case state, events, and policies it can read, and what stage/task decisions it can emit. See the [Case Manager Agent contract](maestro-case-management-component-dictionary.md#case-manager) for the full specification.

### SLAs and escalations

Define **SLAs** and **escalation rules** at both case and stage levels:

- **Case-level SLA** — overall resolution target (for example, resolve within 48 hours).
- **Stage-level SLA** — localized due time (for example, review within 24 hours).
- **SLA state** — on-track, at-risk, or breached. These states surface as badges in case lists and detail views.
- **Escalations** — rules triggered when an SLA is at risk or breached (for example, reassign, notify management, create a priority flag).
- **Pause/Resume** — SLA timers can be paused when the case waits on external input and resumed when actionable again.

### Case personas

Maestro Case enforces **stage-aware access** through personas so the right people see and act at the right time:

A Case Persona is a design-time abstraction representing a role within a case type (for example, Intake Agent, Adjuster, Supervisor). Personas decouple a case's access needs from the organization's identity structure, making case definitions portable across orgs and tenants.

- At design time, the case designer creates personas and scopes each to specific stages.
- At deploy time, an admin binds each persona to users or user groups, so the same case type can have different scopes in different environments.
- At runtime, the system resolves the user's persona(s) and enforces stage scoping accordingly. A user with multiple personas gets the union of stage scopes.

For example, a Loan Processing case might define:
| Persona | Application | Verification | Underwriting | Disbursement |
|---|---|---|---|---|
| Loan Officer | yes |  |  |  |
| Verification Analyst |  | yes |  |  |
| Underwriter |  |  | yes |  |
| Branch Manager | yes | yes | yes | yes |

Tasks within a stage are assigned to a persona, not a specific user. The system resolves persona to role/group to users at runtime to determine task visibility and assignment.

:::note
Full case user roles and access support is coming soon.
:::

## Billing and consumables

Maestro Case follows the same billing as Maestro. Work that runs inside a case consumes the native consumables of the task types you use: AI agents, RPA workflows, API workflows, or IS connectors.

## Next steps

- [Build your first Maestro Case project](building-an-insurance-claims-case-in-30-minutes.md) — A step-by-step tutorial that walks through creating, deploying, and testing a property insurance claims case from scratch.
- [Core constructs reference](maestro-case-management-component-dictionary.md) — Detailed reference for every Maestro Case construct: case entity **[Coming Soon]** , stages, tasks, transition conditions, SLAs, and personas.
- [How to configure stage transitions and re-entry](how-to-configure-a-rework-loop-re-entry.md) — A how-to guide for modeling non-linear case flows with entry, exit, and re-entry conditions.