UiPath Maestro Case: The Complete Step-by-Step Tutorial (2026)

Satish Prasad
68 Min Read

Who This Guide Is For

A note on the examples in this guide: The concepts, terminology, and architecture described here are grounded entirely in official UiPath Maestro documentation (linked throughout). However, the two build-along examples โ€” Employee Grievance Management and IT Change Request Management โ€” are scenarios constructed for this guide. This was a deliberate choice: working through a different scenario than the official docs forces you to actually apply the concepts rather than transcribe a tutorial.

You are a UiPath developer, solution architect, or business analyst who has heard about Maestro Case and wants to understand it from first principles โ€” what it is, when to use it over standard BPMN, how it works under the hood, and how to build one end to end.

Contents

This is not a feature summary. It is a structured, step-by-step build guide anchored entirely in official UiPath documentation. Every concept is linked to its source. Every step is in the order you would actually do it.

By the end, you will have built two complete cases from scratch โ€” an employee grievance management case and an IT change request case โ€” and understood every architectural decision behind them.


Part 1: Understanding What Maestro Case Actually Is

1.1 Maestro in One Paragraph

UiPath Maestro is a cloud-native orchestration platform that unifies automation, AI agents, and human interactions into streamlined, end-to-end business processes. It allows organizations to model workflows visually using BPMN (Business Process Model and Notation), define business rules with DMN (Decision Model and Notation), and coordinate multiple actors โ€” including RPA bots, AI agents, and people โ€” within a single process.

Source: Maestro Overview

1.2 Two Orchestration Models โ€” and Why They Are Different

Maestro gives you two distinct ways to orchestrate work. Choosing the wrong one is the most common mistake beginners make.

Maestro BPMN is a directed, sequence-based workflow. It runs from start to finish along a path you define at design time. It supports branching, parallel execution, and human-in-the-loop tasks โ€” but the overall structure is a fixed flow.

Maestro Case orchestrates long-lived, goal-driven work about a specific situation โ€” a case. Instead of a fixed sequence, a case plan defines stages (named phases) and the rules that govern transitions between them. The actual path through the plan is determined dynamically at runtime based on case data.

The decision framework from the official documentation is precise:

Use Maestro BPMN when the sequence of steps is known and repeatable. Use Maestro Case when work cannot be fully defined upfront โ€” when multiple stages involve frequent decision points, progress depends on evaluating outcomes, and the process is long-running, exception-heavy, and requires human judgment at key moments.

Source: Maestro BPMN vs. Maestro Case

1.3 The Decision Test

Before building anything, apply this quick test from UiPathโ€™s own documentation:

If the next step depends on what just happened and no single flowchart can capture every path โ€” consider Maestro Case. If the process follows the same path every time โ€” use Maestro BPMN.

Source: Maestro BPMN vs. Maestro Case

1.4 The Eight Signals That Tell You to Use Maestro Case

From the official documentation, case management adds the most 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
  • Multiple entry channels exist โ€” the same type of case can originate from a portal, email, API call, or external event
  • Persistent case data accumulates โ€” a central business record grows richer as each stage completes

Source: Introduction to Maestro Case

1.5 Real-World Scenarios Where Maestro Case Is the Right Answer

The following table maps directly to UiPathโ€™s documented use cases:

Business ScenarioWhy Maestro Case
Insurance claimsLong-running, multi-party (claimant, adjuster, inspector), frequent exceptions, SLA-driven
Disputes and chargebacksBack-and-forth between parties, evidence gathering, escalation paths, non-linear progression
Loan origination and underwritingMultiple review stages, conditional paths based on risk scores, regulatory requirements
KYC/AML remediationDocument collection across stages, regulatory decision points, audit trail requirements
Customer escalations and complaintsTiered resolution, re-entry when a fix does not hold, SLA commitments, multi-team handoffs
Vendor/Supplier onboardingMulti-stage vetting (legal, compliance, finance), conditional stages based on vendor type, document collection
Order fulfillment exceptionsBackorders, partial shipments, returns โ€” multi-system coordination with SLA tracking
Public sector investigations and referralsAd-hoc approvals, cross-department coordination, policy-dependent routing

Source: Introduction to Maestro Case โ€” Business Scenarios


Part 2: The Architecture โ€” Five Layers You Must Understand

Before you open Studio Web, you need a mental model of how Maestro Case works end to end. The official documentation describes it as a five-layer stack. Data flows downward from event sources through orchestration and execution, and surfaces upward into the business user experience.

Source: The Maestro Case Lifecycle

UiPath Maestro Case: The Complete Step-by-Step Tutorial (2026) 6

Layer 1: Event Triggers โ€” How a Case Begins

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

Trigger SourceDescriptionExample
Data Fabric entityA โ€œRow createdโ€ event on a Data Fabric entity starts the case. Entity fields become case fields.A new row in a Home Claims entity creates a property insurance case
Wait for connectorAn Integration Service connector event starts the case. The API payload becomes the case entity.A Microsoft Teams channel message triggers a Withdrawn stage
Portal / FormA user submits data through a web formAn employee submits an expense report through a self-service portal
EmailAn inbound email is parsed and its data is mapped to entity fieldsA forwarded receipt email creates a new claim line item
APIAn external system calls the case creation endpointAn ERP system triggers a claim case on a policy event
ScheduledA time-based trigger creates or follows up on casesA daily job creates follow-up cases for stale items

A case plan can have more than one trigger. For example, a grievance management case might accept submissions from a self-service portal, an inbound email parsed by IXP Communications Mining, and a manager referral โ€” all mapping to the same entity.

Source: The Maestro Case Lifecycle โ€” Layer 1

Layer 2: The Case Entity โ€” Single Source of Truth

The Case Entity 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.

Every case project automatically creates three data objects:

ObjectPurpose
Case EntityThe central business data model. Holds structured data used by conditions and tasks.
Case DocumentsAttachments and files associated with the case (receipts, photos, contracts)
Case CommentsNotes, 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.

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

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.

Source: The Maestro Case Lifecycle โ€” Layer 2

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, Stages, Tasks, and Rules.

Source: The Maestro Case Lifecycle โ€” Layer 3

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

