Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Configuring stages for your application

Updated on May 19, 2016

As part of the process of creating an application, you can create one or more case types, according to the information that you provide in the New Application wizard. Each of these case types contains three stages by default. You can add primary stages or alternate stages, delete stages, and reorder stages to model the life cycle of your case.

Although the screen captures and specific options in this articles are from version 7.1 of the Pega Platform, the conceptual information in this article is relevant to versions 7.1 through 7.1.7. For more information about stage configuration in later versions of the Pega Platform, refer to the following help topics:

The following figure shows a stage-based diagram of a purchase request case.

A stage-based diagram of a purchase request case

Stages in the Purchase Request case type

You can configure each stage with steps and optional actions, which can range from single tasks to complex, multi-step processes. The Pega 7 Platform manages automatic steps, starting them either in sequential order or simultaneously when the stage is entered. Optional actions are available during the appropriate stage, but are performed at the discretion of the end user.

After all the actions in a primary stage have been completed, the case can automatically transition to the next primary stage, while controlled transitions allow cases to move to any stage. Application designers can also block entry into a stage if initial criteria are not met, or skip a stage entirely under certain conditions.

After all the required stages have been completed, the case can be resolved. To indicate this point – and to prevent the case from transitioning automatically to another stage – you can designate a stage as a resolution stage. The resolution stage provides a visual indicator of the end of the life cycle of the case, but does not automatically resolve the case.

Adding, removing, and reordering stages

A stage represents the first level of case decomposition. Stages are high-level groupings, which application designers use to organize the required and optional tasks that are performed as a case is processed and resolved. You can use stages to develop a sense of the tasks that must be performed in sequence, those that can occur in parallel, and optional tasks that can be performed at the discretion of the end user.

If you think of steps as the tasks that are required to process a case, stages are a means of sequencing those tasks and establishing dependency relationships among them.

By default, Application Express provides three stages when a case type is created. As a best practice, cases should not exceed nine (9) primary stages – a case that contains more stages might not have been fully decomposed, and might contain multiple cases or child cases.

As a general rule, cases should include at least three (3) stages. Remember, however, that stages are a tool to aid in managing a process. If two stages are sufficient to establish an understanding of the life cycle of a case, an application designer should not feel compelled to create additional stages.

A child case often can consist of fewer than three (3) stages, however, because it represents only a portion of the overall business process.

Adding a primary stage

To create a primary stage, click the icon to the right of the last stage. This action automatically adds a new stage to the end of the case life cycle.

Case with one stage, with the Add Stage icon (a plus sign) highlighted

Add stage option for a case type

Case with two stages

A case type with two stages

Adding an alternate stage

Unlike primary stages, which are intended to be run for most – if not all – cases that are defined by a case type, alternate stages allow you to group exception actions or "ad hoc" steps. To add an alternate stage, click the Actions menu on the Case Type form and click Configure Alternate Stages. Alternate stages appear below the primary stages, and are indicated with a gold background, rather than a blue background.

Alternate stage for a case type, in this example, for a rejection

Alternate stage for a case type, as indicated by the gold background for the stage label

When considering the use of an alternate stage, keep the following points in mind:

  • Alternate stages do not support automatic transitions. To exit an alternate stage, you must configure a controlled transition.
  • Alternate stages should not be used in place of a child case.
  • An alternate stage can represent either an exception path or a primary stage that does not occur at a defined point in the overall case life cycle.

Deleting a stage

To delete either a primary or an alternate stage, click the Stage Options menu icon icon_StepOptions.png and click Delete this stage. When you delete a primary stage, Case Designer automatically renumbers the following stages to ensure the success of any automatic stage transition.

Reordering primary stages

You can change the order of primary stages as needed to model the life cycle of your case. Click Edit Stages to open The Edit Primary Stages dialog box, which allows you to drag and drop stages to reorder them. From this dialog box, you can also add new stages and delete existing ones.

Using the Edit Primary Stages dialog box to reorder case stages

The Edit Primary Stages dialog box in Case Designer

When you click OK, Case Designer refreshes to reflect your changes.

Configuring a stage

For each stage, you can use the Stage Configuration dialog box to configure stage transition options, set the stage to be a resolution stage, and add optional, stage-level processes and actions. To open the Stage Configuration dialog box, click the Stage Options menu icon and click Configure stage behaviors.

The Stage Configuration dialog box

The Stage Configuration dialog box in Case Designer

Automatic and optional actions

Within each stage, steps represent processing actions that must be taken to complete the stage and ultimately resolve the case. Steps are performed in a prescribed order, managed by the Pega 7 Platform. Optional actions can be left to the end user's discretion.

Automatic steps

By default, the steps added to a stage are processed automatically, in sequential order.

Automatic steps, which is automatically sequenced as the case is processed

Two sequential steps in a stage

Steps can also be configured to run immediately when the case enters that stage.

To distinguish between steps that occur in sequence and those that occur on entering the stage, a blue double line divides parallel processing paths within the stage. Within each path, all actions occur in sequential order. When processing a case, the end user can perform an available step in any processing path.

Two parallel processing paths in a stage

Parallel steps in a stage

In the previous example, Send Email and Enter Accounting Information are actions available to the end user when the case enters the Procurement stage. If the end user then completes the Enter Accounting Information step, the next actions are Send Email and Create Orders.

