# The Maestro Case lifecycle: from event trigger to app experience

> Maestro Case lifecycle from event triggers through case entity data, case plan rules, Case Manager decisions, task execution, and Case App experiences.

## Overview

A case is a long-lived business object — a claim, dispute, investigation, loan — that outlives any single task or session and moves non-linearly through stages as data and decisions accumulate. Maestro Case drives that lifecycle end to end: an event creates the case, a Case Plan defines the possible stages and the rules that govern transitions, the Case Manager decides what happens next using rules-first orchestration with Case Manager Agent fallback, and the Case App exposes the live work to business users.

This document traces data through every layer of the stack — triggers → Case Entity **[Coming Soon]**  → Case Plan → Case Manager → tasks → runtime experience — so you can form an accurate mental model before designing your first case plan.

**Audience:** Intermediate to Advanced — Automation Developers, Solution Architects, Business Architects

## Why understand the full stack

Maestro Case is not a single feature. It is a coordinated system of design-time definitions (Case Plan, Case Entity **[Coming Soon]**, stages, tasks, rules) and runtime engines (Case Manager, Case App, Case Instance Management). Understanding the full lifecycle helps you:

- **Design robust case plans** that account for the non-linear nature of real-world work.
- **Avoid common pitfalls** such as rigid stage sequencing, unclear field ownership, or missing re-entry logic.
- **Communicate across roles** — from the developer who models stages in Studio Web to the case worker who completes tasks in the Case App.

## Architecture at a glance

The Maestro Case stack consists of five layers. Data flows downward from event sources through orchestration and execution, and surfaces upward into the business user experience.

