PegaRULES Process Commander Upgrade Guide. Version 7.1.5

Transcription

1 PegaRULES Process Commander Upgrade Guide Version 7.1.5

2 Copyright 2014 Pegasystems Inc., Cambridge, MA All rights reserved. This document describes products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. The document and product are protected by copyright and distributed under licenses restricting their use, copying distribution, or transmittal in any form without prior written authorization of Pegasystems Inc. This document is current as of the date of publication only. Changes in the document may be made from time to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request. This document does not imply any commitment to offer or deliver the products or services described. This document may include references to Pegasystems product features that have not been licensed by your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems service consultant. For Pegasystems trademarks and registered trademarks, all rights reserved. Other brand or product names are trademarks of their respective holders. Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors. This document or Help System could contain technical inaccuracies or typographical errors. Changes are periodically added to the information herein. Pegasystems Inc. may make improvements and/or changes in the information described herein at any time. This document is the property of: Pegasystems Inc. One Rogers Street Cambridge, MA Phone: (617) Fax: (617) Document:PegaRULES Process Commander Upgrade Guide Software Version: Updated: Wednesday, April 09, 2014 PegaRULES Process Commander Upgrade Guide 2

3 Contents About this Guide 4 Intended Audience 4 Before You Upgrade 4 Documentation Resources 4 Platform Support Guide 4 Installation, Upgrade and Deployment Information and Updates 4 Introduction 5 Typical Enterprise Application Upgrade Process 5 PRPC Application Elements and Split-Schema 6 Next Steps 7 Standard Upgrade Procedure 8 Overview 8 Step 1 Environment Considerations 8 Step 2 Database Preparation 8 Step 3 Upgrade the Rulebase 8 Step 4 Upgrade PRPC Applications 8 Step 5 Configure PRPC 9 Environment Considerations 9 Optional: Move System Settings from PRPC Configuration Files 10 Database Preparation 10 Confirm Database User Privileges 11 Keep Your Database Maintenance Current 11 Backup the PRPC System and Database 12 Optional: Remove Old Rulesets (command-line method) 12 Update the PRPC Database Schema 12 Optional: Manually Generate and Apply DDL 13 Upgrade the Rulebase 14 Update the PRPC Rules 14 Upgrade PRPC Applications 23 Configure PRPC 24 Log in to PRPC to Perform Final Steps 25 Run the Update Wizard 25 PegaRULES Process Commander Upgrade Guide 1

4 Enable Developer Help and the System Management Application 26 Configure Search 27 Redeploy Custom and Third-party JAR Files 28 Lock and Roll RuleSet Versions 29 Run the Final Rules Conflict Report 31 Upgrade Solution Frameworks 31 Complete Post-Upgrade Configuration 31 Test Your Applications 32 Check the Pega Discovery Network (PDN) for Updates 32 Upgrading from a Single to Split-Schema Configuration 33 Overview 33 Migrate script 33 Common properties 34 Custom properties 35 Migration directory properties 35 Operational properties 35 Rules schema object properties 36 Upgrading options 36 Upgrade script 36 Upgrading with one database 38 Create a new physical schema 40 Migrate rules tables 40 Upgrade the rules schema 41 Generate rules schema objects 43 Run data schema upgrade 44 Reconfigure the Application Server 44 Clean Up Unused Tables 45 Upgrading with two databases 45 Create two new physical schemas 46 Migrate rules tables 46 Upgrade the rules schema 46 Migrate and generate rules schema objects 46 Final steps 48 PegaRULES Process Commander Upgrade Guide 2

5 Upgrading a Split-Schema Configuration 49 Overview 49 Important notes 49 Step 1: Creating new Schemas 50 Step 2: Migrate the Rules schema 50 Source information 50 Target information 51 Temporary directories 51 Operational properties 51 Run migration script 51 If accessing one database at a time 51 Step 3: Upgrade the Rules schema 52 Step 4: Migrate to the new Rules schema 52 Step 5: Run the Data Upgrade 53 Step 6: Shut Down PRPC 54 Step 7: Reconfigure the Application Server 54 Step 8: Start Up PRPC 54 PegaRULES Process Commander Upgrade Guide 3

6 About this Guide This guide describes how to upgrade an existing instance of PegaRULES Process Commander (PRPC) on Versions 5.x, 6.x, and 7.x to Version It does not describe how to perform an install of a new PRPC instance. That information is in the PRPC Installation Guide for your database and application server platform. Intended Audience This guide is intended for anyone involved in the planning and upgrade of PRPC systems. Before You Upgrade Before attempting to upgrade to PRPC 7.1.5, review the important upgrade information in the Release Notes, stored in the root of your distribution and the PDN. Version 7 introduces new features and functionality which may cause compatibility issues with your existing application. You may need to take certain actions before running the upgrade process. Documentation Resources A variety of documentation and online resources are available to help you with your upgrade and deployment process. The Pega Discovery Network (PDN) is Pegasystems' online documentation and information site. It is the central depository for the review and download of updates to this guide and other installation/upgrade and deployment documentation. To access the latest installation and deployment information, navigate to Platform Support Guide The Platform Support Guide lists the databases and application servers supported for the release, and is published on the PDN. It is important that you review this document before installing PRPC to verify that you are installing on supported versions of your database and application server. To access the latest Platform Support Guide, click the Resources tab on the PDN and click the link under PRPC Deployment. Installation, Upgrade and Deployment Information and Updates release notes, deployment information and the latest versions of the installation and upgrade guides are available for review and download from the PDN. PegaRULES Process Commander Upgrade Guide 4

7 Introduction PRPC supports in-place upgrades and will continue to work with a standard configuration. This is now known as a single-schema configuration. In addition to a standard in-place upgrade, PRPC provides new tools and a process to create a new compliant split-schema configuration from a PRPC 5.x or 6.x single schema configuration. In a split schema configuration, the PRPC schema is split into two schemas in the same database and database instance: a Rules Schema contains Rules tables and associated data and objects a Data Schema contains transaction data, including Work objects A split schema configuration is now the recommended configuration for new PRPC installations, and for any customers upgrading to PRPC The process begins by running a new utility, which exports target objects from your existing PRPC database. The utility is intelligent and designed to export the required objects, leaving any customizations intact. You then import the contents into a new schema and run an in-place upgrade. The normal upgrade process is conducted against the new schema, which is inactive and serving no consumers / traffic. A split-schema configuration is required for customers planning to use PRPC High Availability. Split-schema allows you to perform rolling upgrades, whereby you conduct an in-place upgrade in one environment and then migrate or roll the upgraded objects to other environments. This is a more flexible configuration and allows for minimal downtime in the participating environments. The process works because once upgraded, the Rules schema can be integrated into other environments via the export and import of specific database objects such as tables, stored procedures, and triggers. Typical Enterprise Application Upgrade Process In this example, a project is initiated to upgrade and enhance an existing PRPC enterprise application to run on PRPC The project requires three environments, each of which with slightly different sizing and uptime requirements: Development a small instance targeted at the development team for rule development and unit testing, with small amounts of transaction data User Acceptance Testing (UAT) a moderate instance which contains a representative sample of production-like data where system and performance testing can be completed to certify the application readiness for production Production the full-size deployment that manages the production user population and production transaction volumes. By employing a different upgrade approach for each type of system, you minimize the critical production outage window and reduce overall migration risk by ensuring that only tested and proven rules are moved into production. The basic process design is: 1. Prior to upgrade, ensure that the Development system reflects Production and contains all new capabilities that need to be rolled out. PegaRULES Process Commander Upgrade Guide 5

