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)

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.

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

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.

• 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.

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

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

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

• 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.

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

• 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.

• 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.

• 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).

• 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:

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

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

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.

• 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.

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