Configure Wait shape in Pega
In this blog article, we will see how we can configure wait shape in Pega and how to use it effectively in the applications.
What is a wait shape?
– It is an advanced flow shape that makes your flow to wait for a certain amount of time.
– The wait time can be directly specified as an expected wait date time parameter or can depend on case status of other dependent cases.
– You can configure a Workbasket in the wait shape, so that the case waits in the workbasket when the flow reaches the wait shape
Business scenario 1: A banking organization uses Pega application to process home loans. Loan processing case type has a process to generate the property valuation report. This is done by a third party vendor who don’t have access to the banking internal application. As a bank employee, he/she can schedule an external task to the third party vendor and just needs to wait for 1 week to get the valuation report.
This is the ideal business case for wait shape.
You may wonder, why we need a wait shape, instead we can have an assignment shape routed to a workbasket. Of course, we can do it.
Wait shape vs Workbasket assignment shape?
The main difference is wait shape does not come with a primary flow action (no user action) to perform in the wait shape, whereas the workbasket assignment shape always comes with a flow action to perform.
Now, revisit the business scenario again. The action is totally dependent on a third-party vendor to generate the valuation report and as a business employee, he/she has no need to do any action during that window. Just do nothing!
Note: Of course, there can be scenario, where you may get valuation report in 3 days, In such case you can provide an other action add attachments to attach the valuation report and provide an option to force continue the wait shape. That is possible.
The main takeaway point is, If the user doesn’t have any primary action to perform in some waiting period, always go with the Wait shape.
I am going to alter the business scenario a little bit for case dependency.
Business Scenario 2: For the same loan application, Valuation report process is changed in such a way that first a check I made in the internal valuation report repository to see a valuation report is already available for the property. If no, then schedule an appointment with third-party vendor. All the valuation reports should be stored and reportable.
The implementation approach for this scenario is to have a parent-child case relationship between the Loan case and the Valuation report case.
Loan case has to wait until the valuation report case is completed. It has a case dependency.
This is again the exact use case for wait shape, where we do nothing (no user action) on the loan case until the valuation report case is completed.
We will see both scenarios in action shortly.
Technical scenario
I would like to explain a technical scenario, where you may need to use a wait shape. Say you have exposed an service-REST API that calls an activity to create a 5-stage automated case. Once the first stage – Validation is crossed, then service-REST should return the newly created Case ID with a success message. When this is configured as a synchronous activity, then the API cannot respond till all 5 automated stages are completed! In this case, you can have a wait shape in the validation shape that waits for a few seconds, so that a pause is made in the flow and the synchronous execution comes back to the Service API to send the response.
It may be a bit complex requirement but read it again line by line. You will get what I meant about the technical scenario.
Now it is time to learn all the configuration points in a wait shape
What are the configuration points in a wait shape?
First, insert a wait shape inside any existing flow to read all the configurations.
Double-click on the wait shape to check the configurations
You will find 2 blocks
- Details
- Advanced
Details block
Wait type – Timer/Case dependency
We already saw the 2 business scenario use cases for Timer and case dependency
Let’s start with Timer.
Timer
Set date/time interval – you can specify the numbers for days/hours/minutes/years/months/weeks etc.
Note: It doesn’t use any calendar. Just adds no of days.
This is like a kind of hardcoding to specify the flow to rule to wait for 3 hours or 1 week or whatever number. I don’t recommend this approach.
Use the other option.
Reference date/time –
Here you can specify either a Date time property or a date time expression that calculate the wait date time.
Using date time property –
In our business scenario, In a workstep, say you have made an appointment with third-party vendor to capture the vendor details and the deadline date for the report, say in the next 3 days (17/05/2020). The deadline date is captured in a date time property – ValuationReportDeadline in the first screen and the same property can be referred to in the wait shape.
Using Expression –
You can save the fixed number of wait days – Say, 7 for now in a DSS rule.
And then you can use the two functions addDate & getDataSystemSetting to add the dynamic no of days to the current date time.
We will see how it works later. For now, we can either use expressions builder to calculate the waiting time or you can refer to a property directly for this option.
Case Dependency
You can wait based on some dependency with other cases.
Wait for all all child cases to be resolved –
This will exactly solve our second business scenario, where we defined the valuation report as a child case to the loan processing case and need to wait till the valuation report case is completed.
This is very simple and may be the most commonly used case dependency option.
Wait for – Any / All
This is similar to parallel flow processing (split join, split for each etc), where you can wait for at least one of the cases to reach the expected status or all cases should go to the expected state.
Case Type – You can select any case type on the right side.
You also get an option to Other – where you can define the class name in the field.
You can foresee a limitation here. can we specify two case types here? – No!!
Either then you need to go with ‘Wait for all child cases to be resolved’ or you can specify any one case here.
Status configurations
To be resolved – We expect the dependent case get resolved – Resolved -*
Note: This may not always mean the happy path scenario – there can be situations, where your status can vary like – Resolved-cancelled or resolved-duplicate. So, use this option carefully.
To reach status – You can specify any work valid work status here. You can also specify ‘Resolved-completed’ status instead of using the first radio button.
Consider status after wait begins – You may want to consider the processing to check the case status only when the wait shape begins
Assume that the child case or valuation report has started somewhere before and in status Open. Once the wait shape is reached, it doesn’t consider any of the existing status before and just checks only the new status.
Important note: Use this option only when necessary!
Scope –
This is a bit tricky field to understand. I will try my best to make it easy.
For the case dependency wait processing, we need to help Pega to search the cases on which context.
You see there are three contexts – Current case, Parent case and Top case. First, let’s define the boundary between the terms!
Let’s say there are 4 cases and the Parent-child relationship is shown below.
You see there are two parent case – A and B and three child cases – B, C and D. This I don’t want to explain 🙂
Current case (B) – It explains the current context in which we are running. We are in Loan processing case and we are specifying the wait shape in the loan processing case. The current case = Loan processing case.
Parent case (A) – Case A is the Parent to our loan processing case – B
Top case (A) – Top level cases can never be covered by any other case and cannot be instantiated by other cases. They can contain child cases but cannot be a child case. Case A is the top level case here.
When scope is current
Pega searches the dependent cases within the current case type (B) and its descendent case type (C)
When scope is Parent case
Here the Parent case is A
Pega searches the dependent cases within the Parent case A and its descendent case types (B, C and D)
When Scope is Top case
Here the Top case is also A
Pega searches the dependent cases within the Top case A and its descendent case types (B, C and D)
Use can also use Other – to specify a class name to search for.
Note: Drop comments with scenario, if you have some question on scope.
Users can choose to continue the process –
By using this option, we provide an option for end users to stop waiting and continue to the next step.
This option can really come in handy as an error handling workaround, where manually you can proceed skipping the wait shape.
Local action permitted for end user –
As I said, in wait shape there won’t be any primary action for the end user, but we can always provide them some local actions to perform at the wait shape.
Let’s say the end user received the valuation report document before the deadline of 1 week, then they can use the local action – Add attachments to manually upload the documents as attachments to the case.
Advanced block
Assigned to workbasket – Specify the workbasket name, and where the case can wait during the waiting period. Have your own application workbasket instead of default WB.
Harness – specify the harness that is presented to the end-user when they open the waiting assignment.
Instruction – Refers to a field value rule – Await dependency. You can specify a valid message to the end users.
Service level – you can specify the SLA rule to perform some time-based action.
For example, you can send a notification email after 2 days of waiting using SLA escalation activity.
Now you know all the configuration points in the wait shape.
Let’s implement the wait shape in the flow rule.
How to use a Timer-based wait shape?
As a pre-requisite, a new Sales case type is created.
Step 1: Include a wait shape in the flow.
Use the wait shape from automations category.
Step 2: Include the Timer configuration.
I am going to use the DSS configuration and expression to refer to the date time.
Update the DSS configuration to 2. I am going to use addToDate to add +2 minutes to the current date time for testing.
The expression I used is – @addToDate(@DateTime.CurrentDateTime(),””,””,@getDataSystemSetting(MyKnowPega,WaitForValuationReport),””)
Step 3: Save and run the flow rule.
Since the routing is to workbasket, you may not get the assignment to work.
Note: There are some configurations in the flow rule, from where you can always look for an assignment from workbasket.
Using the other actions button, open the action – Continue Process.
You see an option to continue and the default section for wait shape.
The section – pyContinueAfterWait holds the UI configuration.
Okay now refresh the case and see the update operator – It will be the SLA processing agent.
Do I need to explain how this works 😄
Of course, the SLA agent processing is involved. Pega creates a queue instance with pyMinimumdateTimeprocessing as wait deadline time current time + 2 minutes. The SLA agent does the rest.
How to use case dependency wait shape?
To test this, do the following pre-requisites
1. Create a child case – Valuation Report to the parent case – Loan processing.
2. In the Loan processing case, Add the child case – Valuation Report.
Okay, let’s start with the wait shape configuration
Step 1: Set the Timer to case dependency.
Specify the dependent case as Valuation Report.
To reach status – Resolved-Completed
Important note: For our scenario, we can also use AllCoveredResolved ticket which can move the process in the parent flow.
Step 2: As soon as you save the configuration, Pega automatically creates a declare trigger rule in the valuation Report class.
Step 3: Open and check the declare trigger configuration.
You see the following configurations
Trigger when an instance is – saved and committed.
Monitoring property – Whenever pyStatusWork property changes. Good configuration, because it is case status dependency.
Trigger activity – pxCheckFlowDependencies.
Step 4: Open the activity – pxCheckFlowDependencies
The activity does three main jobs
– Get the case hierarchy map to fetch the right scope case.
– Populate Dependencylist using Index-AssignmentDeps table entries.
We will see how it gets populated at the end.
Tip: You see the Java step does a SQL query. SQL query can be executed only on the exposed columns (other that selecting from pr_read_from_stream). So, all the assignment dependencies should be exposed! In assignment table?
3. Queues an entry for agent processing – ProcessFlowDependencies
Agent activities do the rest.
We need to check the final configuration, from where the Index-Assignmentdeps are filled.
Step 2: Open the tracer
Step 3: Save the configuration and run the loan processing case.
You will see the activity – Dependency gets called.
Do you know which triggers this activity?
We know that in wait shape workbasket assignment is configured and by default the assignment type is Dependency 🙂 That is why this activity gets triggered.
Also, a declare Index rule Indexes the assignment dependencies into separate index tables pr_index_assignmentdeps
The declare Index fires based on the when the condition defined.
Check the instances of class – Index-AssignmentDeps
So, for every active wait shape with case dependency, you will find an entry here. This entry will be used by the processing activity.
Getting back to the screen. You see a case-dependent wait shape with a subcase.
Step 4: Open the valuation report sub-case and resolve-complete the case.
Step 5: Now check the Loan processing case – The wait shape is automatically removed or processed.
We are at the end of the wait shape article.
As a summary
– Use wait shape to wait for a fixed timer or a case dependency situation
– For timer-based wait configuration, OOTB SLA agent does the processing.
– For case dependency-based wait configuration – Assignmentdeps Index table, Declare trigger on dependency cases and OOTB Flow dependencies agent do the processing.