8 2. Upgrade the Development system using the standard in-place upgrade process. 3. Conduct unit testing in Development and remediate any issues encountered. Exploit new capabilities that will need to roll into Production. 4. Set up the UAT system as a copy of the Production rulebase and with some suitable subset of transaction data. 5. When development is complete, upgrade the UAT system by replacing the rulebase with the one from Development by copying the appropriate tables and other database objects, and by replacing the PRPC base engine classes with those from Development. 6. Test and certify correct execution in UAT. Fix any problems in development and re-upgrade UAT periodically using the same table-copy technique. When testing is complete, Development and UAT will contain an identical rulebase. 7. Complete the Production upgrade using the same technique of copying the rulebase via tablecopies and replacing the PRPC base engine classes. At this point, Development becomes the Production Support system, and a new development system can be created to commence build-out of new capabilities for subsequent release. PRPC Application Elements and Split-Schema The heterogeneous upgrade approach made possible by split-schema takes advantage of the fundamental structure of PRPC application elements. A PRPC application can be viewed as a collection of logical system components distributed as jar or ear files for deployment within an application server. These components include PRPC Rules and Base PRPC Classes, both of which are stored as rows within a series of database tables. The PRPC Rules, Framework Rules and Customer Rules constitute the rulebase and are represented by a small number of database tables. Rules tend to be volatile in a development environment and mostly stable in a production environment. The Rules tables do not grow very large, as they tend to contain tens of thousands of rows, rather than millions or billions as with Transaction tables. An upgrade of PRPC and a Framework will replace the PRPC and Framework Rules entirely, leaving Customer Rules intact but restructured to reflect additional properties or internal format changes required by the new release. PegaRULES Process Commander Upgrade Guide 6

9 The PRPC Engine accesses rules at execution time to dynamically generate Java code which is then assembled and compiled into Java Generated Classes. As rules are changed, these classes may be discarded and replaced. The generated classes are stored as rows within database tables and on the application server s file-system using the classpath. An upgrade of PRPC will replace the base engine classes while generated classes will be automatically recreated on demand (First Use Assembly) at execution time. The transaction information upon which the application executes to do Work -- objects such as cases, correspondence and history - are contained in separate database tables. Transaction tables and data tend to be small in development and test systems where only sample data is used and often very large in production systems. Upgrades seek to avoid changes in the format of transaction data. If a format revision is introduced, it is versioned and designed for backward compatibility. The split-schema technology in PRPC allows Rules and Transaction data to reside in separate schema. In addition to enabling a rolling, heterogeneous upgrade process, split-schema provides other operational advantages and enables you to leverage PRPC High Availability features. See the PRPC High Availability Guide on the PDN for more information. Next Steps If you are interested in upgrading to a split-schema configuration, familiarize yourself with the tools and process covered in the Upgrading to a Split Schema Configuration topic of this guide. The tools and techniques in this section will help you design the larger upgrade process. Note that you must execute an in-place upgrade in at least one environment. The standard procedures for executing an in-place upgrade are covered in the next topic Standard Upgrade Procedure. This is the recommended procedure to follow if you choose to maintain a singleschema PRPC system. Many of the considerations apply to a split-schema upgrade, and should therefore be consulted before, during and after the in-place upgrade step of a rolling upgrade process. PegaRULES Process Commander Upgrade Guide 7

10 Standard Upgrade Procedure This section describes the steps used to perform a standard upgrade from PRPC Version 5.x, 6.x, or 7.x to Version Overview A standard upgrade involves the completion of several steps that are briefly described below. Each of these steps is described in fuller detail later in this document. Step 1 Environment Considerations Make sure that you environment meets the requirement for PRPC Review the requirements in the 7.1 Platform Support Guide and the Installation Guide for your application server to confirm that your environment and configuration settings are up to date. Step 2 Database Preparation To prepare the database for the upgraded PRPC rulebase, complete a full backup of your existing PRPC database before upgrading. The upgrade procedure modifies both the database schema and the Rules data; make sure you use a backup procedure that preserves both. After performing the full backup, you modify the database schema to support the rulebase. You can do this using one of two methods. Automatically the Installation and Upgrade Assistant (IUA) creates a delta of the changes between your existing schema and the schema, and only applies the changes, leaving any customizations intact. Manually use the generateddl.bat/.sh script included with your distribution to manually generate the delta of the changes explained above in the form of a SQL script, and then apply the generated SQL using the database utilities provided by your vendor or third party database. Step 3 Upgrade the Rulebase You upgrade the rulebase using one of two methods. Installation and Upgrade Assistant (IUA) The IUA is PRPC's graphical installer tool. You launch the IUA via the PRPC_Setup.jar program located in the root of your distribution directory. Command-line method Upgrade the RuleBase using the command-line script upgrade.bat/.sh, located in the scripts directory of your distribution. The script is configured via the SetupDatabase.properties file. Step 4 Upgrade PRPC Applications Deploy the new PRPC applications to your application server. Review the application server configuration described in the PRPC Installation Guide. Undeploy the current PRPC Java applications prweb.war or the prpc_*.ear file appropriate to your application server, prsysmgmt.war, prhelp.war. PegaRULES Process Commander Upgrade Guide 8

11 Deploy the new PRPC applications prweb.war or the prpc_*.ear file appropriate to your application server, prsysmgmt.war, prhelp.war. Step 5 Configure PRPC After you deploy the new PRPC application, you complete the PRPC Configuration Phase by logging into PRPC and completing some upgrade configuration steps. Environment Considerations Review Pegasystems documentation to understand PRPC's dependencies on your database and application server environments. Review the 7.1 Platform Support Guide, which is available on the PDN or from your Pega representative. This document lists the recommended software components needed to support PRPC and any special requirements or known issues with particular vendors or versions. Review this Upgrade Guide and the Version 7 Release Notes. Check the PDN for the most recent information on the release. Configure your database server and app server to use the same time zone and character encoding to avoid conflicts. After reviewing the upgrade process for your release, consider the following questions. Are you changing the supporting systems environment? If you are updating the version, or changing the vendor of your database server or application server, complete and verify those changes before upgrading PRPC. If you upgrade the supporting software at the same time as PRPC, it becomes very difficult to isolate the cause of any problems that might occur. Do you use any Pegasystems Frameworks as part your application? If you are using a Pegasystems Framework, confirm whether your framework is supported for this version of PRPC. You may need to upgrade your version of the framework to work with the new version of PRPC. Have you customized the PRPC database? If your site has made changes to the PRPC schema, you will also need to incorporate those changes into the database after the upgrade schema is applied. In particular, you should merge any changes to triggers, views, or stored procedures that you made in the previous version, and review any custom rules or work tables that you created. The upgrade procedure leaves tables you have added to the schema in place, but you may need to modify the tables to match changes in Pegasystems' schema. For example, the upgrade does not change customer rule or work tables. However, if the upgrade has added new columns to Pegasystems' rule or work tables, you may need to do the same. Do you use third-party or custom libraries? PegaRULES Process Commander Upgrade Guide 9

