Press "Enter" to skip to content

What is circumstance in Pega?


In this post, we will see detailed explanation about circumstancing in Pega.

  • Imagine, you lost your atm card, (I feel bad to start a post in negative manner πŸ™ )
  • Β You are calling to your bank customer care number. Some customer service agent attends the call and transfer it to appropriate department.
  • It means their business is like, few people are specialized in servicing lost ATM cards. The call gets routed to them and they will advice us what else needs to be done.

Similarly every business process can contain some specialization.
I am going to explain some specialization scenarios with respect to amazon website discount policy.
Three discount policies are

  • Apply discount, if the Customer type is Platinum
  • Add discount coupons, if the customer type is platinum & purchase amount exceeds 50k
  • Apply offer rates during festive periods.

Let’s come to our Pega. Imagine, we implemented Pega solution to amazon website. We designed the primary sales process and we have a separate discount flow(imagine discount as a complex flow).

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

  • Create 3 different sales flow with a single sub process in each, satisfying the three discount policies.
  • Create a Single sales flow with 3 different sub process for three discount policies.
  • Create a single sales flow with a single sub process.

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

The answer is circumstancing the discount Flow πŸ™‚

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.

We will see it more in a seperate post coming soon πŸ™‚

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 polocy
  • 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 most valued customers and for other customer just a normal discount process is applicable.

So What do you mean by specialized based on conditions?

We can specify the circumstance conditions in 3 ways.

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 allow circumstancing for many rule instances.

How would one identify the rule is eligible for circumstancing?

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 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
OfferDate – Date property

2. Create a simple discount flow
I just added a single assignment shape to display the pyLabel property. ( this is only for testing purpose). 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 a assignment shape to include the three properties in flowaction – section. Then add a sub process shape.

Note: create 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

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 customer type as “Gold”
Since discount flow is not circumstanced for 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 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, cis 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 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 current Date crossed the start date.

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

  • The specialized rule gets picked, when 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 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 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 discount process, when Customer Type =’Platinum’ and Purchase amount >50000

For multivariate circumstance, 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 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 proeprties – Customer type, Purchase amount

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

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 technical category
  • You can specify the definitions for the circumstance template. It means you basically define the values for the properties you added in 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 purpose, 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 checks 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 higher version and circumstanced version in lower version. No problem with that. Rule resolution cares it πŸ™‚
4. There may be some situtation, where you need to delete all those circumstanced rules and make a rule generic one. Its so simple πŸ™‚

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

now the circumstanced rules below this version becomes invalid. Pega rule resolution consider this rule as base rule. From then you create specialized versions for this rule πŸ™‚

