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.

Comparing RuleSet pre-requisites and RuleSet Lists

Updated on September 10, 2021


Prerequisites and profile RuleSet lists are both lists of RuleSets and versions, but they have greatly different uses.

Both create a list of RuleSet versions, but

  • Prerequisites are used in validating newly-created rules at save time (to be sure all the rules referenced by the new rule are valid for the RuleSet of the new rule), whereas
  • Profile RuleSet lists are used during the actual execution of the rules (at run-time).

Suggested Approach


Two kinds of RuleSet lists are defined in different places for different purposes, and there is no relationship between the two.

  • When creating rules, prerequisites are used.

    Rule validation (when saving a rule form) is always performed against the prerequisite RuleSet list, not the profile RuleSet list.  Therefore, it is possible at rule creation time to validate against RuleSet lists that are not in the user's profile.

  • When running rules, profiles are used.

    Therefore, it is possible at run-time to execute rules from a RuleSet version that is not in that RuleSet's prerequisites, if that RuleSet is present in the user's profile.

If the user needs to create or change rules and then test them by executing, the RuleSet of the new rule must be present in both the Prerequisite and Profile RuleSet lists for that user (though the order of the RuleSets and their versions can be different).  See Example #2 for details.

NOTE: The Rule Resolution process does not cross major versions for rule searches.   Thus, for Profile RuleSets, if the RuleSet is Pega-RULES:03-02, then the user will not be able to see or use any rules from the RuleSet Pega-RULES:02-02, even though this version is less than the version 03-02. For the prerequisite RuleSet, a Prerequisite of major version 02 (RuleSet 02-02-01) would not be found if the major version 03 (03-01-01) is on the system.


