Summary

You can use the Rename a Class wizard to rename a class and all of its pattern inheritance dependent classes. In addition you can choose to rename associated objects such as work- instances, properties, activities, and flows.

The wizard reports any locked RuleSets or rules that are checked out before performing the rename.

In addition to exact matches to the specified class name to be changed, references to the name in embedded strings, for example in property names or in embedded Java modules containing references to the old property will be identified. The wizard displays a listing of these "inexact" matches, and you can select which to include to be renamed and which to preserve unchanged.

Results

When complete, the renaming procedure changes your system in the following ways:

1. The class is renamed.
2. Direct and pattern inheritance references the new class name. There will be no effect on rule resolution.
3. All properties, activities, flows, etc. that referenced the original class now reference the class by the new name.
4. If the class is a work pool or defines an external data table, the Data-Admin-DB-Table instance is updated to reflect the new class name.
5. The wizard creates a new History- class for the new class, and it will identify that the class has been renamed. The History- class for the old class name is deleted.
6. References in embedded strings and embedded Java modules will be identified, and you can select which to change on a case by case basis.

Note: This is an advanced feature. Renaming a class can potentially effect hundreds or thousands of rules and alter your application's behavior. Be sure you understand the effects of your change on rule resolution and class inheritance in your application.

Follow the procedure below to complete the Rename a Class wizard.

Update: This article describes V5.5 features. For V5.4, see How to rename a Class.

Suggested Approach

Preparations

Complete these preparations before using this tool:

1. Perform a database backup of the PegaRULES database before using this wizard.
2. Determine the class to be renamed, and choose a new name for the class to be created.

   The class to be renamed must meet the following prerequisites:

   • The original class may not be one of the standard classes provided by Pegasystems.
   • The original class cannot be in a Final state, and all rules that will be modified must be checked in and unlocked.
   • The new name of the class must not exist in the Process Commander system. Class names are global rather than local to a specific rule set.
   • You can rename both abstract and concrete classes, but the new name must be in the same format as the old name. That is, you cannot rename a concrete class to be abstract by adding a dash to the name, or rename an abstract class as a concrete class be dropping the dash. For example, A- cannot be renamed to B, and B cannot be renamed to A-.
3. Consider how the new name fits into the class hierarchy. If the class hierarchy includes classes that are derived from the original class (through pattern inheritance), consider how their new names fit into the class hierarchy.
4. Work at a time when no one is executing or updating the rules to be renamed.

Starting the tool

Select Tools > Rule Management > Rename a Class to start the wizard.

Procedure

1. Select the old and new class name, and set the RuleSet scope.

   

   1. In the Old Class Name field, specify the name of the class you want to rename. The field prompts with existing class names as you type. The search for this class name is not case-sensitive.
   2. In the New Class Name field, specify the new name to be applied to the class.
   3. Select Yesto limit the search to RuleSets in your RuleSet list, or No to search all RuleSets in your system (excluding the standard Pega- RuleSets, which define Process Commander.)

      Depending on your selection, the list of RuleSets on this page is updated to list the available RuleSets in your RuleSet list or in the system generally.

   4. From the list of available RuleSets, select the ones in which you want to rename this class, and click Next.
2. If there are work object instances associated with any of the classes that will be renamed, the following warning appears.

   

   In the Rename field, click Yes to update the work object instances by changing the pxInsName and pzInsKey values to reference the new class name. Click No to leave the work objects unchanged. However, if you choose No, work objects that referenced the original class can only be viewed as XML. Click Next to continue to the next step of the wizard.

3. The next page lists all the classes that will be renamed.

   

   The list includes the subclasses of the class you specified that are associated by pattern inheritance with the original name. The page also lists counts of the number of records searched, number of records in which the class name occurred, and the total number of occurrences. The Old name, New name, and RuleSet of each class that will be changed is listed. The matching substring that will be changed within each class name is highlighted in red.

   To confirm these changes, click Next to continue to the next form of the wizard.