By default, the end user is prompted to perform the first (topmost) available step when the case enters the stage, although all current steps are available on the Overview tab of the case, if the end user has the required security privileges.

With parallel paths, the case can be pending for multiple end users at the same time

The run-time view of a case with parallel steps

In the previous example, the Get Program Approval assignment is pending for one user, while the Get IT Approval assignment is pending for another user. Either user can log in and process their assignment, without disrupting the case flow for the other user.

To skip a step, you can configure a When rule as a condition for performing the action. When the case reaches the action, the Pega 7 Platform evaluates the When rule. If the result is true, the Pega 7 Platform skips the action and advances to the next action in the sequence.

Optional actions

Optional actions – either processes or flow actions – can be added to the stage configuration, and do not appear as steps within Case Designer. To perform an optional action, select the action that you want from the Other Actions menu.

An optional action configured for a stage can be run from any assignment within that stage, if the end user has the required security permissions. To restrict the availability of an optional action, configure a When rule to test whether the action should be available to the end user. Optional actions restricted in this manner are available to the end user only when the When rule returns a true result.

Transitioning to another stage

In order to continue processing, a case must transition to the next stage after a stage is complete. For primary stages, the default option is an automatic transition to the next primary stage. To direct a case to a different primary stage, or an alternate stage, you must specify a controlled transition. Controlled transitions can be configured for any primary or alternate stage, and can occur either at a specific point in a process, or​ as an optional action​. You can also prevent a transition if certain qualifications are not​ met, and skip a primary stage altogether under specific circumstances​.

Automatic transitions at stage end

By default, all primary stages automatically transition to the following stage after all the steps in that stage are either completed or skipped. This behavior ensures that the case is always available for processing. In Case Designer, stages with automatic transitions appear with an angled right edge.

Stage with an automatic transition, as indicated by the angled right edge

A stage that automatically transitions to the next stage in the sequence

To disable the automatic transition for a primary stage, open the Stage Configuration dialog box and click Occurs manually by end user or as defined in a process model.

Selection on the Stage Configuration dialog box for disabling automatic transition

Transition options for a stage

Controlled transitions

To allow transitions to alternate stages, or before the completion of the stage, you can add a controlled transition to a stage. Controlled transitions can be either added to a specific point in a process by use of the Change Stage smart shape, or left to the end user by use of the Change Stage flow action as an optional action.

When the Pega 7 Platform encounters a Change Stage smart shape in a process, it automatically transitions the case to the specified stage. The Change Stage shape is most useful for automating transitions to and from alternate stages.

The Change Stage flow action allows the user to select the stage to which the case transitions. You can add the Change Stage flow action to an individual assignment as a local action, to a connector, or to the entire stage as an optional action.

Skipping a stage

In certain situations, you might have to skip a primary stage entirely and proceed to the following stage. To avoid entering a stage, you can create a testable condition with a When rule, referenced from the Stage Configuration dialog box.

If the When rule returns a true (positive) result, your application skips the stage – and all of its actions – and proceeds to the next primary stage. You cannot skip an alternate stage, because your application cannot identify the next stage to enter.

To configure a case to skip a specific stage:

  1. Create a When rule to test a specific condition and return a true or false answer. Remember that in the event of a true result, the Pega 7 Platform skips the stage.
  2. Click the Options menu on the stage, and click Configure stage behaviors.
  3. In the Stage Configuration menu, select your When rule in the Skip stage when field.
  4. Click OK, and save the case.

Whenever your application attempts to transition to a new primary stage, it evaluates any skip condition configured for the stage. If the When rule returns a false result, the case enters the stage. If the When rule returns a true result, the Pega 7 Platform skips the stage and proceeds to the next primary stage.

If your application cannot transition the case into a new stage, processing of the case halts at the current step. If this happens, an end user must manually perform a transition to a stage that the case can enter.

Validating a case prior to stage entry

In certain situations, you might have to confirm that a case has been sufficiently processed before entering a stage. To ensure that a case enters a stage only when it meets certain qualifying criteria, you can use a validation rule to test the case.

Cases that fail validation do not enter a new stage. Instead, the end user receives an error message indicating the failure, and the case remains in the current stage.

When a case fails stage-entry validation, a new transition attempt must be made to advance the case, because the Pega 7 Platform does not re-attempt the transition. When using stage-entry validation on either an automatic transition or a transition performed by the Change Stage smart shape, add the Change Stage flow action to the stage being exited as an optional action, which allows the user to attempt the transition after the validation conditions are satisfied.

Resolving a case

After you have decomposed the life cycle of a case into stages, the last stage should be identified as a resolution stage. Resolution stages are indicated in Case Designer with a vertical right edge, rather than an angled edge, and a red line across the bottom.

Resolution stage, as indicated by the vertical right and and red horizontal line

A stage that resolves a case

Completing a resolution stage does not automatically resolve the case. Cases in the resolution stage must be resolved by changing the status of the case to a "Resolved-" status, such as Resolved-Completed or Resolved-Withdrawn.

Unlike other stages, resolution stages do not allow an automatic transition on completion, although controlled transitions – either by using the Change Stage smart shape or the Change Stage flow action – can be configured.

A case can contain any number of primary or alternate resolution stages.


Pega Platform 7.1.1 - 7.1.7 Case Management Financial Services Healthcare and Life Sciences Insurance Communications and Media Government Healthcare and Life Sciences Consumer Services

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us