We will see more about rule resolution and rule availability in coming posts πŸ™‚

  1. Sushil Sushil

    Hi Prem ,

    Good article on circumstance.
    I need one information if for a section rule , single value , multi variate and date time circumstance has been defined then at run time which circumstance version will be picked up first by rule resolution?

    • Premkumar G Premkumar G

      Thanks Sushil :).

      Remember for any rule, we can circumstance either using Single value and data or Multivariate. you cannot have both πŸ™‚
      Assuming you circumstanced a rule using single value, date time – Always single values takes first precedence

      Hope you are clear now

  2. Brahmesh Brahmesh

    Hi, I have a query with multi variance .Let’s say,A template is configured with two properties (Type,Year) and circum Def is defined for each one like below , Circum Def1 would be Type = ‘ Gold’
    Circum Def2 would be Year >=2015
    A rule is specialized by two circum def versions.
    Which rule gets picked up during rule resolution if object data matches both the conditions (Circum Def)?
    Will it throw conflict error during design ?

    • Premkumar G Premkumar G

      Hi brahmesh,
      Great question πŸ™‚ I missed out explaining the scenario, you mentioned above!
      You can configure the priorities in Circumstance template rule – Definitions tab.

      I have updated the post accordingly πŸ™‚ Thanks once again !

  3. Naveen Abbina Naveen Abbina

    Good explanation Prem.

    • Premkumar G Premkumar G

      Thank you so much, Naveen Abbina. πŸ™‚

  4. Navpreet Navpreet

    Nice Explanation

    • Premkumar G Premkumar G

      Thank you so much, Navpreet. πŸ™‚

  5. Veera Veera

    Clear picture on circumstance, Thank you so much for your efforts Prem

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Veera. πŸ™‚
      You are welcome. πŸ™‚

  6. Veera Veera

    Thank you so much for your efforts.

    • Premkumar G Premkumar G

      You are welcome, Veera. πŸ™‚

  7. Good explanation,Thank you so much for your efforts.

    • Premkumar G Premkumar G

      Thank you so much, Veera. πŸ™‚
      It is my pleasure to post stuffs. πŸ™‚
      Happy to hear that you like it. πŸ™‚

  8. bhagiradha bhagiradha

    worthful information

    • Premkumar G Premkumar G

      Thank you, Bhagiradha. πŸ™‚
      Glad that you find the information useful. πŸ™‚

  9. Pradeep Pradeep

    Crystal Clear explanation Prem , Great Job. Thanks

    • Premkumar G Premkumar G

      Thank you so much for your comments, Pradeep. πŸ™‚
      You are welcome. πŸ™‚

  10. Ashwani Mishra Ashwani Mishra

    You are doing great work…..Worthful information…Keep it up sir..Now I am a Fan of your post…
    I am reading your post on daily basis. Thank you so much for your time and effort.

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Ashwani. πŸ™‚
      Your appreciation means a lot to me.
      No words can tell how happy I feel, on reading your comment. Really glad to hear that you find it useful. πŸ˜€
      Thank you so much. πŸ™‚ You are always welcome and it is my pleasure to post stuffs. πŸ™‚

  11. Kousik Kousik

    Really good job, Prem. Please keep it up.

    • Premkumar G Premkumar G

      Thank you so much, Kousik. πŸ™‚
      Yeah sure. πŸ™‚

  12. RayMir RayMir

    Good explanation with example,Thank you so much Prem… πŸ™‚

    • Premkumar G Premkumar G

      Thank you so much, RayMir. πŸ™‚
      And you are most welcome. πŸ™‚

  13. Prasanth Prasanth

    Hi Prem,

    I appreciate you are doing awesome job. I’m my opinion can you provide some vedio tutorial for the same..

    • Premkumar G Premkumar G

      Hi Prasanth,

      Thank you so much for your appreciation. Yeah, I’ve thought about it and few other people have also mentioned the same thing. I’ll try to make video tutorials soon. πŸ™‚ Thank you once again. πŸ™‚

  14. Ashwani Ashwani

    Hi, I have a query with date property.
    The circumstance rule should run every year in the month of Sep only, then how can this be achieved?

    Here start date and end date takes the date with a year and there is no when rule available thereby I can use can anyone suggest, please.

    • Amikesh Amikesh

      I think it can be done through Multivariate Circumstancing. We can apply condition using expression builder on some date property in Circumstance definition. something like. month(.GivenDate)=8. month() is the function which returns month no. (0-11).

  15. pradeep reddy pradeep reddy

    HI prem,
    how can we achieve this if I have customer type
    gold silver platinum which one is best single value property are multiple values please explain this

  16. Ershad Ershad

    I have a question Prem.

    We have to open all the circumstance rule and make the base rule = “True”.

  17. Prasu Raya Prasu Raya

    Hi Prem,

    The way you explaining and the examples you given are very easy to understand for beginners also. Your posts are very helpful to me. Thank you so much.

    • Premkumar G Premkumar G

      Hi Prasu,

      Glad to hear that you are finding it useful. πŸ™‚
      You are most welcome. πŸ™‚

  18. Soujanya Soujanya

    Can u let me know the rules that can’t be circumstanced?

  19. Sushma Sushma

    Very nice explanations and the examples used are very simple and to the point πŸ™‚ I am learning so much from your posts.Keep posting more stuffs.Great Effort!!

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Sushma. πŸ™‚
      Glad to read your comment. πŸ˜€

  20. Ashiq Ashiq

    Awesome Explanation…. Keeping Rocking my friend.

    • Premkumar G Premkumar G

      Thank you so much, Ashiq. πŸ˜€

  21. Naresh G Naresh G

    Hi Prem ,

    Is it possible every PEGA PRPC rule Participate in circumstance ???.I mean any specific rules are not possible do circumstance please give me a clarity on this .

  22. Lakshmi Lakshmi

    Hi prem,
    That was really a clear cut view. I am so glad that i found your blog.

    I have an issue Prem, Where i have to create a control when user clicks the “EXPORT BUTTON” the data he is viewing on the page should be sent to his mail id. No downloading should be done to his local system.

  23. kasun kasun

    Hi Prem,
    Can you explain how to circumstance improve reusability and maintanability ?

  24. Raghu K Raghu K

    Awesome Explanation Prem πŸ™‚ we are so happy to get learning information from this Blog.

  25. Avinash T Avinash T

    Hi Premkumar,

    Thank you for sharing your knowledge
    One of my friends suggested this site & Posts are very helpful for Beginners.
    The information provided in Posts with navigation & Screenshots are clear.

    Avinash T

  26. Avinash Avinash

    HI Prem,

    Clear and Neat explanation , Thanks a lot for your efforts.


  27. Noor Noor

    Hi Prem,
    I know the basics of circumstance rule but i didn’t know how it works like implementation wisely based on single , data ,multi varient properties.after reading your explanation all my doubts are clear. thank you so much for giving such valuable information to all

  28. koteswar koteswar

    Hi premkumar,
    Thank you I got a clarity for circumstance topic and your way of Explanation is Awesome.
    I am following your posts

Leave a Reply

Your email address will not be published. Required fields are marked *

error: Content is protected !!