Examples of Circumstancing in Pega 7

Circumstancing can be used to handle special scenarios that would normally require changes to an existing rule -the base rule- without having to change that rule. Circumstancing allows a developer to create a copy of the base rule -the circumstanced rule-, which is applied at run time when a certain condition is met. This condition can be based on:

  • A single property
  • Multiple properties (multivariate)
  • A date range (time-qualified)

Summary

  1. Sample Application and Use Case
  2. Single Property Circumstancing in Pega 7
  3. Multivariate Circumstancing in Pega 7
  4. Time-Qualified Circumstancing in Pega 7

In the following examples, variants of a section rule are created to show different purchase discounts based on:

  • A customer category property: The value is either "Premium" or "Basic" (single property circumstancing).
  • 2 properties, the customer category and the state of the customer’s primary residence (multivariate circumstancing)
  • A DateTime property and a specified date range (time-qualified)

The sample application consists of a section rule that is used to collect customer information. It then uses a circumstanced section rule to display different discount information based on some elements of the provided customer data.

Pega 7 Application - Example of a Section Rule to Collect Customer Information

  • The base version of the ShowDiscount section is shown in the screen shot below. It displays a standard message to basic customers.

Pega 7 Application - Example of a Section showing a discount, this is the base rule

In this example, a circumstanced variant of the base section rule ShowDiscount is created so that a discount is shown to premium customers.

  • The circumstanced ShowDiscount rule will be shown when "Premium" is selected for the customer category in the Collect Customer Information section.
  • In the Designer Studio, the ShowDiscount section can be circumstanced by clicking on Save and then selecting Specialize by circumstance.

Pega 7 Edit Section Rule - Specialize by Circumstance

  • Select Property for the Circumstance by option.
  • This will display two fields where the Property and a Value (case-sensitive) must be entered.
  • In this example, the property is .Customer.Category of type Text and the value is "Premium".
  • Click on Create and open to create the new circumstanced rule variant and then click on Save.

Pega 7 Designer Studio - Specialize Section - Single Property

  • In this case, the specialized ShowDiscount rule will inform a premium customer of a 20% discount on all purchases.

Pega 7 Edit Section Rule -Circumstanced rule

  • At runtime, whenever "Premium" is selected for a customer category in the Collect Customer Information section…

Pega 7 Section Rule to Collect Customer Information

  • … the specialized ShowDiscount section rule is selected during rule resolution.

Pega 7 Circumstanced Section Rule showing discount at runtime

  • The base version of ShowDiscount is still selected during rule resolution whenever the category value is NOT "Premium".

Multivariate circumstancing allows the creation of a specialized rule based on multiple single-value properties.

  • For this example, another specialized rule of the ShowDiscount section is created using two single-value properties, Customer.Category and Customer.State.
  • The intention is to show a discount of 30% for a "Premium" customer that resides in the state of "California".
  • Multivariate circumstancing requires the creation of 2 additional rules: a Circumstance Template and a Circumstance Definition.

(a) Create the Circumstance Template

  • In the Designer Studio, navigate to Records > Technical and then right-click on Circumstance Template to create a new circumstance template rule.

Pega 7 Designer Studio - Create Circumstance Template Form

  • Provide a label for the circumstance Template and set the Apply to class.
  • Click on Create and open.
  • The Edit Circumstance Template dialog is used to select multiple properties that will be used by the circumstance definition.
  • In this case, the Customer.Category and Customer.State properties are added to the template.
  • Click on Save.

Pega 7 Designer Studio - Edit Circumstance Template Form

(b) Create the Circumstance Definition

  • In the Designer Studio, navigate to Records > Technical and then right-click on Circumstance Definition.
  • On the Definition tab, a decision table shows the properties from the circumstance template as columns.
  • The values in the first condition are "Premium" for Customer.Category and "California" for Customer.State.
  • This means that whenever the configured properties match the provided values, the circumstanced rule will be selected during rule resolution.

Pega 7 Designer Studio - Edit Circumstance Definition Form

(c) Multi-Variate Circumstancing for ShowDiscount

  • Open the rule that is to be circumstanced using the template and definition, here ShowDiscount.
  • Click on Save and select Specialize by circumstance.
  • Setting a Circumstance Template and a Circumstance Definition is required for the Circumstance by Template option (i.e. multivariate).

Pega 7 Designer Studio - Specialize Section - Circumstance by Template

  • Note: If the same rule has been circumstanced by a property before, the earlier circumstance rule must be deleted first.
  • A rule can not have multiple circumstance versions based on the same property (single and multivariate) as this could cause conflicts during rule resolution.
  • The newly created multivariate circumstanced section rule can be edited now. In this case, ShowDiscount will show a specific discount for premium customers from the state of California:

Pega 7 Designer Studio - Edit Circumstanced Section

  • At run time, when a given Customer instance matches the circumstance definition: Category = "Premium" AND State = "California"

Pega 7 Example Section to Collect Customer Information - Circumstance Discount Message based on State and Category

  • …the circumstanced ShowDiscount section, showing a 40% discount, will be displayed:

Multivariate specialized show discount message

Time-qualified circumstancing allows to create a variant of a rule that is based on a start date and/or an end date. At run time, the circumstanced rule is selected if the actual system time is after the start date and before the end date.

If only a start date was set, the circumstanced rule is executed if the system time at run time is after the start date. Similarly, if only an end date was specified, the circumstanced rule is executed if the system time at run time is before the end date.

  • Open the rule that is to be circumstanced by a Date range and click on Save and select the Specialize by circumstance option.
  • In the Circumstance by section select Date range only as shown below.
  • In the below example, the circumstanced rule will be selected during rule resolution when the system time is between January 6th 2016 10:00 PM and January 6th 2016 10:45 PM, i.e. the circumstanced rule will only be executed during this 45 minute window.

Pega 7 Specialize Section - Section Record Configuration - Circumstance by Date range using Start Date and End Date

  • As mentioned earlier, if only a start date is set, the circumstanced rule will be selected during rule resolution if the system time is greater than the start time.
  • In the example below, the circumstanced rule will always be executed once January 6th 2016 11:45 PM has passed.

Pega 7 Specialize Section - Section Record Configuration - Circumstance by Date range and Start Date only

  • Time-Qualified Circumstancing could be used to implement logic for displaying a special discount during the Christmas holiday season.

Leave a Reply