4. If the wizard finds rules to be modified in locked RuleSets or locked RuleSet Versions, this form displays a list of the locked RuleSets and RuleSet versions.

   

   For each RuleSet version, supply a password to unlock the RuleSet or check Skip.

    

   If you provide a password, the wizard unlocks the RuleSet version, renames the rules as specified, and then relocks the RuleSet. If you choose Skip, the wizard will not rename rules in the RuleSet. These rules will be listed on the wizard summary page with a status of SKIPPED.

   If you need to review the locked rules in more detail, or follow-up with others to get them unlocked, you can click Export to Excel to save this listing in a spreadsheet.

5. If the wizard finds that rules to be modified are checked out, the next page displays a warning and provides a link to a report of the rules.

   

   Click Display to open a report of the checked out rules. From the report window you can open the rules and check in any rules you have checked out.

   If you need to arrange for any rules in the report that are checked out by other users to be checked in, you can click Export to Excel to save a list of the rules in a spreadsheet. If you exit the wizard to arrange for rules to be checked in, resume the renaming process by restarting the wizard from the beginning.

   Note: You can continue the rename process with checked out rules. The wizard will rename the original rule, but checked out instances of the rule will not be modified. As a result, the checked out instances will no longer be able to be checked in and changes to the checked out instances will be lost.

   When all rules are checked in, click Next to continue.

   • The next page reports the number of occurrences of the class or RuleSet names that will be changed.

     

     If you want to review all the rules that will be changed, click Export To Excel to create an Excel spreadsheet containing a detailed listing of the rules that will be changed. Click Next to confirm the changes. The wizard searches for instances to refactor but does not make any changes yet.

   • The next page reports inexact matches with the class name you asked to change; instances of the name that are found in strings that are not clearly class names.

     

     Select the check box next to each instance that you want to rename, or select the check box at the top of the Rule Type column to select all the instances on this page.

     If there is more than one page of records, you will see page navigation tools at the top of the page.

     

     Note: You must display each page and select the instances that you want to include. Only the instances you select on each page will be renamed.

     These are additional occurrences not included in the summary on the previous page, "Rules That Will Be Changed." The wizard cannot determine whether these strings should be changed when the class names are changed. For example, if the original class name is your company name, you may have also used that string in other properties in the system that you do not want to change.

     For example, the name may be embedded in a Java class name, a URL string, or some other property. These may be incidental occurrences of the class name that you do not wish to change. For example, if you had used your organization name for the original class name, you might want to keep the name where it appears in strings displayed in the user interface.

     The rules are identified by their Rule Type and Name.

     

     The specific item that will be changed is identified in the Path and Value columns.

     

     The Path column specifies the property that contains the value, and the Value column contains the string that will be changed. In this case, for example, the occurrences of AlphaCorp embedded in these strings would be changed to BetaCorp.

     The final columns specify the RuleSet and RuleSet Version of each rule.

     

     To review these rules outside the wizard, click Export To Excel to create a spreadsheet of the rules listed on the currently displayed page. You can also create a spreadsheet of the entire report, containing the rules listed on all the pages, by clicking the Export All To Excel button at the bottom of any page.

     When you are satisfied with the selection, click Finish to begin the rename processing. Depending on the rule you chose to rename and the number of rules in your system, this can take some minutes to complete.

   • The final page lists all rule instances that you selected to be renamed that could not be changed successfully.

     

     Hover over the error message in the Status column to see more details on the error. The Status column reports the following error conditions:

     • FAIL— The system was unable to refactor the rule.
     • SKIPPED— The rule was not selected for refactoring on the previous page of the wizard.
     • REFACTORED WITH ERRORS — The refactored rule was saved to the system, but the rule is not valid. Review these rules in Process Commander and correct the validation errors.

     Click Review Log to get a complete listing of the results for all the rules, both successful and unsuccessful. Click Done to exit from the wizard.