The event processing cycle:

  1. Event received โ€” a trigger fires, a task completes, a Case Entity field changes, or a timer arrives
  2. Rule evaluation โ€” the Case Manager evaluates all applicable rules whose WHEN matches the event and whose IF condition holds
  3. Agent fallback โ€” for decisions not covered by a deterministic rule, the Case Manager Agent reasons over case state
  4. State update โ€” stages and tasks transition; the Case Entity is updated; new events may be emitted
  5. Case completion โ€” when a case-level complete or exit rule fires (or the agent decides the case is done), the case closes

Source: The Maestro Case Lifecycle โ€” Layer 4

Layer 5: The Runtime Experience โ€” Two Interfaces for Two Audiences

The Case App is for business users (case workers and case managers). It surfaces:

  • Case list โ€” a filterable view of all case instances with status, priority, and SLA indicators
  • 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 โ€” complete, reopen, reassign, escalate, add notes

Case Instance Management is for process operators. It provides:

Operator ActionDescription
PauseTemporarily halt a running case. SLA timers pause. No tasks activate until resumed.
ResumeRestart a paused case. SLA timers resume from where they stopped.
CancelTerminate a case permanently. All running tasks stop.
MigrateMove a live case instance to a newer version of the case plan, preserving current state and data.
RetryRe-execute a failed task or transition to recover from transient errors.

Source: The Maestro Case Lifecycle โ€” Layer 5


Part 3: Core Concepts โ€” The Building Blocks

These concepts must be clear before you build. They come directly from the UiPath Core Concepts reference.

Source: Introduction to Maestro Case โ€” Core Concepts

3.1 Case Keys: System vs. External

Each case is uniquely identified by a case key:

Key TypeDescriptionExample
System keyAuto-generated by Maestro on case creationHC-1234, CLM-00891
External (customer-defined) keyAn upstream ID passed at creation so the same real-world case is recognized across toolsCRM 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.

Source: Defining Case Keys

3.2 Stages: Primary vs. Secondary

Stages are the named phases of a case โ€” for example, Intake, Review, Settlement, Closure.

Stage KindPurposeHow It Is ReachedVisibility in Case App
Primary stageThe expected progression of the caseCan be entered through edges from a preceding stage on the canvas, or by its configured entry ruleShown as core stage nodes in the Case App timeline
Secondary stageException or alternative paths that can occur at any time (e.g., Request Info, Denied, Withdrawn)No incoming edges โ€” reached only when its entry rule evaluates trueSurfaced separately when active; not part of the core timeline

Marking a stage as secondary means: do not wire me into the main lifecycle โ€” I will 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.

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

Multiple stages can be active in the same case at the same time โ€” parallel processing is controlled by entry rules.

Source: Introduction to Maestro Case โ€” Stages

3.3 Tasks: Types and Execution Modes

A task is a unit of work inside a stage. Maestro Case supports the following task types:

Task TypeDescription
Human actionForms, approvals, and clarifications assigned to a person
RPA WorkflowUI automation for legacy systems, extraction, and reconciliation
API WorkflowSystem-to-system operations via workflow
Execute ConnectorInvoke a connector activity (send notification, create record in external system)
AI Agent (UiPath)Autonomous reasoning over data for judgment-based work
External AgentThird-party AI agent invoked via API
Maestro Agentic ProcessA multi-step BPMN process invoked as a task
Child CaseAnother case is spawned as a child with its own lifecycle
Wait for TimerPause until a duration elapses or a target date is reached
Wait for Connector EventPause until an external event arrives via a connector

Every task runs in one of three execution modes:

Execution ModeBehaviorExample
SequentialThe task executes in a defined order within the stage. Sequences can include parallel branches.Verify income โ†’ (Run credit check โˆฅ Pull employment history) โ†’ Calculate DTI โ†’ Generate decision
Event-drivenHas an entry rule and fires whenever the event makes the rule evaluate true. Can fire multiple times if the event recurs.Request additional documents fires WHEN a verification task flags a missing document IF Documents.Missing == true
Ad-hocDefined in the case plan but only starts when a user manually triggers it at runtimeEscalate to supervisor โ€” kicked off by the case worker on judgment

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

  • run only once = true โ€” the task is skipped on re-entry. Its previous output is retained.
  • run only once = false (default) โ€” the task resets and runs again every time the stage is re-entered, producing fresh output.

Source: Introduction to Maestro Case โ€” Tasks

3.4 Rules: The CMMN WHEN / IF / ACTION Pattern

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.

Every rule has three parts:

  • WHEN โ€” the event that triggers evaluation. Internal events include CaseCreated, StageEntered, StageCompleted, StageExited, TaskCompleted, CaseSlaAtRisk, CaseSlaBreached, StageSlaAtRisk, StageSlaBreached, and changes to case entity fields. External events include Integration Service connector events, timer firings, child case completion, and direct API calls.
  • 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.

Rules are scoped to three levels:

Case-level rules:

RulePurposeExample
Case completeMark the entire case as completedWHEN all required stages complete IF Outcome == "Approved"
Case exitTerminate the case before it reaches normal completionWHEN Application.Status changes IF Application.Status == "Withdrawn"

Stage-level rules:

RulePurposeExample
EntryGate when the stage beginsWHEN Application.Submitted event arrives IF Application.Type == "Mortgage"
CompleteDecide when the stage finishes normallyWHEN any task in the stage completes IF all required tasks are Done
ExitBail out of the stage early, even if incompleteWHEN UnderwritingDecision changes IF UnderwritingDecision == "Reject"
Re-entryReturn to a previously completed stage for controlled reworkWHEN Verification.Result changes IF Verification.Result == "Failed"

Entry rules carry an interrupting toggle:

  • interrupting = true โ€” all currently active stages are automatically exited and the case is forced into the newly entering stage. Use for hard exception paths like Withdrawn or Fraud Hold.
  • interrupting = false โ€” the new stage activates alongside any existing active stages. Parallel processing.

Defaults: primary stages default to interrupting = false (join in parallel). Secondary stages default to interrupting = true (take over the case).

Complete and Exit rules carry an action determining what happens after the stage ends: complete/exit the case, wait for manual selection, or return-to-origin.

Task-level rules:

RulePurposeExample
EntryGate when a task starts. Used by event-driven tasks to fire on a triggering event.WHEN a verification task flags a missing document IF Documents.Missing == true