12 If you have integrated third-party or custom libraries into your PRPC system, make sure you have a copy of them before upgrading. The upgrade may overwrite your deployed libraries. Does your organization have special requirements for your site? Your site may have special deployment, integration, or security requirements. Be sure to schedule an early review of the upgrade procedure with the appropriate System and Database Administrators. Optional: Move System Settings from PRPC Configuration Files If you are upgrading from 6.1 SP2 or earlier, System Settings you may have added to the prconfig.xml or prbootstrap.properties configuration files should be moved to Dynamic System Settings (Data-Admin-System-Settings). Settings you have entered in env elements in your current prconfig.xml or prbootstrap.properties files will continue to work, and this task can be done at any time. Pegasystems provides a utility that can move the settings automatically from the configuration files to Data-Admin-System-Settings instances. See "Upgrading Configuration Settings from Prior Versions to Version 6.2" in the Configuration Settings Reference Guide on the PDN for details. Note that the instructions on how to run this utility are the same for Version as they are for Version 6.2. Moving these settings to the database has several advantages. Since the settings are stored as Data- instances, they can be read from the database by all nodes running your PRPC installation. All nodes will have the same setting values, unlike the values in the prconfig.xml file, which apply only to the node where that file is located. The values of the settings can be viewed and modified from PRPC. Values stored in the configuration files must be changed by editing the file, which sometimes requires redeploying the PRPC application. Database Preparation Review the Installation Guide for the database and application server platform that matches your environment for the database requirements for this release. Modify your PRPC Database configuration to match the latest requirements. See the 7.1 Platform Support Guide for the supported versions and other prerequisites. In particular, pay attention to the changed requirements described below. Undeploy the current PRPC Java applications prweb.war or the prpc_*.ear file appropriate to your application server, prsysmgmt.war, prhelp.war. PRPC 7.1 implements User Defined Functions (UDF) to support reporting capabilities. Be sure to configure your database as described below. MS SQLServer You must enable the common language runtime (CLR) on the database. To check whether CLR is enabled, run the following script. select value from sys.configurations where name ='clr enabled' If the value returned is 1, CLR is enabled. PegaRULES Process Commander Upgrade Guide 10

13 Oracle Make sure that Java is enabled for the PRPC database. If you are using Oracle 11g, do not use the UCP (Universal Connection Pool) feature in your PRPC database. An Oracle bug (BUG ) causes a failure when an application tries to call a stored procedure. This causes PRPC to work incorrectly with a database using UCP. DB2-LUW Make sure that Java is enabled for the PRPC database. Confirm Database User Privileges Make sure that the database user you use to connect to the PRPC database to run the upgrade for this database with full read, alter and write permissions. MS SQLServer Set the user account for the PRPC database user with public and db_ owner roles with all corresponding System Permissions granted. In particular, confirm that the role includes the CREATE FUNCTION permission in the database and the ALTER and EXECUTE permissions on the PRPC schema. Oracle Set the user account for the PRPC database user with the default RESOURCE and CONNECT roles with all corresponding system privileges granted. In particular, be sure that the user has been explicitly granted the Create View and Create Procedure system privileges. DB2-LUW Create a user account for the PRPC database user with at least SYSADM privileges. The database user used to connect to the database during the upgrade procedures must be explicitly granted the CREATE_EXTERNAL_ROUTINE privilege. The privilege can be removed after the upgrade is complete. It is not needed for normal PRPC functions. Increase DB2-LUW log file size. Before running the Installation and Upgrade Assistant for a DB2-LUW database, increase the log file size to at least 655,360 KB. The default log file size is 425,984 KB. PostgreSQL Ensure that the database user is the owner of the PRPC schema. If it is a split-schema system, the user must own both schemas. Keep Your Database Maintenance Current Before upgrading the PRPC database, be sure that your database maintenance routines are up to date. In particular, be sure to rebuild the database indices before running the Rulebase Load process in the Installation and Upgrade Assistant. Out-of-date indices in the database can cause the rulebase upgrade process to take significantly longer than in a properly maintained database. PegaRULES Process Commander Upgrade Guide 11

14 Backup the PRPC System and Database Before upgrading your current PRPC installation, be sure to back up the PRPC database, your applications and the PRPC system itself. Follow these steps to back up PRPC. 1. Verify that all rules are checked in. 2. Shut down the PRPC application server. 3. Back up the database. Use your database utilities to create a backup of the PRPC database. 4. If you have edited any of the following PRPC configuration files in the APP- INF\classes directory of an EAR deployment or the WEB-INF\classes directory of a WAR deployment, include these in the backup: prbootstrap.properties prconfig.xml prlogging.xml pegarules.keyring or any.keyring files with other names If you have added System Settings to your prbootstrap.properties or prconfig.xml files, you should convert them to Dynamic-System-Settings Data- instances. 5. Backup any third-party or custom JAR files that you installed with the PRPC application. Redeploying the PRPC applications may delete these from your application server. Optional: Remove Old Rulesets (command-line method) Prior to upgrading the rulebase, you can optionally remove older rules from the database. In most cases, removing older rules decreases the overall upgrade time. Once configured, the process permanently removes rules older than n, where n is the current major-minor version that you are upgrading from. For example, if you are upgrading from 6.2 SP2 ( ) to 7.1.5, this feature removes rules of version and older. The rulebase cleanup process can be run from the command line automatically or manually. In both cases, use the cleanup.bat/.sh script. For automatic application, ensure the property run.ruleset.cleanup=true is specified in setupdatabase.properties. When the cleanup script runs, it will automatically generate *and* apply the SQL to your database. For manual application, ensure the property run.ruleset.cleanup=false is specified in setupdatabase.properties. When the cleanup script runs, it will generate a SQL script that can be applied using native database vendor tools. Update the PRPC Database Schema For a standard upgrade, your existing schema needs to be updated to be compatible with PRPC The schema can be updated in one of two ways: Automatically the UI-based Installation and Upgrade Assistant automatically updates the schema leaving any customizations intact PegaRULES Process Commander Upgrade Guide 12

15 Manually the generateddl command-line script generates a SQL script that can be applied using standard vendor or 3rd party tools Optional: Manually Generate and Apply DDL A generateddl script is provided for Windows (generateddl.bat) and Linux (generateddl.sh). Both scripts work identically and accept the arguments noted in the table below using the following convention: generateddl.bat --action[upgrade] --arg1[value] --arg2[value]... --argn[value] You must supply the --action parameter to the script. If no additional arguments are passed to the script, the script defaults to the values of the properties set in the setupdatabase.properties file. Script Arguments setupdatabase.properties Required? Description --action none Yes --dbtype pega.database.type Yes --dbschema data.schema.name Yes * --outputdirectory none --mtsystem multitenant.system Yes ** Required in the command line using a value of upgrade (Optional) sets the data schema for a split-schema environment (Optional) the output directory for the scripts. Defaults to [distributionimage] /schema/generate/[dbtype] Whether this is a Multitenant System. 'true' if yes, 'false' if no --username pega.jdbc.username Yes Database username --password pega.jdbc.password Yes Database password --url pega.jdbc.url Yes Database jdbc url enclosed in double quotes --driverjar pega.jdbc.driver.jar Yes Path to the jdbc driver --driverclass pega.jdbc.driver.class Yes Class of the jdbc drver --connproperties Database vendor type. Enter udb for DB2-LUW, mssql for MS SQLServer; oracledate for Oracle, postgres for PostgreSQL jdbc.custom.connection.properties (Optional) Semicolon-delimited custom JDBC properties (e.g. prop1-1=value;prop2=value;prop3=value) * Required if using a split-schema database configuration ** Required if installing or upgrading a Multitenant system 1. Open the file setupdatabase.properties for editing. This file is located in the scripts folder of your distribution. 2. Specify the properties noted in the table above. 3. Type generateddl.bat or generateddl.sh passing in the required --action upgrade parameter. For example: #generateddl.bat --action upgrade PegaRULES Process Commander Upgrade Guide 13