![Maestro Case architecture](https://dev-assets.cms.uipath.com/assets/images/maestro/case-management-architecture-f0a60576.png)

The sections below walk through each layer in the order data travels.

## Layer 1 — event triggers (how a case begins)

**Event triggers** are the entry points that create a case instance and hydrate the Case Entity **[Coming Soon]**  with initial data. A single case plan can define multiple triggers so that the same type of case can originate from different channels.

| Trigger source | Description | Example |
|---|---|---|
| **Data Fabric entity** | A "Row created" event on a Data Fabric entity or VDO starts the case. The entity fields become case fields. | A new row in a Home Claims entity creates a property insurance case. |
| **Wait for connector** | An Integration Service connector event (API call, webhook, message) starts the case. The API payload is treated as the case entity. | A Microsoft Teams channel message triggers a Withdrawn stage. |
| **Portal / Form** | A user submits data through a web form. | An employee submits an expense report through a self-service portal. |
| **Email** | An inbound email is parsed and its data is mapped to entity fields. | A forwarded receipt email creates a new claim line item. |
| **API** | An external system calls the case creation endpoint. | An ERP system triggers a claim case on a policy event. |
| **Scheduled** | A time-based trigger creates or follows up on cases. | A daily job creates follow-up cases for stale items. |

Each trigger maps its incoming data to fields in the **Case Entity**. This initial mapping — sometimes called *hydration* — determines the data that is available to every downstream stage, task, and transition condition.

:::note
A case plan can have more than one trigger. For example, an insurance claims case might accept submissions from a portal, an email parser, and a phone-call transcription API — all mapping to the same `AutoInsuranceClaim` entity.
:::

## Layer 2 — the case entity (single source of truth)

The **Case Entity** **[Coming Soon]**  is the persistent, structured data object at the center of every case instance. It lives for the entire lifetime of the case and serves as the single source of truth that all stages, tasks, and transition conditions read from and write to.

### Out-of-the-box data objects

Every case project automatically creates three data objects:

| Object | Purpose |
|---|---|
| **Case Entity** | The central business data model. Holds structured data used by conditions and tasks. |
| **Case Documents** | Attachments and files associated with the case (receipts, photos, contracts). |
| **Case Comments** | Notes, annotations, and communications added by participants throughout the lifecycle. |

All three share an immutable `caseID` system field that is auto-generated at case creation and ties all case data together.

### How data reaches the entity

| Source | Mechanism |
|---|---|
| **Native in Data Fabric** (recommended) | Create a business entity in Data Fabric and link it to the case. |
| **VDO in Data Fabric** | Register an external data source as a Virtual Data Object and link the VDO. |
| **Case trigger payload** | Pass data through the trigger (for example, an API connector). The payload fields become case fields. |

### Why a central entity matters

- **Task independence** — Tasks do not need to know about each other. Each task reads from and writes to the entity through input/output mappings.
- **Orchestration context** — The Case Manager evaluates transition rules against entity fields. When a task writes `adjusterDecision = "approve"` back to the entity, downstream entry rules that reference `adjusterDecision` immediately evaluate.
- **Audit trail** — Every change to the entity is tracked with who, when, and what changed.
- **Single source of truth** — There is no ambiguity about the current state of the case for any participant or system.

### The write-back pattern

The write-back pattern is the primary mechanism for moving data through a case:

1. A task reads specific fields from the Case Entity via **input mapping**.
2. The task performs its work (validation, agent reasoning, human review, RPA extraction).
3. The task writes its results back to the Case Entity via **output mapping**.
4. Updated entity values cause transition rules to re-evaluate, potentially activating the next stage or task.

```
Task A writes → Case Entity updates → Rules evaluate → Next stage activates
```

This pattern keeps tasks decoupled. A "Validate Policy" connector task and an "Analyze Photos" agent task do not communicate directly. Instead, each enriches the entity, and the Case Manager reads the entity to decide what happens next.

:::note
Design your entity schema so that each field is written by exactly one task. If multiple tasks write to the same field, the last writer wins and earlier data is lost. Use namespaced fields (for example, `validation.result` vs. `categorization.result`) to prevent collisions.
:::

## Layer 3 — the case plan (design-time blueprint)

The **Case Plan** is the visual blueprint you build in Studio Web. It defines the *possible* phases a case can move through and the rules that govern transitions. Unlike a linear workflow, a Case Plan does not prescribe a single fixed path. The actual path is determined at runtime based on data and decisions.

A Case Plan consists of four elements:

- **Event Triggers** — the events that create or influence a case instance (described in Layer 1).
- **Stages** — the named phases of the case.
- **Tasks** — the work items within each stage.
- **Rules** — the WHEN/IF/ACTION definitions that govern entry, completion, exit, and re-entry of stages and tasks.

### Stages

**Stages** are the major phases a case moves through — 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 rule. 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 rule**. | Shown as **core stage nodes** in the Case App timeline — the main lifecycle case workers see. |
| **Secondary stage** | Exception or alternative paths that can occur at any time (for example, *Pending with Customer*, *Denied*, *Withdrawn*). | **No incoming edges** — toggling secondary removes them. Reached only when its entry rule evaluates true, and can activate at any point in the case. | Surfaced separately when active (not part of the core timeline). |

Each stage defines:

- **Entry rule** — when the stage activates. Carries an **interrupting** toggle that controls take-over behavior. Defaults: primary stages = `false` (parallel); secondary stages = `true` (take-over).
- **Complete rule** — the normal finish (for example, when required tasks are done). Carries an **action** (complete/exit the case, wait for manual selection, return-to-origin).
- **Exit rule** — an early bailout when continued processing is pointless. Carries the same **action** options as the complete rule.
- **Re-entry rule** — how rework returns the case to a previously completed stage.
- **Stage SLA and escalations** — due time, warning thresholds, and escalation recipients.

Stages can be marked **required** or **optional**. A case cannot close until all required stages have completed. Optional stages activate only when their entry rules are met, and the case can close without them.

**Multiple stages can be active in the same case at the same time.** Whether stages run in parallel or in sequence is controlled by entry rules and their interrupting toggle.

### Tasks

A **task** is a discrete unit of work inside a stage. Each task has a type that determines how the work is performed:

| Task type | What it does |
|---|---|
| **Human action** | Presents a form, approval, or review to a person in the Case App. |
| **AI Agent (UiPath)** | Invokes a UiPath AI agent for autonomous reasoning over data. |
| **External Agent** | Calls a third-party AI agent outside UiPath (for example, via API). |
| **RPA Workflow** | Triggers a UiPath robot for UI automation in legacy systems. |
| **API Workflow** | Calls an external system via a custom API request. |
| **Execute Connector** | Calls an external system through a pre-built or custom Integration Service connector. |
| **Maestro Agentic Process** | Invokes a Maestro BPMN as a task, with its own orchestration, and returns a result to the parent case. |
| **Child Case** | Spawns a separate case definition as a child, linked to the parent via `caseID`. |
| **Wait for Timer** | Pauses until a duration elapses or a target date is reached. |
| **Wait for Connector Event** | Pauses until an external event arrives via a connector. |

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

- **Sequential** — the task runs in a defined order within the stage. Sequences can include parallel branches that fan out and rejoin.
- **Event-driven** — the task has an entry rule and fires whenever the event makes the rule evaluate true. Can fire multiple times if the event recurs.
- **Ad-hoc** — the task is defined in the case plan but only starts when a user manually triggers it at runtime.

**Multiple tasks can be active in the same stage at the same time** — sequential parallel branches, event-driven tasks firing independently of the sequence, and ad-hoc tasks launched alongside running work.

Each task is configured with:

- **Inputs / Outputs** — mapped to and from the Case Entity **[Coming Soon]** .
- **Required flag** — determines whether the parent stage must wait for this task.
- **Entry rule** — required for event-driven tasks; optional for sequential and ad-hoc tasks (where it acts as a guard).
- **Run only once** — if `true`, the task is skipped on stage re-entry and its previous output is retained; if `false` (default), the task re-executes on every re-entry, producing fresh output.
- **Assignment and SLA** — for human actions, who should do the work and when it is due.

### Rules

**Rules** are the mechanism that controls lifecycle movement. 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. 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 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)* — a 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:

| Scope | Rule types | Purpose |
|---|---|---|
| **Case** | Case complete, Case exit | Finish or terminate the case. |
| **Stage** | Entry, Complete, Exit, Re-entry | Govern stage activation, normal completion, early bailout, and rework. Stage Entry rules carry an **interrupting** toggle; Complete and Exit rules carry an **action** (complete/exit the case, wait for manual selection, return-to-origin). |
| **Task** | Entry | Gate when a task starts. Used by event-driven tasks to fire on a triggering event, and optionally by sequential or ad-hoc tasks to guard execution. |

The distinction between **Exit** and **Complete** at the stage level is important. A Complete rule fires when work finishes normally. An Exit rule fires when a change in data makes continued processing unnecessary — it acts as a circuit breaker. Both result in the Case Manager applying the rule's action and evaluating what happens next.

## Layer 4 — the case manager (runtime orchestration)

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

It orchestrates using two complementary methods:

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

### How the Case Manager processes an event

The following sequence repeats throughout the case lifetime:

1. **Event received** — a trigger fires, a task completes, a Case Entity field changes, a timer or connector event arrives, or a stage transitions.
2. **Rule evaluation** — the Case Manager evaluates all applicable case-, stage-, and task-level rules whose **WHEN** matches the event and whose **IF** condition (if present) holds. Matching rule **actions** are applied (activate a stage, complete a stage, exit a stage, etc.).
3. **Agent fallback** — for decisions not covered by a deterministic rule, the Case Manager Agent reasons over case state and policies to choose the next action.
4. **State update** — stages and tasks transition; the Case Entity is updated; new events may be emitted, triggering the next cycle.
5. **Case completion** — when a case-level *Case complete* or *Case exit* rule fires (or the agent decides the case is done), the case closes.

### Rules and the agent work together

Rules cover the predictable: "If the adjuster approves and the amount is under $50,000, enter Settlement." The agent covers the unpredictable: a missing document with no clear policy path, an edge-case fraud pattern, or an unusual combination of conditions. The Case Manager always tries rules first and falls back to the agent only when rules do not match.

