Skip to main content
Verify the version tags to ensure you are consuming the intended content or, complete the latest version.

Managing flow changes for Cases in flight

There are several fundamental approaches to update the flows that are already in production safely in your Pega Platform™ application. Because each application configuration and the business setting are unique, choose the approach that best fits your situation.

Caution: Whichever approach you choose, always test the assignments with existing cases, not just the newly created cases.

Approach 1: Move existing assignments

In this approach, you set a ticket that is attached to the same flow, change to a new stage, or restart the existing stage. In-flight assignments advance to a different assignment where they resume processing within the updated version.

You run a bulk processing job that locates every outdated assignment in the system affected by the update. For each affected assignment, bulk processing should call Assign-.OpenAndLockWork followed by Work-.SetTicket, pxChangeStage, or pxRestartStage. For example, you can run a Utility shape that restarts a stage (pxRestartStage).

The following example shows a bulk assignment activity that uses SetTicket:

Move Assignment

After you configure the activity, you deploy the updated flow and run the bulk assignment activity.

Note: The system must be offline when you run the activity.

For example, a small insurance underwriting branch office processes about 50 assignments a day; most are resolved within two days. In addition, there is no overnight processing. You run a bulk process because the number of unresolved assignments is relatively small, and the necessary locks can be acquired during the evening. Note that it is not necessary to use the Commit method.


  • A batch process activity directs assignments by performing the logic outside the flow.
  • You do not need to update the flow by adding a Utility shape to the existing flow.
  • The activity enables you to keep the processing logic in the flow, makes upgrades easier, and also facilitates flow configuration and maintenance in App Studio.


  • It might be impractical if the number of assignments is large or if there is no time period when the background processing is guaranteed to acquire the necessary locks.

Approach 2: Use dynamic class referencing

For case-specific rules, you use dynamic class referencing to establish the differentiation of a flow’s current state from its desired future state. 

On case creation, the system immediately establishes the value of the differentiating property, pxCreateDateTime. In combination with the differentiation value, the pxObjClass of the case changes. The pyDefault data transform for the case can determine the current year through the following logic:

<var>Param.CurrentYear</var> = @toInt(@String.substring(@DateTime.CurrentDateTime(),0,4))

Then, you change the pxObjClass of the case by using the following logic:

.pxObjClass => .pxObjClass + "-Y" + Param.CurrentYear

Although this approach requires you to create a class for every year, the approach does not behave the same as as-of-date circumstancing.

One way to avoid creating a class for each year is to skip one or more years when pointing to the direct parent class if no flow changes occurred in those years that might impact the in-flight cases. Instead of always using Param.CurrentYear, you can determine the most recent year when class specialization occurred by using a data page with the following logic:

Param.ContractYear = D_ContractYearToUse[ObjClass:Primary.pxObjClass, StartYear:Param.CurrentYear].ContractYear 

.pxObjClass =>.pxObjClass + "-Y" + Param.ContractYear 

For example, you can you the following logic in D_ContractYearToUse:

<code>.ContractYear = Param.StartYear</code>

<code>For each page in D_StartsWithClassNameDesc[ObjClass:Param.ObjClass].pxResults </code>

<code>Param.Year = <the last 4 characters in> pyClassName </code>

<code>IF (Param.Year only contains digits AND Param.Year <= Param.StartYear) </code>

<code>THEN Primary.ContractYear = Param.Year </code>

<code>Exit Transform </code>


  • Classes in the ruleset stack of an application are requestor-level information and are compatible with the ability of Pega Platform to display the current state of a case. The system does pick the right class at run-time in conjunction with the configuration of the application rule. The application rules in the following table are necessary only during design and development. In production, you use dynamic class referencing to establish the pxObjClass that each case type uses.
    Name Work ID prefix Implementation class
    BookEvent EVENT- FSG-Booking-Work-BookEvent-Y2022
    WeatherPrep WPREP- FSG-Booking-Work-WeatherPrep-Y2021
    RoomsRequest ROOMS- FSG-Booking-Work-RoomsRequest-Y2020


  • There are arguments against using this dynamic class referencing. The following table addresses each argument:
    Argument Counterargument
    Creating classes takes extra time. It takes very little time to create and configure a new class to extend another class directly. If you need to create a class only once a year, the amount of time to perform this task is negligible compared to other development tasks that would take place within that year.
    The inheritance path can become too long and or impact rule resolution performance. There is no restriction on the depth of an inheritance hierarchy. The system reaches other limits before inheritance hierarchy becomes an issue.
    Extra classes complicate future database table storage decisions. Class groups, work pools, and Data-Admin-DB-Table records determine where the system persists data.
    Does not scale. Increasing the number of unique pxObjClass values in the same database table does not affect system architecture.

