Circumstances — Concepts and terms

A circumstance-qualified rule instance (often referred to as a "circumstanced rule") is always based upon an unqualified rule instance ( base rule ). You can circumstance a base rule with a single property and its value, or with multiple properties and their values (called multivariate circumstancing ). The circumstanced rule is selected by rule resolution if the value of the circumstance property on the rule matches that property's value on the clipboard at runtime.

On many displays, a icon identifies a circumstance-qualified rule instance. A icon identifies a base rule instance that has one or more circumstanced instances. The rule form for a circumstance-qualified rule displays the property and its value next to the Circumstance label located in the top right area of the form.

Assume that you have difference pricing levels for your customers. You first define a base pricing rule for all customers. Then you qualify the base rule by creating circumstanced rules for customers at different buying levels. The property .CustomerType is part of the customer order and has values of "Silver" and "Gold". In this example, a customer has purchased a $100 item. Using the property and values, you create circumstance-qualified instances of the base rules as shown here:

• BasePrice rule — if .CustomerType=(none), then Price =$100
• BasePrice circumstance 1 — if .CustomerType = “Gold”, then price = $100 - 25%
• BasePrice circumstance 2 — if .CustomerType =“Silver”, then price = $100 - 10%

When the system processes the order, the value of that property dictates which rule is run and thereby determines the discount (if any) the customer receives.

For information on how rule resolution processes circumstanced rules, see How the system finds rules through rule resolution. See also the Pega Developer Network article PRKB-25168 About rule resolution.

If you use a single circumstance property, you define the property name and its value directly in the Save As form.

If you use multivariate circumstancing, you two rules in the Save As form:

• Circumstance Templates (Rule-Circumstance-Template rule type)
• Circumstance Definitions (Rule-Circumstance-Definition rule type)

Multivariate circumstancing enable you to specialize a rule by more than one feature. For example, an insurance company may be required to collect, for every state, claims that exceed a specific amount and the method by which the claims were conveyed (letter, phone, email, and so on). Another example may be the need for a rule that is specialized by an age range and not an absolute value.

To create a circumstance-qualified rule, first define an unqualified or base rule instance (with the Circumstance values left blank). Then use the toolbar Save As button ( ) to create a second rule qualified by a circumstance. If the original rule has an Applies To class as an initial key part, the circumstance-qualified rule must have the same Applies To class or a subclass derived from that class.

For instructions on how to create circumstance-qualified rules, see these Pega Developer Network articles:

• PRKB-25172 How to create a rule with a single circumstance property
• PRKB-25173 How to create a rule with multiple circumstances properties

Select View > Rules > Find by Circumstance to create a list view report comprising single-property and multiple-property circumstanced rules. You can filter the report by searching on the following default circumstance properties: U.S. State Codes, Channels, and Customer Level. You can also search for circumstance-qualified rules by entering text used in key parts (Applies To or Name) in the Name Contains field.

For more information on how to report on circumstanced rules, or how to add or change the circumstance property columns for the report, see the Pega Developer Network article PRKB-25220 How to find rules with a specific circumstance .

For decision tree, decision table, and map value rules, you can redirect one circumstance-qualified rule to another circumstance-qualified rule (a peer with the same base rule), to reduce the number of distinct rules that you need to maintain. Select the Redirect this rule check box on the Results tab.

Circumstances are available only for certain rule types — those with the Allow Selection based on Property Rules? box selected on the Class form defining the rule type. As of Version 5.4, you can circumstance-qualify Declare-Constraints, Declare-Expression, and Declare-OnChange rules. You cannot use circumstances with a final rule.

If a circumstance-qualified stream rule contains JSP tags (rather than directives), the base rule must also contain JSP tags rather than directives. Conversely, if the time-qualified rule contains directives, the base rule must contain directives.

If two rules with the same Applies To key part and family name are both unqualified and each has one or more associated property circumstance-qualified rules, the same circumstance property must be used. For example, if activity MyClass.Alpha has an associated circumstance-qualified rule using property .State, then another activity MyClass.Alpha cannot have a circumstance rule with any property other than .State.

Database software supporting your Process Commander system limits the number of columns that can occur in any database table. When creating a Circumstance Definition rule, you may not exceed this limit. See Pega Developer Network article PRKB-25322 Troubleshooting: "Exceeds the maximum number of columns" when creating a Circumstance Definition rule.

In releases before V5.2, circumstance-qualified rules with a RuleSet version number lower than the RuleSet version of a base rule were ignored (never selected) during rule resolution. Starting with version V5.2, this is not the default rule resolution behavior: you can copy a base rule to a higher version without the need to also copy each of the (possibly many) qualified rules associated with the base rule into that higher version. If desired, you can revert in specific cases to pre-5.2 behavior by selecting the Base Rule check box on the form produced by the Availability toolbar button ().

Use the Circumstance Property Issues report (a link in the Rule Reports area of the Monitor Activity slice) to identify single circumstance-qualified rules that incorrectly use two or more different properties. Such conflicts can arise when rules are imported into a RuleSet that already contains some circumstanced rules.