16 4. The script writes the output to the following directory. <PRPC_HOME>\schema\generated This directory is deleted and recreated each time the generateddl script is executed. If you want to save a copy of the DDL, rename the directory prior to running the tool. Upgrade the Rulebase To upgrade the PRPC database, you run the Installation and Upgrade Assistant (IUA) from the PRPC_ Setup.jar to upload and import the 7.1.5RuleSets. The computer on which you run the IUA must have access to allow a database connection to the PRPC database. This computer should also have at least: 3 GB of available RAM 6 GB of disk space available for the temporary directory, pegaguiinstallertemp By default, this directory is created in the directory in which PRPC_Setup.jar is run. You can specify a different location for the directory in the IUA. This directory is deleted when the assistant's processes are complete. A local installation of a Java 6 or Java 7 JDK Update the PRPC Rules Make sure you have completed all applicable Database Preparation procedures before running the IUA. In particular, be sure you have completed the following tasks: Modify Database to Support User Defined Functions Confirm Database User Requirements Make sure you have configured the database user you will use during the upgrade with full read, write, and administration permissions. The user must have access to the schema for the PRPC database. In particular, the database operator used to connect to the database during the upgrade procedure must be explicitly granted privileges that allow them to create user defined functions: MS SQLServer CREATE FUNCTION Oracle CREATE PROCEDURE DB2 CREATE_EXTERNAL_ROUTINE Then, follow these steps to upgrade the PRPC rules in the database. 1. Double-click the PRPC_Setup.jar file or right-click the file and click Open With > Java, to launch the Installation and Upgrade Assistant (IUA). If JAR files are not associated with Java commands on your system, you can launch the installer at the command-line. In a command-line console, change to the directory containing PRPC_ Setup.jar, and type in the following command: java -jar PRPC_Setup.jar PegaRULES Process Commander Upgrade Guide 14

17 2. Click to review the License Agreement. PegaRULES Process Commander Upgrade Guide 15

18 3. Review the License Agreement and click to select the Installer Mode. PegaRULES Process Commander Upgrade Guide 16

19 4. Select Upgrade and click to select your Database Type. PegaRULES Process Commander Upgrade Guide 17

20 5. Select the type of your PRPC database. Click to specify the Database Connection. When you select a database type, the IUA automatically populates certain fields on the following screen. If you decide to select a different database type, click to return to this screen and make a new selection. PegaRULES Process Commander Upgrade Guide 18

21 6. Complete the fields to specify the database connection to your PRPC database as described below. Some of the fields on this screen in particular the JDBC Driver Class Name and the Database JDBC URL - are pre-populated based on the type of database you selected on the prior screen. If you edit these or any other fields on this screen, and then later decide to change the database type, the IUA may not populate the fields correctly. If this occurs, you can enter the correct field values as documented below, or exit and re-launch the IUA to select the intended database type. JDBC Driver Class Name Enter the JDBC Driver Class Name The IUA will attempt to pre-populate this field for you based on your selection of the Database Type on the prior screen. If the field does not populate correctly, you can copy and paste the values below or exit and re-launch the IUA. IBM DB2 LUW Microsoft SQL Server Oracle Database PostgreSQL com.ibm.db2.jcc.db2driver com.microsoft.sqlserver.jdbc.sqlserverdriver oracle.jdbc.oracledriver org.postgresql.driver JDBC Driver JAR File Enter the full path to the appropriate driver file for your database type and version. See the Release Notes for a list of supported JDBC drivers. Database JDBC URL Enter the JDBC connection URL for your PRPC database. PegaRULES Process Commander Upgrade Guide 19

22 The IUA will attempt to pre-populate this field for you, based on your selection of the database type on the prior screen. If the field does not populate correctly, you can copy and paste the values below, or exit and re-launch the IUA. IBM DB2 LUW Microsoft SQL Server Oracle Database PostgreSQL jdbc:db2://servername:50000/ dbname:fullymaterializelobdata=true;fullymaterializeinputstreams=true; progressivestreaming=2;usejdbc4columnnameandlabelsemantics=2; jdbc:sqlserver://servername:1433; database=dbname;selectmethod=cursor;sendstringparametersasunicode=false jdbc:postgresql://servername:5432/dbname Database Username and Password Enter the user name and password you created for the PRPC user on your database. Be sure you have configured the database user you will use during the upgrade with full read, write, and administration permissions. The user must have access to the schema for the Process Commander database. In particular, the database operator used to connect to the database during the upgrade procedure must be explicitly granted privileges that allow them to create user defined functions. IBM DB2 LUW Microsoft SQL Server Oracle Database CREATE EXTERNAL ROUTINE CREATE FUNCTION CREATE PROCEDURE Oracle users should use a "Deployment" user instead of the user associated with the rules schema or data schema for this step. "Upgrading from a Single to Split-Schema Configuration" on page 33 Rules Schema Name Enter the name of the Rules schema in the PRPC database. Data Schema Name Enter the name of the Data schema in the PRPC database. If you are upgrading from PRPC 5.x or 6.x to PRPC 7.1.5, the value is identical to the Rules Schema Name. 7. When you have completed entry of the database connection information, click Test Connection. If the connection is not successful, review your connection information, correct any errors and retest. 8. When successful, click to continue. PegaRULES Process Commander Upgrade Guide 20

23 Check the Bypass Automatic DDL Application box if you have already applied the PRPC 7.1 schema to your database. To manually generate the PRPC DDL for you platform, use the generateddl.bat/.sh script. For detailed instructions, see the Database Preparation section of your 7.1.5Installation Guide. 9. Click to select Upgrade Options. PegaRULES Process Commander Upgrade Guide 21

24 Select the Upgrade Options. Check the Run rulebase cleanup box to permanently remove rules older than n, where n is the current major-minor version that you are upgrading from. For example, if you are upgrading from 6.2 SP2 ( ) to 7.1.5, this feature will remove rules of version and older. Check the Update existing applications checkbox to run the Update Wizard as part of the automated upgrade process. The Update Wizard is an activity that modifies several types of existing rules in your system to be compatible with 7.1.5, and then performs a few procedures to complete your system configuration. If you do not choose to run the wizard automatically, you must run it from within PRPC when you first log in after the upgrade. Check Rebuild database indexes if you want the IUA to rebuild the database indexes automatically at the end of the Rulebase Load process. The IUA rebuilds the database indexes to ensure good performance in the upgraded system. The amount of time this process adds to the upgrade procedure depends on the size of your database. 10. Click to start the Rulebase Load. PegaRULES Process Commander Upgrade Guide 22

25 Click to begin updating the database with the rules. The IUA automatically displays a log so you can follow the process. The rulebase upgrade time can last for several hours and will vary widely based on network proximity to the database server. The log window may appear inactive when the IUA is processing larger files. The upgrade log can be found in the [distribution image]/scripts/logs directory. 11. Click to close the IUA. Upgrade PRPC Applications Before reconfiguring your Application Server to work with PRPC 7.1.5, review the application server configuration requirements in the 7.1 Platform Support Guide and the Installation Guide for your application server and database platform. If you are making changes in your environment as part of the PRPC upgrade, do them before upgrading PRPC. Perform the following steps to redeploy the PRPC components. 1. Make sure that the PRPC applications prweb.war or the prpc_*.ear file, prhelp.war, and prsysmgmt.war are not running. 2. Use your application server administrative utilities to remove each of the current versions of the PegaRULES Process Commander Upgrade Guide 23