Source: Introduction to Maestro Case โ€” Rules

3.5 Exit Rules vs. Complete Rules โ€” A Critical Distinction

This is one of the most misunderstood distinctions in Maestro Case.

A Complete rule fires when the work in a stage finishes normally โ€” all required tasks are done and the output meets the completion condition. It represents successful forward progress.

An Exit rule fires when a change in data makes continued processing in the current stage unnecessary or pointless โ€” it acts as a circuit breaker. The stage is abandoned mid-flight, not completed. Tasks that were running when the exit fires are stopped.

Example:

In an Underwriting stage:

  • Complete rule: WHEN all underwriting tasks finish IF CreditScore >= 650 AND DTI <= 43
  • Exit rule: WHEN UnderwritingDecision is written IF UnderwritingDecision == "Hard Decline" โ€” there is no point continuing the stage; the case should immediately route to the Declined secondary stage.

Both Complete and Exit rules carry an action (complete the case, exit the case, wait for manual selection, return-to-origin) that determines what Maestro does next.

Source: Exit Rules and Early Stage Termination

3.6 SLAs and Escalations

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

  • Case-level SLA โ€” overall resolution target (e.g., resolve within 48 hours)
  • Stage-level SLA โ€” localized due time (e.g., review within 24 hours)
  • SLA states: on-track, at-risk, or breached โ€” surface as badges in case lists and detail views
  • Escalations โ€” rules triggered when an SLA is at risk or breached (reassign, notify management, create a priority flag)
  • Pause/Resume โ€” SLA timers can be paused when the case waits on external input

Source: Introduction to Maestro Case โ€” SLAs and Escalations

3.7 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. Personas decouple a caseโ€™s access needs from the organizationโ€™s identity structure, making case definitions portable across organizations 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
  • At runtime: the system resolves the userโ€™s persona(s) and enforces stage scoping

Example for a Loan Processing case:

PersonaApplicationVerificationUnderwritingDisbursement
Loan Officeryes
Verification Analystyes
Underwriteryes
Branch Manageryesyesyesyes

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

Source: Introduction to Maestro Case โ€” Case Personas


Part 4: Designing the Case Entity Schema

The case entity schema is the most important design decision you will make. A poorly designed schema causes data collisions, stale computed values, and broken rules. Do this before opening the stage canvas.

Source: Designing a Persistent Case Entity Schema

Step 1: Understand the Three Out-of-the-Box Data Objects

ObjectPurpose
Case EntityHolds all structured business data that stages, tasks, and rules read from and write to
Case DocumentsStores attachments and files associated with the case
Case CommentsStores notes, annotations, and communications added by case workers throughout the lifecycle

All three share an immutable caseID system field. Focus your schema design on the Case Entity โ€” it is the single source of truth for all case processing logic.

Step 2: Choose Where the Entity Lives

SourceDescriptionWhen to Use
Native in Data Fabric (recommended)Create the entity as a native business entity in Data Fabric and link it to your caseNew processes where you own the data model
Virtual Data Object (VDO) in Data FabricRegister an external source as a VDO in Data Fabric and link the VDO to the caseEntity data lives in an external system (CRM, ERP) and you want to reference it without duplicating
Case trigger payloadPass existing data in the case creation trigger; the payload fields become case fieldsLightweight integrations where you hydrate the case at creation time

Step 3: Classify Every Field Into Two Categories

CategoryDefinitionCharacteristicsExamples
Input fieldsData provided when the case is created by a trigger, form, or external systemPopulated at creation. Read-only after hydration.policyNumber, claimantName, dateOfLoss, lossDescription
Computed fieldsData produced by tasks during case processing. Start empty, written back as tasks complete.Empty at creation. Written by exactly one task.validationResult, damageEstimate, adjusterDecision, paymentReference

Input fields such as employeeId, policyNumber, or reportId should never be overwritten by tasks. Document these fields as read-only in your schema.

Step 4: Establish Field Ownership โ€” One Writer Per Field

Field ownership is the most critical principle for preventing data collisions. Each computed field in the entity must be written by exactly one task. If two tasks write to the same field, the last writer wins and previous data is lost.

Use namespaced fields to avoid ambiguity when multiple tasks produce similar output types:

  • Use photoAnalysis for the output of an image analysis agent task
  • Use fieldInspection for the output of a human field inspection task
  • Avoid a generic analysisResult field that multiple tasks might contend for

Step 5: Reference Schema โ€” Employee Expense Reimbursement

This example uses a corporate expense reimbursement case โ€” a process most organizations run with spreadsheets and email chains, which makes it an ideal candidate for Maestro Case.

Business context: An employee submits an expense report. It goes through receipt validation, policy compliance checking, line-item categorization, manager approval, and finance sign-off before payment is issued. Exceptions include receipts with missing data, amounts exceeding policy thresholds, and flagged anomalies from the finance system.

Why this needs Maestro Case and not BPMN: Reports over a certain threshold require a second-level approval that standard reports skip. Reports with flagged anomalies loop back to the employee for clarification. International reports require a currency conversion task that domestic reports never touch. No single sequence handles all paths.

{
  "entityName": "ExpenseReport",
  "fields": {

    // --- Input fields (set at submission, never overwritten by processing tasks) ---
    "reportId":           { "type": "string",  "required": true, "generated": true },
    "submittedBy":        { "type": "string",  "required": true },
    "employeeEmail":      { "type": "string",  "required": true },
    "department":         { "type": "string",  "required": true },
    "costCenter":         { "type": "string",  "required": true },
    "submissionDate":     { "type": "date",    "required": true },
    "tripPurpose":        { "type": "string",  "required": true },
    "totalClaimed":       { "type": "decimal", "required": true },
    "currency":           { "type": "string",  "required": true },
    "lineItems":          { "type": "array",   "items": "ExpenseLineItem" },
    "receiptFiles":       { "type": "array",   "items": "url" },

    // --- Computed fields (each owned by exactly one task) ---
    "receiptValidation":  { "type": "object",  "writtenBy": "Validate Receipts" },
    "categorizedItems":   { "type": "array",   "writtenBy": "Categorize Line Items" },
    "policyCheckResult":  { "type": "object",  "writtenBy": "Policy Compliance Check" },
    "anomalyFlags":       { "type": "array",   "writtenBy": "Flag Anomalies" },
    "convertedAmount":    { "type": "decimal", "writtenBy": "Currency Conversion" },
    "managerDecision":    { "type": "string",  "enum": ["approved", "rejected", "more_info_needed"] },
    "financeDecision":    { "type": "string",  "enum": ["approved", "rejected", "on_hold"] },
    "approvedAmount":     { "type": "decimal", "writtenBy": "Finance Approval" },
    "paymentReference":   { "type": "string",  "writtenBy": "Trigger Payment" },
    "rejectionReason":    { "type": "string",  "writtenBy": "Manager Approval OR Finance Approval" }
  }
}

