About the Ruleset Maintenance wizard

The Ruleset Maintenance wizard helps you copy rulesets and ruleset versions into new versions, merge several ruleset versions into one version, move rules out of one ruleset into another, or change a ruleset version's number. Select the Designer Studio > System >Refactor > RuleSets menu item, then click Copy/Merge RuleSet to start the wizard.

  • Use the Move operation to rename a ruleset: the process moves the rules from the existing ruleset into the new ruleset you specify, and then deletes the source ruleset.
  • For Copy operations, the target rules, if they exist, must be unlocked and checked in before the operation can be completed.
  • For Move operations, the source and target rules, if they exist, must be unlocked and checked in before the operation can be completed.
  • For Change a Version operations, the source rules should be checked in.

Operations of 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 of your system.

Functions of the wizard

Moving a ruleset

To move a ruleset, select an existing ruleset and specify a target name and, optionally, a version. The wizard processes the source rules in each ruleset version in the ruleset and any non-versioned rules associated with the ruleset. The RuleSet and RuleSet Version fields of each rule are updated to the values specified as the target. The result is that the rule appears to have been deleted from its source ruleset and copied into the target ruleset. The value of the rule's pzInsKey does not change.

The handling of 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 preserves the structure and contents of the source ruleset's versions under the target ruleset.

  • If you move a ruleset and specify a target version, ruleset versions in the source ruleset are merged by skimming the rules to the specified version under the target ruleset. That is, the highest-versioned instance of each rule in the source ruleset versions is moved to the target ruleset and specified ruleset version.

For example, if you move a ruleset containing 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 will contain the highest version of all the source rules contained in versions 01-01-01, 01-01-02 and 01-01-03 with lower-versioned duplicates dropped. In this example, if a rule is duplicated in both 01-01-01 and 01-01-02, the rule will be moved from 01-01-02 to the new ruleset name with ruleset version 01-02-01, and the duplicate rule in 01-01-01 will be dropped.

When you move a ruleset, the wizard also updates the references to affected ruleset versions in the following rules or data instances anywhere in the system, so they reference correctly 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

Copying a ruleset version performs the same function as the Save As toolbar action. The original source ruleset version does not change. Each target rule that is created is identical to the original source rule with the following exceptions:

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

As with moving a ruleset, moving a ruleset version changes the source rules. The wizard updates the RuleSet Version fields of each rule to the values specified as the target. The result is that the rule appears to have been deleted from its source ruleset version, and copied into the target ruleset version. In a move, the value of the rule's pzInsKey does not change.

Merging rulesets and ruleset versions

You can merge multiple source ruleset versions belonging 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 (01-01-01) or another designated level. You control the merge by specifying the target version and the order in which the ruleset versions will be processed.

When you select the ruleset versions, you establish the order of precedence by the order in which you list them in the wizard interface. The wizard processes the rules in the order listed, top-to-bottom, collects the first version of every rule it finds, and drops other duplicate rules:

  • The wizard first processes rules from the first ruleset version listed, 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, dropping any that are duplicates of what it has already processes.
  • Processing continues in the same way down the list of versions.
Note: Compress rulesets with prerequisites beginning with the ruleset of least dependency. For example, if ruleset A requires ruleset B as a prerequisite, and ruleset B requires ruleset C as a prerequisite, then you should compress the ruleset A first, 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 have the option of deleting the sources once the merge is complete. However, if you merge ruleset versions and opt to delete the sources, the source versions are deleted, but not their ruleset(s).

When you merge ruleset versions, you have the option of excluding categories of non-versioned rules. The categories are listd at the bottom of the form. Clear the check box to exclude a category.

Note: When you select Libraries and Functions from the list of non-versioned rules, all functions are merged when the ruleset name has changed. When the ruleset name is the same and only the version has changed, functions are treated like versioned rules and only patch functions are merged.

For an example of the merge operation, see PDN article How to merge RuleSets using the RuleSet Maintenance wizard.

Changing a ruleset version number

You can change the version number for a particular ruleset version, whether or not the version which you designate as the new number 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 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 same rules are found 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 conflict, leaving 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 were skipped because they were in conflict with the target.

Locked ruleset versions

The wizard does not change rules that belong to locked ruleset versions. If a ruleset version that will be changed by the wizard operation is locked, you are prompted for the password to unlock the version before proceeding. To copy a ruleset version the target rules cannot be locked. The source rules can be locked, since they are not changed by the copy operation. To move a ruleset or ruleset version, both the source and target rules must be unlocked.

Checked-out Rules

As a best practice, make sure that all rules are checked in before you move or copy a ruleset or ruleset version. Select Designer Studio > Application > Development > Checked Out Rules. Complete the parameters and click Run. Review the resulting report to confirm that no rules from that ruleset version are checked out.

If the wizard encounters rules to be modified that are checked out, it 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 ones for which you have permission, or save a list of the rules in a spreadsheet.

You must check in any rules you have checked out or arrange for any rules in the report that are checked out by other users to be checked in before you can complete the wizard. If you exit the wizard to arrange for rules to be checked in, you must restart the wizard from the beginning.

Affected Rules and data instances

The wizard automatically adjusts any references to ruleset versions in the following rules or data instances, system wide, to match the versions that exist after a merge or move:

  • Ruleset versions ( “prerequisite” field)
  • Rule-Application (lists on the General tab)
  • Organization data instance (listing ruleset versions here is possible, deprecated)
  • Access group data instances

Prerequisites and preparations

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

  • Back up your Pega Platform system before performing operations with this wizard.
  • You can only copy or move rulesets or ruleset versions that are in your ruleset List.
  • Make sure the rules that will be modified by the operation you specify are unlocked and checked in. As described above, the wizard will warn you if it encounters locked or checked-out rules during the copy or move, but it is a best practice to make sure that all the rules you will operate on are unlocked and checked in before running the wizard.

When you are working with ruleset versions, the Copy missing RuleSet Prerequisites check box appears at the bottom of the first form of the wizard. Select this check box to have the wizard copy any prerequisite rulesets that the ruleset version that results from your process will require.

Starting the wizard

Select the Designer Studio >System > Refactor >RuleSets menu item, then click Copy/Merge RuleSet to start the wizard. Then select the operation you wish to execute.

For help in completing the first form, see RuleSet Maintenance wizard.

Follow-up tasks

Recommended next steps

This wizard does not modify references to rulesets that are deleted or modified. Repair any references to rules that have been moved by the wizard by replacing references to the source ruleset with the target or another ruleset. In particular,

  • If a ruleset to be moved is referenced in an application rule, be sure to update the references on the application rule form:

    - Application RuleSets section on the General tab

    - Component and Shared RuleSets section on the General tab

    - Production RuleSets section on the General tab

  • Update any references to the old ruleset in Access Groups, including the local customization section on the Settings tab.

Recovering merged rulesets

Note: Before merging the rulesets, the tool creates a backup of each rule named Bkup_SourceRuleSet.zip and Bkup_TargetRuleSet.zip. If needed, you can use the Import .zip facilities to recover the original rulesets.

Logging

Each execution of this wizard creates an instance of the Log-Merge-RuleSet class, including error messages or other results. The key to this instance is the date and time the wizard was started.

Class rules do not have a version. Do not delete Class rules (or other rules that have no version) if any version of the ruleset remains in use.

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