Article

Upgrading rules schema

This article describes the steps involved in the split schema upgrade process from PRPC 5.x and PRPC 6.x applications to Pega 7. The scope of this article is for Pega 7 release versions only (until Pega 7.1.7).

The rules schema should only be upgraded after the rules migration has been completed.

This process can be initiated from either IUA wizard or the command line using upgrade.bat or upgrade.sh script.

Reduce the number of hops between the machines when triggering the upgrade to the Database Server. If possible, trigger the upgrade from the database server so that there is no network latency. The number of hops directly impacts the time taken for the upgrade.

Upgrading rules schema

The rule schema upgrade runs the following targets in SetupDatabase.xml.

Initialization

This step prepares the environment for the upgrade process, such as creating the temporary directory and performing the following tasks:

  • Reading the properties from setupDatabase.properties.
  • Performing prerequisite checks, which are provided in the setupDatabase.properties and include database driver jar, driver class, database type, JDBC URL, and schema name.
  • Creating a new property file resume.properties, which updates the status as failed or completed during the target process.
  • Checking whether the system temp directory has enough space or not. Pegasystems recommends 4GB space for upgrading.
  • Checking the configuration file for the schema set to Rule Schema and the Pega-Rules product that the version is being upgraded from.
  • Setting up temporary directories.

Configuration

This step auto-generates the configuration files those are used by the upgrade process.

  • Generating prbootstrap.properties.
  • Generating prconfig.xml
  • Generating prlogging.xml

Clean up rulesets

This feature generates SQL delete scripts (and optionally executes them) for removing previous versions of PRPC rules for performance (for the upgrade and post upgraded system).

  • Generating clean up ruleset scripts in the distribution scripts folder PRPC-RulesetCleanup.sql
  • Removing PRPC rules from one minor version less than the version being upgraded from.

For example, if upgrading from PRPC 6.3 SP1 (06-03-10), then it would delete the rules lesser than 06-02.

Sample Scripts:

DELETE FROM RULES.pr_sys_decchg WHERE PXRULESETVERSION <'05-04' AND PXOBJCLASS LIKE 'Rule-%' AND PXRULESET LIKE 'Pega-%';

DELETE FROM RULES.pr4_rule_property WHERE PYRULESETVERSION <'05-04' AND PXOBJCLASS LIKE 'Rule-%' AND PYRULESET LIKE 'Pega-%';

DELETE FROM RULES.pr4_rule_file WHERE PYRULESETVERSION <'05-04' AND PXOBJCLASS LIKE 'Rule-%' AND PYRULESET LIKE 'Pega-%';

DELETE FROM RULES.pr4_fieldvalue WHERE PYRULESETVERSION <'05-04' AND PXOBJCLASS LIKE 'Rule-%' AND PYRULESET LIKE 'Pega-%';

DELETE FROM RULES.pr4_rule WHERE PYRULESETVERSION <'05-04' AND PXOBJCLASS LIKE 'Rule-%' AND PYRULESET LIKE 'Pega-%';

DELETE FROM RULES.pr4_rule_flow WHERE PYRULESETVERSION <'05-04' AND PXOBJCLASS LIKE 'Rule-%' AND PYRULESET LIKE 'Pega-%';

Generate upgrade DDL

This step invokes PRDDLutility with the DB connection information for the system being upgraded. The appropriate DDL is generated and written to the <Distribution Image>\schema\generated folder.

  • Compares the current version of PRPC schema with Pega 7 schema.
  • Generates the create table scripts if any new rule tables are added OOTB for later releases of Pega 7.
  • Generates alter table scripts for any new columns added OOTB for later releases of Pega 7.
  • Generates the User-Defined Functions (UDFs).
  • Generates the disable/enable trigger scripts.
DDL can also be manually generated using genenrateDDL option.

Schema upgrade

This step applies the DDL generated from Step 4. If the DDL is manually generated using the generateDDL utility, then skip this step by setting the following property:

bypass pega schema

Apply User Defined Functions

This step adds the User-Defined Functions (UDFs) into the data schema. This is only required for unexposed columns (BLOB) reporting.

Step this step by setting up the following property in setupdatabase.properties file.

bypass UDF generation

Disable database triggers

This step disables certain database triggers on tables in the rules schema preventing population of the updates cache.

This takes the disable trigger statements generated in Step 4 (Generate Upgrade DDL) from the following location:

Pega 7.x\schema\generated\oracledate\util\triggers\disable

Engine load

This step loads the new engine classes for the new version of Pega 7.

Reorganize database indexes

This step calls the SPPR_REBUILD_INDEXES procedure to rebuild indices and forces the re-computation of table stats for the purpose of upgrade performance. The performance impact of this step varies by database platform.

This step execution is driven by the following property setting in setupDatabase.properties file.

rebuild indexes

Upgrade Java syntax