Notice rejectionReason has a comment indicating two possible writers โ€” this is a design smell. In production, resolve it by splitting into managerRejectionReason and financeRejectionReason so each is owned by exactly one task and downstream rules can distinguish the source.

Step 6: Wire Input and Output Mappings to Tasks

After defining the schema, connect it to tasks through input and output mappings.

Input mapping example โ€” Validate Policy task:

"input": {
  "policyNumber": "caseEntity.policyNumber"
}

Output mapping example โ€” Validate Policy task:

"output": {
  "caseEntity.policyValid": "taskOutput.policyValid"
}

Cross-check every taskโ€™s output mapping against your schema annotations. Confirm that no two tasks write to the same Case Entity field.

Step 7: Validate the Schema Against Rules

Stage rules (entry, complete, exit, re-entry) evaluate against Case Entity fields. Before building the stage canvas, verify that:

  • Every field referenced in a ruleโ€™s IF clause is present in the schema
  • The field is written by a task that completes before the rule evaluates
  • The field type matches the operator used in the rule

Example โ€” Exit rule on Intake stage depends on the policyValid field:

WHEN PolicyCheckCompleted event arrives
  IF caseEntity.policyValid == false

Confirm that the Validate Policy task writes policyValid and completes within the Intake stage before this Exit rule evaluates.

Common Schema Troubleshooting

ProblemCauseResolution
A computed field contains unexpected or stale dataMultiple tasks write to the same fieldAudit output mappings. Assign each field to exactly one task and use namespaced field names.
A rule never evaluates to trueThe field referenced in the ruleโ€™s IF clause is not yet written by the time the rule evaluatesVerify that the task responsible for writing the field completes within the current or a preceding stage
Input fields are being overwritten during processingA task output mapping targets an input fieldRemove the output mapping that targets the input field. Document input fields as read-only.

Source: Designing a Persistent Case Entity Schema

RPA to Agentic AI: The Complete Transition Guide for Automation Professionals (2026)


Part 5: Step-by-Step Build โ€” Employee Grievance Management Case

This section builds an original case from scratch: an Employee Grievance Management system. This process is deliberately chosen because it does not appear in any UiPath tutorial, it has all the characteristics that make Maestro Case the right choice, and it is a process most mid-to-large organizations actually need.

Why Employee Grievance Management Needs Maestro Case

When an employee files a grievance, the journey is never linear. It may go to an HR officer, then to a manager, then back to HR if the managerโ€™s response is disputed. A formal investigation may be triggered mid-process. The employee may withdraw at any point. The whole thing must be auditable to the day under employment law in most jurisdictions.

Every one of the eight Maestro Case signals applies:

  • Long-running โ€” grievances typically take 5โ€“30 business days to resolve
  • Exception-heavy โ€” escalations, withdrawals, appeals, and formal investigation triggers are routine
  • Multi-role โ€” HR Officer, Department Manager, HR Director, Legal Counsel each own specific stages
  • SLA-driven โ€” employment law in most regions mandates response within defined timeframes
  • Full audit trail required โ€” every decision, communication, and document exchange must be recorded
  • Rework loops โ€” if an informal resolution is rejected by the employee, the case re-enters formal investigation
  • Multiple entry channels โ€” employees submit via self-service portal, email, or manager referral
  • Persistent case data โ€” evidence, responses, and decisions accumulate across stages and are needed at every subsequent stage

What We Are Building

UiPath Maestro Case: The Complete Step-by-Step Tutorial (2026) 7
[Intake & Triage] โ†’ [Informal Resolution] โ†’ [Formal Investigation] โ†’ [Decision] โ†’ [Closure]
                             โ†•
            [Employee Clarification]  (secondary โ€” missing information)
            [Legal Review]            (secondary โ€” activated for serious allegations)
            [Withdrawn]               (secondary โ€” employee withdraws at any point)
            [Appealed]                (secondary โ€” employee appeals the Decision)

Prerequisites

  • UiPath Automation Cloud with Maestro enabled
  • Studio Web access
  • An HRIS system accessible via Integration Service connector (for employee record lookups)
  • An email connector configured (for notifications)

Step 1: Create the Case Project

Open Studio Web. Select New Project โ†’ Case Management Project. Name it EmployeeGrievanceManagement. Select your Orchestrator folder.

You will land on the Case Plan canvas with the Data Manager panel on the left, the stage canvas in the center, and the Properties panel on the right.


Step 2: Build the Case Entity Schema

Before touching the stage canvas, design the entity. Open the Data Manager panel and create a new entity called GrievanceCase.

Input fields โ€” set at submission, read-only:

FieldTypeRequiredNotes
grievanceIdstringyesAuto-generated
submittedBystringyesEmployee ID
employeeNamestringyesResolved from HRIS at trigger
employeeEmailstringyes
departmentstringyes
reportingManagerstringyesManager employee ID
grievanceCategorystringyese.g., harassment, pay dispute, working conditions
grievanceDescriptionstringyesFree text from the employee
submissionDatedateyesAuto-populated
evidenceFilesarraynoUploaded documents
severitystringyeslow / medium / high โ€” self-reported

Computed fields โ€” written by tasks, empty at creation:

FieldTypeWritten By
hrAssessmentobjectHR Triage Agent
classifiedSeveritystringHR Triage Agent (overrides self-reported severity if needed)
managerResponseobjectManager Response task
employeeResponseToManagerstringEmployee Feedback task
informalResolutionOutcomestring (enum: agreed / rejected / withdrawn)HR Officer decision task
investigationFindingsobjectInvestigator Report task
legalReviewNotesobjectLegal Counsel task
formalDecisionstring (enum: upheld / partially_upheld / not_upheld)HR Director decision task
decisionRationalestringHR Director decision task
closureNotesstringClosure task

Note on namespacing: managerResponse and employeeResponseToManager are deliberately separate fields rather than a generic responseField. This prevents the write-back collision that would occur if both the Manager Response task and the Employee Feedback task targeted the same field.


Step 3: Configure Case Keys

In the Case Settings panel:

  • System key prefix: GRV- โ€” produces keys like GRV-1042
  • External key: map to submittedBy + submissionDate concatenated โ€” or, if your HRIS generates a case reference number at submission, use that as the external key

The external key lets HR officers look up a Maestro case using the reference number the employee was given at submission โ€” without needing to know Maestroโ€™s internal ID.


Step 4: Configure the Case Trigger

This case supports two trigger channels:

Trigger 1 โ€” Self-service portal form submission:

  • Type: API (a form submission calls the Maestro case creation API)
  • Payload fields map to all input fields in the entity

Trigger 2 โ€” Manager referral via email:

  • Type: Wait for Connector Event (email connector, inbound email to grievance@company.com)
  • IXP Communications Mining parses the email body to extract the submitter name, department, grievance category, and description into structured fields
  • Maps to the same input fields as Trigger 1

Both triggers create a GrievanceCase instance โ€” the lifecycle is identical regardless of channel.


Step 5: Add Primary Stages

On the canvas, add four primary stages connected with edges:

[Intake & Triage] โ†’ [Informal Resolution] โ†’ [Formal Investigation] โ†’ [Decision] โ†’ [Closure]

Mark all four as required.


Step 6: Add Secondary Stages

Add these stages and toggle each as Secondary:

  • Employee Clarification โ€” when the grievance description lacks enough information to proceed
  • Legal Review โ€” activated when the HR triage classifies the allegation as legally sensitive (harassment, discrimination, whistleblowing)
  • Withdrawn โ€” when the employee withdraws at any point
  • Appealed โ€” when the employee appeals the formal decision within the appeal window

Secondary stages have no incoming edges. They activate via their entry rules whenever the triggering condition is met, regardless of where the primary lifecycle currently sits.


Step 7: Build the Intake & Triage Stage

This stage validates the submission and classifies the grievance before any human review begins.

Tasks:

Task 1 โ€” Verify Employee Record (Execute Connector, Sequential)

  • Connector: HRIS lookup by submittedBy employee ID
  • Input: submittedBy, department, reportingManager
  • Output: writes hrAssessment.employeeVerified (boolean) to the entity
  • If the employee is not found or is not in active employment, the exit rule terminates the case
  • run only once = true โ€” employee status does not change mid-case

Task 2 โ€” HR Triage Agent (AI Agent โ€” UiPath, Sequential, after Task 1)

  • This agent reads the grievance description, category, and self-reported severity
  • It classifies the actual severity (classifiedSeverity) based on the content โ€” overriding the self-reported value if the language indicates a more serious situation than the employee flagged
  • It flags legally sensitive allegations (hrAssessment.legalFlag = true) and sets hrAssessment.suggestedPath (informal / formal)
  • Input: grievanceDescription, grievanceCategory, severity, evidenceFiles
  • Output: writes hrAssessment and classifiedSeverity to the entity
  • Tool: Context Grounding index over the companyโ€™s grievance policy and employment law guidelines
  • run only once = false โ€” if the case re-enters Intake after a withdrawal and re-submission, re-classify with fresh context

Task 3 โ€” Send Acknowledgement (Execute Connector, Sequential, after Task 2)

  • Email connector sends the employee a case reference number and expected timeline
  • run only once = true โ€” only acknowledge once, even if Intake is re-entered

Intake & Triage Stage Rules:

Entry rule:

WHEN CaseCreated
(no IF condition โ€” Intake activates immediately on case creation)

Complete rule:

WHEN TaskCompleted (Send Acknowledgement)
IF hrAssessment.employeeVerified == true
   AND hrAssessment.suggestedPath != null
ACTION: advance to next stage (determined by the edge and the path routing below)

Exit rule โ€” invalid submission:

WHEN TaskCompleted (Verify Employee Record)
IF hrAssessment.employeeVerified == false
ACTION: exit the case

This is a genuine circuit breaker โ€” not a normal completion. The submission was invalid. No further processing is warranted.


Step 8: Build the Informal Resolution Stage

Most organizations require an informal resolution attempt before escalating to a formal investigation. This stage handles that.

Tasks:

Task 1 โ€” Notify Manager (Execute Connector, Sequential)

  • Sends the reporting manager a summary of the grievance (not the full text โ€” the manager receives only enough to respond)
  • Input: reportingManager, grievanceCategory, classifiedSeverity
  • run only once = true

Task 2 โ€” Manager Response (Human action, Sequential, after Task 1)

  • Assigned to persona: Department Manager
  • The manager submits their response via the Case App task form
  • Input: grievanceDescription (read-only view), grievanceCategory
  • Output: writes managerResponse to the entity
  • SLA: 5 business days

Task 3 โ€” Employee Feedback (Human action, Sequential, after Task 2)

  • Assigned to persona: HR Officer (who facilitates the conversation between the employee and manager)
  • The HR Officer records whether the employee accepts or rejects the managerโ€™s response
  • Output: writes employeeResponseToManager and informalResolutionOutcome to the entity

Task 4 โ€” Request Clarification (Execute Connector, Event-driven)

  • Entry rule: WHEN any task in the stage completes IF grievanceDescription contains keywords flagged by HR as ambiguous (set as a case entity flag by the Triage Agent)
  • Sends the employee a structured clarification request
  • This fires independently of the sequential flow whenever ambiguity is flagged

Informal Resolution Stage Rules:

Entry rule โ€” standard path:

WHEN StageCompleted (Intake & Triage)
IF hrAssessment.suggestedPath == "informal"
interrupting: false

Entry rule โ€” skip to Formal if severity is high:

WHEN StageCompleted (Intake & Triage)
IF classifiedSeverity == "high" OR hrAssessment.legalFlag == true

This entry rule is not wired โ€” instead the Complete rule of Intake triggers a direct jump to Formal Investigation for high-severity cases, bypassing this stage entirely.

Complete rule โ€” resolved informally:

WHEN TaskCompleted (Employee Feedback)
IF informalResolutionOutcome == "agreed"
ACTION: advance to Closure (skip Formal Investigation and Decision)

Exit rule โ€” escalate to formal:

WHEN TaskCompleted (Employee Feedback)
IF informalResolutionOutcome == "rejected"
ACTION: activate Formal Investigation stage

Step 9: Build the Formal Investigation Stage

This is the most complex stage โ€” it handles the full investigation with multiple parallel workstreams.

Tasks:

Task 1 โ€” Assign Investigator (Human action, Sequential)

  • Assigned to persona: HR Director
  • The HR Director nominates an investigator from the HR team (or an external party for senior staff cases)
  • Output: writes hrAssessment.assignedInvestigator to the entity

Task 2 โ€” Gather Evidence (Sequential, parallel branch)

  • Sub-task 2a: RPA Workflow pulls relevant HR records, attendance data, and previous case history from the HRIS
  • Sub-task 2b: Human action โ€” the investigator collects statements from witnesses
  • Both run in parallel and must complete before the next step

Task 3 โ€” Legal Review trigger (Event-driven)

  • Entry rule: WHEN StageEntered (Formal Investigation) IF hrAssessment.legalFlag == true
  • Activates the Legal Review secondary stage immediately when formal investigation begins for legally sensitive cases
  • The secondary Legal Review stage runs in parallel with the main investigation

Task 4 โ€” Investigator Report (Human action, Sequential, after Task 2)

  • Assigned to persona: Investigator
  • The investigator submits their findings via the Case App task form
  • Output: writes investigationFindings to the entity
  • SLA: 10 business days from stage entry

Formal Investigation Stage Rules:

Entry rule:

WHEN StageExited (Informal Resolution โ€” rejected path)
OR
WHEN StageCompleted (Intake & Triage) IF classifiedSeverity == "high"
interrupting: false

Complete rule:

WHEN TaskCompleted (Investigator Report)
IF investigationFindings != null
   AND (hrAssessment.legalFlag == false OR legalReviewNotes != null)
ACTION: advance to Decision

The IF condition ensures the case does not advance to Decision while Legal Review is still in flight.


Step 10: Build the Decision Stage

Tasks:

Task 1 โ€” HR Director Decision (Human action, Sequential)

  • Assigned to persona: HR Director
  • The director reviews all findings, the investigation report, and (if applicable) legal review notes
  • Output: writes formalDecision (upheld / partially_upheld / not_upheld) and decisionRationale
  • SLA: 5 business days

Task 2 โ€” Communicate Decision (Execute Connector, Sequential, after Task 1)

  • Email connector sends the formal decision letter to the employee
  • run only once = true

Decision Stage Rules:

Complete rule:

WHEN TaskCompleted (Communicate Decision)
IF formalDecision != null
ACTION: advance to Closure

Step 11: Configure Secondary Stage Rules

Employee Clarification:

Entry rule:

WHEN TaskCompleted (Request Clarification event-driven task fires)
IF grievanceDescription.clarificationNeeded == true
interrupting: false

Complete rule:

WHEN Wait for Connector Event (employee replies via portal or email)
IF clarificationReceived == true
ACTION: return-to-origin (send back to the stage that activated this)

Legal Review:

Entry rule:

WHEN StageEntered (Formal Investigation)
IF hrAssessment.legalFlag == true
interrupting: false

Complete rule:

WHEN TaskCompleted (Legal Counsel task)
IF legalReviewNotes != null
ACTION: return-to-origin

Withdrawn:

Entry rule (interrupting by default for secondary stages):

WHEN Wait for Connector Event (withdrawal API call from portal)
OR
WHEN external API call (employee emails withdrawal to HR)
(no IF condition โ€” any withdrawal at any time)
interrupting: true
ACTION: exit the case

Appealed:

Entry rule:

WHEN Wait for Connector Event (appeal submitted via portal within 10 business days of Decision)
IF formalDecision != null AND daysElapsedSinceDecision <= 10
interrupting: true
ACTION: re-enter Formal Investigation (with run-only-once tasks skipped)

This is the rework loop: an appeal sends the case back to Formal Investigation. Tasks marked run only once = true (like Assign Investigator) are skipped โ€” the same investigator handles the appeal. Tasks marked run only once = false (like Gather Evidence and Investigator Report) re-execute with fresh scope.


Step 12: Configure SLAs

LevelSLAAt-Risk ThresholdBreach Action
Case SLA30 business days from submission24 business days elapsedNotify HR Director + escalate to CHRO
Intake & Triage2 business days1.5 daysNotify HR Officer
Informal Resolution10 business days8 daysNotify HR Officer + manager
Formal Investigation15 business days12 daysNotify HR Director
Decision5 business days4 daysNotify HR Director

Pause SLA timers when: Employee Clarification secondary stage is active (waiting on the employee), or Legal Review secondary stage is active (waiting on legal counsel).


Step 13: Configure Stage Personas

PersonaIntake & TriageInformal ResolutionFormal InvestigationDecisionClosure
HR Officerview + actview + actviewviewview + act
Department Manageract (own tasks only)
HR Directorviewviewview + actview + actview
Investigatoract (own tasks only)view
Legal Counselact (legal tasks only)view
Employee (portal)view own caseview + submitview status onlyview decisionview

Step 14: Configure the Case App Layout

In Studio Web, select Configure Case App:

  • Case title: Grievance #{{caseKey}} โ€” {{grievanceCategory}} ({{submittedBy}})
  • Case detail layout:
    • Summary card: submittedBy, department, grievanceCategory, classifiedSeverity, SLA badge
    • Timeline: all stage transitions and task completions
    • Documents tab: evidenceFiles, uploaded statements
    • Decision section (visible after Decision stage): formalDecision, decisionRationale
  • Task inbox columns: task name, assigned persona, SLA due date, case severity badge

Step 15: Publish and Deploy

  1. Click Publish in Studio Web
  2. Version: 1.0.0
  3. Target Orchestrator folder
  4. Deploy

The case is live. Employees submitting via the portal or emailing the grievance inbox will now automatically create a GrievanceCase instance. HR Officers, Managers, and the HR Director each see only the tasks and case data their persona is scoped to in the Case App.