### Case Manager Agent configuration

The Case Manager Agent is configured with:

- A **model** (the LLM powering the agent).
- A **user prompt** (policies, constraints, and behavioral instructions).
- **Tools** (actions the agent can take, such as moving a stage, escalating, or updating the entity).
- **Context** (automatically accumulated from execution history, task outcomes, and entity changes).
- An **escalation policy** (conditions under which the agent escalates to a human instead of acting autonomously).

:::note
When neither rules nor the Case Manager Agent can resolve a decision — due to ambiguous data, conflicting policies, or a scenario outside the agent's authority — the Case Manager escalates to a human via the configured persona.
:::

## Layer 5 — the runtime experience

At runtime, two interfaces expose case data and controls to different audiences.

### Case app (for business users)

The **Case App** is the business-user-facing workspace where case workers and case managers interact with live case instances. It surfaces:

- **Case list** — A filterable view of all case instances with status, priority, and SLA indicators (on-track, at-risk, breached).
- **Case detail view** — The current stage, Case Entity data, task statuses, timeline of events, and full audit trail.
- **Task inbox (My Work)** — Pending human tasks awaiting action: forms, approvals, reviews.
- **Quick actions** — Contextual actions based on role and current stage: complete, reopen, reassign, escalate, add notes.

The Case App comes in two options: an **out-of-the-box Case App** (a pre-built, no-code workspace that ships with Maestro Case) and a **custom coded Case App** (built with the pro-code TypeScript SDK for bespoke views and workflows). The out-of-the-box app is configurable at design time — in Studio Web, select **Configure case app** from the Maestro Case settings to define the case title and case details layout.

A single Case Plan definition generates a Case App that handles thousands of individual case instances, each at a different point in its lifecycle.

### Case instance management (for operators)

**Case Instance Management** is the operations console in Maestro where process operators monitor the health of all running cases and intervene when issues arise.

| Operator action | Description |
|---|---|
| **Pause** | Temporarily halt a running case. SLA timers pause. No tasks activate until resumed. |
| **Resume** | Restart a paused case. SLA timers resume from where they stopped. |
| **Cancel** | Terminate a case permanently. All running tasks stop. |
| **Migrate** | Move a live case instance to a newer version of the case plan after a fix or update, preserving current state and data. |
| **Retry** | Re-execute a failed task or transition to recover from transient errors. |

When a case enters an error state — a task fails, an integration times out, or the case gets stuck — it becomes a **case incident**. Operators use the Instance Management console to diagnose and resolve incidents with the actions above.

:::note
* The Case App is for *business users* (case workers, managers) who work on individual cases.
* Case Instance Management is for *process operators* who monitor system health and intervene when things go wrong.
:::

## Tracing data end to end: a walkthrough

To make the lifecycle concrete, consider a property insurance claims case:

1. **Event trigger fires.** A new row is created in a Home Claims Data Fabric entity. The trigger maps entity fields (policy number, claimant name, loss description) into the Case Entity **[Coming Soon]**  and creates a case instance with key `HO-1234`.

2. **Case Manager activates the first stage.** The entry rule for *Intake* evaluates to true (**WHEN** `CaseCreated` event arrives). The stage becomes active.

3. **Tasks execute within Intake.** An extraction task (AI Agent) processes claim details. A lookup task (Execute Connector) verifies the policy. An anomaly-detection agent checks historical claims. Each task writes results back to the Case Entity.

4. **Intake completes, Review activates.** When all required Intake tasks finish and `validationPassed == true`, the Intake **Complete** rule fires. The Case Manager evaluates entry rules for the next stages and activates *Review*.

5. **Review tasks run.** A coverage-check connector, a human claim-officer verification task, and an auditor agent produce outputs. The claim officer writes `decision = "Approve"` back to the entity.

