Core Concepts – Circumstance in Pega

In this blog article, we will see some detailed explanation about rule circumstancing in Pega

Update: The concept of Circumstancing remains the same across different Pega versions. The screenshots in this blog article were reused from Pega 7 version. Use this blog article to learn the concepts and you can try it out in the latest versions as well.

Rule Circumstancing = Rule Specialization = Code Specialization

Example: Imagine, you lost your atm card, (I feel bad to start a blog article in a negative manner 🙁 ). You are calling to your bank customer care number. Some customer service agent attends the call and transfer it to appropriate department or if it is automated, the IVR and get the right CSR to handle the lost cards.

What you find here is, that there is a group of CSRs specially trained to handle the lost cards and the customers with such service are routed to the specialized CSRs.

Likewise, every business process can have some kind of specialization.
Let’s look at some more specialization scenarios with respect to Amazon website discount policy.
Three discount policies are

• Discount Policy 1 – Apply discount, if the Customer type is Platinum
• Discount Policy 2 – Add discount coupons, if the customer type is platinum & purchase amount exceeds 50k
• Discount Policy 3 – Offer discount rates during festive periods.

Let’s come to our Pega. Imagine, we implemented Pega solution to Amazon Sales process..

We designed the primary sales case and we have a separate discount process flow(imagine discount as a complex flow).

In order to satisfy the above Amazon discount policy, I give you three solutions.

Solution 1 – Create 3 different sales flow with a single subprocess in each, satisfying the three discount policies.

Solution 2 – Create a Single sales flow with 3 different sub-processes for three discount policies.

Solution 3 – Create a single sales flow with a single sub process.

Single sales flow with a single sub-process seems good :), but to achieve the complex discount flows with a single sub-process?

The answer is circumstancing the discount Flow

(Technically, we will be creating specialized version of flow rules based on conditions)

What is circumstancing?

– Circumstancing is a process, by which we can specialize a rule

– Circumstancing helps in making rules more reusable and makes it easier to maintain.

– Rule resolution makes use of circumstancing to pick the right rule to run.

What is rule resolution?

Rule resolution is an internal algorithm used by Pega, to identify which rule to run. we know every business process involves running separate rules to complete the process. Rule resolution helps in identifying the appropriate rules.

Why do we circumstance a rule?

As I mentioned in the above example, there may be some situation where we need to override some existing process in certain conditions- For most valued customers follow a different discount policy

Instead of creating new rules, we can circumstance an existing rule to follow different process based on some conditions.

Here existing rule refers to base rule

What is a base rule?

A base rule is always required to create any circumstanced version

For example – You need to have a specialized discount process only for the most valued customers and for other customers just follow a normal discount process.

So What do you mean by specialized based on conditions?

We can specify the circumstance conditions in 3 ways.

Three types of circumstancing

a) Circumstance using single value property – absolute value

b) Time varied circumstance –

This can evaluate a data time property against start date or end date or both. It can also evaluate if the current date is within a date range.

c) Multivariate Circumstance – use multiple property values.

Make use of Circumstance definition and circumstance template rule.

For example – circumstance based on Purchase amount & Customer type.

Before that, you should get a question here.

What are the rules eligible for circumstancing?

Pega allows circumstancing for many rule instances.

How would one identify the rule is eligible for circumstancing?

(The below action is applicable to more curious nerd developers)

Step 1: Open any concrete class that inherits from Rule- class.
Say for example – Let’s take activity. The pxObjClass of the activity is ‘Rule-Obj-Activity’

Open the ‘Rule-Obj-Activity’ class form.

Step 2: Click on the general tab and look into the rule instances of this class block.

a)  Allow selection of rules based on property values? – Enable this check box to make the rule instance (activity) specialized by circumstancing.

This is applicable for types that can be circumstanced based on property values

b) Allow rules that are only valid for a certain period of time? – Enable this checkbox to make the rule instance specialized based on time range.

It means the specialized rule runs only within a particular date range – say between Jan 1 to Jan 31.

