UiPath Documentation
maestro
latest
false

Maestro user guide

Modeling primary and secondary stages

Overview​

Primary stages represent the sequential happy-path phases of a case (for example, Intake → Review → Settlement → Closure), while secondary stages handle exception paths such as requesting additional information, denying a case, or processing a withdrawal. Use this guide to build both stage kinds in the Case Plan Designer in Studio Web, configure their rules, and connect them to create a complete case lifecycle.

Audience: Intermediate — Automation Developers, Business Architects

Prerequisites​

  • Access to Studio Web.
  • A case project already created in Studio Web with a case name, case key, and trigger configured. See Create a case and set up the trigger for details.
  • A case entity [Coming Soon] available via Data Fabric, VDO, or case trigger, with fields that stage rules can evaluate (for example, decision, action).
  • Familiarity with case entity fields and how tasks write back to them.

Step 1: adding primary stages to the canvas​

Primary stages define the happy path — the sequential phases every case follows under normal conditions.

Opening the case plan designer​

  1. In Studio Web, open your case project.
  2. Navigate to the case plan canvas.

Adding stages​

  1. Select the + icon beside an existing stage, or select the + icon directly on the canvas, to add a new stage.

  2. Repeat to create all the primary stages for your process. For example, a property insurance claims case uses four primary stages:

    • Intake
    • Review
    • Settlement
    • Closure

  3. Arrange the stages in the expected order of progression from left to right.

Step 2: configuring primary stage rules​

Each primary stage carries rules — entry, complete, exit, and optional re-entry — that control its lifecycle. Configure these rules using case entity fields populated by tasks.

Setting Entry rules​

Define when each stage activates. The first primary stage typically activates on case creation; subsequent stages activate when the preceding stage completes.

  1. Select a stage on the canvas to open its configuration panel.
  2. Configure the Entry rule for the stage. Examples:
    • Intake: Activates on case creation (default for the first stage).
    • Review: Activates when Intake tasks complete.
    • Settlement: Activates when the Review decision is a qualifying outcome (for example, vars.adjusterDecision == "approve").

Setting Complete and Exit rules​

Define when the stage finishes normally (Complete rule) and when it should bail out early (Exit rule).

  1. In the stage configuration panel, set the Complete rule and, if needed, the Exit rule.
  2. Use case entity fields and/or task completion status. Examples:
    • Intake → Review: Complete rule fires when required Intake tasks complete and vars.validationPassed == true.
    • Review → Settlement: Complete rule fires based on the decision or action from Review tasks; Exit rule fires early if a denial decision is detected.

Configuring re-entry rules (optional)​

Re-entry rules allow a case to return to a previously completed stage for rework. This is what makes case management non-linear.

  1. Open the Re-entry rule panel on the originating stage (the stage that decides rework is needed).
  2. Define the rule. For example:
    • Review → Intake (rework): WHEN the claim officer review task completes IF vars.decision == "Claim is missing key incident reports".
  3. On the target stage (Intake), confirm the per-task runOnlyOnce flags reflect the rework intent. Tasks re-run by default; set runOnlyOnce: true on tasks whose previous output is still valid (for example, Extract claim details). Tasks like Incident reports Robot and Anomaly agent (Snowflake) stay at the default false so they re-execute. See Configuring a rework loop for the full pattern.
Note:

When a stage is re-entered, tasks with runOnlyOnce: false (the default) re-execute and produce fresh output. Tasks with runOnlyOnce: true are skipped and retain their previous results.

Step 3: adding secondary stages​

Secondary stages handle exception paths — situations where the case deviates from the happy path. Toggling a stage as secondary removes its incoming edges and lets it activate from anywhere when its entry rule evaluates true. The stage's Complete rule (or Exit rule) action then decides what happens next: typically Return-to-origin, Exit the case, or Wait for manual selection.

Three common patterns:

  • Return-to-origin — the case routes back to the stage that activated this one after the secondary stage completes.
  • Case-ending — the case ends when the secondary stage completes (action = Exit the case or Complete the case).
  • Connector-driven entry with case-ending exit — an external event triggers entry into the secondary stage, and the case ends on completion.

By default, a secondary stage's Entry rule has interrupting = true, so activating it exits any other active stages and forces the case into the secondary stage. Override per stage if you want parallel activation.

Adding a return-to-origin secondary stage​

Use this pattern when the case must collect additional information and then resume processing from the stage that initiated the detour.

Example: Pending with Customer

  1. Add a new stage to the canvas, name it (for example, Pending with Customer), and mark it secondary.
  2. Configure two Entry rule branches so different outcomes from the originating stage can route the case here:
    • vars.decision == "Request documents"
    • vars.decision == "Missing reports"
  3. Set the Complete rule action to Return-to-origin so the case routes back to the stage that activated this one (for example, Review) when all tasks complete.
  4. Add tasks to this stage (for example, Request documents, Document agent).

