Pega Platform 8.6: Upgrade Guide For Tomcat and Oracle
Pega Platform 8.6: Upgrade Guide For Tomcat and Oracle
Trademarks
For Pegasystems Inc. trademarks and registered trademarks, all rights reserved. All other trademarks or
service marks are property of their respective holders.
For information about the third-party software that is delivered with the product, refer to the third-party
license file on your installation media that is specific to your release.
Notices
This publication describes and/or represents products and services of Pegasystems Inc. It may contain
trade secrets and proprietary information that are protected by various federal, state, and international
laws, and distributed under licenses restricting their use, copying, modification, distribution, or transmittal
in any form without prior written authorization of Pegasystems Inc.
This publication is current as of the date of publication only. Changes to the publication may be
made from time to time at the discretion of Pegasystems Inc. This publication remains the property
of Pegasystems Inc. and must be returned to it upon request. This publication does not imply any
commitment to offer or deliver the products or services described herein.
This publication may include references to Pegasystems Inc. product features that have not been licensed
by you or your company. If you have questions about whether a particular capability is included in your
installation, please consult your Pegasystems Inc. services consultant.
Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain
inaccuracies or typographical errors, as well as technical inaccuracies. Pegasystems Inc. shall not be liable
for technical or editorial errors or omissions contained herein. Pegasystems Inc. may make improvements
and/or changes to the publication at any time without notice.
Any references in this publication to non-Pegasystems websites are provided for convenience only and
do not serve as an endorsement of these websites. The materials at these websites are not part of the
material for Pegasystems products, and use of those websites is at your own risk.
Information concerning non-Pegasystems products was obtained from the suppliers of those products,
their publications, or other publicly available sources. Address questions about non-Pegasystems
products to the suppliers of those products.
This publication may contain examples used in daily business operations that include the names of
people, companies, products, and other third-party publications. Such examples are fictitious and any
similarity to the names or other data used by an actual business enterprise or individual is coincidental.
This document is the property of:
Pegasystems
One Rogers Street
Cambridge, MA 02142-1209, USA
Phone: 617-374-9600 Fax: 617-374-9620
www.pega.com
Document: Pega Platform upgrade
Publication date: October 22, 2021
Feedback
If you have comments for how we can improve our materials, send an email to [email protected].
Contents
Post-upgrade tasks.................................................................................................................................................................................. 28
Upgrading from PRPC 6.1 SP2 and earlier: updating ruleset columns.............................................................................................28
Optional: Upgrading to Hazelcast 4.x.................................................................................................................................................... 28
Appendices................................................................................................................................................................................................ 46
Migrate script properties......................................................................................................................................................................... 46
Customizing deployment script behavior............................................................................................................................................. 49
Database connection properties and script arguments....................................................................................................... 49
Additional upgrade properties..................................................................................................................................................50
Manually generating and applying the DDL......................................................................................................................................... 52
Generating and applying DDL in an out-of-place upgrade.................................................................................................. 53
Generating and applying DDL in an in-place upgrade..........................................................................................................56
Generating the DDL file...............................................................................................................................................56
Applying the DDL file................................................................................................................................................... 57
Alternative upgrade: Upgrading in-place.............................................................................................................................................. 57
Upgrade methods for an in-place upgrade............................................................................................................................ 58
Upgrading in-place by using the Installation and Upgrade Assistant................................................................... 58
Upgrading in-place from the command line............................................................................................................ 60
Alternative upgrade: Upgrading out-of-place with a double migration process............................................................................. 60
For High Availability systems: Preparing the cluster for upgrading.................................................................................... 61
Creating three new schemas on two databases....................................................................................................................61
Migrating the existing rules schema........................................................................................................................................62
Migrating the rules schema when the process includes access to both databases............................................62
Migrating the rules schema when the process can only access one database................................................... 63
Upgrade methods for the migrated rules schema................................................................................................................65
Upgrading by using the Installation and Upgrade Assistant..................................................................................65
Upgrading out-of-place by using the command line...............................................................................................66
Evaluating customizations
Consider your application customization, libraries, database, and special site requirements before
continuing.
• Components and third-party applications — If you are using any components or third-party
applications, confirm whether they are supported for this version of the Pega Platform. It might be
necessary to upgrade your versions of the components and third-party applications to work with the
new version of the Pega Platform.
• Customized Pega Platform database — If you made changes to the Pega Platform database schema,
incorporate those changes into the database after you upgrade the database schema. In particular,
you should merge any changes to 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 might need to
modify the tables to match changes in the Pega schema.
Also verify that schema references in stored procedures, and views correctly reflect the new schema
names.
• Third-party or custom libraries — If you have integrated third-party or custom libraries into your
system, make sure you have a copy of them before upgrading. The upgrade might overwrite your
deployed libraries if you added third-party JAR files to the prweb.war file the database and installed
them.
• Special site requirements — Your site might have special deployment, integration, or security
requirements. Schedule an early review of the upgrade procedure with the appropriate system and
database administrators.
• If you customized your web.xml to include a servlet for custom authentication, then the application
URL alias shown in application definition will be for informational purpose only. This application
URL alias will always be shown with the log in. For example: When Dev Studio is launched using
PRAuth servlet then the application URL shown has PRAuth as the servlet. You will have to replace the
customized servlet name instead of what is shown in application URL to launch an application.
Before you upgrade, ensure that your work resources in your application are thread-safe by reviewing
Best practices for writing background processing work.
If you do not configure stream nodes, by default, a Pega node starts with the following node types: Web
User, Background Processing, Search, and Stream. These nodes are the minimum set of node types that
are required to run Pega Platform. If you configure your own set of node types for each application server
JVM, make sure that your Pega cluster contains this minimal set of node types.
-DNodeType=Stream
1. Manually generate the DDL file. For more information, see Optional: Generating and applying DDL in
an out-of-place upgrade with a single migration.
2. In the DDL file, change pegadata.pr_data_ih to pegaih.pr_data_ih.
Committing hotfixes
Before you upgrade, commit any uncommitted hotfixes on your system. If there are uncommitted
hotfixes when you upgrade, the hotfixes are automatically committed. For information about committing
hotfixes, see Committing hotfixes.
Configuring ports
Before you configure your application server, ensure that the following ports are open and available:
• Search (Elasticsearch) — one TCP port in the range 9300-9399 (default 9300). This port is used for
internal node-to-node communication only, and should not be externally accessible.
• Cluster communication — leave open the port range 5701-5800. By default, the system begins with
port 5701, and then looks for the next port in the sequence (5702, followed by 5703 and so on). To
override the default port range, set a different value for the initialization/cluster/ports setting in the
prconfig.xml file.
• Kafka stream nodes — Port 9092
• Stream REST service — Port 7003
• Pega Platform can include multiple servers, or nodes, and each node can contain multiple Java Virtual
Machines (JVMs). The number of available ports in this range needs to be greater than or equal to the
greatest number of JVMs on any one node in the cluster. For example, if there are three JVMs on one
node, and seven JVMs on another node, there must be at least seven ports available.
1. On the database server, open the file SPFILE DBNAME.ora in the database directory.
2. Verify that the settings are as follows:
NLS_LENGTH_SEMANTICS=CHAR scope=both;
NLS_CHARACTERSET=AL32UTF8;
NLS_NCHAR_CHARACTERSET=AL16UTF16;
upgrade, your administrator should verify that your current processes outside of the use of a SPFILE
DBNAME.ora file are up-to-date to support the use of CHAR Oracle semantics:
• For Pega Platform installations: Manually generate and apply a DDL script that sets the session
initialization parameter NLS_LENGTH_SEMANTICS to CHAR. For the required steps, see Manually
generating and applying the DDL . Run the generateddl.bat (or generateddl.sh) script on your
database properties file, instruct your database administrator to add this line at the start of the
generated DDL script: alter session set nls_length_semantics=char, and then apply the
updated DDL to your database.
• Instruct your database administrator to create a logon trigger to run alter session set
nls_length_semantics=charwhenever the Admin user connects to the database, which ensures
that the session uses CHAR semantics.
• For Pega application installations and changes: Download the DDL script and apply a DDL
script that sets the session initialization parameter NLS_LENGTH_SEMANTICS to CHAR. For the
required steps, see Viewing and applying schema changes. Download the DDL script, instruct
your database administrator to add this line at the start of the script: alter session set
nls_length_semantics=char, and then apply the updated DDL to your database.
If your deployment does not meet all these criteria, follow the steps in this section to edit the
setupDatabase.properties file. The setupDatabase.properties file controls scripts which perform
the following tasks:
• The upgrade.bat or upgrade.sh script upgrades Pega Platform.
• The generateddl.bat or generateddl.sh script generates a DDL file of schema changes.
You can use the generateddl script regardless of whether you use the IUA or the command-line
script.
• The cleanup.bat or cleanup.sh script generates a DML file from which you can subsequently
remove old or unused rules after you complete your upgrade.
• The generateudf.bat or generateudf.sh script generates user-defined functions.
1. Open the setupDatabase.properties file in the scripts directory of your distribution image:
Directories.distributionDirectory\scripts\setupDatabase.properties.
2. Specify the properties for your system. For each property, add the appropriate value after the equal
sign. See Database connection properties and script arguments.
3. Optional: If you are repeating a failed upgrade, configure the resume property:
• To resume from the last successful step, set automatic.resume=true.
• To restart from the beginning, set automatic.resume=false.
4. Save and close the file.
◦ SELECT ON SYS.V_$PARAMETER
◦ ALTER SESSION
1. On the database server, use your preferred method to create users and grant the users unlimited
access to the user's tablespace. The following SQL example creates a user with unlimited access to the
default tablespace, USERS:
ALTER USER <user> DEFAULT TABLESPACE USERS QUOTA UNLIMITED ON USERS;
2. Use the Oracle tools to assign the appropriate roles and privileges to this user.
3. Repeat steps 1 and 2 for the remaining users:
• Oracle schema users: create separate Oracle rules and data schema users
• Deployment user
• Base user
• Admin user (for dual-user configurations)
In-place upgrades
While the out-of-place upgrade using a single migration process is the recommended method with
minimal downtime, some clients might need to perform the upgrade in-place. This upgrade process
upgrades rules without using temporary schemas and involves down time. For details, see, Alternative
upgrade: Upgrading in-place.
3. Migrate the rules structure and content and data structure from the existing rules and data schemas to
the new rules and temporary data schemas. Running the migration script creates any required tables
in the new rules and temporary data schemas, and copies and moves the rule content.
4. Upgrade the new rules schema. This process uses the temporary data schema in which it creates and
modifies any necessary data tables to store interim data content; these tables and data are discarded
when the temporary data schema is removed.
5. You must grant access to the new rules schema tables by using migrate.sh again to generate the
necessary rules objects (GRANT statements) which will link the existing data schema to the new rules
schema after you upgrade the new rules schema.
6. Shut down the system and upgrade the existing data schema.
7. Redeploy the application to run using the new rules, as described in Reconfiguring the application
server.
8. Revert the high availability cluster settings you modified at the beginning of the upgrade process.
9. Delete the temporary data schema from your database.
1. Use a text editor to edit the migrateSystem.properties file in the scripts directory of your
distribution image:
Pega-image\scripts\migrateSystem.properties
2. Configure the source properties. For more information, see Migrate script properties.
# Connection Information
pega.source.jdbc.driver.jar=full path/DRIVER.jar
pega.source.jdbc.driver.class=database driver class
pega.source.database.type=database vendor type
pega.source.jdbc.url=URL of database
pega.source.jdbc.username=Deployment user name
pega.source.jdbc.password=password
pega.source.rules.schema=existing rules schema
pega.source.data.schema=existing data schema
pega.target.jdbc.driver.jar=full path/DRIVER.JAR
pega.target.jdbc.driver.class=database driver class
pega.target.database.type=database vendor type
pega.target.jdbc.url=database URL
pega.target.jdbc.username=Deployment user name
pega.target.jdbc.password=password
pega.target.rules.schema=new rules schema
pega.target.data.schema=temporary data schema
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
pega.rules.objects.generate=false
pega.rule.objects.apply=false
9. Specify whether you will have your database administrator manually apply the DDL changes to the
schema. These changes include the user-defined functions (UDF) supplied by Pega. By default, the IUA
generates and applies the schema changes to your database.
• To generate and apply the DDL outside the IUA, you must first manually generate and apply the
DDL and UDF before continuing the deployment. For more information, see Optional: Generating
and applying DDL and Optional: Installing user-defined functions. . After the DDL and UDF have
been applied, select Bypass Automatic DDL Application and continue the deployment.
• To have the IUA automatically apply the DDL changes and the UDF, clear Bypass Automatic DDL
Application.
10. Click Next.
11. Select your options and click Next:
• Optional: Select Update applications schema. The Update Applications Schema utility updates
all auto-generated tables with the schema changes in the latest base tables. You can also run the
update applications schema utility later from the prpcUtils.bat or prpcUtils.sh script, or from
Dev Studio. For information about using the Update Applications Schema utility, see the online help.
• Optional: Select Run rulebase cleanup to permanently remove old rules. In most cases,
removing older rules improves the general performance of the system. Running the cleanup script
permanently removes rules older than the current version. You can also generate the cleanup
script DDL later using the cleanup.bat (on Windows) or cleanup.sh (on Linux) script. For more
information about using the cleanup script, see Customizing deployment script behavior.
• Optional: Select Update existing applications to modify your existing applications to support
the new version of the Pega Platform. The specific actions depend on your current version of
Pega Platform. If you do not automatically update the applications as part of the IUA, follow the
instructions in Updating existing applications to update the applications as part of the post-upgrade
process.
• Optional: Select Rebuild database indexes to have the IUA to rebuild the database indexes after
the rulebase loads. The IUA rebuilds the database indexes to ensure good performance after
the upgrade. The amount of time this process adds to the upgrade depends on the size of your
database.
12. Click Start to begin loading the rulebase. During the upgrade, the log window might appear inactive
when the IUA is processing larger files.
13. Click Back to return to the previous screen, and then click Exit to close the IUA.
1. Use a text editor to edit the migrateSystem.properties file in the scripts directory:
Pega-image\scripts\migrateSystem.properties
pega.target.jdbc.driver.jar=full path/DRIVER.JAR
pega.target.jdbc.driver.class=database driver class
pega.target.database.type=database vendor type
pega.target.jdbc.url=database URL
pega.target.jdbc.username=Deployment user name
pega.target.jdbc.password=password
pega.target.rules.schema=new rules schema name
pega.target.data.schema=existing data schema name
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
pega.rules.objects.generate=true
pega.rules.objects.apply=true
1. If encryption is enabled on the cluster, enable encryption on the upgrade script by adding the following
line to the prconfig.xml file:
You must enable encryption so that nodes that are created during the upgrade can join the existing
encrypted cluster.
2. If you have not already done so, configure the connection properties. Use your existing data
schema name for data.schema.name. Use the new rules schema name for rules.schema.name.
If you have an optional customer data schema separate from the Pega data schema, enter the
customerdata.schema.name. For more information, see Customizing deployment script behavior.
# Connection Information
pega.jdbc.driver.jar=/path-to-the-database-JAR-file/DRIVER.jar
pega.jdbc.driver.class=database driver class
pega.database.type=database vendor type
pega.jdbc.url=URL of the database
pega.jdbc.username=Deployment user name
pega.jdbc.password=password
rules.schema.name=new rules schema
data.schema.name=existing data schema
customerdata.schema.name=optional-customer-data-schema
3. Shut down the application server and ensure that no other processes are using the data schema.
4. Open a command prompt, and navigate to the scripts directory.
5. Run upgrade.bat (for Windows) or ./upgrade.sh (for Linux), passing in the --dataOnly argument
and true parameter, for example:
upgrade.bat --dataOnly true
What to do next: After you upgrade the data schema, redeploy the application to run using the
new rules and then review the post-upgrade tasks sections to complete the upgrade. At a minimum,
you must reconfigure the application to run using the new rules as described in Reconfiguring the
application server and enable rule creation, as described in Enabling rule creation.
Post-upgrade tasks
This section describes additional tasks to perform after the new rules schema and the existing data
schema have been upgraded.
Pega has reviewed the features and fixes in Pega Platform and has identified the areas where an upgrade
from Pega Infinity release 8.x to 8.y will have an upgrade impact. An upgrade impact occurs when a
feature or enhancement imposes a noticeable or blocking change. Review the release notes with upgrade
impact to determine whether you need to perform additional steps before or after an upgrade. For more
information, see Pega Platform changes with upgrade impact.
1. Open context.xml.
2. In the <context> element, update the following line to set the new default rules. Replace RULES with
your new rules schema name.
<Environment name="prconfig/database/databases/PegaRULES/defaultSchema"
value="RULES" type="java.lang.String" />
1. Open context.xml.
2. In the <context> element, update the following line to set the new default rules. Replace RULES with
your new rules schema name.
<Environment name="prconfig/database/databases/PegaRULES/defaultSchema"
value="RULES" type="java.lang.String" />
1. Make sure that prweb.war file for your application server is not running.
2. Remove each of the current versions of the applications.
a. In the Tomcat Web Application Manager page, find the row for each application and select
Undeploy.
b. In the WEBAPPS directory, delete any remaining folders or WAR files.
3. Copy the prweb.war file from the Pega-image\archives\ directory to the Tomcat_home\webapps\
directory.
4. Restart the application server.
5. Shut down the server and delete the prweb.war file from the Tomcat_home\webapps\ directory to
prevent Tomcat from redeploying the application each time the server restarts.
6. Verify that any third-party or custom JAR files that you added to the prweb.war file or the database
and installed are still in-place on the application server. Restore any JAR files that were deleted when
the Pega Platform redeployed.
follow URL redirects will not require updates; however, some automated tests may notice the URL redirect
and report a performance impact. As a known example, JMeter reports a performance impact; therefore
Pega provides JMeter-specific update instructions, Updating JMeter test scripts after migrating to Pega 8.4
or later.
If your Pega Platform 8.3 or earlier application logic/rules manipulate URLs, you must update the logic
after the upgrade to use the current URL aliasing format for each Pega application running from the same
hostname.
from: http:host/prweb/<PRServlet-name>/accessgroupHash/PRThread
to: http://host/prweb/<PRServlet-name>/app/<application-URL-alias>/accessgroupHash/
PRThread
After you upgrade your application from Pega Platform 8.3 or earlier, you must also review your
application rules to find any that use the clipboard property, pxRequestor.pxReqServletNameReal, to
discover a servlet name. For these rules, update each to use the pxRequestor.pxReqServlet property
as described in the table below.
Enabling operators
Pega Platform deployment security requires an administrator to enable new operators shipped with Pega
Platform and requires password changes after the first login.
The administrator and new operators shipped with Pega Platform must change their passwords when
they first log in:
• [email protected]
• AESRemoteUser
• [email protected]
• External
• ExternalInviteUser
• IntSampleUser
• PRPC_SOAPOper
• [email protected]
• UIServiceManager
• [email protected]
1. In the header of Dev Studio, click Configure > Org & Security > Authentication > Operator Access.
2. In the Disabled operators list, click the link for the Pega-provided operator that you want to enable.
The following standard operators are installed but disabled by default. When these standard operators
first log on, they are required to change their passwords. Enable only those operators you plan to use.
3. On the Edit Operator ID page, on the Security tab, select Force password change on next login and
clear Disable Operator.
4. Select Update password.
5. Enter a password that conforms to your site standards and click Submit.
6. Click Save and close the operator page.
7. Repeat steps 2 through 6 for the remaining operators.
1. In the header of Dev Studio,click Configure > Decisioning > Decisions > Data Sources > Interaction
History Summaries.
2. On the Decisioning: Data Sources page, on the Interaction history summaries tab, recreate
(rematerialize) all the interaction history aggregates that have been materialized and that have first or
last aggregates by clicking Manage > Recreate aggregates for each data set.
Delete entries from the prconfig.xml file Delete the following entries:
env name="pega/sequenceid/
useOldOOTBIDGenerator" value="true"
env name="database/databases/
customUniqueIDproc"
value="sppc_data_uniqueid_custom"
Delete dynamic system settings In Dev Studio delete the following dynamic
system settings:
• prconfig/pega/sequenceid/
useoldootbidgenerator/default
• prconfig/database/databases/
customuniqueidproc/default
2. If you used a database sequence to generate work IDs, ensure that each case type has a row defined in
the pc_data_uniqueid table. Also, ensure that the pyLastReserveID property for each case type matches
the maximum of the relative database sequence value plus 1.
1. In the header of Dev Studio, click Configure > Application > Structure > Referencing Applications.
2. Display the application page by clicking Lock and Roll for each application.
3. Review the ruleset version prerequisites for the application ruleset by selecting + next to
Prerequisites. To modify a required rule form, click the name of the ruleset version to edit it.
4. Select the Lock checkbox and select Update my application to include the new ruleset versions.
5. Enter the password for this ruleset version and select the Roll checkbox.
6. In the Roll to Version field, enter a new ruleset version or accept the default version which increments
the current version by one.
7. In the NEW section of the Prerequisites verify the list of ruleset prerequisites.
In particular, verify that the lowest ruleset points to the appropriate version of Pega Platform
8. Apply the changes to your ruleset by clicking Run.
9. Repeat these steps for each application in your system.
For example, after upgrading to the latest versions of these core UI layers, some of the color, styling or
default behaviors of your application might change and some of the override CSS and sections from your
current UI Kit may need to be refactored and modified. The effort is similar to adopting and using a new
feature.
For information about how to update to the latest version of the UI Kit application, see Updating the UI kit
in your application.
1. In the header of Dev Studio, click Configure > System > Release > Upgrade > Update Existing
Applications.
2. If any actions are listed, click Run to start the utility.
3. Test the application. If the test results are acceptable, repeat these steps on your production system.
1. In the header of Dev Studio, click Configure > System > Release > Upgrade > Upgrade Applications
Schema.
2. If any actions are listed, click Run to start the utility.
3. Test the application. If the test results are acceptable, repeat these steps on your production system.
Before you begin: You can upgrade to Cassandra 3.11.3 on all operating systems except IBM AIX. If
you are using IBM AIX, do not perform this procedure, and continue to use Cassandra 2.1.20 which is
still supported.
1. Ensure that the following ports are open to other members of the Cassandra cluster for their
internode (Gossip) exchange:
• 7000 – Internode communication (not used if TLS enabled)
• 7001 – TLS internode communication (used if TLS enabled)
2. Ensure that port 9042, the CQL native transport port, is open to all the nodes in the Pega cluster.
Before you begin: Ensure that you have free hard drive space that is at least equal to the size of your
Cassandra data.
During the DDS nodes upgrade, you cannot add new nodes, create or truncate database tables, or run a
repair process.
During the SSTables upgrade, the node can be used to read and store data. Upgrading SSTables can be a
lengthy process, for example, upgrading SSTables that store 1 TB of data takes approximately 8 to 9 hours
on an AWS EC2 C5.4xlarge instance. You can disable or postpone the automatic SSTables upgrade. If you
do not upgrade SSTables, Cassandra continues to run using the old data format but might perform less
efficiently.
1. In the header of Dev Studio, click Configure > Decisioning > Infrastructure > Services > Decision
Data Store.
Schema versions:
988ef087-bd96-3606-8359-fc8b20d0f253: [10.0.2.21, 10.0.2.23]
If the output contains more than one schema version, contact Global Client Support.
4. In the prconfig.xml file, set the value of the dnode/cassandra_version property to 3.11.3.
5. Stop Cassandra for the DDS node that you want to update by performing the following actions:
a. In the header of Dev Studio, click Configure > Decisioning > Infrastructure > Services > Decision
Data Store.
b. For the selected node, in the Action column, click Execute > Stop.
c. Wait for the status of the selected node to change to STOPPED.
6. Back up Cassandra SSTables.
7. Back up the following configuration files from the conf directory: cassandra.yaml, cassandra-
env.sh, cassandra-rackdc.properties, and logback.xml.
8. Optional: Specify how and if you want to perform the automatic SSTables upgrade by performing one
of the following actions:
• If you want to customize the automatic upgrade of SSTables, configure the number of
SSTables per keyspace to be upgraded at the same time by specifying the value of the dnode/
cassandra_upgrade_sstables/jobs property. Set this property to 0 to use all available
compaction threads.
• If you do not want to automatically upgrade SSTables, in the prconfig.xml file, set the value of the
dnode/cassandra_upgrade_sstables property to false.
9. Restart Pega Platform.
10. Repeat steps 4 through 9 for each remaining DDS node.
11. Optional: To check the progress of the SSTables upgrade, from the console, from the Cassandra
distribution directory, run the following command: ./bin/nodetool compactionstats, and review
the output.
What to do next: If you disabled the automatic upgrade of SSTables in step 8, you can update them
later by setting the value of the dnode/cassandra_upgrade_sstables property back to true, and
then restarting Pega Platform.
1. In the header of Dev Studio, click Configure > Decisioning > Infrastructure > Services > Decision
Data Store.
2. Perform one of the following actions:
• If the status of all Decision Data Store (DDS) nodes is NORMAL, continue to step 3.
• If the status of one or more of the DDS nodes is other than NORMAL, contact Global Client Support to
complete the procedure.
3. Select a DDS node by clicking the status column for that node.
4. In the upper-right corner, click Show diagnostics.
5. Verify that the list of reachable nodes contains all the running DDS nodes in the cluster.
For example:
If the list does not contain all the running DDS nodes, contact Global Client Support.
6. Search for ReleaseVersion and verify that it is defined as follows: ReleaseVersion=3.11.3.
If the ReleaseVersion is not defined as 3.11.3, repeat steps 4 through 9 from Upgrading Cassandra
on Decision Data Store nodes for this node.
7. Repeat steps 3 through 6 for each of the remaining DDS nodes.
What to do next: If you use custom cassandra.yaml settings or if you overwrite them by using the
prconfig.xml file, revise the current cassandra.yaml settings so that they are compatible with
Cassandra 3.11.3. For more information, see the DataStax documentation on configuring Cassandra.
1. Open the Records Explorer to search for the service email rule that you created to configure replies to
Pulse email notifications.
2. Expand the Integration-Services category and click Service Email.
3. Click the service email rule that you created for Pulse email replies.
4. In the Message header section on the Request tab of the service email, add the following fields:
You can update the agent schedules after starting a node with a node type, when the agent schedule is re-
created. To learn about updating or converting agents to created in older versions of Pega Platform, see
Best practices for writing background processing work.
If you did not develop agent schedules with the Node Classification feature of Pega 7.2.2, skip this section.
• Pega 7.3
• Pega 7.3.1
• Pega 7.4
If you are upgrading from another version, skip this section.
If you added these privileges prior to the upgrade, skip this section.
1. Click the Operator menu in the Dev Studio header and select Operator.
2. In the Application Access section, expand an access group and click the role that you need to modify.
3. Click the @baseclass class in the Access Class column.
4. In the Privileges section, click the Plus icon and, in the Name column, add the following privileges for
the type of access required.
• pzSystemOperationsObserver – Required to access the Requester Management landing page
and to view performance and trace entry details.
• pzSystemOperationsAdministrator – Required to access the Requester Management landing
page and perform most actions on requestors. To trace requestors and view the clipboard you also
need to have the pzDebugRemoteRequestor privilege.
5. Enter 5 for the production level in the Level column.
Production level 5 provides the highest security.
6. Click Submit.
7. In the Access Class column, click the Pega-Landing class and repeat steps 4 through 6.
Note: If the Pega-Landing class is not in the table, add it by clicking the Plus icon at the end of
the table and entering Pega-Landing in the Class field.
8. Save the access role form.
1. In the header of Dev Studio, click Configure > Org & Security > Tools > Security > Role Names.
2. In the pop-up window that displays roles, click the role that you want to edit.
3. In the Dev Studio, click the @baseclass class in the Access Class column.
4. In the Privileges section, click the Plus icon and, in the Name column, select the pxViewSystemInfo
privilege.
5. In the Level column, enter 5 for the production level. Production level 5 provides the highest security.
6. Click Submit.
7. Repeat steps 1 through 6 for each role that requires modification.
Because only prefixes were added to the names of standard rules, you can inspect the ruleset
for a rule name that is similar to your invalid reference.
• Recreate your override by copying the renamed version of the rule in the Pega-Survey ruleset.
Ensure that all references to your original override are redirected to your new override, before
you delete the original override.
e. Manually review and upgrade your application for references, such as Java steps in an activity, that
are not detected by the validation tool.
3. Upgrade the rules that support the surveys in your application.
a. In the header of Dev Studio, click Configure > System > Release > Upgrade > Validate.
b. Click Revalidate and Save.
c. In the Update Rule Forms dialog box, enter values in the fields to perform validation on the
following classes:
• Rule-PegaQ-Question
• Rule-PegaQ-QuestionCollection
• Rule-PegaQ-QuestionGroup
• Rule-PegaQ-Questionnaire
For more information about the options that you can choose while running the Revalidate and Save
tool, see the Pega Platform help.
4. Find the surveys in your application that run on an embedded page instead of the context, or primary
page, of the parent flow.
a. In the Application Explorer, expand Survey > Survey to display a list of surveys in your application.
b. Click a survey name to open the Survey form.
c. Click Actions > View references to find the flow that calls your survey.
d. Click the Open icon next to the flow name.
e. On the flow diagram, inspect the configuration of the Subprocess shape that calls your survey.
f. If the Define flow field is set to On embedded page, note the value in the Page property field.
g. Repeat steps b through f for each survey in your application.
5. If you do not have any surveys that run on embedded pages, you can skip this step. Customize the
upgrade utility so that it finds and edits the correct pages for in-flight surveys.
a. Find the Work-.pyUpgradeSurveyProperties data transform by searching for it or by using the
Application Explorer.
b. Save a copy of the rule to an unlocked ruleset version in your application.
c. On the Definition tab of the Data Transform form, use the Update Page action to set the current
page to the embedded page that you noted from step 4.
d. Enclose the Update Page action with a When action if only some surveys run on the embedded
page.
e. Repeat steps c and d for each embedded page that you noted from step 4.
f. Click Save.
6. Run the upgrade utility for in-flight surveys.
a. In the header of Dev Studio, click Configure > System > Release > Upgrade > Upgrade Tools.
b. Click Update Survey Work Objects.
c. In the Upgrade survey work objects dialog box, select the check box next to each class that
defines a survey.
d. Click Run utility.
7. Correct references to deprecated APIs.
For more information about deprecated APIs and the APIs that supersede them, see the release notes
for Pega Platform 7.3.
Appendices
The appendices include information about optional processes and troubleshooting.
Property Description
pega.source.jdbc.driver.jar The path to the JDBC JAR file. For databases that
use multiple JDBC driver files, specify semicolon-
pega.target.jdbc.driver.jar
separated values.
Property Description
Custom properties
The following properties are used during migration to configure custom settings.
Property Description
Property Description
Operational properties
Use the following properties to migrate Rules objects.
Property Description
Property Description
Property Description
Property Description
1. Open the setupDatabase.properties file in the scripts directory of your distribution image:
Directories.distributionDirectory\scripts\setupDatabase.properties.
2. Specify the properties for your system. For each property, add the appropriate value after the equal
sign. See Database connection properties and script arguments.
3. Optional: If you are repeating a failed upgrade, configure the resume property:
• To resume from the last successful step, set automatic.resume=true.
• To restart from the beginning, set automatic.resume=false.
4. Save and close the file.
1. Clone the DDL and have the DBA apply the DDL:
a. Clone the DDL. For details about running the migrate script, see Migrate script properties.
1. Edit the migrateSystem.properties file to set the source schema names:
# Connection Information
pega.source.jdbc.driver.jar=full path/DRIVER.jar
pega.source.jdbc.driver.class=database driver class
pega.source.database.type=database vendor type
pega.source.jdbc.url=URL of database
pega.source.jdbc.username=Deployment user name
pega.source.jdbc.password=password
pega.source.rules.schema=original rules schema name
pega.source.data.schema=original data schema name
2. Edit the migrateSystem.properties file to set the target schema names. The settings depend
on whether you have one database or two databases:
• One database:
pega.target.jdbc.driver.jar=full path/DRIVER.jar
pega.target.jdbc.driver.class=database driver class
pega.target.database.type=database vendor type
pega.target.jdbc.url=URL of database
pega.target.jdbc.username=Deployment user name
pega.target.jdbc.password=password
pega.target.rules.schema=new rules schema
pega.target.data.schema=temporary data schema
• Two databases:
pega.target.jdbc.driver.jar=full path/DRIVER.jar
pega.target.jdbc.driver.class=database driver class
pega.target.database.type=database vendor type
pega.target.jdbc.url=URL of database
pega.target.jdbc.username=Deployment user name
pega.target.jdbc.password=password
pega.target.rules.schema=temporary rules schema
pega.target.data.schema=temporary data schema
pega.clone.generate.xml=true
pega.clone.create.ddl=true
pega.clone.apply.ddl=false
pega.bulkmover.unload.db=false
pega.bulkmover.load.db=false
pega.rules.objects.generate=false
pega.rules.objects.apply=false
pega.clone.generate.xml=false
pega.clone.create.ddl=false
pega.clone.apply.ddl=false
pega.bulkmover.unload.db=true
pega.bulkmover.load.db=true
pega.rules.objects.generate=false
pega.rules.objects.apply=false
pega.target.jdbc.driver.jar=full path/DRIVER.jar
pega.target.jdbc.driver.class=database driver class
pega.target.database.type=database vendor type
pega.target.jdbc.url=URL of database
pega.target.jdbc.username=Deployment user name
pega.target.jdbc.password=password
pega.target.rules.schema=new rules schema
pega.target.data.schema=temporary data schema
• Two databases:
pega.target.jdbc.driver.jar=full path/DRIVER.jar
pega.target.jdbc.driver.class=database driver class
pega.target.database.type=database vendor type
pega.target.jdbc.url=URL of database
pega.target.jdbc.username=Deployment user name
pega.target.jdbc.password=password
pega.target.rules.schema=temporary rules schema
pega.target.data.schema=temporary data schema
3. Migrate the changes to the new rules schema; create rules schema objects, and create links between
the new rules schema and the data schema.
a. Clone the DDL.
1. Edit the migrateSystem.properties file to set the source and target schema properties. The
settings depend on whether you have one database or two databases:
• For the source with one database:
pega.source.jdbc.driver.jar=full path/DRIVER.jar
pega.source.jdbc.driver.class=database driver class
pega.source.database.type=database vendor type
pega.source.jdbc.url=URL of database
pega.source.jdbc.username=Deployment user name
pega.source.jdbc.password=password
pega.source.rules.schema=new rules schema
pega.source.data.schema=
pega.source.jdbc.driver.jar=full path/DRIVER.jar
pega.source.jdbc.driver.class=database driver class
pega.source.database.type=database vendor type
pega.source.jdbc.url=URL of database
pega.source.jdbc.username=Deployment user name
pega.source.jdbc.password=password
pega.source.rules.schema=temporary rules schema
pega.source.data.schema=
pega.target.jdbc.driver.jar=full path/DRIVER.jar
pega.target.jdbc.driver.class=database driver class
pega.target.database.type=database vendor type
pega.target.jdbc.url=URL of database
pega.target.jdbc.username=Deployment user name
pega.target.jdbc.password=password
pega.target.rules.schema=new rules schema
pega.target.data.schema=existing data schema
pega.target.jdbc.driver.jar=full path/DRIVER.jar
pega.target.jdbc.driver.class=database driver class
pega.target.database.type=database vendor type
pega.target.jdbc.url=URL of database
pega.target.jdbc.username=Deployment user name
pega.target.jdbc.password=password
pega.target.rules.schema=new rules schema
pega.target.data.schema=existing data schema
pega.clone.generate.xml=false
pega.clone.create.ddl=true
pega.clone.apply.ddl=false
pega.bulkmover.unload.db=false
pega.bulkmover.load.db=false
pega.rules.objects.generate=false
pega.rules.objects.apply=false
2. Optional: If your customer data schema is different than your Pega data schema, insert the
following entry to specify the customer data schema name. Replace customer-data-schema with
your customer data schema name.
pega.customerdata.schema=customer-data-schema
3. Run the generateddl.bat (on Windows) or generateddl.sh script (on Linux) with
the -action=upgradeDataOnly argument, for example: generateddl.bat -
action=upgradeDataOnly
b. If you upgrade by copying the rules schema to the new environment and running the data schema
upgrade, and Pega applications that include changes to the data schema are installed, you must
generate and apply schema changes for your Pega applications.
c. Have the database administrator apply the DDL to the data schema.
d. Use the command line to upgrade the data schema.
1. Open the setupDatabase.properties file in the scripts directory of your distribution image:
Directories.distributionDirectory\scripts\setupDatabase.properties.
2. Configure the database connection properties. Set your Rules Schema Name and Data Schema
Name fields based on the number of databases:
• One database: Use the new rules schema name for the rules schema name and the
temporary data schema for the data schema name.
• Two databases: Use the temporary rules schema name for the rules schema name and the
temporary data schema for the data schema name.
3. Edit the setupDatabase.properties file to bypass the schema upgrade because the DDL is
already applied: bypass.pega.schema=true
4. Run the upgrade.bat or upgrade.sh script with the --dataOnly argument and true parameter,
for example: upgrade.bat --dataOnly true
# Connection Information
pega.jdbc.driver.jar=\path-to-the-database-JAR-file\DRIVER.jar
pega.jdbc.driver.class=database driver class
pega.database.type=database vendor type
pega.jdbc.url=URL of the database
pega.jdbc.username=Deployment username
pega.jdbc.password=password
rules.schema.name=rules-schema-name
data.schema.name=data-schema-name
customerdata.schema.name=optional-customer-data-schema
If you do not specify an output directory, the script writes the output to the default directory: Pega-
image\schema\generated\
Note: The output directory is deleted and re-created each time the generateddl script runs. To
save a copy of the DDL, rename the directory before you run the script.
1. Review the DDL file in the output directory and make any necessary changes. The default directory is:
Pega-image\schema\generated\database\oracledate>
2. Apply the DDL file.
a. Register the DDL file with the database. Register the .jar file with the database.
b. Apply the CREATE FUNCTION DDL.
The output directory is deleted and re-created each time the generateddl script runs. To save a copy of
the DDL, rename the directory before you rerun the script.
• JDBC Driver Class Name — Verify that the pre-populated values are correct.
• JDBC Driver JAR Files — Click Select Jar to browse to the appropriate driver files for your database
type and version.
• Database JDBC URL — Verify that the pre-populated value is accurate.
• Database Username and Password — Enter the Deployment user name and password.
• Rules Schema Name — Enter the existing rules schema name.
• Data Schema Name — Enter the existing data schema name.
• Customer Schema Name — Optional: If you have a separate customer data schema, enter the
existing customer data schema name.
8. Click Test Connection. If the connection is not successful, review your connection information, correct
any errors, and retest. When the connection is successful, click Next to choose how to apply the data
schema.
On IBM Db2 for Linux, UNIX, and Windows, and IBM Db2 for z/OS, Test Connection does not verify
that the schemas exist. Instead, the schemas are automatically generated when the first CREATE TABLE
statement executes after the deployment is complete.
9. Specify whether you will have your database administrator manually apply the DDL changes to the
schema. These changes include the user-defined functions (UDF) supplied by Pega. By default, the IUA
generates and applies the schema changes to your database.
• To have the IUA automatically apply the DDL changes and the UDF, clear Bypass Automatic DDL
Application.
10. Click Next.
11. Select your options and click Next:
• Optional: Select Update applications schema. The Update Applications Schema utility updates
all auto-generated tables with the schema changes in the latest base tables. You can also run the
update applications schema utility later from the prpcUtils.bat or prpcUtils.sh script, or from
Dev Studio. For information about using the Update Applications Schema utility, see the online help.
• Optional: Select Run rulebase cleanup to permanently remove old rules. In most cases, removing
older rules improves the general performance of the system. Running the cleanup script
permanently removes rules older than the current version.
• Optional: Select Update existing applications to modify your existing applications to support
the new version of the Pega Platform. The specific actions depend on your current version of
Pega Platform. If you do not automatically update the applications as part of the IUA, follow the
instructions in Updating existing applications to update the applications as part of the post-upgrade
process.
• Optional: Select Rebuild database indexes to have the IUA to rebuild the database indexes after
the rulebase loads. The IUA rebuilds the database indexes to ensure good performance after
the upgrade. The amount of time this process adds to the upgrade depends on the size of your
database.
12. Click Start to begin loading the rulebase. During the upgrade, the log window might appear inactive
when the IUA is processing larger files.
13. Click Back to return to the previous screen, and then click Exit to close the IUA.
What to do next: After you upgrade the data schema, redeploy the application to run using the
new rules and then review the post-upgrade tasks sections to complete the upgrade. At a minimum,
you must reconfigure the application to run using the new rules as described in Reconfiguring the
application server and enable rule creation, as described in Enabling rule creation.
Note: During the upgrade, you can still use the original system, but any rules created after the
migration are lost when you switch to the upgraded rules schema. The data schema retains all
new data and work.
2. Create a new schema in your existing database, the new rules schema. Leave these new schemas
empty.
3. Create a new, temporary database and then create two blank schemas, one for the temporary rules
schema, and one for the temporary data schema.
4. Migrate the existing rules schema to the temporary rules and the existing data schema to the
temporary data schema.
5. Upgrade the temporary rules schema.
6. Migrate the upgraded temporary rules schema to the new rules schema in your existing database.
7. Shut down the cluster to ensure the upgrade process can complete with causing conflicts on your
system.
8. Use the upgrade script to upgrade the existing data schema and reference the new rules schema.
9. For high availability systems, restart the cluster and then enable rule creation.
Migrating the rules schema when the process includes access to both
databases
If you have access to both the temporary and original databases, run the migrate script once to migrate
the structure and content of the existing (source) rules and data schemas to the filesystem where you
created the two (target) schemas on the temporary database.
1. Use a text editor to edit the migrateSystem.properties file in the scripts directory:
Pega-image\scripts\migrateSystem.properties
2. Configure the source properties. For more information, see Migrate script properties.
Note: If you are starting with a single-schema system, the pega.source.rules.schema and
pega.source.data.schema names are the same.
# Connection Information
pega.source.jdbc.driver.jar=full path/DRIVER.jar
pega.source.jdbc.driver.class=database driver class
pega.source.database.type=database vendor type
pega.source.jdbc.url=URL of database
pega.source.jdbc.username=Deployment user name
pega.source.jdbc.password=password
pega.source.rules.schema=existing rules schema name
pega.source.data.schema=existing data schema name
3. Configure the target properties. Leave the target data schema name blank:
pega.target.jdbc.driver.jar=full path/DRIVER.JAR
pega.target.jdbc.driver.class=database driver class
pega.target.database.type=database vendor type
pega.target.jdbc.url=database URL
pega.target.jdbc.username=Deployment user name
pega.target.jdbc.password=password
pega.target.rules.schema=temporary rule schema
pega.target.data.schema=temporary data schema
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
pega.rules.objects.generate=false
pega.rule.objects.apply=false
Migrating the rules schema when the process can only access one
database
If you can only access one database at a time (for example, if there is a firewall between the two servers),
run the migration script twice: first on a system that can access the existing (source) database, and then,
after you move the structure and content to the filesystem where it can access the temporary target
database, run the script on the temporary (target) system.
Make sure that the system that accesses the temporary database has access to the bulkmover directory
and the structure and content generated from the source database.
1. On a system that can access the original database, export rules from the original database.
a. Use a text editor to edit the migrateSystem.properties file in the scripts directory:
Pega-image\scripts\migrateSystem.properties
b. Configure the source properties. For more information, see Migrate script properties.
Note: If you are starting with a single-schema system, the pega.source.rules.schema and
pega.source.data.schema names are the same.
# Connection Information
pega.source.jdbc.driver.jar=full path/DRIVER.jar
pega.source.jdbc.driver.class=database driver class
pega.source.database.type=database vendor type
pega.source.jdbc.url=URL of database
pega.source.jdbc.username=Deployment user name
pega.source.jdbc.password=password
pega.source.rules.schema=existing rules schema name
pega.source.data.schema=existing data schema name
# Connection Information
pega.target.jdbc.driver.jar=full path/DRIVER.JAR
pega.target.jdbc.driver.class=database driver class
pega.target.database.type=database vendor type
pega.target.jdbc.url=database URL
pega.target.jdbc.username=Deployment user name
pega.target.jdbc.password=password
pega.target.rules.schema=temporary rules schema
pega.target.data.schema=temporary data schema
pega.clone.generate.xml=true
pega.clone.create.ddl=false
pega.clone.apply.ddl=false
pega.bulkmover.unload.db=true
pega.bulkmover.load.db=false
pega.rules.objects.generate=false
pega.rule.objects.apply=false
pega.clone.generate.xml=false
pega.clone.create.ddl=true
pega.clone.apply.ddl=true
pega.bulkmover.unload.db=false
pega.bulkmover.load.db=true
pega.rules.objects.generate=false
pega.rule.objects.apply=false
8. Click Test Connection. If the connection is not successful, review your connection information, correct
any errors, and retest. When the connection is successful, click Next.
9. Specify whether you will have your database administrator manually apply the DDL changes to the
schema. These changes include the user-defined functions (UDF) supplied by Pega. By default, the IUA
generates and applies the schema changes to your database.
• To generate and apply the DDL outside the IUA, you must first manually generate and apply the
DDL and UDF before continuing the deployment. For more information, see Optional: Generating
and applying DDL and Optional: Installing user-defined functions. After you apply the DDL and
UDF, select Bypass Automatic DDL Application and continue the deployment.
• To have the IUA automatically apply the DDL changes and the UDF, clear Bypass Automatic DDL
Application.
10. Click Next.
11. Select your options and click Next:
• Optional: Select Update applications schema. The Update Applications Schema utility updates
all auto-generated tables with the schema changes in the latest base tables. You can also run the
update applications schema utility later from the prpcUtils.bat or prpcUtils.sh script, or from
Dev Studio. For information about using the Update Applications Schema utility, see the online help.
• Optional: Select Run rulebase cleanup to permanently remove old rules. In most cases,
removing older rules improves the general performance of the system. Running the cleanup script
permanently removes rules older than the current version. Alternatively, you skip this now and then
generate a DML later using the cleanup.bat or cleanup.sh script. For details about manually running
Pega-provided script outside of the IUA, see Customizing deployment script behavior.
• Optional: Select Update existing applications to modify your existing applications to support
the new version of the Pega Platform. The specific actions depend on your current version of
Pega Platform. If you do not automatically update the applications as part of the IUA, follow the
instructions in Updating existing applications to update the applications as part of the post-upgrade
process.
• Optional: Select Rebuild database indexes to have the IUA to rebuild the database indexes after
the rulebase loads. The IUA rebuilds the database indexes to ensure good performance after
the upgrade. The amount of time this process adds to the upgrade depends on the size of your
database.
12. Click Start to begin loading the rulebase. During the upgrade, the log window might appear inactive
when the IUA is processing larger files.
13. Click Back to return to the previous screen, and then click Exit to close the IUA.
or use the temporary data schema name, it will be upgraded along with the original data schema in
a later step.
c. Optional: If you are repeating a failed upgrade, configure the resume property:
• To resume the upgrade from the last successful step, set automatic.resume=true.
• To restart the upgrade from the beginning, set automatic.resume=false.
d. Save and close the file.
2. Open a command prompt and navigate to the scripts directory.
3. Run either upgrade.bat or upgrade.sh.
Migrating to the new rules schema when the process includes access
to both databases
If your system has access to the temporary and original databases, run the migrate script once to migrate
to the new rules schema.
1. Use a text editor to edit the migrateSystem.properties file in the scripts directory:
Pega-image\scripts\migrateSystem.properties
2. Configure the source properties. For more information, see Migrate script properties.
# Connection Information
pega.source.jdbc.driver.jar=full path/DRIVER.jar
pega.source.jdbc.driver.class=database driver class
pega.source.database.type=database vendor type
pega.source.jdbc.url=database URL
pega.source.jdbc.username=Deployment user name
pega.source.jdbc.password=password
pega.source.rules.schema=temporary rules schema
pega.source.data.schema=
pega.target.jdbc.driver.jar=full path/DRIVER.JAR
pega.target.jdbc.driver.class=database driver class
pega.target.database.type=database vendor type
pega.target.jdbc.url=database URL
pega.target.jdbc.username=Deployment user name
pega.target.jdbc.password=password
pega.target.rules.schema=new rules schema
pega.target.data.schema=existing data schema
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
pega.rules.objects.generate=true
pega.rules.objects.apply=true
Migrating to the new rules schema when the process can only access
one database
If the system can only access one database at a time (for example, if there is a firewall between the two
servers), run the migration script twice: first on a system that can access the original source database, and
then on a system that can access the temporary target database.
Make sure that the system that accesses the temporary database has access to the bulkmover directory
and the DDL generated from the source database.
1. On a system that can access the original database, export rules from the original database.
a. Use a text editor to edit the migrateSystem.properties file in the scripts directory:
Pega-image\ scripts\migrateSystem.properties
b. Configure the source properties. For more information, see Migrate script properties.
# Connection Information
pega.source.jdbc.driver.jar=/path-to-the-database-JAR-file/DRIVER.jar
pega.source.jdbc.driver.class=database driver class
pega.source.database.type=database vendor type
pega.source.jdbc.url=URL of database
pega.source.jdbc.username=Deployment user name
pega.source.jdbc.password=password
pega.source.rules.schema=temporary rules schema
pega.source.data.schema=
pega.clone.generate.xml=true
pega.clone.create.ddl=false
pega.clone.apply.ddl=false
pega.bulkmover.unload.db=true
pega.bulkmover.load.db=false
pega.rules.objects.generate=false
pega.rules.objects.apply=false
pega.clone.generate.xml=false
pega.clone.create.ddl=true
pega.clone.apply.ddl=true
pega.bulkmover.unload.db=false
pega.bulkmover.load.db=true
pega.rules.objects.generate=true
pega.rules.objects.apply=true
1. If encryption is enabled on the cluster, enable encryption on the upgrade script by adding the following
line to the prconfig.xml file:
You must enable encryption so that nodes that are created during the upgrade can join the existing
encrypted cluster.
2. If you have not already done so, configure the connection properties. Use your existing data
schema name for data.schema.name. Use the new rules schema name for rules.schema.name.
If you have an optional customer data schema separate from the Pega data schema, enter the
customerdata.schema.name. For more information, see Customizing deployment script behavior.
# Connection Information
pega.jdbc.driver.jar=/path-to-the-database-JAR-file/DRIVER.jar
pega.jdbc.driver.class=database driver class
pega.database.type=database vendor type
pega.jdbc.url=URL of the database
pega.jdbc.username=Deployment user name
pega.jdbc.password=password
rules.schema.name=new rules schema
data.schema.name=existing data schema
customerdata.schema.name=optional-customer-data-schema
3. Shut down the application server and ensure that no other processes are using the data schema.
4. Open a command prompt, and navigate to the scripts directory.
5. Run upgrade.bat (for Windows) or ./upgrade.sh (for Linux), passing in the --dataOnly argument
and true parameter, for example:
upgrade.bat --dataOnly true
What to do next: After you upgrade the data schema, redeploy the application to run using the
new rules and then review the post-upgrade tasks sections to complete the upgrade. At a minimum,
you must reconfigure the application to run using the new rules as described in Reconfiguring the
application server and enable rule creation, as described in Enabling rule creation.
# Connection Informationpega.jdbc.driver.jar=\path-to-the-database-JAR-file\DRIVER.jar
pega.jdbc.driver.class=database driver class
pega.database.type=database vendor type
pega.jdbc.url=URL of the database
pega.jdbc.username=Deployment user name
pega.jdbc.password=password
rules.schema.name= rules-schema-name
data.schema.name=data-schema-name
3. Optional: If you have a split-schema, on the data schema run the following commands::
4. From the Pega-image \scripts directory, run the generateudf.bat (for Windows) or
generateudf.sh (for Linux) script with the --action install argument.
generateudf.bat --action install --dbType oracledate
5. Add all of the upgraded nodes that you upgraded in step 3, back to the load balancer to start taking
traffic.
6. Upgrade the remaining half of the nodes (the non-upgraded nodes) one by one.
a. Perform steps 2 b through 3 g.
b. Add the node back to the load balancer to start taking traffic.
7. To switch back to embedded mode from client-server mode, shut down all stand-alone Apache Ignite
servers after all of the nodes are upgraded and no longer use the stand-alone Apache Ignite server
cluster.
Limitations
You can reverse upgrades in many situations, but there are limitations.
Reversing an upgrade is not supported for:
• In-place upgrades
• Major release upgrades
• Single-schema systems
• Multitenancy systems
• Multi-hop upgrades, for example:
◦ You can:
1. Upgrade from Pega Platform version 7.2 to version 8.6.
2. Reverse the upgrade to return Pega Platform version 7.2.
◦ You cannot:
1. Upgrade from Pega Platform version 8.2 to version 8.4 (first hop).
2. Upgrade again from Pega Platform version 8.4 to version 8.6 (second hop).
3. Reverse the upgrade back to Pega Platform version 8.2.
If new Data- instances (including Work- instances) are created by using data objects modified by the
upgrade process, the new instances might not function properly after reversal.
The table below describes the reverse behavior for some database objects that are either added or
modified (before or after an upgrade), or added or modified by the product during the upgrade process.
Reversing an upgrade
Use a script to reverse an upgrade.
1. Check the scripts/log directory for the presence of multiple Reverse_ timestamp.xml files. Note the
file name with the latest time stamp.
2. If you have not done so already, edit the setupDatabase.properties file to configure the reversal.
a. Open the setupDatabase.properties file in the scripts directory of your distribution image:
Directories.distributionDirectory\scripts\setupDatabase.properties.
b. Configure the connection properties.
# Connection Information
pega.jdbc.driver.jar=/path-to-the-database-JAR-file/DRIVER.jar
pega.jdbc.driver.class=database driver class
pega.database.type=database vendor type
pega.jdbc.url=URL of the database
pega.jdbc.username=Deployment user name
pega.jdbc.password=password
rules.schema.name=new rules schema
data.schema.name=existing data schema
c. If there are multiple versions of the Reverse_timestamp.xml file, specify the file name from step 1
in the reversal.schema.file.name property, for example:
reversal.schema.file.name=Reverse_2021-01-01-12:00:00.xml
d. Save and close the file.
3. Optional: This step is optional since the changes made to the data schema are forward compatible
and do not need to be reversed. By default, the reverse script automatically performs this step, unless
you enable bypass schema changes. If you enabled bypass schema changes and you would like to
perform this step, then you can generate the DDL and apply it manually. In the scripts directory of the
upgrade distribution image, run the generateDDL.bat (for Windows) or generateDDL.sh (for Linux)
script to generate the reverse statements by using the --action argument and reverse parameter,
for example generateDDL.bat --action reverse. Have your database administrator apply the
generated DDL.
For more information about generating and applying the DDL, see Generating and applying DDL in
an out-of-place upgrade or Optional: Generating and applying DDL in an out-of-place upgrade with a
single migration
4. In the scripts directory of the upgrade distribution image, run the reverse.bat (for Windows) or
reverse.sh (for Linux) script. If there are any errors, review the information in the scripts\logs
\CLI-Reverse-Log-timestamp.log file.
5. Reconfigure the application server one node at a time (in a rolling manner):
a. Shut down the prweb application.
b. Verify that the prweb application is configured to use the previous (pre-update) rules schema name.
c. Deploy the old prweb application.
d. Start the prweb application.
6. To verify that the reversal was successful, check the version of Pega Platform on the log-in screen.
1. Review the failure message for information about the source of the error. Use the information in the
error message to correct the error before you continue.
2. If you used the IUA, select either Resume or Start Over when the system displays the Resume
Options screen.
3. Optional. If you used the command-line script, set the automatic.resume property in the
setupDatabase.properties file:
• To resume the deployment from the last successful step, set automatic.resume=true.
1. Take down any application servers that use the failed schema.
2. Backup your database.
3. In ResourceKit\AdditionalUpgradeScripts\MigrationRecoveryScripts
\database_cleanDups.sql, replace all instances of @RULES_SCHEMA with the name of the schema
that contains the pr4_base table.
4. Use your vendor tools to run the database_cleanDups.sql script on the database.
5. Run the expose tool from either prpcUtils or prpcServiceUtils with the following settings:
expose.classes.included=Rule-
expose.included.descendent=true
expose.reindexType=full
expose.update.rule.summary=true
For more information about the expose tool, see Populating properties by using a direct connection to
the database, or the comments in the prpcUtils.properties or prpcServiceUtils.properties
files.
6. Use the generateddl.bat (for Windows) or generateddl.sh (for Linux) script to generate and apply
the DDL. See Manually generating and applying the DDL .
7. Use your vendor tools to rebuild the indexes for the tables in your rules schema.
Before you begin: If you are upgrading from 5.x, Pega requires you to upgrade to 7.4.x before you
can upgrade to Pega Platform 8.x.
Single schemas includes both rules and data, which you must split into two schemas: a data schema and a
separate rules schema.
Uses the following three schemas: Uses the following four schemas:
• Existing rules and data schema – your current • Existing rules and data schema – your current
single schema. This schema will be your data single schema. This schema will be your data
schema after the upgrade. schema after the upgrade.
• New rules schema – a temporary schema • New rules schema – a temporary schema you
you create in your database that the upgrade create in the same database as your existing
process uses to stage the rules upgrade. This schema that the upgrade process uses to stage
schema will be your rules schema after the the rules upgrade. This schema will be your
upgrade. rules schema after the upgrade.
• Temporary data schema – a temporary schema • Temporary data schema – a temporary schema
you create in your database that the upgrade you create in a separate database that the
process uses to stage the data tables with your upgrade process uses to stage the data tables
data. with your data.
• Temporary rules schema – a temporary
schema you create in a separate database that
the upgrade process uses to stage the rules
upgrade.
The process for upgrading a split-schema configuration detailed in the following steps that are similar to
an out-of-place upgrade with a single or double migration, depending on whether you leverage database
or two databases during the process.
Upgrading with one database Create a new blank rules schema and a new
temporary database schema in your existing
database. Leave these new schemas empty.
For details, see Creating a new rules and data
schema.
Upgrading with two databases Create a new rules schema in your original
database and in a second database, create
two blank schemas, one for the temporary
rules schema, and one for the temporary data
schema. Leave these new schemas empty. For
details, see Creating three new schemas on two
databases.
2. Migrate the rules from the existing single schema to the new rules. Use the appropriate section of
instructions, depending on whether you are leveraging one database or two databases in Migrating the
existing rules schema.
Note: When you edit the migrateSystem.properties file to configure the source properties,
ensure that pega.source.rules.schema and pega.source.data.schema name references
your existing single schema, not separate rules and data schemas.
3. Upgrade the migrated rules in the new rules schema in using your choice of tool.
Use one of the following Pega-provided upgrade tools:
• Upgrading out-of-place by using the Installation and Upgrade Assistant
• Upgrading out-of-place by using the command line
Note: When you configure the database connection properties, set your Rules Schema
Name and Data Schema Name fields based on the number of databases:
◦ One database: Use the new rules schema name for the rules schema name and the
temporary data schema for the data schema name.
◦ Two databases: Use the temporary rules schema name for the rules schema name and
the temporary data schema for the data schema name.
4. Generate the rules schema objects to associate them with the existing data schema. For details, see
Migrating and generating rules schema objects .
5. Upgrade the data schema. See Upgrading the data schema.
6. To review the upgrade log files, see Reviewing log files.