Optimizing Case Design: Stage Transitions, Wait Shapes, and Enterprise Pipelines

Case design is the backbone of every Pega application, yet it is the area where well-meaning teams most often paint themselves into a corner. A case type that models the business cleanly will scale, stay testable, and survive years of change; one that buries logic in flow shapes and over-uses assignments becomes a maintenance tax that compounds with every release. This guide walks through the case lifecycle model end to end and shows how to make the architectural choices that keep cases fast and clean.

The case lifecycle model: stages, processes, steps

Pega's Case Lifecycle Management organizes work as a hierarchy you read top to bottom and left to right. A case type contains stages; each stage contains one or more processes (flows); each process contains steps (single actions, automations, or sub-processes). The lifecycle view in App Studio is not just documentation — it generates the underlying flow rules that actually run.

The mental model matters because it dictates where logic belongs:

• Stages represent meaningful milestones in the business — Intake, Review, Fulfillment, Resolved. A user or auditor should understand case status by reading the stage name alone.
• Processes group the work that happens inside a stage. A Review stage might hold a Manager Approval process and a Compliance Check process running in parallel.
• Steps are the atomic units: collect information from a user, run an automation, or call a sub-case.

Keep stages coarse-grained. If you find yourself creating a stage per screen, you are modeling UI navigation, not the business lifecycle.

Primary, alternate, and resolution stages

Pega distinguishes three kinds of stages, and using them correctly is what makes a case readable:

Stage type	Purpose	Typical example
Primary	The expected "happy path" sequence the case normally follows	Intake → Review → Fulfillment
Alternate	Off-track paths reached only by an explicit Change Stage action	Escalation, Rework, On Hold
Resolution	Terminal stages that close the case with a resolved status	Resolved-Completed, Resolved-Rejected

A resolution stage sets a pyStatusWork value beginning with Resolved-, which is what reporting and SLA logic keys off. Do not improvise a "Done" primary stage that merely stops — set a proper resolved status so downstream analytics, archival, and the case manager portal behave correctly.

Stage transitions

How a case moves between stages is one of the highest-leverage design decisions. Pega supports several transition types:

1. Automatic on stage completion — when the last step of the last process in a stage finishes, the case advances to the next primary stage. This is the default and should cover the majority of transitions.
2. Manual transition — a user explicitly moves the case via a Change Stage step or a case-wide action, often into an alternate stage.
3. Conditional transition — the case skips or selects a stage based on a when rule evaluated at stage completion.

You configure conditional movement through the stage's transition settings rather than by wiring decision shapes between stages. Express the condition as a declarative when rule so it is reusable and testable:

When rule: RequiresComplianceReview
  applies-to: PegaTrainer-Loan-Work-Application
  expression: .LoanAmount > 50000 OR .ApplicantRiskTier == "High"

Reference that when rule from the stage configuration so the lifecycle reads as a clear business statement. The alternative — embedding the same boolean inside a decision shape mid-flow — hides the rule from the lifecycle view and from anyone auditing the case type.

Stage entry and exit validation

Stages support entry and exit validation so a case cannot drift into an invalid state. Exit validation is the more common pattern: before a case leaves a stage, run a validate rule to confirm the required data is present and consistent.

<!-- Conceptual shape of a Rule-Obj-Validate referenced on stage exit -->
<Validate name="ValidateApplicationComplete" appliesTo="PegaTrainer-Loan-Work-Application">
  <Field name="ApplicantName" required="true"/>
  <Field name="LoanAmount" required="true">
    <Condition expression=".LoanAmount > 0" message="Loan amount must be positive"/>
  </Field>
  <Field name="SubmittedDate" required="true"/>
</Validate>

If validation fails, Pega keeps the case in the current stage and surfaces the messages to the user — no half-populated case slips into Fulfillment. Keep validation declarative and field-scoped; do not pour cross-entity business logic into a single monolithic validate rule.

Wait shapes: pausing a case deliberately

A Wait shape pauses a flow until a defined condition is satisfied. There are two principal modes, and choosing the right one prevents both stuck cases and wasteful polling:

• Wait for a timer / duration — pause until a fixed date-time or for a relative duration (for example, "wait 3 business days" or "wait until the first of next month"). Useful for cool-down periods, scheduled follow-ups, or regulatory waiting windows.
• Wait for a case dependency — pause the parent until one or more child cases reach a specified status (for example, all child Document Verification cases are Resolved-Completed). This is the clean way to coordinate a parent with its spun-off children.

A dependency wait is event-driven: Pega resumes the parent automatically when the watched child status is met, so you avoid building a polling loop. Reach for a wait shape instead of an Assignment whenever no human action is required — an assignment that exists only to "hold" a case is an anti-pattern that pollutes worklists and SLA reporting.

Parallel processing

Real cases rarely run in a single line. Pega gives you three constructs for concurrency:

• Split-For-Each — iterate a process over each element of a page list (for example, run a verification sub-process for every line item on an order). You can configure it to join when all, any, or some iterations complete.
• Split-Join — launch several different named processes in parallel and rejoin once a join condition is met. Use it when distinct work streams (credit check, fraud check, KYC) run concurrently but must converge.
• Spinoff — start a sub-process or child case and do not wait — the parent continues immediately. Pair spinoff with a later dependency wait if the parent eventually needs the result.

A common pattern: spin off independent child cases for parallel work, let the parent proceed through non-dependent steps, then place a wait-for-dependency shape at the convergence point.

Service Level Agreements (SLAs)

