Skip to main content

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

RuleSet Maintenance wizard

Updated on November 15, 2021

Manage reusable resources in your application in a convenient and intuitive way by performing operations in the Ruleset Maintenance wizard. You can copy rulesets and ruleset versions into new versions, merge several ruleset versions into a single version, move rules from one ruleset into another, or change the version number for a ruleset. As a result, you save time and increase efficiency of the development process.

Before you begin working in the RuleSet Maintenance wizard, consider the following information:

The available operations for this wizard depend on the Pega-RuleRefactoring agents. If you use this wizard, confirm that the Pega-RuleRefactoring agents are enabled on at least one node in your system.

Moving a ruleset

When you move a ruleset, the wizard processes the source rules in each ruleset version in the ruleset and any non-versioned rules that are associated with the ruleset. The wizard updates the ruleset name and the ruleset version of each rule to the values that you specify as the target. As a result, the wizard deletes the source ruleset and copies the rules into the target ruleset. The values of the pzInsKey of the rules remain unchanged.

The way in which the wizard handles multiple ruleset versions in the ruleset depends on whether you specify a target version:

  • If you move a ruleset without specifying a target version, the wizard keeps the same structure and contents of the source ruleset versions under the target ruleset.
  • If you move a ruleset and specify a target version, the wizard merges ruleset versions in the source ruleset by skimming the rules to the specified version under the target ruleset. As a result, the wizard moves the highest-versioned instance of each rule in the source ruleset versions to the target ruleset and specified ruleset version.

For example, if you move a ruleset that contains rules with ruleset versions 01-01-01, 01-01-02, and 01-01-03 into a new target ruleset and specify a version of 01-02-01, the target ruleset version contains the highest version of all the source rules that versions 01-01-01, 01-01-02, and 01-01-03 contain. The wizard omits lower-versioned duplicates. In this example, if both 01-01-01 and 01-01-02 ruleset versions contain a duplicated rule, the wizard moves the rule from 01-01-02 to the new ruleset name with ruleset version 01-02-01, and omits the duplicate rule in 01-01-01.

When you move a ruleset, the wizard also updates the references to affected ruleset versions in the following rules or data instances in the system, so that the references point correctly to the versions that exist after the move:

  • Rule-Obj-Class
  • Rule-Access-Deny-Obj
  • Rule-Access-Role-Name
  • Rule-Access-Role-Obj
  • Rule-Application-Requirement
  • Rule-Application
  • Rule-Application-UseCase
  • Rule-Connect-SOAP
  • Rule-Declare-Pages
  • Rule-RuleSet-Name
  • Rule-RuleSet-Version

You cannot copy a ruleset.

Copying or moving a ruleset version

When you copy a ruleset version, the original source ruleset version remains unchanged. Each target rule that the wizard creates is identical to the original source rule with the following exceptions:

  • You must specify a ruleset version for the target rules that is different than the ruleset version of the source rules.
  • The wizard creates a new pzInsKey value for the target rules by using the create date/time as one of the values in the construction of the new target pzInsKey. The create date/time value is the only difference between the data that differentiates the source and target pzInsKey values.

Moving a ruleset version changes the source rules. The wizard updates the ruleset version of each rule to the values that you specify as the target. The wizard deletes the rule from its source ruleset version, and copies the rule into the target ruleset version. The value of the pzInsKey of the rule remains unchanged.

Before you copy or move a ruleset, ensure that you unlock and check in the target ruleset.

Merging rulesets and ruleset versions

You can merge multiple source ruleset versions that belong to the same or different rulesets. For example, you can skim the ruleset by collecting only the highest version of every rule in the ruleset versions into the target, or you can compress the rulesets down to a lower level. You control the merge by specifying the target version and the order in which the wizard processes ruleset versions.

When you select the ruleset versions, you establish the order of precedence by listing the ruleset versions in the wizard interface. The wizard processes the rules in the order, from top to bottom, collects the first version of every rule that the wizard finds, and omits any duplicate rules. The wizard processes rules in the following order:

  • The wizard first processes rules from the first ruleset version that you list, and then discards duplicate rules in the following versions in the list.
  • Then the wizard processes any remaining rules in the second ruleset version in the list, and omits any rules that are duplicates of the rules for which the processing is complete.
  • The wizard continues to process rules in the same way down the list of versions.