26 PRPC applications. Tomcat In the Tomcat Web Application Manager page, find the row for each PRPC application and select the Undeploy link. In the WEBAPPS directory, delete any remaining PRPC folders or WAR files. WebSphere In the WebSphere Administrative console, navigate to Applications -> Enterprise Applications to see a list of the installed applications. Select each of the PRPC applications and click Uninstall. When you click Uninstall on a package, WebSphere empties the./installedapps/* directories. To complete the uninstall, you should also delete the following directories:./config/temp/*./wstemp/*./temp WebLogic Click Deployments to see the Summary of Deployments page. Click Lock & Edit in the Change Center, select each PRPC application, and click Delete. 3. Delete everything in the PRPC temporary directory. This is the directory that you specified for the JNDI location url/initialization/explicittempdir. 4. Follow the procedures in the Installation Guide for your application server to deploy the PRPC applications to your application server. prweb.war or the appropriate prpc_*.ear file prsysmgmt.war the System Management application prhelp.war the Developer Online Help application Do not start the redeployed PRPC applications while the rulebase update process is running in the IUA. By default, your application server may start the PRPC applications automatically when they are deployed. If you deploy and start the PRPC application before creating the database, the application generates an error and fails to start. This error is not harmful, and you will be able to restart the application successfully when the database is available. 5. Verify that any third-party or custom JAR files that you install with the PRPC application are still in place in the application server. Restore any that may have been deleted when the PRPC components were redeployed. Configure PRPC After completing the rulebase update in the IUA, follow these procedures to complete the PRPC upgrade. PegaRULES Process Commander Upgrade Guide 24

27 Log in to PRPC to Perform Final Steps 1. Stop and restart the application server. 2. Ensure that all the PRPC applications have started. prweb.war or prpc_ *.ear file prhelp.war prsysmgmt.war 3. Access the PRPC servlet, PRServlet, through a browser. Type in the URL for PRPC application: For example: The PegaRULES login screen (PRServlet) displays. 4. Login to PRPC using the following credentials. UserID: administrator@pega.com Password: install The PRPC Developer portal displays with a welcome message in the What s Happening section of the page. This page provides links to tools you will use to complete the upgrade process. Run the Update Wizard If you did not chose to run the Update Wizard automatically as part of the process in the IUA, run it now by clicking Upgrade Wizard in the What's Happening message. PegaRULES Process Commander Upgrade Guide 25

28 1. Either click Upgrade Wizard in the What's Happening message or select > System > Upgrade > Upgrade Existing Applications. This page lists a series of activities that modify your existing applications to support the upgraded version of PRPC. The specific actions listed depend on which version of PRPC you have upgraded from. The display lists the functions that will be performed, the number of records that will be modified, and an estimate of the time each function will take. 2. Click Run at the bottom of the page to start the wizard. The page updates as each action is run, and a progress bar tracks the total processing. Wait for the wizard to finish. When the message Update Wizard Complete displays, go on to the rest of the configuration activities. Enable Developer Help and the System Management Application To enable Help and the System Management Application, you must set the URLs that are used to access them. PegaRULES Process Commander Upgrade Guide 26

29 1. Select > System > Settings > URLs. 2. Complete this page to specify the URLs to access the Online Help (prhelp.war) and System Management (prsysmgmt.war) applications, and the Public Link URL used for Directed Web Access. Each of these fields takes the form: If you specify localhost as the <host>, only users logged into the same server on which the applications are deployed are able to access the applications. In most cases you should supply the actual server name to allow access to the applications from other computers. Edit the Online Help URL field to contain the specific server host and port for the prhelp application. For example: Edit the Public Link URL field to contain the specific server host and port that will be used by the Directed Web Access feature. For example: port>/prweb/prservlet Directed Web Access (DWA) enables external users that do not have a PRPC Operator ID to process an assignment in your application on a one-time basis. The URL you specify here is provided in an to the external users to access PRPC and may identify a proxy server. For more information, see the PDN article How to Implement Directed Web Access. Edit the SMA URL field to contain the specific server host and port for the System Management Application. For example: 3. Click Submit. 4. Log out of PRPC and log back in for these changes to take effect. Configure Search Search indexing supports the full-text search facility in PRPC for rules, data instances, and work objects. PegaRULES Process Commander Upgrade Guide 27

30 By default, Search indexing is enabled and starts automatically when you start the application server after upgrading PRPC. The Search engine uses default settings after an upgrade; prior settings are not preserved and will need to be reconfigured. 1. Click > System > Settings > Search. 2. Expand Index Host Node Settings. Modify the settings as required for your site and click Submit. 3. In the Index Administration section: Click Re-Index for All Rules to regenerate the Rules indices. The page displays the progress of the index process as it progresses, and a confirmation dialog box when it completes. Click Re-Index for All Data Optionally, you can re-index Work classes. Click the Enable checkbox, then click Re-Index for All Work. Redeploy Custom and Third-party JAR Files If you had any custom JAR files in your PRPC installation, you must use the Import Wizard to re-import them. 1. Select > Application > Distribution > Import. 2. Browse to select the JAR for import, then click Next. PegaRULES Process Commander Upgrade Guide 28

31 3. Review and complete the remaining screens in the wizard until the JAR is imported. Lock and Roll RuleSet Versions After an upgrade, lock your existing RuleSets and roll them into new versions before continuing development. This ensures that future development is based on the upgraded Pega RuleSets and that your applications consistently reference the latest features. The upgrade process automatically updates any prerequisite for Pega-ProCom to the highest version of the Pega-ProcessCommander RuleSet in the system. 1. Click > Application > Structure >Other Applications. This page displays all applications in the system and lists the RuleSets and RuleSet versions that make up each application including those inherited from any built-on applications. 2. For each application, click Lock and Roll to display the application page. Select + next to Prerequisites to see the RuleSet version prerequisities for the application RuleSet. You can click on the name of the RuleSet version to open and modify its rule form. 3. Select the Lock checkbox and select Update my Application to include the new RuleSet PegaRULES Process Commander Upgrade Guide 29

32 Versions. The Password field displays. 4. Enter the Password for this RuleSet version and select the Roll checkbox. 5. In the Roll to Version field, enter a new RuleSet Version or accept the default version which increments the current version by one. 6. In the New section of the Prerequisites you can modify the RuleSet prerequisites. By default, they are the same as the current prerequisite. You can select different prerequisites, add additional prerequisites, and/or delete prerequisites from the New list. 7. Click Run to apply the changes to your RuleSet. PegaRULES Process Commander Upgrade Guide 30

33 8. Repeat these steps for each application in your system. Run the Final Rules Conflict Report Click Final Conflicts Report in the What's Happening message or click > System > Upgrade > Final Conflicts. PRPC displays a report of rules in your system that reference Pega rules that have been made Final in this release. The rules listed vary depending on the specific PRPC release from which you are upgrading. Rules that are marked Final can no longer be overridden. If you have custom rules in your applications that override PRPC rules that have now been made Final, your existing rules will continue to execute correctly. However, you will not be able to modify them after you upgrade to the new RuleSet. If you modify and try to save a custom rule that overrides a Final rule, validation fails and you receive an error message. To resolve the conflict, you must delete application rules that override Final system rules, and replace the functionality in your application with other rules. If you are unsure how to respond to a Final rule, contact your onsite Pega representative or Global Customer Support. Upgrade Solution Frameworks If your PRPC installation includes any of Pegasystems Solution Frameworks, upgrade the Framework before continuing with these steps in PRPC. Follow the instructions in the Upgrade Guide for the version of your Solution Framework that is compatible with PRPC Then continue with the configuration described in this step. To ensure good performance when upgrading a large PRPC Framework application, such as CPM, it is important to disable all PRPC agents and run only a single PRPC node when you import the Framework application JAR file. This ensures that the only activity executing in the PRPC system is the import job itself. To disable agents: 1. Select > System > Tools > System Management Application and open the Node for the PRPC system you are upgrading. You may need to click + and create the node if this is your first time in the System Management Application. 2. In the System Management Application, go to Agent Management > Agents and click Stop under All activities in queue. 3. After the Framework import is complete, click Restart to re-enable the agents. Complete Post-Upgrade Configuration Following the upgrade, you may need to make some additional modifications to your existing applications to take advantage of new functionality in PegaRULES Process Commander Upgrade Guide 31

34 Review Upgrade Tools In PRPC, click >System > Upgrade > Upgrade Tools to review additional upgrade activities that may apply to your applications. It is recommended that you run all of these utilities, even though some may not return results for your application. Review the General Utilities and run those that apply to your applications. These utilities help you identify general issues with your application. Test Your Applications The procedures in this section remove the known compatibility issues between version and earlier PRPC versions. However, depending on your development methods, you may discover additional modifications that need to be made in your existing applications when they are upgraded to Be sure to perform full testing of your application functionality after the upgrade. Check the Pega Discovery Network (PDN) for Updates Visit the Pega Discovery Network (PDN) at for the latest information about this release of PRPC. PegaRULES Process Commander Upgrade Guide 32

35 Upgrading from a Single to Split-Schema Configuration This section describes how to upgrade your system to a split-schema configuration from an environment with a standard, single-schema configuration. To upgrade from a split-schema configuration, see the Upgrading from a Split-to-Split Configuration topic. First, there is an overview of the process, followed by descriptions of the migrate and upgrade scripts, and finally, steps for upgrading with one database or two databases. Overview In a split-schema configuration, PRPC Rules are maintained in one schema, and Data and Work are maintained in another schema. This configuration is officially supported as an option in PRPC as part of the standard product, and is required for customers planning to use PRPC High Availability features. To upgrade to a split-schema configuration, you first conduct an out-of-place upgrade. An out-of-place upgrade refers to the process of upgrading an inactive PRPC rulebase; that is, a rulebase that is not actively serving any consumers. One of the advantages of this approach is that it imposes minimal downtime on the system to be upgraded. This is ideal for customers that have strict downtime requirements, especially in Production or other critical environments. Customers requiring zero downtime must use the High Availability features. For more information on PRPC High Availability, see the PRPC 7.1.5High Availability Administration Guide. In PRPC 7.1.5, new tools have been introduced to automate various aspects of an out-of-place upgrade. These tools are described in this section, along with the process for using them. To perform the upgrade, at the minimum, you need one machine, one database, and two schemas. The generic process for upgrading to a split-schema configuration can be summarized in the following steps: Create a blank schema: Create a new blank schema in a database of the same type and version (or in the same database). Migrate: Migrate the Rules table and associated objects from the current PRPC schema to the new schema. Upgrade Rules: Upgrade the Rules in the new schema. Upgrade Data: Apply any DDL changes to the old schema, which now will only use the Data objects. Reconfigure: Reconfigure the application server to access both the old and the new schema. Migrate script The migrate script is the main script you will use to migrate the Rules objects from the Data and Rules schema in your pre-7.1 system to a new Rules schema. You will also use the script to perform operational functions, such as generating and applying Rules schema objects after upgrading the Rules schema. The Migrate script, called migrate.bat or migrate.sh for Linux, is located in the scripts folder of your distribution and configured via the migratesystem.properties file. You are strongly encouraged to use the migrate.bat/.sh script to perform these steps. The use of vendor tools is not recommended. The Migrate script is designed to automate many aspects of the data movement process, including: PegaRULES Process Commander Upgrade Guide 33

36 Export of appropriate tables and data objects from the source system schema; Generation and application of DDL to the target system schema; Import of appropriate tables and data objects to the target system schema. Common properties The following common properties must be configured in the migratesystem.properties file to log on to the databases used for each schema. If you are using one database for each schema, these properties will be the same for each step. However, if you are using different databases for the Rules and Updated Rules schemas, these properties will be different, depending on which database the schema is hosted on. The table below lists the common properties, their descriptions, and valid values. Source properties apply to the system being migrated from, and target properties apply to the system being migrated to. Set the properties by adding the appropriate value after the equals sign in the properties file. Set the properties by adding the appropriate value after the equals sign in the properties file. Property pega.source.jdbc.driver.jar pega.target.jdbc.driver.jar Description The path to the JDBC jar file. For databases that uses multiple JDBC driver files (such as DB2), you may specify semicolon separated values. Valid values are: Oracle 10g (Type 4): oracle.jdbc.oracledriver pega.source.jdbc.driver.class pega.target.jdbc.driver.class IBM DB/2 Type 4: com.ibm.db2.jcc.db2driver SQL Server 2008: com.microsoft.sqlserver.jdbc.sqlserverdriver PostgreSQL 9.1.4: org.postgresql.driver pega.source.database.type pega.target.database.type Valid values are: mssql, oracledate, udb, db2zos, postgres Valid values are: Oracle 10g (Type 4): IBM DB/2 z / OS: jdbc:db2://localhost:50000/dbname pega.source.jdbc.url pega.target.jdbc.url IBM DB/2 Type 4: jdbc:db2://localhost:50000/dbname:fullymaterializelob Data=true; fullymaterializeinputstreams=true;progressivestreamin g=2; usejdbc4columnnameandlabelsemantics=2; SQL Server 2008: jdbc:sqlserver://localhost:1433;selectmethod=cursor; sendstringparametersasunicode=false pega.source.jdbc.username pega.target.jdbc.username PostgreSQL 9.1.4: jdbc:postgresql://localhost:5432/dbname Database username. PegaRULES Process Commander Upgrade Guide 34

37 Property Description On Oracle, you will use the Deployment user most of the time, as noted in the steps below. pega.source.jdbc.password pega.target.jdbc.password Database password. Custom properties The following properties are used during migration to configure custom settings. Property pega.source.jdbc.custom.connection.properties pega.target.jdbc.custom.connection.properties pega.source.data.schema pega.target.data.schema pega.target.bypass.udf pega.target.zos.properties Description Any custom connection properties. Used to correctly schema qualify tables in stored procedures, views and triggers. This property is not required if migrating before performing an upgrade. Set this property to bypass udf generation on the system. The location of the db2zos site specific properties file. Only used if the target system is a db2zos database. Valid value: config/db2zos/db2sitedependent.properties Migration directory properties Set the directories for migration objects. Property pega.bulkmover.directory pega.migrate.temp.directory Description The directory where output from the bulk mover will be stored. This directory will be cleared when pega.bulkmover.unload.db is run. This property must be set if either pega.bulkmover.unload.db or pega.bulkmover.load.db is set to true. The location where a temporary directory will be created for use by the migrate system utilities. Operational properties Use the following properties to migrate Rules objects. Set to true or false. Property pega.move.admin.table pega.clone.generate.xml pega.clone.create.ddl pega.clone.apply.ddl pega.bulkmover.unload.db pega.bulkmover.load.db Description Set to true if migrating before an upgrade and migrating to a different system. If true admin table(s) required for an upgrade will be migrated with the rules tables. Generate an XML document containing the definitions of tables in the source system. It will be found in the schema directory of the distribution image. Create DDL from the generated xml document. This DDL can be used to create copies of rule tables found on the source system. Apply the generated clone DDL to the target system. Unload the data from the rules tables on the source system into the pega.bulkmover.directory. Load the data onto the target system from the pega.bulkmover.directory. PegaRULES Process Commander Upgrade Guide 35

38 Rules schema object properties This table describes operations that should only be run when migrating upgraded rules: Property pega.rules.objects.generate pega.rules.objects.apply Description Generate the rules schema objects (views, triggers, procedures, and functions). The objects will be created in the pega.target.rules.schema but will contain references to the pega.target.data.schema where appropriate. Apply the rules schema objects (views, triggers, procedures, and functions) to pega.target.rules.schema. Upgrading options You can either use the Installation and Upgrade Assistant (IUA) or an upgrade script to upgrade the Rules schema. It is recommended that you use the IUA for most upgrades, unless there are specific options that you need to configure using the command line script. The process of using the IUA is identical to the one described in the Rulebase Setup section of this document, with one exception: On the Database Connection screen, you will specify the new Rules schema name for both the Rules Schema Name and Data Schema Name fields. For example: Upgrade script If you prefer to have more control over your upgrade, you can use the Upgrade script. The Upgrade script, called upgrade.bat or upgrade.sh for Linux, is located in the scripts folder of your distribution PegaRULES Process Commander Upgrade Guide 36

39 and configured via the setupdatabase.properties file. The table below describes the properties. Common and custom properties The common properties for the setupdatabase.properties file have similar values as the properties in the migratesystem.properties file, except without the "source" or "target" references in the property name: pega.jdbc.driver.jar pega.jdbc.driver.class pega.database.type pega.jdbc.url pega.jdbc.username pega.jdbc.password The custom property, jdbc.custom.connection.properties, is also used for similar purposes. "Common properties" on page 34 and "Custom properties" on page 35 for details about these properties. Upgrade properties The following table describes the rest of the properties in this file. When performing a typical upgrade, you should not modify these properties. Property pega.codeset.name Description The Pega codeset name, usually Pega-EngineCode. pega.codeset.version The Pega codeset version, such as rules.schema.name data.schema.name user.temp.dir pega.zos.properties bypass.pega.dll.generation bypass.pega.schema bypass.udf.generation run.assembler import.assembled.classes rebuild.indexes The user name is used for default schema name. Used for systems running Split Schema. For those that are not, the value of rules.schema.name is the default value for this property. The temporary directory for the user. The default is used if this property is left blank. z/os site specific properties file. Generate schema dynamically. Setting to false will enable dynamic DDL generation. Setting to true or leaving blank will cause system to use torque/velocity files in../schema folder. Generate schema will be skipped if this property is set to true. Leave this property blank if you need to generate the schema. Generate UDF will be skipped if this property is set to true. Leave this property blank if you need to generate the UDF. Run assembler after install/upgrade? This property defaults to true for an upgrade and false for an install. This setting is to generate the Assembled Java classes instead of Importing them. Load Assembled Java classes. True or false value. Rebuild Database Rules Indexes. This occurs after Rules Load to improve Database Access Performance. This option is ignored and set to false for PegaRULES Process Commander Upgrade Guide 37

40 Property system.name production.level Description db2 z/os. However, rebuilding database indexes is strongly recommended for better performance. In DB2 z/os it can be executed manually by running the stored procedure SPPR_REBUILD_INDEXES. The system name uniquely identifies a single Process Commander System. Since multiple PRPC Systems may reference the same database, it is important that each system has a unique name in order to distinguish them from each other. During installs, the following system name will be created. During installs, the above system name is generated with the following production level. The system production level can be set to one of the below integer values (1-5): 5 = production; 4 = preproduction; 3 = test; 2 = development; 1 = experimental multitenant.system upgrade.runupdatewizard import.hotfix.path import.codeset.name import.codeset.version build.conclusions db2zos.udf.wlm run.ruleset.cleanup generate.benchmarks benchmark.warning.threshold.value benchmark.kill.threshold.value Is this a multitenant system? A multitenant system allows organizations to act as distinct PRPC installations. Run the update wizard after upgrade? Default value is false. Update wizard can be run from upgrade scripts, prpcutils, or by directly launching in PRPC after upgrade. Load HotFixes on install/upgrade? HotFix path can be single file, multiple comma delimited files or directory. Files can be loaded through prpcutils or by directly launching in PRPC after install/upgrade. Path must be relative to /scripts directory. Pre-build the Pega Conclusions. Workload manager to load UDFs into db2zos. Run RuleSet Cleanup. Generate and execute a SQL script to clean old rulesets and their rules from the system. If you would like to only generate the script, not execute it, see cleanup.bat or cleanup.sh script. Uncomment to generate timing benchmarks. Upgrading with one database This section describes the process for upgrading your system using one machine, one database, and two schemas. The picture below shows the schemas with arrows depicting the upgrade steps. PegaRULES Process Commander Upgrade Guide 38

41 The schema labeled Data Schema is your existing (pre-7.1) schema. As such, this schema contains Rules, Data and Work tables and database objects (triggers, stored procedures, etc.). In contrast, the schema labeled Rules Schema contains only Rules tables and database objects. At the conclusion of the process described in this section, the Data Schema will be used only for Data and Work objects, and the Rules Schema will be used for Rules objects. It is important to keep this in mind as you go through this process. The arrow that goes from the Data Schema to the Rules Schema indicates how you will initially migrate Rules tables and database objects from your existing pre-7.1 schema to the Rules Schema. Rules tables will still exist in this Data Schema, but after the upgrade process has been completed, they will no longer be used. The arrow that goes from the Rules Schema back to itself indicates the in-place upgrade to be performed on this schema, as well as the migration step to generate and apply the Rules schema objects. While this is all shown in one database, you can also perform this upgrade using two different systems and databases. This is encouraged to take advantage of high availability features for upgrades that require minimal downtime. Additionally, if you are upgrading a production system, you may want to use this setup. See "Upgrading with two databases" on page 45 for details. On Oracle databases, users and schemas are the same thing. In the original database, you must create and use a separate "Deployment" user. This user should have Database Administrator privileges in order to access both the rules and data schemas, and to issue grants to them. See the Oracle installation guide for your application server for details about these privileges. PegaRULES Process Commander Upgrade Guide 39

42 Create a new physical schema First, create a new blank schema in a database of the same type and version. This can be done using your database vendor s administrative tools. In the schematic above, this schema is labeled and referred to as the Rules Schema. On Oracle, this will also create a new user associated with the schema. Grant the UNLIMITED TABLESPACE privilege to this user. Migrate rules tables Next, use the migrate script to migrate the rules tables and other required database objects from the existing schema (the Data Schema in the picture above) to the new schema. You will also use this script later to generate and apply rules objects after the upgrade. To use the Migrate script: 1. Use a text editor to edit the migratesystem.properties. The file is located in the scripts directory of your distribution. <PRPC_HOME>\scripts\migrateSystem.properties 2. Configure the properties used to access the source system. #The system where the tables/rules will be migrated from pega.source.jdbc.driver.jar=source.jar pega.source.jdbc.driver.class=source.class pega.source.database.type=type pega.source.jdbc.url=source.url pega.source.jdbc.username=source.user pega.source.jdbc.password=source.pass On Oracle, use the username and password of the Deployment user. Enter the original schema, the Data Schema, as the source rules schema: pega.source.rules.schema=data Schema 3. Configure the properties used to access the target system. pega.target.jdbc.driver.jar=target.jar pega.target.jdbc.driver.class=target.class pega.target.database.type=type pega.target.jdbc.url=target.url pega.target.jdbc.username=target.user pega.target.jdbc.password=target.pass On Oracle, use the username and password of the Deployment user. Enter the name of the rules schema: pega.target.rules.schema=rules Schema PegaRULES Process Commander Upgrade Guide 40

43 If you are upgrading from a 7.1 split schema system to a newer version with split schema, specify the source data schema using the pega.source.data.schema property. See "Upgrading from a Split-to-Split Configuration" for details. 4. Configure file system directories required by the utility: pega.bulkmover.directory=output directory pega.migrate.temp.directory=temporary directory 5. Enable operations to be performed by the utility. It is recommended to set the value for each of these properties to true, as shown below. pega.move.admin.table=true pega.clone.generate.xml=true pega.clone.create.ddl=true pega.clone.apply.ddl=true pega.bulkmover.unload.db=true pega.bulkmover.load.db=true 6. Save the script after editing. 7. Open a command prompt, and navigate to the scripts directory. 8. Execute the script by typing migrate.bat or./migrate.sh for Linux. Command line output will automatically be written to a file in the <PRPC_HOME>\scripts\logs directory. Upgrade the rules schema Next, upgrade the migrated Rules schema using either the Installation and Upgrade Assistant (IUA), or the command line script upgrade.bat or upgrade.sh for Linux. Using the Installation and Upgrade Assistant If you prefer a UI-based approach, use the Installation and Upgrade Assistant (IUA). The procedure for running the assistant is identical to the one described the Rulebase Setup section of this document -- with one exception: On the Database Connection screen, you will specify the new Rules schema name for both the Rules Schema Name and Data Schema Name fields. For example: PegaRULES Process Commander Upgrade Guide 41

44 Using the command line If you prefer a scripted, command-line approach, use the upgrade.bat or the upgrade.sh for Linux tool. This script is located in the scripts folder of your distribution and is configured via the properties file setupdatabase.properties. To use the Upgrade script, follow this procedure. 1. Use a text editor to edit the setupdatabase.properties. The file is located in the scripts directory of your distribution. <PRPC_HOME>\scripts\setupDatabase.properties 2. Configure the properties used to access the system containing the schema to be upgraded: pega.source.jdbc.driver.jar=rules Schema jar pega.source.jdbc.driver.class=rules Schema class pega.source.database.type=type pega.source.jdbc.url=rules Schema url pega.source.jdbc.username=rules Schema user pega.source.jdbc.password=rules Schema pass On Oracle, use the username and password of the Rules Schema user. 3. Enter the name of the Rules schema to be upgraded: PegaRULES Process Commander Upgrade Guide 42

45 rules.schema.name=rules Schema When using the Upgrade script, it is not necessary to configure the name of the Data Schema via the property data.schema.name. If this property is not specified, the Upgrade script assumes that the value is the same as the value specified by rules.schema.name. 4. Save the script after editing. 5. Open a command prompt, and navigate to the scripts directory. 6. Execute the script by typing upgrade.bat or./upgrade.sh for Linux. The Upgrade script writes log output to the directory <PRPC_HOME>\scripts\logs. If you encounter any errors or issues when running the script, make sure you save the contents of this directory first. Generate rules schema objects Next, use the Migrate script to generate rules schema objects. This is a crucial step that must be done for the Rules schema to operate properly. To do this, you use the same migrate.bat or migrate.sh script as before, but configured differently. You are strongly encouraged to use the migrate.bat/.sh script to manage this step of the process. The use of vendor tools to manage this step is not recommended. Follow these steps to generate rules schema objects: 1. Open the migratesystem.properties file that you used to migrate the Rules Schema. Keep the same values for the source and target destinations. Since you are not migrating the Rules Schema again, set all of the Operational properties to false in the migratesystem.properties file: pega.move.admin.table=false pega.clone.generate.xml=false pega.clone.create.ddl=false pega.clone.apply.ddl=false pega.bulkmover.unload.db=false pega.bulkmover.load.db=false 2. Set the following properties to true to generate and apply rules objects: pega.rules.objects.generate=true pega.rules.objects.apply=true 3. Save the script after editing. 4. Open a command prompt, and navigate to the scripts directory. 5. Execute the script by typing migrate.bat or./migrate.sh for Linux. Command line output will automatically be written to a file in the <PRPC_HOME>\scripts\logs directory. PegaRULES Process Commander Upgrade Guide 43

46 Run data schema upgrade Thus far you have only dealt with the Rules schema. However, PRPC 7.1 also requires changes to the Data schema. To make the requisite changes to the Data schema, follow the steps below. If you are upgrading from a version prior to 7.1, shut down your system before running the data schema upgrade. If you are upgrading from a 7.1 version to a later version, you do not need to shut down your system before running the data schema upgrade. 1. Use a text editor to edit the setupdatabase.properties. The file is located in the scripts directory of your distribution. <PRPC_HOME>\scripts\setupDatabase.properties 2. Configure the properties used to access the system containing the Data Schema: pega.jdbc.driver.jar=data Schema jar pega.jdbc.driver.class=class pega.database.type=type pega.jdbc.url=url pega.jdbc.username=user pega.jdbc.password=pass On Oracle, use the username and password of the Deployment user. 3. Configure the name of the Rules Schema: rules.schema.name=rules Schema 4. Configure the name of the Data schema: data.schema.name=data Schema 5. Save the script after editing. 6. Disable PRPC access to the Data Schema. 7. Open a command prompt, and navigate to the scripts directory. 8. Execute the script by typing upgrade.bat or./upgrade.sh for Linux, passing in the dataonly argument and true parameter. For example: >upgrade.bat --dataonly true The Upgrade script writes log output to the directory <PRPC_HOME>\scripts\logs. If you encounter any errors or issues when running the script, be sure to save the contents of this directory first. Reconfigure the Application Server Deploy the 7.1.5WAR or EAR file on the application server and modify the JNDI settings so that the datasource is using the correct schemas. Refer to the Installation Guide for your specific platform for configuration instructions. PegaRULES Process Commander Upgrade Guide 44

47 Clean Up Unused Tables It is recommended that you drop unused rules tables in the data schema after running a split schema upgrade. Follow the steps below to do so. 1. To open the optimize schema wizard, click the Designer Studio menu option > System > Database > Optimize Schema. 2. Select the PegaDATA database. 3. Click view the unused tables to display a list of PRPC tables without Class mappings. Select the ones you want to delete and click Proceed with Changes to have PRPC drop the tables, or you can drop them manually in your database. Upgrading with two databases As an alternative to the above, you can set up your upgrade schema on a different database and server, as shown below. In this case, the source and target systems are different, so be sure to configure the common properties correctly to access each database. In this setup, you will migrate Rules objects from the Data Schema to another database to be upgraded (called the "Updated Rules Schema" in the picture). Then you will migrate the Updated Rules Schema into a new Rules Schema on the database containing the Data Schema. PegaRULES Process Commander Upgrade Guide 45