Note: you can check the rule class to know the rule types that can be circumstanced.

How do you circumstance a rule?

Step 1: Open any rule form
Step 2: Click on the Save As button and check the dropdown.

Step 3: Click on specialize by circumstance, you will get a form to select circumstance type.

Circumstance by

a) Template – you can specialize a rule using circumstance definition & circumstance template
b) Property and Date – you can use this option to specialize a rule using proeprty value, date value or date range.
now the basics are over.

Let’s check the circumstance types one by one 🙂

What are the pre-requisites required to test circumstancing using flows?

1. Create 3 new properties

You can do this by creating properties from the Case data model.
PurchaseAmount
CustomerType
OfferDate – Date property

2. Create a simple discount process flow

Update: Create this flow rule manually without using case designer. For a reason 😉

This is the main rule which will be circumstanced.
I just added a single assignment shape to display the pyLabel property. ( this is only for testing purposes). you can include any logic inside.

In the connector, I set pyLabel value as “This is a base rule”

In the ‘ShowDiscount’ flowaction section – add the pyLabel property to confirm this is the base rule 🙂

3. Create a new main flow – AmazonSales

Add an assignment shape to include the three properties in flowaction – section. Then add a sub process shape.

Note: create a new flowaction, section to include the new properties.

Click on the subprocess and add the discount flow we created above.

Cool. everything fine. let’s start exploring circumstance types

Different Circumstance types

1. Circumstance based on property value

This circumstance type is based on absolute property value ( equal to operation)

Scenario : The discount process is totally different when the Customer type =’Platinum’

Note: If you want to implement the scenario – Purchase Amount > 50 K ( not absolute value), you can go ahead with circumstance template.

So we are going to specialize the discount flow based on the purchase amount property.
Step 1: Open the Discount flow. click on Save as -> Specialize by circumstance.

Step 2: Choose circumstance by – Property and Date

Select property value as “CustomerType” = “Platinum”. Click on submit.

Step 3: You have created a circumstanced instance. How simple right. You can see the circumstanced label near the rule name.

Step 4: For testing purpose, in the start shape connector, set pyLabel = “Platinum Customer”

Step 5: Run the Amazon sales flow & set customer type =’Platinum’
Click on submit. the flow should follow the circumstanced version of discount flow.

Step 6: You can see the circumstanced flow version ran :). Verify the label value – platinum customer.

Step 7: you can run the flow, and select the customer type as “Gold”
Since the discount flow is not circumstanced for the Gold customer type, the base rule gets picked.

Now you know how to circumstance based on property value.

2. Time varied circumstance

This type of circumstance is based on time values.

Scenario: You can have a specialized discount offer process at some particular time interval.

a) Based on the date time property
Three values are involved – Date property, start date & end date.

You can either have a property in date property field or it can be null.

When date property is not null – Here OfferDate

(i) start date is not null; end date is null

The specialized rule gets picked, when the Offer Date property value in clipboard, crossed the start date. OfferDate>Start Date ( 06/23/2017)

(ii) start date is null; end date is not null

The specialized rule gets picked, when the Offer Date property value in clipboard, is before the end date. OfferDate<Start Date ( 06/30/2017)

(iii) start date is not null; end date is not null

The specialized rule gets picked, when the Offer Date property value in the clipboard, is within the start date and end date range.

When date property is null

Note : When date property is null, current date time stamp is validated against the date range.

(i) start date is not null; end date is null

The specialized rule gets picked, when the current date crossed the start date.

(ii) start date is null; end date is not null

The specialized rule gets picked, when the current date is before the end date

(iii) start date is not null; end date is not null

The specialized rule gets picked, when the current date is within the start date and end date range.

Hope you get a picture now.

Let’s test time variate circumstance.

Important note : Single value circumstance and time variate circumstance can work together.
Scenario – Use a specialized version of discount process for platinum customers when the Offer date(Purchase date) is in June month.

You need to implement a specialized version of discount flow when the Customer type ‘Platinum’ and Offer date is within start date ( 01/06/2017) and end date (30/06/2017)

