How to use the Search/Replace a String wizard (V5.5)

Updated on May 8, 2019

Summary

You can use the Search/Replace a String wizard to search for and replace a string wherever it appears in rules in the entire PegaRULES database. You can search and replace the string in:

all RuleSets in the system
the RuleSets included in your RuleSet list
a single RuleSet or set of selected RuleSets

The wizard reports any locked RuleSets or rules that are checked out before performing the replacement, and any class names that might be affected. A list of qualifying rules appears for your review before any rules are altered.

Specifying the string to replace

In changing a string, the utility looks for the specified string anywhere in any value within any rule within the search scope, and gives you the option to select the rules you want to modify. For the selected rules, it will replace the original string with the replacement string.

Strings are replaced only in rules, not in work objects, assignments, attachments, or other objects. If string replacement changes rules in subclasses of Work- or any of its properties, the subsequent processing of those work objects in those classes may encounter problems

Important: Rules updated by this wizard are not automatically revalidated and may become invalid as a result of string replacement. As a precaution, export the RuleSets in to a ZIP archive or back up the entire PegaRULES database before using this tool. The ZIP archive can serve as a backup if the results of the wizard are not satisfactory.

Suggested Approach

Select Tools > Rule Management > Search/Replace a String to start the tool.
Specify the string value you want to match, the new string value you want to change it to, and identify the RuleSets in which you want the change to be made.
1. In Original String Value enter the string to be replaced.
2. In New String Value enter the string to replace Original String Value.
3. Select Yes to 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 replace this string, and click Next to perform a preview scan identifying the number of rules that are found matching the original string value. No rules are updated by this step.
This page reports the results of the search including number of records searched, records with occurrences found and the number of occurrences found for the string.

In addition, if the string to be replaced is found in class or RuleSet names. The page lists the classes and/or the RuleSets that would be modified by the string replacement.
You may continue with the string replacement, but it is recommended that you exit from this wizard and first:
- Rename any classes listed using the Rename a Class wizard
- Rename any RuleSets listed on this form using the Copy/Move RuleSet utility wizard
Those tools provide more complete information and some safeguards to protect your system while refactoring. Then run this wizard again to complete the string replacement.
To continue, click Next.
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 process by restarting the wizard from the beginning.
Note: You can continue the rename process with checked out rules, however the original rule and the checked out rule will be changed only if the operator running the wizard is the same as the operator who checked out the rule, and the string is not a key part of the rule. In all other cases, only the original rule will be changed, and the 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.
To continue, click Next.
- 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, modifies the rules as specified, and then relocks the RuleSet. If you choose Skip, the wizard will not modify 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.
- This form reports instances of the string that will be replaced.
  Select the check box next to each instance that you want to change, 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 replaced.
  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 scrolling to the bottom of the page and 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 processing. This can take some minutes to complete.
  When the processing is complete, a final page lists all instances that could be successfully changed.
- This page lists all rule instances that you selected 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 or is a locked rule that was skipped.
  - REFACTORED WITH ERRORS — The refactored rule was saved to the system, but the rule is not valid. Review these rules 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 Finish to exit from the wizard.