Note: When you compress rulesets with prerequisites, begin with the ruleset that contains the fewest dependencies. For example, if ruleset A requires ruleset B as a prerequisite, and ruleset B requires ruleset C as a prerequisite, then first compress the ruleset A, then B, and finally C. If you compress the rulesets in the order C, B, and A, you risk losing some rules that you expected to retain.

When you merge rulesets or ruleset versions, you can delete the sources when the merge is complete. However, if you merge ruleset versions and opt to delete the sources, the source versions are deleted, but not their rulesets.

When you merge ruleset versions, you can also exclude categories of non-versioned rules.

Note: When you select Libraries and Functions from the list of non-versioned rules, the wizard merges all functions are merged when the ruleset name changes. When the ruleset name is the same and only the version changes, the wizard treats functions as versioned rules and only merges the patch functions.

Changing a ruleset version number

You can change the version number for a particular ruleset version, no matter if the version number that you designate already exists. The target version belongs to the same ruleset as the source version. All rules, including non-resolved rules, from the source ruleset version become part of the target version. All rules retain their original pzInsKey values, and therefore retain their history.

When the ruleset version change is complete, the wizard deletes all rules in the source version.

Rule conflicts

For move, copy, and change operations, you can specify how to handle conflicts if the wizard finds the same rules in both the source and the target. You can choose to overwrite the target rules with the source rules, or to not move or copy the source rules that are in conflict with the target, and leave the target rules unchanged. If you choose not to overwrite the rules, the Summary page of the wizard lists the rules in the source that the wizard skips because of the conflict with the target.

Locked ruleset versions

The wizard only changes rules that belong to unlocked ruleset versions. If a ruleset version that you want to change by the wizard operation is locked, the wizard prompts you for the password to unlock the version before continuing with the operation. To copy a ruleset version, ensure that you first unlock the target rules. You can lock the source rules because the copy operation leaves the target rules unchanged. To move a ruleset or ruleset version, ensure that you unlock both the source and target rules.

For more information about locking rulesets, see Defining the security of a ruleset.

Checked-out rules

As a best practice, ensure that you check in all rules are checked in before you move or copy a ruleset or ruleset version.

If the wizard encounters checked out rules, the wizard displays a warning page and provides a report of the checked out rules. From the report window you can open the rules and check in the rules for which you have permission, or save a list of the rules in a spreadsheet. If you exit the wizard to check in rules, you must restart the wizard from the beginning.

For more information about rule check in, see Checking in a rule.

Prerequisites and preparation

Before running the RuleSet Maintenance wizard, consider the following guidelines:

  • Back up your Pega Platform system before you run operations in the wizard.
  • You can only copy or move rulesets or ruleset versions that are in your ruleset list.
  • Ensure that you unlock and check in rules that you want to modify. You receive warning if the wizard encounters any locked or checked out rules during a copy or move operation, but as a best practice unlock and check out the rules before you start the wizard.

When you work with ruleset versions, you can copy any prerequisite rulesets that the target ruleset version requires.

Recovering merged rulesets

Before merging the rulesets, the wizard creates a backup of each rule named and You can optionally use the files to recover the original rulesets.


Each operation of the wizard creates an instance of the Log-Merge-RuleSet class, that includes error messages or other information. The key for this instance is the date and time of the start of the wizard.

Class rules do not have a version. Do not delete Class rules if any version of the ruleset remains in use.

In some organizations, audit or compliance policies might prohibit deleting old rules, even if the rules are not in use.

  • Copying ruleset versions in a RuleSet Maintenance wizard

    Promote reuse of resources across your application to save time and make your development process more efficient by copying ruleset versions. Instead of creating new elements of your application, you can copy existing rules so that you perform necessary modifications and implement existing functionality for your business requirements.

  • Merging rulesets and ruleset versions in a RuleSet Maintenance wizard

    Increase efficiency and speed up your application development by merging rulesets and ruleset versions. As a result, you make managing the resources in your system more convenient.

  • RuleSet Maintenance wizard step 3

    If you opted to run the wizard as a background process, a message displays on the page stating that your request is being processed and that you will receive an email notification once it has completed.

  • RuleSet Maintenance — Locked Rules

    If the wizard finds rules to be modified in locked rulesets or locked ruleset versions, this form displays a list of the locked rulesets or ruleset versions with a Password field for each.

  • RuleSet Maintenance — Checked-Out Rules

    If the wizard finds that rules to be modified are checked out, this page displays a warning. Click Display to open a report of the checked-out rules. From the report window you can open the rules or Click Export to Excel to save a list of the rules in a spreadsheet.

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