Step 1: Open the Discount flow base rule -> save as -> Specialize by circumstance
Step 2: Circumstance by -> property and date

Customer type – Platinum
Offer Date is between 01/06/2017 and 30/06/2017

Step 3: For testing purpose, set pyLabel = “Platinum customer purchased in June”.

Step 4: Run the main sales flow and set the Customer type as Platinum of offer date within June month.

Step 5: Check if the specialized discount flow is called.

Step 6: Now test the same process, by providing date range outside june month.

Step 7: verify, if the specialized discount flow for the platinum customer (irrespective of offer date) is called.

We have successfully test time variate circumstance.

3. Multivariate circumstance

This type of circumstance is based on two or more property values.

Scenario: You can have a specialized version of the discount process, when Customer Type =’Platinum’ and Purchase amount >50000

For multivariate circumstances, you need to create 2 new additional rules
1. Circumstance template
2. Circumstance definition

Note: Always create a circumstance template first and then add definitions for that template.

What is a Circumstance template rule?

– It belongs to the technical category.
– In this rule type, you can specify the properties that will be used for multivariate circumstancing.

In our scenario, we need to use two properties – Customer type, Purchase amount

Step 2: Add the two properties required for multivariate circumstancing.

Now circumstance template is ready. Let’s create definitions for this template

What is a circumstance definition rule?

– It belongs to tthe echnical category

– You can specify the definitions for the circumstance template. It means you basically define the values for the properties you added in the template rule.

Scenario – In our example, we need to use value as Customer Type =’Platinum’ and Purchase amount>50000.

How to configure a circumstance definition rule?

Step 1: Create a new circumstance definition rule
Go to records -> Technical -> Circumstance template -> Create new.

create the definition under the Discount template we created above.

Step 2: Set the values for the definitions
CustomerType – “Platinum”; Purchase amount > 50000

Okay now the pre-requisite rules for multivariate circumstancing are ready

Let’s specialize the discount process using circumstance definition & template.

Step 1: Open the discount flow. Save As -> Specialize by circumstance.

Step 2: Add the template name and definition name.

You get an error. This is because we already defined a specialized version based on customer type.

Note: You cannot circumstance a same base rule twice by template and Property and date. You can always use any one.I will delete the customer type property circumstancing.

Step 4: for testing purposes, use the pyLabel = “Multivariate circumstance”

Step 5: Set purchase amount = 100000 & Customer type = ‘Platinum’

Step 6: Verify the multivariate specialized version rule is picked.

Step 7: let’s test by changing the purchase amount to 100.

Step 8: Verify the base rule gets picked.

What happens when there are 2 or more circumstance definitions available?

Step 1: You have created 2 separate definition rules. One checking Purchase amount > 50 K & Another checking

Customer Type =’Platinum’

Circumstance Definition 1- Purchase Amount > 50K

Circumstance Definition 2- Customer Type = “Platinum”

Imagine what happens, when Purchase Amount >50K & Customer Type =”Platinum”.

Which definition will have priority? Confused?!

Open the circumstance template rule -> Definitions tab

You can see the Definitions are arranged in the order you created.

Click on Show conflicts.

You can see the If condition – First, it checksthe Purchase amount & if it is > 50 K then the first definition apply.

The priority is Purchase amount then Customer type.

Priority Definitions

If you need to customize the priorities, you can add the definitions in the correct order

Things to remember

1. Circumstance makes it easy to maintain the rules.
2. Based on the requirement, you can make use of single value, time variate or multivariate circumstancing. Use it wisely.
3. You can have your base version in the higher version and the circumstanced version in the lower version. No problem with that. Rule resolution cares it.
4. There may be some situations, where you need to delete all those circumstanced rules and make a rule generic one. It’s so simple.

Open the rule form and click the available link.
Check the base rule to be true.

now the circumstanced rules below this version become invalid. Pega rule resolution considers this rule as base rule. From then you create specialized versions for this rule.