What This Build Demonstrates That the Tutorial Does Not

  • Two independent trigger channels (API + email with IXP Communications Mining) feeding the same case lifecycle
  • An AI Triage Agent that classifies severity and overrides the userโ€™s self-reported value โ€” and why run only once = false matters here
  • A stage that can be bypassed entirely (Informal Resolution) for high-severity cases via a routing condition in the preceding Complete rule
  • A Legal Review secondary stage that runs in parallel with the Formal Investigation primary stage โ€” and a Complete rule that waits for both before advancing
  • An appeal rework loop (Appealed secondary stage re-entering Formal Investigation) with selective task re-execution controlled by the run only once flag
  • SLA pause/resume triggered by secondary stage activation
  • A persona model with five distinct roles including an external-party Investigator persona
  • The design smell of two tasks writing to one field โ€” and how to fix it by splitting into named fields

Part 6: A Second Pattern โ€” IT Change Request Management

The grievance case above showed human-driven routing and a human-initiated rework loop (an appeal). This second example is deliberately different: an IT Change Request (CR) Management case, which demonstrates system-driven routing and an automatic rework loop with zero human routing decisions.

Why IT Change Requests Need Maestro Case

An IT change request is a request to modify a production system. The path it takes is never fixed:

  • Standard, pre-approved, low-risk changes should skip the full review board and fast-track to approval
  • Normal changes go through a full Change Advisory Board (CAB) review
  • Emergency changes bypass the CAB entirely and route to an Emergency CAB, with a mandatory post-implementation review
  • A CAB rejection sends the request back to the requester for rework
  • A failed implementation must trigger an automatic rollback and re-enter risk assessment with the failure as new evidence

No single flowchart captures all of this โ€” which is exactly the test from Part 1.

Stage Map

[Submission & Classification] โ†’ [Risk Assessment] โ†’ [CAB Review] โ†’ [Implementation] โ†’ [Post-Implementation Review] โ†’ [Closure]
                                                            โ†•
                        [Emergency CAB]          (secondary โ€” bypasses standard CAB)
                        [Fast Track]             (secondary โ€” skips CAB for low-risk standard changes)
                        [Rework Required]        (secondary โ€” CAB rejects; returns to requester)
                        [Rollback]               (secondary โ€” implementation fails; mandatory)
                        [Withdrawn]              (secondary โ€” requester cancels)

Pattern 1 โ€” Classification-Driven Routing

The Submission & Classification stage includes an AI Agent that reads the change description and classifies two things: change type (standard / normal / emergency) and risk level (low / medium / high / critical). These two computed fields then determine which path the case takes:

IF changeType == "standard" AND riskLevel == "low"
  โ†’ Fast Track secondary stage activates, interrupting = true
  โ†’ CAB Review is skipped entirely

IF changeType == "emergency"
  โ†’ Emergency CAB secondary stage activates, interrupting = true
  โ†’ Standard CAB Review is bypassed

IF changeType == "normal"
  โ†’ Standard CAB Review primary stage proceeds normally

This is conditional stage activation: the same case plan serves three structurally different journeys, determined entirely by what the classification agent writes to the entity.

Pattern 2 โ€” The Automatic Rollback Loop (No Human Routing Decision)

This is the pattern worth studying closely, because it shows Maestro Case orchestrating a correction without anyone deciding to correct it.

  1. An RPA-based Implementation Monitor task watches the change execution and writes implementationOutcome = "failed" to the case entity if the deployment errors out
  2. An event-driven Exit rule on the Implementation stage is watching for exactly this: WHEN TaskCompleted (Implementation Monitor)IF implementationOutcome == "failed"ACTION: activate Rollback secondary stage
  3. Rollback is interrupting = true โ€” it immediately takes over, pausing whatever else was running in Implementation
  4. The Rollback stage executes the technical rollback via an RPA workflow and writes rollbackOutcome to the entity
  5. The Rollback Complete rule does not send the case back to Implementation โ€” it sends it back to Risk Assessment: WHEN TaskCompleted (Rollback execution)IF rollbackOutcome != nullACTION: return-to-origin โ†’ Risk Assessment
  6. On re-entry, Risk Assessment tasks marked run only once = false re-execute. The Risk Agent now reasons over both the original assessment and the new failure data, producing a revised risk score
  7. The case then proceeds through CAB Review again โ€” but this time as a case carrying the memory of its own failed attempt

No human decided to trigger the rollback or to re-run risk assessment. The system detected the failure, the rule matched, and the routing happened automatically. This is the core of event-driven case orchestration: rules react to data changes, not to people clicking buttons.

Case Entity Fields Specific to This Pattern

FieldWritten ByRole in Rules
changeTypeClassification AgentRoutes to Fast Track / Emergency CAB / standard CAB
riskLevelRisk Assessment AgentSets the CAB approval threshold required
implementationOutcomeImplementation Monitor (RPA)Triggers the Rollback Exit rule when โ€œfailedโ€
rollbackOutcomeRollback execution taskGates re-entry into Risk Assessment
cabDecisionCAB Chair (Human action)โ€œapprovedโ€ / โ€œrejectedโ€ / โ€œdeferredโ€
postImplReviewResultPost-Implementation ReviewerRequired field for case closure

How This Differs From the Grievance Case in Part 5

AspectGrievance Case (Part 5)Change Request Case (Part 6)
Rework triggerHuman decision (employee appeals)System detection (implementation fails)
Routing decision-makerHR Officer / HR DirectorNo human โ€” rule fires on entity field change
Re-entry targetSame stage that was exited (Formal Investigation)An earlier stage in the lifecycle (Risk Assessment, not Implementation)
Secondary stage purposeHandle exceptions in the human processExecute automated cleanup, then re-route with enriched data

Studying both patterns side by side is the fastest way to understand the full range of what re-entry rules and secondary stages can do in Maestro Case โ€” from a human appealing a decision, to a robot detecting a failure and the system correcting course on its own.


Part 7: Operating Live Cases โ€” Case Instance Management

Once cases are running in production, the Case Instance Management console in Maestro is where operators monitor health and intervene.

Monitoring Live Cases

The Case Instance Management view shows:

  • All running case instances with status (active, paused, at-risk, breached, failed)
  • Current stage per case
  • SLA indicators
  • Active incidents (failed tasks, stuck transitions)