This utility is run against the existing rule base to identify, document, and correct embedded Java included in custom rules that have used identifiers that in newer versions of Java have become reserved words.

The time taken for this process is completely dependent on the size of the rule base.

Rules upgrade

This step loads the rules for the new version of PRPC. This is effectively a large specialized import operation. The incoming rules are compared against the existing rule base (synchronization) and imported as needed.

This step loads the PRPC_Rules.jar file that contains multiple Pega 7-related JAR files. This starts importing individual JAR files into rules schema. It also moves the rule from PR4_RULE tables to the newly introduced dedicated tables.

The following are the some of the examples of this migration process.

  • All instances of Rule-File-Binary from PR4_RULE_FILE to PR4_RULE_FILE_BINARY
  • All instances of Rule-RuleSet-Version from PR4_RULE to PR4_RULE_RULESET
  • Rule-Application-Requirement from PR4_RULE to PR4_RULE_REQUIREMENT
  • Rule-Application-UseCase from PR4_RULE to PR4_RULE_USECASE
  • Rule-RuleSet-Name from PR4_RULE to PR4_RULE_RULESET
  • Data-Admin-Product-Patch from PR_DATA_ADMIN to PR_DATA_ADMIN_PRODUCT
  • Data-Admin-Product from PR_DATA_ADMIN to PR_DATA_ADMIN_PRODUCT
  • Rule-Message from PR4_RULE to PR4_RULE_MESSAGE
  • Rule-Declare-Pages from PR4_RULE to PR4_RULE_DECLAREPAGES
This process loads the 70+ Pega OOTB JAR files. It takes a considerable amount of time to complete this process.

Remap database tables

If application is being upgraded from a PRPC 5.x or PRPC 6.x version, all of the Data-Admin-DB-Tables are mapped to PegaRULES Data-Admin-DB-Name. As a part of this process, all of the classes are remapped to the respective PegaDATA and PegaRULES Data-Admin-DB-Names.

Optimize newly exposed columns

This step runs the column populated on a number of classes that have been identified during PRPC development to include newly exposed columns.

The following are the class instances that are exposed as a part of this process:

  • Rule-Obj-FieldValue
  • Rule-Declare-Expression
  • Rule-Declare-Index
  • Data-Content-Image
  • Rule-RuleSet-Name
  • Rule-RuleSet-Version
  • Rule-Application-UseCase
  • Rule-Application-Requirement
The time taken for this process is dependent on the number of instances available for the rule types listed above.

Generate declarative indexes

This step generates declarative indices for custom rules. This step goes through all of the Rule- descended classes for generating the declarative indexes.

The time taken for this process is dependent on the number of rules available in the rule base.

Import assembled classes

This step imports the pre-assembled rules for Pega 7. Execution is driven by the following property setting in setupDatabase.properties file:

import assembles classes

Import updates

This step imports post-release candidate build bug fixes that are shipped with the core distribution of PRPC.

Run Update Wizard

This step is run irrespective of the following property if an application is being upgraded from a PRPC 5.x or PRPC 6.x version:

run update wizard

Run assembler

This step runs the static assembler on the rule base. It is possible to skip this step by overriding a value in the setupDatabase.properties file.

run static assembler

This is a time and resource consuming step. The number of Java processes can be increased to speed up the static assembly process or reduced to allow for that static assembly process to be run on more resource constrained environments. The default number of Java processes is three.

Prebuild conclusions

This step regenerates the conclusion cache for the upgraded system. It is possible to skip this step by overriding a value in the setupDatabase.properties file.

prebuild conclusions

Enable database triggers

This step enables database triggers again; the triggers were disabled during the initial steps (Disable Database Triggers) of the upgrade process.

This takes the enable trigger statements generated in Step 4 (Generate Upgrade DDL) from the following location:

Pega 7.x\schema\generated\oracledate\util\triggers\enable

Cleanup

This step cleans up the temporary directory, copies the upgrade logs to a well-known location (/scripts/logs directory of the core distribution), and displays the total runtime to upgrade rules schema.

This step also breaks down the total time taken for each of the Ant Tasks in the upgrade process into various Ant Tasks.

Resume rules upgrade

If the upgrade fails during execution of any of the Ant tasks, resume the upgrade by running the resume.bat/resume.sh from the \\DistributionImage\scripts folder.

As a part of the upgrade process, after completing each Ant task, it writes into the resume.Properties files in the following location:

114716_Pega717\scripts\resume.properties

Consider the following points before running resume.bat:

  • Analyze the log files and fix the actual failure issue.
  • Ensure that the resume.bat/resume.sh script is run from the same location where the upgrade is triggered.
The resume.properties file is deleted as part of the cleanup process.

Published June 4, 2015 — Updated June 17, 2015

Have a question? Get answers now.

Visit the Pega Support Community to ask questions, engage in discussions, and help others.