Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Circumstances and other rule qualifiers

Updated on September 10, 2021

Summary

Process Commander allows you to qualify rules.  Circumstances and other qualifiers usually represent facts about customers.  They allow you to specify that different rules should be used for different situations.

Suppose you had an activity rule which created an invoice for a customer (“CreateInvoice”); this rule applied any discounts, and routed the invoice to the proper people for approval.  Your company may also have different designations for your customers, according to the amount they purchase from you (“Gold”; “Silver”); based on their Customer Level, you may wish to give these premium customers additional discounts on their purchases. 

By applying a circumstance to the base CreateInvoice activity, you can create a rule that will detect when a customer gets a special discount and automatically run a different version of the CreateInvoice activity to apply the correct discount.

 

Suggested Approach

There are several  different qualifiers that may be applied to rules, including:

  • a single Circumstance Property
  • a Circumstance Date
  • multiple Circumstance Properties
  • Date/Time Ranges

These qualifier types may be combined on a rule.  Examples:

  • a rule qualified by a single Circumstance Property may also be qualified by a Circumstance Date, and by a Date/Time Range
  • a rule qualified by multiple Circumstance Properties may also be qualified by a Date/Time Range

When you are creating a new rule, you will not see the qualifier fields, as the first definition of a rule with an entirely new name (creating a New rule) cannot be circumstanced:

Once you have created and saved a rule, use Save As to create a rule with that same name, to add desired qualifiers. 

The Circumstance and Date Range fields only appear on the Save As form.  (You can use the New form to create a copy of a rule if an existing rule is filled in for the Name field, but you will not be able to enter any qualifier information.)

When creating a circumstanced rule, use a property from the work object processing, where different values of this property need different processing (like “CustomerLevel” above).  At runtime, when this rule (“CreateInvoice”) is called, the system will look for the version of the rule that most closely matches the current situation.  If the customer you are creating the invoice for is a “Gold” customer, for example, the system will look for a CreateInvoice activity where the circumstance “CustomerStatus” equals “Gold” and use that.  If there is no such rule, the system will use the standard CreateInvoice activity. 

This leads to a very important point:  you must have a standard (or “base”) version of each qualified rule.  If you have a rule (or several rules) with a given name which have one or more qualifiers, then there must be at least one default rule of that name present with no qualifier, in case none of the qualified rules are appropriate for the runtime situation. 

Once the default rule is defined, then the qualified versions of that rule may be created in:

  • the same RuleSet as the default rule
  • a RuleSet which inherits from the RuleSet of the default rule*

*In other words, where the RuleSet of the default rule is a prerequisite for the RuleSet of the qualified rule.

In addition, the qualified versions of the rule may be defined on:

  • the same class as the default rule
  • a descendant of the class of the default rule

Single Property Qualifiers

There are two qualifiers which rely on a single property:

  • Circumstance Property
  • Circumstance Date
Circumstance Property

You may add a single circumstance to a rule by defining a circumstance property (“CustomerStatus”) in the system, and then adding the name of that property and a value for that property to a rule definition.   Generally, you would define this property in the same class as the rule it qualifies.

If a rule has a Circumstance defined, the Circumstance field at the top of the rule form will display the Circumstance Property and its value for this rule, and a small two-way arrow will appear in the upper right corner of the form.

This qualifier allows you to differentiate rules by some customer value.  For example, you might have a “CreateInvoice” activity, to calculate and route invoices for customers.  Part of this activity might be to add in the customer discount.  There are three levels of discount:

  • “Gold” – 25%
  • “Silver” – 10%
  • “Bronze” – 5%

In this situation, you could define the default CreateInvoice activity to calculate the invoice with no discount.  You could then define a circumstance property called .CustomerCategory for this rule, with values of the categories described above.  The CreateInvoice activity would then have a default version, with no discount, and three circumstanced versions, in which the appropriate discount is applied for each Customer Category.

When you create an Invoice work item, this activity would determine the value of the .CustomerCategory property (which would be part of the customer’s standard information).  Based on that value, rule resolution would choose either the default CreateInvoice rule (no discount) or one of the Circumstanced rules (applying the appropriate discount).

Note that if you define a particular rule to have a specific circumstance property, all versions of that same-named rule in that class may only use that one property as a Circumstance Property.  So from the example above, all activities named “CreateInvoice” defined on the class PegaSample may only use the .CustomerCategory property.  You can create additional copies of the rule where the Values entered for .CustomerCategory change (“Platinum”, “Tin”), but you could not, for example, define a copy of the CreateInvoice activity with the Circumstance Property .StateTax

In order to change the Circumstance Property from one property to another, you must delete all rules with that Circumstance Property; then you must recreate the rules with the new Circumstance Property.

If you wish to define multiple circumstance properties at once, you must create the copy of the rule as a multi-circumstance rule.  See How Multivariate Circumstancing Works.

Circumstance Date