6. **Conditional routing at Review.** The Review **Complete** and **Exit** rules evaluate the `decision` field. If `"Approve"`, the Complete rule fires and the case moves to *Settlement*. If `"Reject"`, the Exit rule fires and routes the case into the secondary *Denied* stage. If `"Claim is missing key incident reports"`, the Re-entry rule sends the case back to *Intake*, re-running only the tasks whose `runOnlyOnce` is `false` (for example, the Incident Reports Robot and Anomaly Agent).

7. **Settlement tasks execute.** A fulfilment process, a settlement process, and a communications agent handle payout and notifications. Each writes back to the entity.

8. **Case closes.** When all required stages complete, the case reaches a terminal state. The full audit trail — every task execution, entity change, decision, and timestamp — is preserved.

9. **Throughout the lifecycle**, a case worker views assigned tasks in the Case App's **My Work** inbox. A case manager monitors the portfolio, reassigns tasks, and handles escalations. An operator watches for incidents in the Case Instance Management console.

## SLAs and escalations across the lifecycle

SLAs add a time dimension to the lifecycle:

| SLA level | Scope | Example |
|---|---|---|
| **Case-level SLA** | Overall target from creation to close. | Resolve within 48 hours. |
| **Stage-level SLA** | Localized due time for a specific stage. | Complete Review within 24 hours. |

SLA states — **on-track**, **at-risk**, and **breached** — surface as badges in the Case App's list and detail views. Escalation rules trigger automatically:

- **At-risk** — SLA is approaching its limit. Notify the case owner and supervisor.
- **Breached** — SLA is exceeded. Reassign to a senior worker or escalate to management.
- **Pause / Resume** — SLA timers pause when the case is waiting on external input and resume when it becomes actionable again.

## User roles in the lifecycle

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

| Role | Responsibility |
|---|---|
| **Case Worker** | Completes human tasks and updates allowed fields within stages they have access to. Sees assigned work in **My Work**. |
| **Case Manager** | Oversees a portfolio. Can reassign, escalate, and (per policy) reopen. May perform stage-level actions like pause and resume. |

For each stage, the Case Plan defines which personas can **view** and which can **act** (complete tasks, reassign, escalate, pause). Tasks inherit stage settings but can further restrict assignees.

:::note
Full case user roles and stage-level access controls are not yet available.
:::

## Key architectural principles

| Principle | Explanation |
|---|---|
| **Agent-first** | AI agents are first-class participants — both as task workers within stages, and as the Case Manager Agent that orchestrates the whole case. Humans step in only when policy or judgment requires it. |
| **Non-linear by design** | Re-entry rules, secondary stages, event-driven tasks, and ad-hoc tasks allow cases to follow the path the data dictates — not a rigid sequence. |
| **Entity-centric** | The Case Entity **[Coming Soon]** is the single source of truth. Tasks are decoupled producers and consumers of entity data. |
| **Rules first, agent second** | Deterministic CMMN rules handle the high-volume happy paths. The Case Manager Agent handles exceptions and ambiguity — and escalates to humans when neither rules nor the agent can decide. |
| **Design-time vs. runtime separation** | The Case Plan is what you design in Studio Web. The Case App and Instance Management console are what business users and operators use every day. A single Case Plan serves thousands of case instances. |

## Related resources

- [Core concepts in Maestro Case](introduction-to-maestro-case.md#core-concepts) — Reference definitions for case keys, entities, stages, tasks, rules, and SLAs.
- [Case Plan Designer overview](introduction-to-maestro-case.md#case-plan-designer-studio-web) — How to model case plans in Studio Web.
- [Configuring stage rules](how-to-model-primary-secondary-stages.md#step-2-configuring-primary-stage-rules) — Detailed guidance on entry, complete, exit, and re-entry rules.
- [Case App overview](maestro-case-management-component-dictionary.md#case-app) — What business users see and how to configure the Case App layout.
- [Case Instance Management](how-to-manage-live-case-instances-pause-migrate-and-retry.md) — Operator actions for monitoring, incident resolution, and live migration.