Every assignment and every case can carry an SLA that drives urgency and escalation. The four milestones to understand:

• Goal — the target time to complete; a soft target.
• Deadline — the hard target; missing it usually triggers escalation.
• Passed Deadline — a recurring interval applied after the deadline to keep escalating.
• Urgency — a numeric value (0–100) that rises at goal and deadline, raising the assignment's priority in worklists and routing.

SLAs trigger escalation actions — notify a manager, reassign to another worklist, raise urgency, or run an activity. Configure the SLA as a reusable Rule-Obj-ServiceLevel, not as ad-hoc logic:

Service Level: StandardApprovalSLA
  Goal:     2 business days  | urgency +20 | notify assignee
  Deadline: 4 business days  | urgency +40 | escalate to ManagerWB
  Passed Deadline: every 1 business day | urgency +10 | notify ManagerWB
  Calendar: BusinessCalendar-IN

Always set a business calendar on time-sensitive SLAs so weekends and holidays do not silently breach a deadline. For a deeper treatment of timer-driven SLAs in combination with wait shapes, see our walkthrough on Pega Deployment Manager branches and CI/CD where pipeline-stage timeouts use the same mechanics.

Child cases and the case hierarchy

Cases form a parent-child tree. A parent can instantiate children explicitly via a Create Case step, or a child can be spun off. The hierarchy unlocks important behaviors:

• Dependency coordination — parents wait on child status; children can roll status up to the parent.
• Encapsulation — each child is its own case type with its own lifecycle, stages, and SLAs, so complex sub-work stays isolated and independently testable.
• Locking — Pega locks the parent when a child operation requires it; design children to minimize the time a parent lock is held.

Use child cases when a unit of work has its own lifecycle and audit trail. Do not split work into a child case merely to "organize" a flow — that adds locking overhead and instance bloat without business benefit.

Performance optimization

The single most important rule: prefer declarative processing over procedural flow logic. Declarative rules (declare expressions, when rules, data transforms triggered on property change) recompute automatically and run outside the flow execution path, so they are cheaper and easier to test.

Concrete guidance:

• Move calculations out of flows. A Declare Expression that derives TotalPremium from line items beats a utility shape recalculating it on every pass.
• Avoid heavy logic in flows. Decision and utility shapes should orchestrate, not compute. Push real work into data transforms, activities scoped narrowly, or declarative rules.
• Minimize assignments. Every assignment is a database write, a worklist entry, and an SLA timer. Combine screens with a single multi-step form rather than chaining assignments. If a pause needs no human, use a wait shape.
• Keep clipboard pages lean. Large embedded page lists copied across stages slow every commit. Load detail data on demand.
• Lazy-load and defer. Defer expensive data lookups until the step that actually needs them.

Anti-patterns to avoid

• The mega-flow — one giant flow with dozens of decision shapes instead of stages. It defeats the lifecycle view and is nearly impossible to test.
• Assignment-as-wait — using a routed assignment purely to hold a case for a timer. Use a wait shape.
• Business logic in connectors — embedding decisions inside integration steps so they never appear in the lifecycle.
• Status by convention — leaving pyStatusWork unset on terminal stages and relying on stage name. Set a real Resolved- status.
• Over-spinning child cases — creating children for organization rather than genuine sub-lifecycles.

Testing case types with PegaUnit and scenario testing

A well-designed case type is testable, and Pega ships two complementary tools. PegaUnit tests individual rules — data transforms, when rules, decision tables — by asserting outputs against expected values. Scenario testing drives a case through its lifecycle end to end against the live application, asserting that the case reaches the expected stage and data state.

A pragmatic split:

1. Unit-test the declarative rules — RequiresComplianceReview, premium calculations, validation conditions — with PegaUnit.
2. Scenario-test the full path: create a case, complete Intake, confirm the conditional transition routes high-value applications into compliance, and verify the case resolves with the correct status.

{
  "testCase": "HighValueLoanRoutesToCompliance",
  "applyTo": "PegaTrainer-Loan-Work-Application",
  "given": { "LoanAmount": 75000, "ApplicantRiskTier": "High" },
  "steps": [
    { "action": "createCase",   "stageExpected": "Intake" },
    { "action": "completeStage", "stage": "Intake" },
    { "assert": "currentStage",  "equals": "ComplianceReview" },
    { "action": "approve",       "by": "ComplianceWB" },
    { "assert": "pyStatusWork",  "equals": "Resolved-Completed" }
  ]
}

Run these in your pipeline so a regression in a transition condition fails the build, not production. If you want hands-on coaching turning these patterns into a clean, tested case type, our Pega mentorship program and structured Pega training cover case design with real project examples.

Key takeaways

• Model the business with coarse stages > processes > steps; let the lifecycle view read like the business itself.
• Use primary, alternate, and resolution stages deliberately, and always set a real Resolved- status on terminal stages.
• Drive transitions with declarative when rules and protect stage boundaries with entry/exit validation.
• Choose wait shapes (timer or case-dependency) instead of assignments whenever no human action is required.
• Coordinate concurrency with split-for-each, split-join, and spinoff, converging via dependency waits.
• Configure SLAs (goal, deadline, passed-deadline, urgency, escalation) with a business calendar.
• Optimize by favoring declarative over procedural logic and minimizing assignments and clipboard bloat.
• Make every case type testable with PegaUnit for rules and scenario testing for end-to-end lifecycle behavior.

Ready to pressure-test your own case design or get unblocked on a tricky stage-transition problem? Get in touch with our team and we will pair you with a senior Pega mentor who has shipped these patterns in production.