Prerequisites are the list of RuleSets and their versions which must be present for a new rule created in an existing RuleSet to be validated upon creation, or for the rules in a new RuleSet to be validated properly (see Example #1).

The RuleSet and Version that is entered into the Prerequisite field of a RuleSet Version definition is an upper limit. If the Prerequisite for a particular RuleSet is Pega-ProCom:04-02-01, then any RuleSets in that major version (04) but below the specified version will be used: 04-01-24, 04-01-50, etc.

The system needs to contain the RuleSet and version specified in the Prerequisite RuleSet list.  Due to the nature of upgrading RuleSets, all versions of a RuleSet within a major version will be present.  If a customer receives PegaRULES RuleSet version 04-03-01, because of the way RuleSets are shipped, they will also receive versions 04-02-01 and 04-01-01. Thus, if the Prerequisite references Pega-ProCom version 04-01-01, and the overall system version of Pega-ProCom is version 04- 03 -01, new rules will still be validated, as long as all the rules referenced by a newly-created rule are present in a 04-01-01 version, to satisfy the Prerequisites.  If some of the rules referenced by the new rule are present only in the 04-03-01 version, the validation will fail.(This should not happen with Pega- RuleSets; it may be an issue if you have many RuleSets that are frequently moved between systems.)

Prerequisites are specified in the appropriate instance of the Rule-RuleSet-Version class:

In the above example, the ACME RuleSet, version 01-01-01, is dependent upon the Pega-ProCom RuleSet, version 04-01-01.  

Pega-ProCom version 04-01-01 itself has a prerequisite:  


Therefore, the ACME RuleSet has both Pega-ProCom 04-01-01 and Pega-RULES 04-01-01 as prerequisites, because Pega-ProCom 04-01-01 requires Pega-RULES 04-01-01.

Whenever a new rule that is subject to rule resolution is created (an Activity, a Flow, a When, etc.), it is defined on a class , and saved into a particular RuleSet and Version.  If the class of the rule being created is not in the same RuleSet as the new rule, it is necessary that the RuleSet of the class be a prerequisite of the RuleSet of the new rule being validated; otherwise, the system will not be able to find the class, and errors will result.  (See Example #2.)

When you save a new rule into a RuleSet, two validations occur:

First Validation - Is the RuleSet of the new rule valid? 

  • Is the version of the RuleSet (of the new rule trying to be saved/validated) correct for the Prerequisite RuleSet list?
  • If the RuleSet version is correct, is this an open (i.e., not locked) RuleSet?

Second Validation - Are the contents of the rule valid?  

  • The new rule may be defined on a class, or may reference properties, activities, etc.  Are the versions of the RuleSets that these classes, activities, etc. belong to correct for the Prerequisite RuleSet list?

In addition to their use when saving rules, prerequisites are used for validation when importing an entire RuleSet, or creating a new RuleSet.  A RuleSet can only be imported into a system that contains all the RuleSets/versions that are listed in its Prerequisites. This guarantees that the moved rules reference only rules that the target system contains. 

Thus, when developing a patch for an older version of a RuleSet, the Prerequisite RuleSet list would specify a dependency on the version of the rules that the organization has on-site.  For example, Pegasystems or a partner may want to create a new RuleSet Version instance for a patch for an organization.  The organization has version 04-01-01, but the current version that Pegasystems is working on is version 04-04-01.  To prevent the developers from building on rules that were introduced in version 04-02, that the organization doesn't have, the prerequisite RuleSet list is set to 04-01-01, so we can be sure that the new patch will work on the organization's version.

Issue with Restricting RuleSets

A third issue may arise with saving a new rule into a RuleSet, from restrictions that are placed on the class itself.  In the Class form, there is a field labeled Limit Rules Applied to This Class To These RuleSets:


If this field is left blank, then there are no restrictions on what RuleSets may extend this class - i.e., it is possible to define properties, activities, etc. on this class and save it into any RuleSet.  

However, if one or more RuleSets are listed under the Limit Rules Applied field, then only those RuleSets may be used to extend the class (save objects on this class).  This class is thus immediately limited to only those RuleSets that are listed in this field.

Profile RuleSet Lists

While prerequisite RuleSet lists govern the creation of new rules, profile RuleSet lists govern rule execution at runtime.  The Profile RuleSet list is the list of RuleSets and their versions which must be present for the system to be able to choose and execute the correct rule (according to rule resolution) for actions at run-time.  Profile RuleSets are specified through Access Groups, Organization, and Divisions, and show up in a user's Profile, as the user's RuleSets.

For whatever version of a RuleSet is displayed in the Profile RuleSet list, users will be able to see and use rules in RuleSets which are equal to or less than that version number.  So if the user's Profile RuleSet includes Pega-RULES:04-02 , then the user will see any rules from that RuleSet that were saved in version 04-02 or 04-01.  Rules that exist in the database at higher versions (04-04) will effectively be invisible.  Again, these rules are only within a major version - if there are rules in version 03-12 on the system, the user will not see these, even though they are in a version less than the 04-02 version in the profile.  

Example 1

Using the above ACME example, a developer may create an activity rule called ProcessPayment, which references the property .pyLabel.  

In this example, the developer has rights to save ProcessPayment into ACME 01-01-01, so the new rule ProcessPayment passes the first validation, because the Lock this Version check box on the RuleSet Version form for this RuleSet is not checked.  

The second validation then checks for the existence of .pyLabel (the property referenced in ProcessPayment) in the Pega-ProCom RuleSet version 04-01-01.   If this property is found, then the system validates the new rule, and save it into the ACME RuleSet.

If, however, the property .pyLabel is found only in PegaRULES version 04-02-01 (i.e., this property is not found in version 04-01-01), then the system does not find it, because the prerequisite is set to 04-01-01 (for both Pega-RULES and Pega-ProCom).   Therefore, although the proposed new rule passes the first validation, it fails to find .pyLabel; the second validation fails, and the developer will receive an error when trying to save the ProcessPayment activity.

Example 2


A developer's profile has the following RuleSets and Versions:






The RuleSet SA4 has the following Required RuleSet and Version in prerequisites (Rule-RuleSet-Version):

Pega-ProCom: 04-01-01

The class AcmeCo-General is in the RuleSet AcmeCo, which has the following Required RuleSet and Version in prerequisites:

Pega-ProCom: 04-01-01

The developer creates a new flow rule in the SA4 RuleSet, on the class AcmeCo-General and tries to save it, but receives the following error:

Class AcmeCo-General does not allow rules to be defined in the SA4 RuleSet.


The issue is that the developer is trying to define this flow in the SA4 RuleSet on a class in the AcmeCo RuleSet, without having established any dependency between these RuleSets.

The system looks at the Class specified for the flow (AcmeCo-General) and tries to validate this new flow using the RuleSet for that Class ( AcmeCo 01-01-01 ).  However, the prerequisite for SA4 is Pega-ProCom 04-01-01 (and by definition, all the prerequisites for that RuleSet); there is no information that the system can find about the AcmeCo RuleSet, because it is not a prerequisite for the SA4 RuleSet.  Therefore, according to the SA4 RuleSet, the AcmeCo RuleSet "doesn't exist," and this flow, which depends upon a class from the AcmeCo RuleSet, can't be validated.

The developer can see the AcmeCo RuleSet, as it is listed in her profile.  Executing already-existing activities will look at rules in that RuleSet during rule resolution at run-time, but the developer cannot save to the AcmeCo RuleSet, or save any rules that depend upon that RuleSet.  


There are two workarounds to this situation:

  1. Create this flow on another class that is in the SA4 RuleSet, or its underlying RuleSets.
  1. Add AcmeCo as a Prerequisite, by adding it to the Required RuleSet and Versions in the Rule-RuleSet-Version entry for the SA4 RuleSet.


Pega Platform 7.1.1 - 8.3.1 System Architect Low-Code App Development Security

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