Approach 3: Switch the application version of in flight cases

Switch the application version of in-flight cases so that users can process existing assignments without updating the flows. Add a new access group that points to the previous application version. Then, add the access group to the operator ID record to switch to the application from the user portal and complete the existing assignments.

For example, an application undergoes a significant reconfiguration. A new version of the application includes a more recent ruleset version. Updates include reconfigured flows and decisioning and data management functionality. The development team decides to create a new access group because of the extent of changes beyond flow updates.

In the following figure, the operator record of a user provides access to two versions of a Booking application, 01.01.01 and 01.01.02. This configuration might be necessary when a requirement exists to complete in-flight cases according to the version in which the application the case creation occurred. The design should display only cases and assignments created in the current application version. getNextWork might need to avoid pulling work associated with a different version. Batch processing also must observe this rule. 



  • The original and newer versions of the application remain intact because no attempt is made to backport enhancements that are in the more recent version.


  • Desirable fixes and improvements incorporated into the newer application version are unavailable to the earlier version.

Avoid processing a case created in the new application version when using the earlierapplication version and vice versa. Both cases and assignments possess a pxApplicationVersion property. Security rules, such as Access Deny, can be implemented to prevent access to cases and assignments that do not correspond to the currently used application version.

You can modify the worklist of a user to display only cases that correspond to the currently used application version, or the application version can display as a separate worklist view column. Likewise, modify getNextWork to return workbasket assignments that correspond to the currently used application version.

Approach 4: Process existing assignments in parallel with the new flow

Process existing assignments in parallel with the new flow to preserve certain shapes, such as Assignment, Wait, Subprocess, and Split-For-Each, within the flow even though newly created cases no longer use those shapes. You can reconfigure the newer version of the flow so that new cases never reach the previously used shapes. Existing assignments continue to follow their original path.

For example, you redesign a process so that new cases no longer utilize the Review and Correct assignments. You replace them with Create and Review Purchase Request assignments. Because you only need to remove two assignments, you decide that running the two flow variations in parallel is the best approach, as shown in the following figure:

Assignment parallel

You make the updates in the new flow version in two steps.

First, drag the Review and Correct assignments to one side of the diagram. Remove the connector from the Start shape to the Review assignment. Keep the Confirm Request connector intact. This step ensures that in-flight assignments can continue for processing.

Next, insert the Create and Review Purchase Request assignments at the beginning of the flow. Connect the Review Purchase Request to the Create Purchase Order smart shape by using the Confirm Request flow action.

The following figure shows the resulting flow:

Assignment Parallel 3

Later, you can run a report that checks whether the earlier assignments are still in process. If not, you can remove the outdated shapes in the next version of the flow.


All cases use the same rule names across multiple versions.


This approach might not be feasible if there are configuration changes. In addition, it might result in cluttered Process Modeler diagrams.

Approach 5: Circumstance

Circumstance as many rules as necessary to differentiate the current state of a flow from its desired future state. One type of circumstancing that satisfies this approach is called as-of-date circumstancing. As-of-date is when a property within a case is identified (for example, pxCreateDateTime). That property then becomes the Start Date in a date range. The End Date in the date range remains blank. You can also use an application-specific DateTime property, such as .CustomerApprovalDate.

You can circumstance rules to handle changes in business logic that occur when cases are in-flight, but this method not a best practice. One drawback is that circumstanced rules are not displayed in App Studio. When configuring the rules in App Studio, only base version of the rule would be visible even though it has circumstanced version of the rule available. 



  • Simple to implement at first with the App Explorer. No need to switch applications.


  • The primary drawback of circumstance is that the Case Designer of Dev studio or App studio will not reflect the circumstance rules, except for its support for specialized case type rules. You cannot specialize case type rules by using the DateTime property because the system does not allow as-of-date circumstance.
  • Because the Case Designer of Dev studio or App studio works in the scope of requestor, you can see only the base versions of circumstance rules, such as flows. The base version is displayed whenever a circumstanced rule is opened from another rule. To locate the correct circumstanced variation of the base rule, click Action > View siblings. The greater the number of circumstanced rules, the harder it becomes to visualize how the collection of similarly circumstanced rules and non-circumstanced rules interact.

Check your knowledge with the following interaction:

This Topic is available in the following Module:

If you are having problems with your training, please review the Pega Academy Support FAQs.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice