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.

Rule resolution

Updated on April 5, 2022

Rule resolution is the search algorithm that the system uses to find the best or most appropriate rule instance to apply in a situation.

Rule resolution applies to all but a few rule types — classes that inherit from the Rule- class. Rule resolution does not apply to instances of classes derived from the Work-, Data-, or any other base class.

While the rule resolution algorithm is fast and invisible, it is important to understand how it operates. As you create applications, make your choices of values for key parts based on how you want rules to be found by rule resolution.

An in-memory rule cache helps the rule resolution process operate faster. If the system finds an instance (or instances) of the rule in question in the cache, it accepts what is in the cache as the candidate rules and skips many steps in the resolution process (see below).

The benefits of rule resolution include:

  • Rules can be shared across applications and organizations. Sharing and reuse are major benefits of object oriented software development.
  • Rules defined at a higher level can be overridden by more specific rules defined at a lower level. While this dilutes the sharing benefit, it provides often needed flexibility while bringing visibility to exceptions.
  • Rules can have multiple versions, even within one ruleset, and security rules control which users see and execute which versions. This facilitates application evolution, testing, and patching.
  • One Pega Platform system can host multiple applications, multiple organizations, and multiple versions of one application with minimal concern for conflicts and interference.
  • Applications can be developed independently from other applications, yet all can depend on common rules that are locked (and so won't change).


The inputs to the rule resolution process are:

  • The key parts of a rule instance being sought, such as its Applies To class and name
  • The user's ruleset list, assembled when the user logs in
  • The class hierarchy — the structure of parent classes and subclasses below the ultimate base class
  • The user's access roles and privileges held, determined by the access group
  • Security and access control rules, such as Access of Role to Object rules and Privileges
  • Rule availability — which rules are available, blocked, final, withdrawn, or not available
  • Whether time and date limitations affect which rules are available for this session
  • In some cases, the value of a circumstance property

The output of the resolution process is the first rule found that matches all the criteria. (Sometimes no rule instance is found, and execution stops.) The system then executes the selected rule. Often this causes one or more additional rules to become needed. These are also found by rule resolution.

The rule resolution process

The steps in the rule resolution process are as follows:

  1. Check the Rules Cache.

    Using rules already in the rules cache avoids additional database lookups.

    If the rule is there, go to Step 8. If not, continue to Step 2.

  2. Choose instances with the correct purpose.

    The purpose, or "family name" combines all the key properties of a rule, excluding the "defined on" class.

    For an activity rule, the key properties include:

    • the Applies To class that the activity is defined on
    • the activity name

    The purpose in this case is the activity name.

    For a Field Value, the key properties include:

    • the Applies To class, as above
    • the Field Name
    • the Field Value

    The purpose in this case is the Field Name plus the Field Value, for example " pyActionPrompt.ViewHistory ".

    The system chooses all items of the appropriate purpose and puts them in a temporary list.

  3. Discard rules where Availability = No.

    The system drops unavailable rules from the temporary list.

  4. Discard inapplicable rulesets and versions.

    The system drops from the list rules that belong to rulesets and versions that are not enabled for the current requestor. For instance, if the user's profile includes the ruleset version ThisRuleSet: 05-01, rules belonging to ThisRuleSet: 04- or ThisRuleSet: 06- are dropped.

  5. Discard all candidates not defined in a class in the 'ancestor tree'.

    Only rules found in classes from which the current class descends by either pattern or direct inheritance will be retained in the list.

    Note: This step is not used for rules which do not have the Use class-based inheritance to arrive at the correct rule to execute check box selected in their class definition.
  6. Rank remaining stack of rule candidates and discard the choices after the first base rule.

    The system ranks the remaining rules on the list in order of

    • Class
    • Ruleset - note that default rules that have been saved to a branch or privately checked out are in their own ruleset.
    • Circumstance
    • Circumstance Date
    • Date/Time Range
    • Version

    The following example shows rules ranked from top to bottom. Rules that have been designated as a base rule are indicated as such.

    1. MyRule in MyRuleset 01-01-05 Circumstance by Property: .pyLabel = Green 
    2. MyRule in MyRuleset 01-01-05 Circumstance by Property: .pyLabel = Yellow 
    3. MyRule in MyRuleset 01-01-05 Base rule 
    4. MyRule in MyRuleset 01-01-04 
    5. MyRule in MyRuleset 01-01-03 Circumstance by Property: .pyLabel = Yellow 
    6. MyRule in MyRuleset 01-01-02 Circumstance by Property: .pyLabel = Green 
    7. MyRule in MyRuleset 01-01-02 Circumstance by Property: .pyLabel = Red 
    8. MyRule in MyRuleset 01-01-01 Circumstance by Property: .pyLabel = Green 
    9. MyRule in MyRuleset 01-01-01

    Note that:

    • The ruleset and version rankings are based on the ordered list in the user's profile.
    • A rule with a specific qualifier ranks higher than one with no qualifier.
    • Circumstanced rules rank alphabetically by Circumstance value.
    • Circumstance Dates rank in descending value.
    • Date/Time ranges rank first by their end-date (in ascending order) and then by their start-date (in descending order).
    • Rules that do not have the Use class-based inheritance to arrive at the correct rule to execute check box selected in their class definition are not ranked by class.

    In the above example, if the MyRule is the rule being searched for, the match is at line 3, and all rules below line 3 are discarded.

  7. Set the cache.

    The process adds the rules that remain on the list to the cache as being selectable for use.

  8. Find the best instance and check for duplicates.

    The process searches down the list for the first rule that:

    • exactly matches a Circumstanced Rule
    • has the correct Circumstanced Date
    • is in the correct Date/Time Range
    • is the default Rule, with no qualifiers

    When it finds a rule that matches these conditions, the process checks whether the next rule in the list is equally correct. If it is, the process sends a message that there are duplicate rules in the system and stops processing.

    If no duplicates are found, the system prepares to use the rule that matched the listed conditions.

  9. Check Availability is not Blocked.

    The process checks Availability again, to see whether it is set to Blocked for this rule. If it is, the system sends a message that it could not find an appropriate rule to use.

  10. Verify requestor is authorized to see the rule.

    The process finally verifies that the requestor has authorization to access the selected rule. If so, the system uses it. If not, it sends a message that it could not find an appropriate rule to use.


Your use of an application can cause Pega Platform to search for a flow named Repair in the class Work-Contract-Application-Complete.

The system first examines in the Work-Contract-Application-Complete class, and then (if no match is found) searches higher classes in the class hierarchy. Only flows belonging to rulesets and versions that are present on your ruleset list are candidates.


A few rule types have instances that are not associated with a ruleset and version and no rule resolution processing occurs when an instance of these classes is needed. For example, access roles ( Rule-Access-Role-Name rule type) must have names that are unique system-wide.

Additionally, some other rule types do not support circumstanced processing.

  • Ruleset list layers

    A completed ruleset list contains sublists of ruleset versions, arranged in two layers. The following table presents the order of the ruleset list.

  • Ruleset list usage during rule resolution

    Each requestor's use of the system continually causes the system to search for a rule instance, which is known as rule resolution. This search uses properties from many sources to find the most appropriate rule for the current need, including class inheritance, security and access control restrictions, and the ruleset list.

  • Viewing your application ruleset list

    An application ruleset is a collection of rules that identify the components of an application. You can view a list of your application rulesets in Dev Studio.

  • Using pattern inheritance for rule resolution

    Rule resolution always first looks for a rule that it needs in the class initially provided.

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. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us