A circumstance date is a qualifier much like a circumstance.  You can add a circumstance date to a rule by creating or identifying a circumstance date property (“AccountCreateDate”) in the system, and then entering the name of that property and a date value for that property to the rule definition.   Generally, you would define this property in the same class as the rule it qualifies.

If a rule has a Circumstance Date defined, the Circumstance field at the top of the ruleform will display the Date Property and its value for this rule, and a small clock (signifying a date/time value) will appear in the upper right corner of the form.

This qualifier allows you to differentiate rules by date.  For example, you might be writing an application for a homeowners insurance company.  Say that new regulations were passed after Hurricane Katrina, requiring homeowners whose homes are in a flood zone to carry flood insurance.  All policies written before the date of this regulation (01/01/2006) are not required to have the flood insurance, but all policies after that date must carry flood protection.  Rather than creating two separate rules, you could create a default policy rule, and then copy it, add a Circumstance Date for this issue, and change the processing to reflect the new regulations.

The calendar date entered into the Date Value field could be thought of as a starting date.   If your work item (the homeowner’s policy) has a create date which is after the Date Value in the rule, then this circumstanced rule will be used for that work item.  If the homeowner’s policy were opened before the Date Value, the default (undated) rule will be chosen.

As an example, an insurance company has a UpdatePolicy activity, which updates homeowner policies.  You have three versions of this activity in their application:

  • the default UpdatePolicy rule
  • a copy of UpdatePolicy which has a Date Property .AccountCreateDate set to 01/01/1993 (contains processing for Hurricane Andrew issues)
  • a copy of UpdatePolicy which has a Date Property .AccountCreateDate set to 01/01/2006 (contains processing for Hurricane Katrina issues)

Depending upon when a homeowner has opened their policy with the company (the AccountCreateDate), a different rule would be chosen to process their policy updates:

If the homeowner opened the policy on:

Their process would use the following rule:

June 1, 1991

the default UpdatePolicy activity (because their policy was opened before either of the defined Circumstance Dates)

June 1, 1995

the “Hurricane Andrew” version of UpdatePolicy (because the date is after the defined “start date” for this Circumstance Date, but before the “start date” of the Katrina rule)

June 1, 2007

the “Hurricane Katrina” version of UpdatePolicy

Again, if you define a particular rule to have a specific Circumstance Date Property, all versions of that same-named rule in that class may only use that one property as a Circumstance Date Property.  So from the example above, all activities named “UpdatePolicy” defined on the class PegaSample may only use the .AccountCreateDate property.  You can create additional copies of the rule where the Values entered for .AccountCreateDate change, but you could not, for example, define a copy of the UpdateInvoice activity with the Circumstance Date Property .PaymentDate

To change the Circumstance Date Property from one property to another, delete all rules with that Circumstance Date Property; then recreate the rules with the new Circumstance Date Property.

NOTE:  If you choose to define multiple circumstance properties (see How Multivariate Circumstancing Works) the Circumstance Date Property is not available; however, you can define a date property as one of the multiple circumstance properties.

Multivariate Circumstancing

As stated above, you can create rules which are circumstanced by one property, or by multiple properties.  If a rule is circumstanced by one property, the name of that property and a value for that rule would be defined when the circumstanced rule is created.

You may wish to circumstance a rule by more than one property.  As an example, an insurance company has to meet various state regulations regarding communication about privacy notices and other customer disclaimers.  The laws vary by state, and may require the insurance company to communicate different disclaimers depending upon the amount of the claim and the type of customer communication (phone call, email, letter). 

In order to allow multiple circumstance values to be evaluated while choosing rules, you must configure two different rule types:

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

NOTE:  Do not confuse the Circumstance Template rule with a template rule.  Template rules may be used as a pattern to copy for creating new rules; a Circumstance Template rule is a template specifically designed to implement the multiple-circumstance-property functionality.

For details, see How Multivariate Circumstancing Works.

Date/Time Ranges

When creating a rule, you can set a date/time range during which that rule is valid.  This Date/Time qualifier ties the execution of that rule to a period of time, based on the current (system) date/time.  For example, you might create a rule to calculate customer discounts; for the month of July, a special 10% discount might apply.   Process Commander will use the current system date to determine whether to use the 10% discount, or the base rule.

If a rule has a Date/Time range defined, a small clock icon will be displayed in the upper right corner of the ruleform.  Moving the mouse arrow over this clock will display the Start and End date for the rule.

Like Circumstance qualifiers, the Date Range is added when copying a base rule by using Save As.  Also, as with Circumstanced rules, you must have a base rule in the system before creating any Date-range-qualified rules.

Unlike circumstance, there is no property associated with a Date/Time range;  Process Commander will automatically retrieve the current date/time information (to compare to the specified range) from the system clock.   

You may also create a rule with a blank (open-ended) Start Date or End Date. 

  • If the Start Date is blank, the qualified rule is considered to have been “always” in force (except when a more specific rule applied), until the specified End Date.
  • If the End Date is blank, then the qualified rule will be in force forever (or until a more specific rule takes effect), beginning with the specified Start Date.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us