Summary

You can use the Rename a Class wizard to change the name of a class, all of its pattern inheritance dependent classes, and associated objects such as properties, activities, and flows. The wizard automatically changes references to the old class name to the new class name in all RuleSets and versions. Each renamed rule belongs to the same RuleSet and Version as the original rule.

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, the wizard identifies references to the name in embedded strings, for example in property names or in property references in embedded Java modules. 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 workpool 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.

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

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

Suggested Approach

Preparations

Complete these preparations before using this tool:

1. As a precaution, 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.
5. Select View > Rules > All Checkouts to produce a report of rules that are checked out. Confirm that no rules that are to be renamed are currently checked out.
6. Confirm that the rules to be renamed belong to RuleSet versions that are not locked.

Starting the tool

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

Procedure

1. Select a Class to Rename

   

   
   In this step you select the class to rename and set options to limit the search.

   Complete the fields as follows:

   Original Class Name	Enter or search for the name of the class to be renamed. Note that the search for this class name is not case sensitive.The wizard matches all occurrences of this string in the system regardless of case.
   New Class Name	The new name to be applied to the class.
   Limit search to RuleSets in my RuleSet List	If Yes, the wizard only scans for matches in rules within application RuleSets specified in the current user's access group. If No, the wizard scans all application rule sets in the system.

   Click Next to continue to the next page of the wizard.

2. Verify Classes to be changed

   

   This page lists all the classes that will be renamed, including the subclasses of the class you specified that are associated by pattern inheritance with the new name. The rule set that contains each class to be renamed is also listed. The matching substring within each class name is highlighted in red.

   When you have confirmed these changes, click Next.

3. Resolve special conditions

   Before beginning the actual processing, the wizard checks for three special conditions

   • Are any of the RuleSets to be changed, locked?

     If the wizard finds rules to be renamed that are in locked RuleSets, the wizard displays a list of them. You cannot continue with locked RuleSets. You must exit from this wizard, unlock the listed RuleSets, and run the Rename a Class wizard again.

   • Are any of the rules to be changed checked out?

     In the same way, if the wizard finds rules to be renamed that are checked out, the wizard displays a list of them, and you cannot continue with checked out rules. You must exit from this wizard, check the rules in, and run the Rename a Class wizard again.

   • Are any of the rules to be changed Work instances?

     If the wizard finds work objects associated with the class being renamed, a page is displayed that asks whether you would like to modify the work objects' class references.

     • If you select Yes, all work objects that reference the original class are modified to reference the new class. The original class will be deleted after the changes to work-items have been completed.
     • If you select No, the work objects references are not modified. The old class will remain however, and work instances of the old class will be still be able to be viewed as XML.

     When you have resolved the special conditions, or if none of the special conditions apply, the wizard displays a summary of the rules that will be changed.

4. View Rules that will be changed

   

   This page reports the number of occurrences of the class name that will be changed.

   If you want to review all the instances that will be changed, click ExportToExcel to create an Excel spreadsheet containing a detailed listing of the rules that will be changed. You can use the spreadsheet to evaluate the effects of renaming the class before beginning the processing.

   Click  Next to continue. The rename process begins.

5. Select Rules to be changed.

   The next page reports matches with the names you have asked to change that are found in the system but that the wizard cannot clearly identify as a class name. These are additional occurrences not included in the previous page, "Rules That Will Be Changed."

   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 OmegaCorp.

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

   

   Page through the listing and review the Value column to see the item that will be changed. Select the check box next to each instance that you want to rename, or select the checkbox at the top of the Rule Type column to select all the instances on the current page. To select all the instances found, you must go to each page of the report and select the checkbox at the top of the Rule Type column on that page.

   You can move between pages using the navigation tools above the table on the right:

   

   Click Next or Previous to move one page forward or back, or click the number of the page to move directly to the page.

   To review these rules outside the wizard, click  ExportToExcel  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  Next 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.

6. Results

   When the rename processing is complete, the wizard displays a listing of all rule instances that you selected to be renamed that could not be changed.

   

   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 could not be validated. Review these rules in Process Commander and correct the validation errors.

   Click Export All To Excel  to get a complete listing of the results for all the rules, both successful and unsuccessful.

   Click  Finish  to exit from the wizard.