Operator Actions

ActionWhen to Use
PauseTemporarily halt a case when external input is needed (waiting on a third party, pending a management decision). SLA timers pause.
ResumeRestart after pause. SLA timers resume from where they stopped.
CancelTerminate permanently when a case is no longer viable (fraud detected, duplicate case found).
MigrateMove a live case instance to a newer version of the case plan after deploying a bug fix or process improvement. The current stage and Case Entity data are preserved.
RetryRe-execute a failed task when a transient error (API timeout, system outage) caused the failure.

Managing Incidents

When a task fails or a transition gets stuck, it becomes a case incident. Operators use the incident detail view to:

  • See exactly which task failed and the error message
  • Retry the failed task (for transient errors)
  • Skip the task and proceed (for non-critical tasks only)
  • Migrate to a new plan version if the failure reveals a design issue

Source: The Maestro Case Lifecycle โ€” Case Instance Management


Part 8: The Component Dictionary โ€” Quick Reference

This section provides a quick-reference dictionary of every Maestro Case component. For the full specification, refer to the official Maestro Case Management Component Dictionary.

ComponentWhat It IsKey Properties
CaseA runtime instance of a case plan, identified by a case keycaseID, system key, external key, status, SLA state
Case EntityThe persistent, typed business record at the center of every casefields (input + computed), caseID, writtenBy annotations
Case DocumentsAttachments and files linked to the casecaseID, file type, upload timestamp
Case CommentsNotes and communications added during the lifecyclecaseID, author, timestamp, content
Case PlanThe design-time blueprint defining stages, tasks, rules, and SLAsversion, stages, tasks, rules, triggers, personas
StageA named phase of the casekind (primary/secondary), required/optional, SLA, tasks, entry/complete/exit/re-entry rules
TaskA unit of work inside a stagetype, execution mode, input/output mappings, run-only-once flag, entry rule, SLA
RuleA WHEN/IF/ACTION definition controlling lifecycle movementscope (case/stage/task), event (WHEN), condition (IF), action
Case ManagerThe orchestrator: rules-first + agent fallbackrules, agent (model, user prompt, tools, escalation policy)
Case PersonaA design-time role abstraction scoped to stagesname, stage scope, can-view, can-act
Case AppThe business-user-facing workspacecase list, detail view, task inbox, quick actions โ€” out-of-the-box or custom TypeScript SDK
Case Instance ManagementThe operations console for process operatorspause, resume, cancel, migrate, retry โ€” plus incident management
SLAA time-based expectation at case or stage levelduration, at-risk threshold, breach threshold, escalation rule
Escalation ruleAutomatic action triggered when SLA is at risk or breachedtrigger condition, action (reassign, notify, flag)

Part 9: The Five Architectural Principles to Remember

From the official UiPath documentation:

PrincipleExplanation
Agent-firstAI 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 designRe-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-centricThe Case Entity is the single source of truth. Tasks are decoupled producers and consumers of entity data.
Rules first, agent secondDeterministic 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 separationThe 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.

Source: The Maestro Case Lifecycle โ€” Key Architectural Principles


Quick Reference: Common Mistakes and How to Avoid Them

MistakeImpactPrevention
Two tasks writing to the same Case Entity fieldLast-writer-wins; previous data silently lost; downstream rules failAssign one writer per field; use namespaced field names
Using an Exit rule when you mean a Complete ruleStage terminates mid-flight; required tasks never completeExit = circuit breaker (abandon the stage). Complete = normal finish. Know which you need.
Setting secondary stages as interrupting = falseSecondary stage activates alongside the primary flow instead of taking over โ€” causing concurrent conflicting statesSecondary stages default to interrupting = true for a reason. Override only when you explicitly want parallel operation.
Forgetting run-only-once on tasks that should not re-execute on re-entryEmail sent twice, duplicate API calls, conflicting computed valuesMark run-only-once = true on any task whose side effects must not repeat
No SLA defined at stage levelCases breach overall SLA before operators can identify which stage is the bottleneckSet stage-level SLAs so monitoring shows exactly where cases are getting stuck
External key not configured when case originates in another systemOperators cannot correlate the Maestro case to the source system recordConfigure external key at design time using the source systemโ€™s ID
Case entity fields referenced in rules before they are writtenRule never evaluates to true; case gets stuckValidate the field ownership chain: task writes field โ†’ field changes event fires โ†’ rule evaluates

Documentation Reference

All content in this guide is grounded in official UiPath documentation. No claims have been made that are not supported by the linked sources.

TopicSource
Maestro Overviewdocs.uipath.com/maestro โ€” Overview
BPMN vs. Case decision frameworkdocs.uipath.com/maestro โ€” BPMN vs Case
Introduction to Maestro Case + Core Conceptsdocs.uipath.com/maestro โ€” Introduction to Maestro Case
The full lifecycle โ€” 5 layersdocs.uipath.com/maestro โ€” Case Lifecycle
Designing the case entity schemadocs.uipath.com/maestro โ€” Entity Schema
Defining case keysdocs.uipath.com/maestro โ€” Case Keys
Task I/O and write-back contractsdocs.uipath.com/maestro โ€” Task I/O
Exit rules and early stage terminationdocs.uipath.com/maestro โ€” Exit Rules
Supplier onboarding (official UiPath example โ€” not reproduced in this guide)docs.uipath.com/maestro โ€” Supplier Onboarding
Insurance claims tutorial (official UiPath example โ€” not reproduced in this guide)docs.uipath.com/maestro โ€” Insurance Claims Tutorial
Component dictionarydocs.uipath.com/maestro โ€” Component Dictionary

Have questions about Maestro Case? Drop them in the comments below. Built something with Maestro Case and want to share the pattern? I would like to hear about it.

Share This Article
Follow:
Satish Prasad An NIT Kurukshetra alumnus and Intelligent Automation Architect, Satish brings 15+ years of battle-tested experience deploying over 100 production bots across Investment Banking and Logistics. Today, he bridges the gap between Data Analytics and the frontier of Agentic AI, building autonomous agents that transform complex business logic into intelligent automation. Catch his latest insights on the evolution of tech vibes and digital autonomy.
Leave a Comment