Adding a case-ending secondary stage​

Use this pattern for final outcomes that end the case without returning to the happy path.

Example: Denied

  1. Add a new stage to the canvas, name it (for example, Denied), and mark it secondary.
  2. Configure the Entry rule based on a decision from an upstream stage:
    • vars.action == "Reject" (triggered from Review).
  3. Set the Complete rule action to Exit the case. When all tasks complete, the case ends.
  4. Add tasks to this stage (for example, Send denial packet, Generate audit report).

Adding a connector-driven case-ending secondary stage​

Use this pattern when an external event — not an internal rule — triggers the case to enter a case-ending state.

Example: Withdrawn

  1. Add a new stage to the canvas, name it (for example, Withdrawn), and mark it secondary.
  2. Set the Entry rule to listen for a connector event:
    • Select the Connector (for example, Microsoft Teams).
    • Select the Trigger (for example, Channel Message Posted).
    • Add filters or parameters as needed.
    • When this external event arrives, the case enters the Withdrawn stage automatically. Because the entry rule defaults to interrupting = true, any active stages are exited.
  3. Set the Complete rule action to Exit the case. When all tasks complete, the case ends.
  4. Add tasks to this stage (for example, Send withdrawal packet, Generate audit report).

Step 4: adding tasks to each stage​

  1. Inside each primary or secondary stage, select + Add Task.
  2. Select the task type (Human action, RPA, API workflow, Execute Connector, AI Agent, Maestro Agentic Process, or Child Case).
  3. Configure inputs and outputs for each task by mapping case entity fields.
  4. Set an Entry rule on tasks where conditional execution is needed (for example, run a task only when Amount >= 1000).

Step 5: validating, publishing, and deploying​

  1. Validate the case plan to confirm that all stages, tasks, and rules are correctly configured.
  2. Publish the case plan from Studio Web.
  3. Deploy and activate the published plan in a target folder.
  4. Monitor live case instances in Case Instance Management and verify that cases move through primary and secondary stages as expected.

Expected outcome​

After completing these steps, your case plan includes:

  • Primary stages arranged in a sequential happy path, each with entry, complete, exit, and optional re-entry rules.
  • Secondary stages that handle exception paths — returning to origin for additional information, ending the case on denial, or responding to external connector events.
  • Tasks within each stage that read from and write back to the case entity [Coming Soon], driving stage rule evaluation.

Cases created from this plan follow the happy path under normal conditions and route to secondary stages when exceptions occur. Terminal secondary stages close the case, and return-to-origin secondary stages resume processing from the point of departure.

Use case example​

Scenario: Property Insurance Claims

StageTypeBehavior
IntakePrimaryFirst stage. Extracts claim details, looks up policy, runs anomaly detection.
ReviewPrimaryCoverage check, appraisal, auditor agent, claim officer verification.
SettlementPrimaryFulfilment, settlement processing, communications agent.
ClosurePrimaryClaim packet creation, audit report generation.
Pending with CustomerSecondary (Complete action: Return-to-origin)Requests missing documents. Returns to Review on completion.
DeniedSecondary (Complete action: Exit the case)Sends denial packet and generates audit report. Case ends.
WithdrawnSecondary (connector-driven entry; Complete action: Exit the case)Activated by a Microsoft Teams message. Sends withdrawal packet. Case ends.

Troubleshooting​

SymptomCauseResolution
A secondary stage never activatesEntry rule does not match any case entity value at runtimeVerify that upstream tasks write the expected values to the case entity fields referenced in the entry rule's IF clause.
Re-entry triggers an infinite loopNo mechanism prevents repeated re-entryAdd a re-entry counter field to the case entity [Coming Soon] and include a threshold in the re-entry rule (for example, vars.reentryCount < 3). Escalate to a human when the threshold is exceeded.
Return-to-origin stage does not route backComplete rule action is not set to Return-to-originOpen the secondary stage configuration and confirm the Complete rule action is Return-to-origin, not Exit the case.
Connector-driven stage does not activate on external eventConnector trigger is misconfigured or filters are too restrictiveVerify the connector and trigger event in the stage entry rule configuration. Check filter parameters against the actual event payload.

Limitations​

  • Case user roles and access scoped to individual stages is not yet available.
  • Native case-entity support in Data Fabric is not yet available.
  • Variable references in stage rules must use fields defined in the deployed case plan version. If a field does not appear, verify that the correct version is selected.

Next steps​

Was this page helpful?

Connect

Need help? Support

Want to learn? UiPath Academy

Have questions? UiPath Forum

Stay updated