PEGA PLATFORM

Pega Platform 8.5

Upgrade Guide
For Tomcat and PostgreSQL
 ©2021 Pegasystems Inc., Cambridge, MA. All rights reserved.

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: May 13, 2021

Feedback
If you have comments for how we can improve our materials, send an email to [email protected].

ii | Pega Platform Upgrade Guide

 Contents

Contents

Planning your upgrade..............................................................................................................................................................................6

Evaluating customizations......................................................................................................................................................................... 6
Reviewing system requirements............................................................................................................................................................... 7
Installation and Upgrade Assistant requirements................................................................................................................... 7
Application server requirements................................................................................................................................................ 7
Database server requirements................................................................................................................................................... 7
Obtaining database connection information..........................................................................................................................................8
Upgrading from Pega Platform version 7.2 and earlier: Using node classification........................................................................... 8
Enabling message retrieval from Kafka by setting stream nodes in high availability systems...........................................8
Upgrading from Pega Platform version 8.1 or 8.2: Configuring Prediction Studio natural langauge processing models............. 9
Correcting Interaction History objects..................................................................................................................................................... 9

Preparing your application server........................................................................................................................................................ 10

Committing hotfixes................................................................................................................................................................................. 10
Configuring ports...................................................................................................................................................................................... 10
Setting JVM security for LINUX or UNIX................................................................................................................................................ 10

Preparing your database........................................................................................................................................................................ 11

Backing up your system and database................................................................................................................................................. 11
Dropping PostgreSQL views.................................................................................................................................................................... 11
Upgrading from PRPC 6.1 SP2 and earlier: moving system settings to the new configuration files............................................. 11
Customizing deployment script behavior............................................................................................................................................. 12
Configuring database users.................................................................................................................................................................... 12
Configuring PostgreSQL user permissions............................................................................................................................. 13
Creating database users by using PostgreSQL tools...............................................................................................14

Performing your upgrade...................................................................................................................................................................... 15

Upgrading with minimal downtime....................................................................................................................................................... 15
For High Availability systems: Preparing the cluster for upgrading.................................................................................... 18
Creating a new rules and data schema.................................................................................................................................. 18
Migrating to the new rules schema......................................................................................................................................... 18
Upgrade methods for the migrated rules schema................................................................................................................ 19
Upgrading out-of-place by using the Installation and Upgrade Assistant............................................................ 19
Upgrading out-of-place by using the command line...............................................................................................21
Importing applications and other rule changes for highly available systems....................................................................21
Upgrading the data schema......................................................................................................................................................22
Reviewing log files...................................................................................................................................................................... 22

Post-upgrade tasks.................................................................................................................................................................................. 23
Upgrading from PRPC 6.1 SP2 and earlier: updating ruleset columns............................................................................................. 23
Reconfiguring the application server.....................................................................................................................................................23
Apache Tomcat: Defining default schemas after out-of-place upgrades...........................................................................23
Redeploying the Pega Platform file......................................................................................................................................... 24
Apache Tomcat: Redeploying Pega Platform............................................................................................................24
Restarting Pega Platform...........................................................................................................................................................24

Pega Platform Upgrade Guide | iii

Contents

Enabling rule creation.............................................................................................................................................................................. 24

Upgrading from Pega Platform version 8.3 or earlier: Guidelines for any required changes in your application URL aliasing... 25
Enabling operators................................................................................................................................................................................... 26
Upgrading from Pega Platform version 8.1 or 8.2: recreating interaction history aggregates.......................................................27
Upgrading from Pega Platform version 8.2 or earlier: batch generating work IDs......................................................................... 27
Recreating PostgreSQL views.................................................................................................................................................................. 28
Upgrading from Pega Platform version 7.2.2 and earlier: porting Apache logging file customizations to the new log file....... 28
Enabling Admin Studio.............................................................................................................................................................................28
Locking and rolling ruleset versions...................................................................................................................................................... 28
Reviewing required post-upgrade search index steps........................................................................................................................ 29
Identifying conflicts with rules that cannot be overridden by running the final rules conflict report...........................................30
Optional: Enabling new UI kit and Cosmos features...........................................................................................................................30
Running upgrade utilities........................................................................................................................................................................ 30
Upgrading your applications................................................................................................................................................................... 31
Optional: Upgrading your application schema.....................................................................................................................................31
Increasing reliability and reducing memory by upgrading to Cassandra 3.11.3..............................................................................31
Configuring access to Cassandra ports................................................................................................................................... 32
Upgrading Cassandra on Decision Data Store nodes........................................................................................................... 32
Verifying the Cassandra upgrade............................................................................................................................................. 33
Upgrading from Pega Platform version 7.3 or earlier: Updating service email rules to reply to Pulse email notifications....... 34
Upgrading from Pega Platform version 7.2.2 or earlier: enabling notifications by upgrading access role names...................... 34
Upgrading from Pega Platform version 7.2.2: customizing the agent schedules for the standard Pega Platform agents........35
Upgrading from Pega Platform version 7.3, 7.3.1, or 7.4: granting access to the Requester Management landing page........ 35
Upgrading from Pega Platform version 7.2.2 or earlier: enabling access to environmental information.................................... 36
Upgrading from Pega Survey 7.2.2 or earlier: enabling the new Pega Survey features................................................................. 37
Upgrading from Platform version 7.2.1 or earlier: Re-scheduling required column population jobs........................................... 38
Testing your applications.........................................................................................................................................................................39

Appendices................................................................................................................................................................................................ 40
Migrate script properties......................................................................................................................................................................... 40
Customizing deployment script behavior............................................................................................................................................. 43
Database connection properties and script arguments....................................................................................................... 43
Additional upgrade properties..................................................................................................................................................44
Manually generating and applying the DDL......................................................................................................................................... 46
Generating and applying DDL in an out-of-place upgrade...................................................................................................47
Generating and applying DDL in an in-place upgrade.......................................................................................................... 50
Generating the DDL file...............................................................................................................................................50
Applying the DDL file................................................................................................................................................... 51
Alternative upgrade: Upgrading in-place...............................................................................................................................................51
Upgrade methods for an in-place upgrade............................................................................................................................ 52
Upgrading in-place by using the Installation and Upgrade Assistant....................................................................52
Upgrading in-place from the command line............................................................................................................ 54
Alternative upgrade: Upgrading out-of-place with a double migration process..............................................................................54
For High Availability systems: Preparing the cluster for upgrading.................................................................................... 55
Creating three new schemas on two databases....................................................................................................................55
Migrating the existing rules schema........................................................................................................................................56
Migrating the rules schema when the process includes access to both databases............................................ 56
Migrating the rules schema when the process can only access one database................................................... 57
Upgrade methods for the migrated rules schema................................................................................................................ 59
Upgrading by using the Installation and Upgrade Assistant.................................................................................. 59
Upgrading out-of-place by using the command line...............................................................................................60
Migrating to the new rules schema......................................................................................................................................... 61
Migrating to the new rules schema when the process includes access to both databases............................... 61
Migrating to the new rules schema when the process can only access one database.......................................62
Importing applications and other rule changes for highly available systems....................................................................63

iv | Pega Platform Upgrade Guide

 Contents

Upgrading the data schema......................................................................................................................................................64

Optional: Manually installing user-defined functions (UDFs) if you did not opt to automatically install UDFs............................ 64
Switching to Hazelcast embedded mode from Apache Ignite client-server mode..........................................................................65
Reversing an out-of-place upgrade........................................................................................................................................................ 67
Limitations....................................................................................................................................................................................67
Upgrade reversal details............................................................................................................................................................67
Reversing an upgrade................................................................................................................................................................ 68
Troubleshoot upgrade errors..................................................................................................................................................................69
Resuming or restarting after a failed deployment................................................................................................................ 69
Removing duplicated rules if rules schema objects were not applied correctly................................................................69
PEGA0055 alert — clocks not synchronized between nodes............................................................................................... 70
Upgrading from Pega Platform version 6.3 SP1 or earlier: Starting from a single-schema configuration....................................70

Pega Platform Upgrade Guide | v

Planning your upgrade

Planning your upgrade

Before you begin the upgrade, evaluate your system, review system requirements, and obtain the
required database information.
Pega Platform upgrades are completed with minimal downtime, with process enhancements that include
the use of DevOps pipelines to migrate upgrade fixes to your environments in a repeatable, consistent
manner. For more information about the upgrade process, see one of the following topics:
• On-premises upgrade process for Pega Infinity release 8.4.2 and later for other application servers and
databases
• On-premises upgrade process for Pega Infinity release 8.4.1 and earlier
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.

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.

6 | Pega Platform Upgrade Guide

 Planning your upgrade

Reviewing system requirements

Before you proceed, ensure that your system meets the following minimum requirements.

Installation and Upgrade Assistant requirements

If you plan to use the UI-based Installation and Upgrade Assistant, ensure that the system meets these
minimum system requirements in addition to all other requirements.
• 1.25 GB minimum available memory
• 10 GB minimum disk space plus at least 8 GB available space in the temporary directory of the root file
system. The default temporary directory for the deployment is java.io.tmpdir.
• Java Platform, Standard Edition Development Kit (JDK)

Application server requirements

Deploy only the Pega Platform web application (prweb.war) on the application server. The application
server must meet the minimum requirements listed in the Platform Support Guide.
• Supported 64-bit JDK. See the Platform Support Guide
• 1 GB minimum free disk space. You might need additional storage space for debugging and logging.
The upgrade process checks for 6400000 KB of free disk space and will not proceed without it, so 8 GB
of free disk space is recommended.
• Memory requirements: Pega Platform runs in memory (heap) on Java Virtual Machines (JVMs). In
general, all activity is distributed over multiple JVMs (nodes) on the application server.
◦ Standard suggested system heap size is 4 - 8 GB based on monitoring of memory usage and
garbage collection frequency.
◦ Larger heaps are advisable if your applications allow a high number of concurrent open tasks per
session or cache a large collection of transaction or reference data.
◦ Do not deploy Pega Platform in an environment where the heap size exceeds the vendor-specific
effectiveness limit.
◦ The host application server memory size must be at least 4 GB larger than the Pega Platform
heap size to allow space for the operating system, monitoring tools, operating system network file
buffering, and JVM memory size (-XMX option). The minimum host application server memory size is
8 GB:
4 GB heap + 4 GB for native memory, operating system, and buffering
If the server does not have enough memory allocated to run Pega Platform, the system can hang
without an error message. The correct memory settings depend on your server hardware, the
number of other applications, and the number of users on the server, and might be larger than
these recommendations. Set MaxMetaspaceSize to a minimum of 768m to avoid a kernel out of
memory crash or Metaspace size errors.

Database server requirements

Your database server must meet the minimum requirements listed in the Platform Support Guide on the
Pega Community.
Verify that the database also includes support for Java if you plan to use user-defined functions (UDFs).

Pega Platform Upgrade Guide | 7

Planning your upgrade

Obtaining database connection information

Before you configure the data source resources, obtain the correct database connection information from
your database administrator.
To determine the database connection URL, obtain the following information from your database
administrator:
• Host name
• Port number
• Database name
When you configure the application server, you will enter the connection string, pega.jdbc.url as follows.
Replace items in italics with the values for your system:
jdbc:postgresql://server:port/database

Upgrading from Pega Platform version 7.2 and earlier:

Using node classification
You can optimize performance and provide higher scalability and stability in a cluster by using node
classification, which is the process of separating nodes, segregating them by purpose, and predefining
their behavior by assigning node types. Every node that is started with the same node type uses the same
template and follows the same behavior.
For complete details on configuring node classification on your system, see Classifying nodes. By
configuring a node with a node type, you dedicate the node to perform particular actions and run only
those agents, listeners, job schedulers, and queue processors that are mapped to the node type. For
example, if a set of nodes is dedicated to user requests, background processes can be disabled to improve
performance. To review the default node types which you can assign to a node in your system, see Node
types for on-premises environments; to update node type assignments on your system, see Assigning
node types to nodes for on-premises environments.
Before you upgrade, ensure that your work resources in your application are thread-safe by reviewing
Best practices for writing background processing work.

Enabling message retrieval from Kafka by setting stream nodes in high

availability systems
Queue Processor rules require at least one stream node. Without a stream node, messages cannot be
queued to or retrieved from Kafka. For on-premises, high availability systems, configure two stream nodes
by using node classification to provide a backup in case one stream node fails. If you are not using a high
availability system, skip this section.

Before you begin: Ensure that the following ports are open:

• Port 7003 for use by the stream REST service
• Port 9092 for Kafka stream nodes

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.

8 | Pega Platform Upgrade Guide

 Planning your upgrade

1. Open the configuration file for your application server:

setenv.sh
2. Configure at least two nodes as stream nodes by entering the following JVM argument:

-DNodeType=Stream

3. Save the configuration file.

For additional details, see Stream node configurations for a Queue Processor rule.

Upgrading from Pega Platform version 8.1 or 8.2:

Configuring Prediction Studio natural langauge
processing models
Before upgrading from Pega Platform 8.1 or 8.2, ensure that all your Prediction Studio natural language
processing (NLP) models are built at least once and are marked as Completed.
Note: If an NLP model is built at least once and is marked as In build, after upgrading from Pega Platform
8.1 or 8.2, the model displays only the last completed model build. If an NLP model is not built at least
once, after upgrading, the model does not appear in Prediction Studio.

Correcting Interaction History objects

If you use Pega Customer Decision Hub and moved Interaction History (IH) tables to their own dedicated
schema, manually generate and edit the data definition language (DDL) file to reference the new schema.
For more information about configuring IH data privileges if IH tables are installed in a schema associated
with a DB rule other than PegaDATA, see the "Interaction History Data privileges" section in Adding
database grants.

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.

Pega Platform Upgrade Guide | 9

Preparing your application server

Preparing your application server

This section describes how to prepare your application server for the upgrade.

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.

Setting JVM security for LINUX or UNIX

If you use UNIX or LINUX, set security to urandom.

1. Open the configuration file for your application server:

setenv.sh
2. Enter the following argument to set security to urandom:
-Djava.security.egd=file:///dev/urandom
3. Save the changes.

10 | Pega Platform Upgrade Guide

 Preparing your database

Preparing your database

Before you begin preparing your database, see the Platform Support Guide to verify that your database is
supported. Then have your database administrator make the modifications described in this section.
• If you are using the PostGIS extension on a PostgreSQL database, ensure that it has not been applied
to the Rules or Data schemas because it will cause the deployment to fail.

Backing up your system and database

Upgrading modifies both the data schema and the rules data; use a backup procedure that preserves
both schemas. Back up the existing database, your applications, and the system.

1. Verify that all rules are checked in.

2. Use your database utilities to back up the Pega Platform database.
3. If you edited any of the following Pega Platform configuration files, include these in the backup:
• prbootstrap.properties
• prconfig.xml
• logging file: prlogging.xml or prlog4j2.xml
• web.xml
• pegarules.keyring or any other .keyring files
Note: For upgrades from PRPC 6.1 SP2 or earlier if you added System Settings to your
prbootstrap.properties or prconfig.xml files, convert them to Dynamic-System-Settings
Data- instances. See Upgrading from PRPC 6.1 SP2 and earlier: moving system settings.
4. Back up any third-party or custom JAR files on your system. Redeploying the Pega Platform applications
might delete these from your application server.

Dropping PostgreSQL views

If you created database views which are dependent on database tables provided by Pega Platform, drop
your views before you continue to upgrade Pega Platform.
After you complete the upgrade, you can recreate the views.

Upgrading from PRPC 6.1 SP2 and earlier: moving

system settings to the new configuration files
If you are upgrading from 6.1 SP2 or earlier, move any custom system settings from the prconfig.xml
or prbootstrap.properties configuration files to the Dynamic System Settings (Data-
Admin-System-Settings). Settings in environment elements in your current prconfig.xml or
prbootstrap.properties files continue to work, and this task can be done at any time.
Pega provides a utility to move the settings 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 Pega Community for details. Note that the instructions on how to run this
utility are the same for Pega 8.5 as they are for version 6.2.

Pega Platform Upgrade Guide | 11

Preparing your database

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 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 dynamic system settings can be viewed and modified from Dev Studio. for details,
see Configuring dynamic system settings; alternately, you can modify the environment element values
in your current prconfig.xml or prbootstrap.properties files, which can require redeploying the
application nodes.

Customizing deployment script behavior

Edit the setupDatabase.properties file to configure deployment scripts.
Skip this section if your deployment meets all the following criteria:
• You will use the Installation and Upgrade Assistant.
• You will allow the Installation and Upgrade Assistant to automatically apply the schema changes and
do not need to create a DDL file.
• You will not use Kerberos authentication.
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.

Configuring database users

This section describes deployment and runtime users and lists all required permissions.
• Deployment user — This user performs actions only during the deployment.
• Run-time users — These users perform actions on the Pega Platform after the deployment. In a dual-
user configuration, an Admin user is granted full privileges, and a Base user is granted a smaller
subset. Pega recommends the dual-user configuration:

12 | Pega Platform Upgrade Guide

 Preparing your database

◦ Base user — The user who runs the Pega Platform. Most run-time operations use the Base user and
associated data source.
◦ Admin user — The user with full privileges for advanced administrative operations.
Pega recommends that you use the dual-user configuration with separate Admin and Base users;
however, you can create a single Base user with both sets of privileges. If there is no separate Admin
user, the Pega Platform uses the Base user for all run-time operations.

Configuring PostgreSQL user permissions

The permissions needed for your database users depend on whether you are using the recommended
dual Admin/Base user configuration.
In a dual-user configuration, an Admin user is granted full privileges, and a Base user is granted a smaller
subset.
For more information about user privileges, see Configuring database users.

Base User * Admin/Deployment User

Schemas owned by this user None data-schema

rules-schema
optional customer-data-schema

Privileges
• USAGE ON SCHEMA data-
schema
• USAGE ON SCHEMA rules-
schema
• ALTER DEFAULT PRIVILEGES
FOR USER admin-user IN
SCHEMA data-schema GRANT
ALL ON TABLES TO base-user
• ALTER DEFAULT PRIVILEGES
FOR USER admin-user IN
SCHEMA rules-schema GRANT
ALL ON TABLES TO data-
schema
• ALTER DEFAULT PRIVILEGES
IN SCHEMA data-schema
GRANT EXECUTE ON
FUNCTIONS TO base-user
• ALTER DEFAULT PRIVILEGES
IN SCHEMA rules-schema
GRANT EXECUTE ON
FUNCTIONS TO base-user

Pega Platform Upgrade Guide | 13

Preparing your database

Base User * Admin/Deployment User

Note: You must

grant the four ALTER
statement privileges
to users before
you upgrade Pega
Platform, because
these privileges apply
only to objects that
are created after the
upgrade.

Creating database users by using PostgreSQL tools

To create database accounts in PostgreSQL, either use the pgAdmin tool which provides a graphical
interface or the PSQL tool which provides a command-line interface. The instructions for using pgAdmin
are included in this guide. See the PostgreSQL documentation for information about PSQL.
• For dual-user configurations, create:
◦ A Base user with read and write permission and the ability to run stored procedures and UDFs.
◦ An Admin user with full access including permission to create and alter tables.
• If you want to use one account, create a user with the same authority and privileges as the Admin user
described above.
To use the pgAdmin tool:

1. Launch the pgAdmin tool.

2. Double-click the PostgreSQL instance that you want to configure.
Note: You must enter the password for the administrator account that was configured when
PostgreSQL was installed.
3. Right-click Login Roles and select New Login Role.
4. In the Role Name field, enter the name for your database user.
5. On the Definition tab, enter the password for this user.
6. On the Role Privileges tab, grant permissions to this user.
7. Click OK.
8. To add a second database user, repeat steps 3 - 7.

14 | Pega Platform Upgrade Guide

 Performing your upgrade

Performing your upgrade

This section covers the required tasks to complete a major upgrade using the out-of-place upgrade
process using a single migration. Pega updated this process for Pega Platform 8.4 version and later to
use two separate schemas, a new rules schema and temporary data schema, instead of the older process
that relied on a single, new rules schema. Pega recommends the single migration, out-of-place upgrade
process; however, depending on your system requirements, Pega continues to support in-place and out-
of-place double migrations as described below.

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.

Single and double migration for out-of-place upgrades

For out-of-place upgrades, the availability of server resources and security features determine whether
you perform a single or double migration.
• To minimize consumption of server hardware resources to avoid performance drain on existing
systems or when network I/O latency is significant, perform a double migration.
1. Migrate the contents of the original schemas to two temporary schemas on a separate database.
2. Upgrade the temporary schema.
3. Migrate the upgraded schema back to the original database.
This is the best practice for database servers that host multiple high-use applications in addition to
Pega Platform, for database servers that have restrictive CPU or I/O limitations, or if the upgrade
process cannot be executed on the database server or within the same data center.
For detailed instructions, see Alternative upgrade: Upgrading out-of-place with a double migration
process.
• If your system includes a firewall or other security measures and the upgrade process does not
have database access to both the source system and the target system, perform a double-migration
upgrade even though you have access to only one database at a time. See the detailed instructions
under Alternative upgrade: Upgrading out-of-place with a double migration process.
• If your system does not have any of these restrictions but still requires minimal downtime, perform a
single-migration upgrade:
1. Migrate the contents of the original schema to a temporary schema on the original database.
2. Upgrade the temporary schema. The temporary schema becomes the new rules schema.
For more information, see Upgrading with minimal downtime .

Upgrading with minimal downtime

Pega recommends upgrading using the single migration process in which the rules schema upgrade
occurs out-of-place. You can continue working in your application running in a highly available system
during the upgrade.
To review the requirements and tasks associate with creating a highly available system, see Configuring
high availability deployments.

Pega Platform Upgrade Guide | 15

Performing your upgrade

The upgrade process involves four schemas:

• Data schema – your existing data schema. This will be your data schema after the upgrade as well.
• Rules schema – your existing rules schema. This schema is upgraded during the upgrade.
• A temporary data schema (Dtmp) – a schema you create on the same database for temporarily staging
the data during the upgrade. You discard this schema after the upgrade.
• New rules schema (Rn) – a rules schema you create on the same database for staging the rules during
the upgrade. This schema will become the rules schema after the upgrade.
Pega provides client-run scripts that copy and replace application rules and that copy data between these
schemas appropriately throughout the upgrade as described below.
To perform an upgrade, complete these steps in the following order:
1. Prepare the cluster for the upgrade by configuring the high availability cluster settings.
2. Create a new rules schema and a new temporary data schema in your existing database. Leave these
new schemas empty.

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.

16 | Pega Platform Upgrade Guide

 Performing your upgrade

5. Shut down the system and upgrade the existing data schema.

6. Redeploy the application to run using the new rules, as described in Reconfiguring the application
server.

7. Revert the high availability cluster settings you modified at the beginning of the upgrade process.
8. Delete the temporary data schema from your database.

Pega Platform Upgrade Guide | 17

Performing your upgrade

For High Availability systems: Preparing the cluster for upgrading

If you are using the recommended High Availability option, you must disable rule creation on the rules
schema to avoid losing any rules created during the upgrade period when switching over to the upgraded
schema. If you are not using the High Availability option, skip this section.
If you are performing an in-place upgrade, you can skip this section.

1. Log in as a user with the PegaRULES:HighAvailabilityAdministrator role.

2. Configure the HA cluster setting to support automatic rule migration:
a. In the header of Dev Studio, click Configure > System > High Availability > HA Cluster Settings.
b. Check Cluster Upgrading – Disable saving of rules.
c. Click Submit.

Creating a new rules and data schema

Create a new blank rules schema and a new temporary database schema in your existing database. Leave
these new schemas empty.
Pega does not support quoted identifiers, so do not wrap your schema name with single or double
quotes. Create each schema name in accordance with the requirements of your deployment database
type.
PostgreSQL databases force unquoted identifiers to lowercase.

Migrating to the new rules schema

Use the migrate script to migrate the rules tables and other required database objects from the existing
rules schema to the new rules schema. To minimize the time required, run the migration scripts from the
same data center as the database server.
Note: Pega strongly recommends that you use the Pega-provided migration script. The use of
vendor tools to manage this step is not recommended, since there are additional manual steps
required to migrate the schema, not documented here, if you do not use the migrate script.

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

3. Configure the target 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

18 | Pega Platform Upgrade Guide

 Performing your upgrade

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

4. Configure the bulkmover directory.

pega.bulkmover.directory=full path to output directory
5. Configure a temporary directory:
pega.migrate.temp.directory=full path to temporary directory
6. Configure the operations to be performed by the utility as shown below:

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

7. Save the properties file.

8. Open a command prompt, and navigate to the scripts directory.
9. Type migrate.bat (for Windows) or ./migrate.sh (for Linux) to run the script.

Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory.

Upgrade methods for the migrated rules schema

Use either the Installation and Upgrade Assistant or a command-line tool to upgrade the migrated rules
schema. Use a command-line tool to upgrade the migrated rules schema.

Upgrading out-of-place by using the Installation and Upgrade Assistant

For a UI-based experience, use the Installation and Upgrade Assistant.
Because of the large volume of data, run the IUA on the same network as the database server. If this is
not possible, run the tool on a system with fast, direct access to the database server. The Deployment
user performs these steps.
The time needed to upgrade can vary widely based on network proximity to the database server.

1. Double-click the PRPC_Setup.jar file to start the IUA.

Note: If JAR files are not associated with Java commands on your system, start the IUA from the
command line. Navigate to the directory containing the PRPC_Setup.jar file, and type java -
jar PRPC_Setup.jar.
The IUA loads and the Pega icon is displayed in your task bar.
2. Click Next to display the license agreement.
3. Review the license agreement and click Accept.
4. Optional: If you are resuming after a previous failed upgrade and the Resume Options screen is
displayed, select either Resume or Start Over.
• If you select Resume, the system uses the previously entered database configuration information to
resume the upgrade from the last successful process. Continue these instructions at step 8.

Pega Platform Upgrade Guide | 19

Performing your upgrade

• If you select Start Over, continue at step 5 to reenter the configuration information.
5. On the Installer Mode screen, choose Upgrade and click Next.
6. Choose your database type and click Next.
7. Configure the database connection. The JDBC drivers allow the Pega Platform application to
communicate with the database. Specify the new rules schema names for both the Rules Schema
Name and Data Schema Name fields.
Note: Some of the fields on the Database Connection screen are pre-populated based on
the type of database you selected. If you edit these or any other fields on this screen, and then
later decide to change the database type, the IUA might not populate the fields correctly. If this
occurs, enter the correct field values as documented below, or exit and rerun the IUA to select
the intended database type. If you are resuming after a failed upgrade, some pre-populated
values might be disabled.
• 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 new rules schema name.
• Data Schema Name — Enter the temporary data schema name.
• Customer Schema Name — Leave blank.
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 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

20 | Pega Platform Upgrade Guide

 Performing your upgrade

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.

Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory.

Upgrading out-of-place by using the command line

To use the command line to configure the setupDatabase.properties file, the Deployment user must
run either upgrade.bat (for Windows) or upgrade.sh (for Linux).

1. If you have not done so already, edit the setupDatabase.properties file.

a. Open the setupDatabase.properties file in the scripts directory of your distribution image:
Directories.distributionDirectory\scripts\setupDatabase.properties.
b. Configure the connection properties. Use the new rules schema name for the rules schema name
and the temporary data schema for the data schema name. Even if your system includes a separate
customer data schema, leave it blank or use the temporary data schema name, it will be patched
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.

Importing applications and other rule changes for highly available

systems
If you plan to import applications or other rule changes in a high available system, doing so during an out-
of-place upgrade rather than after the upgrade improves performance.

1. Open the prpcUtils.properties file in the Pega_HOME\scripts\utils directory.

2. Configure the following property:
import.oop.upgrade=true
3. Save and close the file.
4. Import the application or other rule change. For more information about using the prpcUtils script, see
Using scripting with direct connection to the database and the prpcUtils tool.

Pega Platform Upgrade Guide | 21

Performing your upgrade

Upgrading the data schema

Run the script to upgrade the data schema.

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

2. Shut down the application server and ensure that no other processes are using the data schema.
3. Open a command prompt, and navigate to the scripts directory.
4. Run upgrade.bat (for Windows) or ./upgrade.sh (for Linux), passing in the --dataOnly argument
and true parameter, for example:
upgrade.bat --dataOnly true

Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory.

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.

Reviewing log files

The upgrade creates a series of log files in the Pega-image \scripts\logs directory. Review the log files to
ensure no outstanding issues were introduced during the upgrade process.

22 | Pega Platform Upgrade Guide

 Post-upgrade tasks

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.

Upgrading from PRPC 6.1 SP2 and earlier: updating

ruleset columns
When upgrading from any release prior to PRPC 6.2, you must run additional scripts to update the ruleset
columns.
Depending upon the database platform and the size of the database the script might require significant
time and resources to execute.

1. Navigate to ResourceKit\AdditionalUpgradeScripts and locate the scripts for your database:

• database_rulesetversion_columns_data.sql
• database_rulesetversion_columns_rules.sql
2. Run the scripts:
• Run database_rulesetversion_columns_data.sql against the data schema.
• Run database_rulesetversion_columns_rules.sql against the rules schema.

Reconfiguring the application server

If you performed an out-of-place upgrade, you must reconfigure the application server to use the new
rules schema. The process is different for each application server.

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" />

3. Save the file.

Apache Tomcat: Defining default schemas after out-of-place upgrades

If you performed an out-of-place upgrade on Apache Tomcat, redefine your default schema names. Define
the default schemas in the context.xml file.
Follow these steps to define the default schemas:

1. Open context.xml.

Pega Platform Upgrade Guide | 23

Post-upgrade tasks

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" />

3. Save the file.

Redeploying the Pega Platform file

Replace the existing prweb.war file with the new one found inside the distribution image archive folder.
For more information about redeploying the Pega Platform, see the following topics.

Apache Tomcat: Redeploying Pega Platform

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.

Restarting Pega Platform

Restart Pega Platform to load the updated code and rules from the upgraded rules schema.
1. Stop and restart the application server.
2. Ensure that the new Pega Platform prweb.war file has started.
3. Access Pega Platform through a browser. Enter the URL for the Pega Platform application:
http:// server:portnumber/context_root
For example: http://prpc-server:8080/prweb
4. Log in as [email protected].
The What’s New section of the page includes a welcome message and links to application development
tools.

Enabling rule creation

Ensure that rule creation is enabled. If you did not disable rule creation, skip this section.

1. Log in to Pega Platformas a user with the PegaRULES:HighAvailabilityAdministrator role.

24 | Pega Platform Upgrade Guide

 Post-upgrade tasks

2. In the header of Dev Studio, click Configure > System > High Availability > HA Cluster Settings.
3. Under Cluster Upgrade, clear Cluster Upgrading- Disable saving of rules.
4. Click Submit.
5. Log out of Pega Platform.

Upgrading from Pega Platform version 8.3 or earlier:

Guidelines for any required changes in your application
URL aliasing
Pega allows you to create application URL aliases that support your ability to launch multiple Pega
applications simultaneously in a single browser. This feature makes it easier for clients and your
customers to log into multiple applications using the same browser and access them simultaneously. After
you upgrade your application from Pega Platform 8.3 or earlier, review this section to determine if and
how you must update your application rules to reflect the current URL aliasing format.
You configure your application URL alias in the application definition. For details, see Adding an
application URL alias. Following an upgrade from Pega Platform 8.3 or earlier, your automated tests that
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.

Clipboard Property URL Format Old value (8.3 Current value

and earlier)

pxRequestor.pxReqServletNameReal: 8.3 URL format: <PRServlet- <PRServlet-

This property was updated to include the name> name>/app/
http://
current application alias format and value <application-URL-
host/prweb/
alias>
<PRServlet-name>/
accessgroupHash/
PRThread
Current format
http://host/
prweb/<PRServlet-
name>/app/
<application-
URL-alias>/

Pega Platform Upgrade Guide | 25

Post-upgrade tasks

Clipboard Property URL Format Old value (8.3 Current value

and earlier)

accessgroupHash/
PRThread

pxRequestor.pxReqServlet: This 8.3 URL format: NA <PRServlet-

property supports searches for the name>
http://
provided servlet name.
host/prweb/
<PRServlet-name>/
accessgroupHash/
PRThread
Current format
http://host/
prweb/<PRServlet-
name>/app/
<application-
URL-alias>/
accessgroupHash/
PRThread

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.

26 | Pega Platform Upgrade Guide

 Post-upgrade tasks

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.

Upgrading from Pega Platform version 8.1 or 8.2:

recreating interaction history aggregates
If you use Pega Customer Decision Hub or Pega Marketing and also use interaction history aggregates,
you must perform the following steps to recreate the data sets.
To recreate aggregates, do the following steps:

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.

Upgrading from Pega Platform version 8.2 or earlier:

batch generating work IDs
In Pega 8.2 and earlier, the generation of work IDs is batch-based. Delete either entries from the
prconfig.xml file or dynamic system settings so that work IDs are generated in this way.

1. Do one of the following actions:

Choice Action

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.

Pega Platform Upgrade Guide | 27

Post-upgrade tasks

Recreating PostgreSQL views

If you created database views which are dependent on database tables provided by Pega Platform,
recreate the views by reviewing and picking up the changes caused by the upgrade.

Upgrading from Pega Platform version 7.2.2 and earlier:

porting Apache logging file customizations to the new
log file
To use the new logging service, port your logging file customizations to the new log file.
Starting with Pega 7.3, the Pega Platform uses the Apache Log4j 2 logging service. Prior to Pega 7.3,
the Pega Platform used Apache Log4j 1. Because of the change to the logging service, the name of the
logging configuration file has changed from prlogging.xml to prlog4j2.xml and the format has
changed considerably. If you customized your prlogging.xml file, port the customizations to the new
prlog4j2.xml file. If you do not edit the new prlog4j2.xml file, the Pega Platform uses the default
prlog4j2.xml file and disregards your customized prlogging.xml file. For upgrades to systems that
were using the default logging configuration, no changes are needed.
Pega Platform supports all appenders and layouts supported by Apache Log4j 2. The following commonly-
customized appenders define the logging file locations, names, and archiving policy:
• RollingRandomAccessFile – Configures the PegaRULES.log file that includes all logs except alerts
• RollingRandomAccessFileAlert – Configures the PegaRULES-ALERT.log file that includes all
performance alerts
• RollingRandomAccessFileAlertSecurity – Configures the date and time-stamped PegaRULES-
ALERTSECURITY log file that includes all security alerts
For more information about customizing these appenders, see the Apache Log4j 2 documentation.

Enabling Admin Studio

Admin Studio is the portal in which you perform administrative and operations tasks in Pega
Platform. To access Admin Studio, grant users either the PegaRULES:SysOpsAdministrator or the
PegaRULES:SysOpsObserver role. Admin Studio replaces the System Management Application (SMA).
Users with the SysOpsAdministrator role can view and take actions in Admin Studio. The SysOpsObserver
role has read-only access to data in Admin Studio.

1. Open the appropriate access group.

2. Add the role under Available Roles on the Definition tab.
3. Add pxAdminStudio to the list of available portals on the access group definition.

Locking and rolling ruleset versions

If your system includes ruleset names that use ruleset prerequisite validation instead of application-
based validation, lock your existing ruleset and roll them into new versions before you continue your

28 | Pega Platform Upgrade Guide

 Post-upgrade tasks

development. Locking ensures that future development is based on the upgraded rulesets and that your
applications consistently reference the latest features.
Note: The upgrade process automatically upgrades any prerequisite for Pega-ProCom to the
highest version of the ruleset in the system.

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.

Reviewing required post-upgrade search index steps

Following your upgrade, you should your review your search index configuration to determine if you must
complete any post-upgrade steps. The embedded search in Pega Platform leverages Elasticsearch version
5.6.9.
Depending on the version of Pega software you upgraded from, your search index-related tasks vary.
Review the sections below to determine your appropriate next steps.

If upgrading from release 7.2.2 or later

No immediate action is required and your application will continue to use your existing search indexes.

If upgrading from release 7.1.7 through 7.2.1

While no node configuration changes are required, you must discard your existing indexes and build new
indexes in a new empty index directory. To review your options and to determine the appropriate steps,
see Rebuilding search indexes.
To review a helpful overview of Pega troubleshooting Elasticsearch issues, see Troubleshooting
Elasticsearch issues in Pega 7.1.7 through 7.4.

If upgrading from release 7.1.6 or earlier

You must reconfigure your searching functionality by classifying some of your processing nodes as search
nodes and then creating a search index that uses Elasticsearch. Starting in Pega Platform 7.1.7, the
underlying platform for full-text search transitioned from Lucene to Elasticsearch. Elasticsearch provides
a more robust, fault-tolerant search capability and does not require manual configuration of switchover
activities. Existing search customizations through Pega Platform APIs are intact and used exactly the same
way with Elasticsearch; only the search query generation changes from Lucene to Elasticsearch.
To reconfigure your search functionality to use Elasticsearch, Pega recommends the following articles:
• To configure search nodes, Configuring index host nodes.
• To review an overview of full-text search options, see Configuring full-text search.

Pega Platform Upgrade Guide | 29

Post-upgrade tasks

• To review the options to build your search index and determine the appropriate steps, see Rebuilding
search indexes.

Identifying conflicts with rules that cannot be

overridden by running the final rules conflict report
The Final Rules Conflict Report lists rules in your system that reference final Pega rules for this release.
These rules vary depending on the specific release from which you are upgrading.
Final rules can no longer be overridden. If you have custom rules in your applications that override default
rules and your custom rules are final, your existing rules will continue to function correctly. However, you
will not be able to modify them after you upgrade to the new ruleset.
Note: 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, see the Support area on the Pega Community.
To run the report, click Dev Studio > System > Release > Upgrade > Final Conflicts.

Optional: Enabling new UI kit and Cosmos features

To take advantage of the latest user interface elements, including templates and icons, add the latest
version of the UI Kit or Theme-Cosmos application to the Built On Applications List. You can still continue
to use your current version of the UI Kit or Theme-Cosmos to avoid additional post-upgrade steps, but
then you will not have access to the latest features, functions, and fixes.
Each new release of Pega Platform ships with all the versions of UI Kit provided in previous releases.
Upgrading to a new version of UI Kit or Theme-Cosmos is a development effort. The UI layer is upgraded
every release to stay in sync with the changes in the design system. Therefore, the new UI Kit or Cosmos
rules may not be backward compatible with applications that currently use an older version of the UI Kit.
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.

Running upgrade utilities

Pega Platform includes several upgrade utilities to help you to upgrade your application to use new
features. Run all of the upgrade utilities.
Note: Depending on your Pega application, some utilities may not return results for your
application.

1. Log in as the administrator.

2. In the header of Dev Studio, click Configure > System > Release > Upgrade > Upgrade Tools.
3. Expand General Utilities.
4. Click each utility, and then click Run utility.

30 | Pega Platform Upgrade Guide

 Post-upgrade tasks

Upgrading your applications

If you did not run the Update Existing Application utility during the upgrade, you can run it after the
upgrade to ensure that your existing applications take advantage of new functionality in Pega Platform.
Run the utility first on your development system and test the changes. Then, run the utility again on the
production system. The specific actions required for your application depend on your current version.
The utility lists the actions that will be performed, the number of records that will be modified, and an
estimate of how long each action will take.

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.

Optional: Upgrading your application schema

If you did not opt to upgrade your application schema automatically, run the Upgrade Application Schema
utility.
If you upgraded your application schema automatically as part of the upgrade, skip this task.

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.

Increasing reliability and reducing memory by

upgrading to Cassandra 3.11.3
After you upgrade your on-premises instance of Pega Platform, Cassandra is not automatically upgraded.
Manually upgrade to Cassandra 3.11.3 to increase your system's reliability and reduce its memory
footprint.

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.

To upgrade to Cassandra 3.11.3, complete the following tasks:

1. Configuring access to Cassandra ports.
2. Upgrading Cassandra on Decision Data Store nodes.
3. Verifying the Cassandra upgrade.

Pega Platform Upgrade Guide | 31

Post-upgrade tasks

Configuring access to Cassandra ports

If you will be using embedded Decision Data Store (DDS) services, several ports must be open on the
nodes in the cluster where Cassandra is running so that the nodes can communicate with each other. Skip
this section if you are not using embedded DDS services.
Configure the firewall that is running on nodes in your Cassandra cluster so that these ports are open.
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)
Ensure that port 9042, the CQL native transport port, is open to all the nodes in the Pega cluster.

Upgrading Cassandra on Decision Data Store nodes

Upgrade Cassandra on the Decision Data Store (DDS) nodes in your cluster to incorporate the Cassandra
3.11.3 distribution into your application. By default, upgrading the DDS nodes triggers the upgrade of
SSTables.

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.
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. Ensure that each DDS node in the cluster has the same schema version by performing the following
actions:
a. From the console, from the Cassandra distribution directory, run the following command: ./bin/
nodetool describecluster.
b. Verify that the output contains only one schema version.
For example: 

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:

32 | Pega Platform Upgrade Guide

 Post-upgrade tasks

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.

Verifying the Cassandra upgrade

Verify that the upgrade to Cassandra 3.11.3 has completed successfully by ensuring that the upgraded
Decision Data Store runs correctly.

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: 

Operation mode from management: NORMAL

Reachable nodes: [10.0.2.21, 10.0.2.23]
Unreachable nodes: []

If the list does not contain all the running DDS nodes, contact Global Client Support.

Pega Platform Upgrade Guide | 33

Post-upgrade tasks

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.

Upgrading from Pega Platform version 7.3 or earlier:

Updating service email rules to reply to Pulse email
notifications
If you configured service email rules in Pega Platform 7.3 or earlier, following an upgrade, you must add
required fields in order for your applications to reply to Pulse email notifications correctly.
For complete details on configuring Pulse email notifications, see Configuring Pulse email notifications.

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:

Field name Description Map to Map to key

Message-ID Message-ID Clipboard .pyInboundEmail.pyMessageID

In-Reply-To In-Reply-To Clipboard .pyInboundEmail.pyInReplyTo

References References Clipboard .pyInboundEmail.pyReferences

5. Save the Service Email rule.

6. Restart the email listener that is configured with the service email rule.

Upgrading from Pega Platform version 7.2.2 or earlier:

enabling notifications by upgrading access role names
When upgrading from any release prior to Pega 7.2.2, you must upgrade all the user access role names of
an application with specific classes so that users can receive notifications.
To save time, clone any access role name that contains the preceding classes and assign it to application
users instead of updating the access role names manually. For more information on how to clone an
access role name, see Configuring access roles.

1. In the Records Explorer, click Security > Access Role Name.

34 | Pega Platform Upgrade Guide

 Post-upgrade tasks

2. Open the access role name for the following classes that require editing.
• Data-Notification-Parameters
• Pega-Notification
• Data-Notification-Recipient
• Data-Preference-Operator
3. Click the Plus icon to open the Add Access Role Object dialog box.
4. In the Class field, enter the class name that you want to add to the access role name.
5. Under Access Control, enter 5 in all the fields to provide access to this access role name.
6. Click Save.
7. Perform steps 3 through 6 for each of the remaining classes.

Upgrading from Pega Platform version 7.2.2:

customizing the agent schedules for the standard Pega
Platform agents
If you developed agent schedules on Pega 7.2.2 with the Node Classification feature, manually edit all
customized schedules for standard Pega 7.2.2 agents.
Note: This section applies only to major and minor upgrades, not patches. For details about these
differences, see: Upgrading and patching Pega Infinity.
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.

1. In Dev Studio, open the Agent type you wish to customize.

2. In the agent schedule form, modify any settings that need to be updated. For more information, see
Agent schedule data instances.
3. Click Save.

Upgrading from Pega Platform version 7.3, 7.3.1, or 7.4:

granting access to the Requester Management landing
page
To access the Requester Management landing page in your application, add privileges to the @baseclass
and Pega-Landing access classes in your access roles.
Note: This section applies only to upgrades from the following releases.

• Pega 7.3
• Pega 7.3.1
• Pega 7.4
If you are upgrading from another version, skip this section.

Pega Platform Upgrade Guide | 35

Post-upgrade tasks

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.

Upgrading from Pega Platform version 7.2.2 or earlier:

enabling access to environmental information
Enable access to environmental information to avoid an apparent flaw in some security audits.
Before Pega 7.3, all roles included access to environmental information for the current node.
This information can include version numbers of third-party platforms and JVM information.
This access appears as a flaw in some security audits. Starting with Pega 7.3, the new
@baseclass.pxViewSystemInfo privilege controls access to environmental information. Only the
PegaRULES:SysAdm4 role has this privilege by default. After you upgrade from Pega 7.2.2 and earlier,
add the @baseclass.pxViewSystemInfo privilege to all system administrator roles that need access to
environmental information.

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.

36 | Pega Platform Upgrade Guide

 Post-upgrade tasks

Upgrading from Pega Survey 7.2.2 or earlier: enabling

the new Pega Survey features
For applications using Pega Survey, if you are upgrading from Pega 7.2.2 or earlier, upgrade your
application to use the latest survey features.
You cannot revert surveys to their original implementation after you adopt the rules and APIs that are
provided in the Pega-Survey ruleset.
For each application that uses survey capabilities, repeat the following steps:

1. Remove the reference to the legacy PegaSurvey ruleset.

a. In the header of Dev Studio, click [Your application name] > Definition to open the Application
form.
b. In the Application rulesets section, delete the entry for the PegaSurvey ruleset.
c. Click Save.
2. Upgrade your overrides and custom rules that rely on standard rules that have been renamed to find
rules with invalid references.
a. In the header of Dev Studio, click Configure > Application > Tools > Validation.
b. In the Select Application list, select the name of your application.
c. Click Run Validation.
d. Review the list of rules with invalid references, and resolve each invalid reference by performing one
of the following actions:
• Redirect the invalid reference to a valid rule in the Pega-Survey ruleset.
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.

Pega Platform Upgrade Guide | 37

Post-upgrade tasks

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.

Upgrading from Platform version 7.2.1 or earlier: Re-

scheduling required column population jobs
When you upgrade from Pega Platform version 7.2.1 or earlier, the upgrade process exposes the
pxApplication column on all Work object tables. Because the expose process on systems that were
running 7.2.1 or earlier can temporarily degrade application performance, it is a best practice to
reschedule the column repopulation process to run during off-peak hours.
You can specify a start time for the job and a timeout length. When the job reaches the end of the
timeout, it stops and restarts the next day at the same point. The job continues to recur until all tables are
upgraded. The number of times the job runs depends on the amount of data in your work tables.
Users must have the SysAdm4 role to schedule column population jobs.
1. Configure the start time for the column population:
a. In the Explorer panel, click Records > SysAdm > Agent Schedule.

38 | Pega Platform Upgrade Guide

 Post-upgrade tasks

b. Filter the list. In the Key Contains box at the top of the screen, enter Pega-ImportExport and click
Run.
c. Click any instance of Pega-ImportExport.
Note: You can edit any instance of Pega-ImportExport. Check the NODE NAME field for
information about the node associated with each instance.
d. Click Advanced next to the pxAutomaticColumnPopulation activity line.
e. Enter the start time and schedule for the job and click OK.
f. In the Column Pattern area, select Recurring.
g. Select Enabled.
h. Click Save.
2. Optional: Configure the timeout to set the maximum length of time the column population job will run.
a. In the Explorer panel, click Records > SysAdm > Dynamic System Settings.
b. In the Owning Ruleset field, click the filter icon, enter ImportExport, and click Apply.
c. Double-click AutomaticColumnOptimization/Timeout.
d. Enter the timeout value in minutes.
Note: The default setting is 120 minutes. Change the timeout to reflect the duration of your
off-peak schedule. For example, if your lowest usage occurs from 9 P.M. EST until 4 A.M. EST,
start this job at 9 P.M. and have it run for 420 minutes.
e. Click Save.

Testing your applications

After your upgrade, perform regression testing to verify that application functionality works as expected.
As part of regression testing, perform smoke testing to verify that critical functionality works as expected.
To instantly ensure that specific functionality works appropriately, run sanity tests.

For details about testing your applications, see Testing upgrades.

Pega Platform Upgrade Guide | 39

Appendices

Appendices
The appendices include information about optional processes and troubleshooting.

Migrate script properties

The migrate script, migrate.bat(for Windows) or migrate.sh (for Linux) migrates the rules objects from
the existing schema to a new rules schema, and generates and applies rules schema DDL objects after
upgrading the new rules schema. Edit the migrateSystem.properties file to configure the migrate
script. The Deployment user performs the migrations.
Note: Pega strongly recommends that you use the migrate.bat (for Windows) or migrate.sh
script (for Linux) 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:
• 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 existing rules schema
and the temporary rules schema, 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.

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.

pega.source.jdbc.driver.class Valid values are:

pega.target.jdbc.driver.class • org.postgresql.Driver

pega.source.database.type The database type:

pega.target.database.type postgres

pega.source.jdbc.url The database connection URL. For more

information, see Obtaining database connection
pega.target.jdbc.url
information.

pega.source.jdbc.username Deployment user name.

pega.target.jdbc.username

40 | Pega Platform Upgrade Guide

 Appendices

Property Description

pega.source.jdbc.password Deployment user password.

pega.target.jdbc.password

Custom properties
The following properties are used during migration to configure custom settings.

Property Description

pega.source.jdbc.custom.connection.properties An optional semi-colon-delimited list of custom

connection properties.
pega.target.jdbc.custom.connection.properties

pega.source.data.schema Used to identify which schemas to migrate and to

correctly migrate schema-qualify tables in stored
pega.target.data.schema
procedures and views.
pega.source.rules.schema
pega.target.rules.schema

pega.target.bypass.udf Set this property to bypass UDF generation on the

system.

Migration directory properties

Set the directories for migration objects.

Property Description

pega.bulkmover.directory The full path to the directory where output from

the bulk mover will be stored. This directory
will be cleared when pega.bulkmover.load.db
is set to true. This property must be set
if either pega.bulkmover.unload.db or
pega.bulkmover.load.db is set to true.

pega.migrate.temp.directory The full path to the temporary directory that is

created by the migrate system utilities.

Operational properties
Use the following properties to migrate Rules objects.

Property Description

pega.clone.generate.xml Set to true or false. 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.

Pega Platform Upgrade Guide | 41

Appendices

Property Description

pega.clone.create.ddl Set to true or false. Create DDL from the

generated xml document. This DDL can be used
to create copies of rule tables found on the source
system.

pega.clone.apply.ddl Set to true or false. Apply the generated clone

DDL to the target system.

pega.bulkmover.unload.db Set to true or false. Unload the data from the

rules tables on the source system into the
pega.bulkmover.directory.

pega.bulkmover.load.db Set to true or false. Load the data from the

pega.bulkmover.directory into the rules tables on
the target system.

db.load.commit.rate Specify a commit rate to use when

pega.bulkmover.load.db=true. The default value is
100.

thread.pool.size Allows you to optimize the number of worker

threads used to migrate your database tables,
based on your system hardware. When you do not
specify a value, the size is set to the number of
hardware threads on the machine, up to 32.

custom.jvm.args Allows you to add a list of space delimited JVM

arguments. The max heap size must be set to
at least 4GB; if you increase the commit rate
or thread pool size beyond their defaults, it is
possible that more heap space may be required.

Rules schema object properties

This table describes operations to run when migrating upgraded rules:

Property Description

pega.rules.objects.generate Generate the rules schema objects (views,

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.

42 | Pega Platform Upgrade Guide

 Appendices

Property Description

pega.rules.objects.apply Apply the rules schema objects

(views, procedures, and functions) to
pega.target.rules.schema.

Customizing deployment script behavior

Edit the setupDatabase.properties file to configure deployment scripts.
Skip this section if your deployment meets all the following criteria:
• You will use the Installation and Upgrade Assistant.
• You will allow the Installation and Upgrade Assistant to automatically apply the schema changes and
do not need to create a DDL file.
• You will not use Kerberos authentication.
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.

Database connection properties and script arguments

The database connection properties in the setupDatabase.properties file specify the settings needed
to connect to the database. The script arguments specify the same settings when you use command-line
scripts. Command-line settings override property file settings.

Script argument Property Description

--pega.jdbc.driver.jar pega.jdbc.driver.jar Path and file name of the JDBC

driver.

Pega Platform Upgrade Guide | 43

Appendices

Script argument Property Description

--pega.jdbc.driver.class pega.jdbc.driver.class Class of the JDBC driver

--pega.database.type pega.database.type Database vendor type. Enter the

correct database vendor:
• PostgreSQL or Enterprise DB:
postgres

--pega.jdbc.url pega.jdbc.url The database JDBC URL.

For more information, see
Obtaining database connection
information.

--pega.jdbc.username pega.jdbc.username User name of the Deployment

user.

--pega.jdbc.password pega.jdbc.password Password of the Deployment

user. For encrypted passwords,
leave this blank.

--pega.admin.password pega.admin.password For new installations only.

--rules.schema.name rules.schema.name Sets the rules schema name.

--data.schema.name data.schema.name For split-schema configurations

only, sets the data schema
name.

--customerdata.schema.name customerdata.schema.name An optional customer data

schema separate from the
default Pega data schema.

--user.temp.dir user.temp.dir Optional: The location of the

temp directory. Set this location
to any accessible location.
For example, C:\TEMP.

Additional upgrade properties

The properties in the setupDatabase.properties file help you to customize the upgrade.
The following table describes additional properties in the setupDatabase.properties file that you
might need to edit only for upgrades.

44 | Pega Platform Upgrade Guide

 Appendices

Script argument Property Description

--bypass.pega.schema bypass.pega.schema Bypass both creating the

temporary rules schema and
automatically generating the
user-defined functions, by
setting bypass.pega.schema
to true. This implies that
the upgrade DDL is already
applied. 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 deployment generates and
applies the schema changes to
your database.
To create the temporary rules
schema and automatically
generate the UDFs, leave this
property blank or set it to
false.

--bypass.udf.generation bypass.udf.generation If you set bypass.pega.schema

to false to create the
temporary rules schema,
but still want to bypass
automatically generating the
user-defined functions, set
bypass.udf.generation to true
to manually install the UDFs.

--rebuild.indexes rebuild.indexes Enable the rebuilding of

database rules indexes after
the rules load to improve
database access performance.
If rebuild.indexes=false, you
can rebuild the indexes later by
running the stored procedure
SPPR_REBUILD_INDEXES. The
amount of time this process
adds to the upgrade depends on
the size of your database.

--update.existing.applications update.existing.applications Enable the Update Existing

Applications utility. If you did
not run the Update Existing
Application utility during the
upgrade, you can run it after
the upgrade to ensure that
your existing applications take
advantage of new functionality
in Pega Platform. Run the utility

Pega Platform Upgrade Guide | 45

Appendices

Script argument Property Description

first on your development

system and test the changes.
Then, run the utility again on
the production system. The
specific actions required for
your application depend on your
current version. You can also
run this utility later from the Dev
Studio. The default setting is
false.

--update.applications.schema update.applications.schema Enables the Update Applications

Schema utility to upgrade the
auto-generated rule, data, work,
and work history tables with
the schema changes in the
latest base tables as part of the
upgrade.
You can also run this utility later
from the prpcUtils.bat or
prpcUtils.sh script, or from
Dev Studio. The default setting is
false.

--run.ruleset.cleanup run.ruleset.cleanup Enable the cleanup of older

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.

--reversal.schema.file.name reversal.schema.file.name Specify a schema filename to be

used for a filename reversal.

--automatic.resume automatic.resume Specifies whether the system

restarts after an upgrade failure
from the point in the process
where the failure occurred. The
default value is true.

Manually generating and applying the DDL

If you chose not to automatically apply the DDL, then you must generate and apply the DDL manually.
The process for generating and applying DDL differs depending on whether you are performing an out-of-
place upgrade or an in-place upgrade.

46 | Pega Platform Upgrade Guide

 Appendices

Generating and applying DDL in an out-of-place upgrade

Use the migrate and generateddl scripts to generate and apply DDL changes as part of an out-of-place
upgrade.
Use the migrate and generateddl scripts in different steps to generate and apply required platform-
specific DDL and write them to a file. You can then view and edit the file or directly apply it by using
database management tools. For detailed instructions, communicate with your database administrator.

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

3. Edit the migrateSystem.properties file to create the DDL:

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 Platform Upgrade Guide | 47

Appendices

pega.rules.objects.apply=false

4. Run the migrate.sh or migrate.bat script to create the DDL.

b. Have the database administrator apply the DDL.
c. Populate the tables. For details about running the migrate script, see Migrating the existing rules
schema.
1. Leave the source and target schema properties as in step 1a.
2. Edit the migrateSystem.properties file to populate the table:

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

3. Run the migrate.sh or migrate.bat script to populate the table.

2. Upgrade the rules schema and apply the DDL for the rule schema changes:
a. Create the DDL of changes to the rules schema.
1. Edit the setupDatabase.properties file to set the rules and data schema names:
• 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

2. Run the generateddl.bat or generateddl.sh script.

b. Have the database administrator apply the DDL.
c. Use the command line to upgrade the rules schema.
1. Edit the setupDatabase.properties file to bypass the schema upgrade because the DDL is
already applied: bypass.pega.schema=true
2. Leave the rules and data schema names as in step 2a.
3. Run the upgrade.bat or upgrade.sh script.

48 | Pega Platform Upgrade Guide

 Appendices

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=

• For the source with two databases:

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=

• For the target with 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=existing data schema

• For the target with 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=new rules schema
pega.target.data.schema=existing data schema

2. Edit the migrateSystem.properties file to create the DDL:

pega.clone.generate.xml=false
pega.clone.create.ddl=true

Pega Platform Upgrade Guide | 49

Appendices

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

3. Run the migrate.sh or migrate.bat script to create the DDL.

b. Give the DDL to the database administrator to apply.
4. Upgrade the data schema and apply the DDL for the data schema changes:
a. Create the DDL of changes to the data schema.
1. Edit the setupDatabase.properties to set the rules and data schema names:

rules.schema.name=new rules schema

data.schema.name=existing data schema

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 or generateddl.sh script with the --upgradeDataOnly argument
and true parameter, for example: generateddl.bat --upgradeDataOnly true
b. Have the database administrator apply the DDL to the data schema.
c. 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

Generating and applying DDL in an in-place upgrade

Use the generateddl scripts to generate and apply DDL changes as part of an in-place upgrade.

Generating the DDL file

Follow these steps to generate a DDL file for your database administrator to apply manually.

1. Edit the setupDatabase.properties file.

a. Configure the connection properties. The customer data schema is optional.

# Connection Information
pega.jdbc.driver.jar=\path-to-the-database-JAR-file\DRIVER.jar

50 | Pega Platform Upgrade Guide

 Appendices

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

b. Save and close the file.

2. At a command prompt, navigate to the Pega-image \scripts directory.
3. Run generateddl.bat or generateddl.sh and pass in the required --action argument:
#generateddl.bat --action upgrade

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.

Applying the DDL file

Before you continue, have your database administrator follow these general steps to apply the schema
changes; these schema changes can include changes to user-defined functions:

1. Review the DDL file in the output directory and make any necessary changes. The default directory is:
Pega-image\schema\generated\database\postgres
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.

Alternative upgrade: Upgrading in-place

Upgrade your system in-place if you do not require high availability.
The in-place upgrade process involves system downtime, which means you cannot use the system while
the upgrade process runs. For information about the major upgrade process that uses the out-of-place
upgrade process with minimal downtime, see Performing your upgrade.
Performing an in-place upgrade can be summarized in the following steps:
1. Shut down the system.
2. Upgrade the rules and data schema. For details, see Upgrade methods for an in-place upgrade.

Pega Platform Upgrade Guide | 51

Appendices

3. Restart the system to complete the upgrade .

Upgrade methods for an in-place upgrade

Use either the Installation and Upgrade Assistant or a command-line tool to upgrade in-place.

Upgrading in-place by using the Installation and Upgrade Assistant

For a UI-based experience, use the Installation and Upgrade Assistant.
Because of the large volume of data, run the IUA on the same network as the database server. If this is
not possible, run the tool on a system with fast, direct access to the database server. The Deployment
user performs these steps.
The time needed to upgrade can vary widely based on network proximity to the database server.

1. Double-click the PRPC_Setup.jar file to start the IUA.

Note: If JAR files are not associated with Java commands on your system, start the IUA from the
command line. Navigate to the directory containing the PRPC_Setup.jar file, and type java -
jar PRPC_Setup.jar.
The IUA loads and the Pega icon is displayed in your task bar.
2. Click Next to display the license agreement.
3. Review the license agreement and click Accept.
4. Optional: If you are resuming after a previous failed upgrade and the Resume Options screen is
displayed, select either Resume or Start Over.
• If you select Resume, the system uses the previously entered database configuration information to
resume the upgrade from the last successful process. Continue these instructions at step 8.
• If you select Start Over, continue at step 5 to reenter the configuration information.
5. On the Installer Mode screen, choose Upgrade and click Next.
6. Choose your database type and click Next.
7. Configure the database connection. The JDBC drivers allow the Pega Platform application to
communicate with the database. Specify the existing schema names for the Rules Schema Name and
Data Schema Name fields.
Note: Some of the fields on the Database Connection screen are pre-populated based on
the type of database you selected. If you edit these or any other fields on this screen, and then
later decide to change the database type, the IUA might not populate the fields correctly. If this
occurs, enter the correct field values as documented below, or exit and rerun the IUA to select
the intended database type. If you are resuming after a failed upgrade, some pre-populated
values might be disabled.

52 | Pega Platform Upgrade Guide

 Appendices

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

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, select Bypass Automatic DDL Application and
continue the deployment. After you complete the deployment, manually generate and apply the
DDL and UDF. For more information, see Optional: Generating and applying DDL and Optional:
Installing user-defined functions.
• 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.

Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory.

Pega Platform Upgrade Guide | 53

Appendices

Upgrading in-place from the command line

To use the command line to configure the setupDatabase.properties file, the Deployment user must
run either upgrade.bat (for Windows) or upgrade.sh (for Linux).

1. If you have not done so already, edit the setupDatabase.properties file.

a. Open the setupDatabase.properties file in the scripts directory of your distribution image:
Directories.distributionDirectory\scripts\setupDatabase.properties.
b. Configure the connection properties. Use the existing schema names for the rules schema and data
schema names.
c. Optional: If you have a separate customer data schema, set the target schema name:
pega.target.customerdata.schema=existing-customer-data-schema
d. 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.
e. Save and close the file.
2. Open a command prompt and navigate to the scripts directory.
3. Run either upgrade.bat or upgrade.sh.

Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory.

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.

Alternative upgrade: Upgrading out-of-place with a

double migration process
Perform an out-of-place upgrade to minimize downtime. Use a double migration to avoid performance
drain on existing database servers. The rules schema upgrade occurs out-of-place, and the data schema
upgrade occurs in-place.
An out-of-place upgrade with double-migration involves five schemas:
• Data schema – your current, existing data schema. This will be your data schema after the upgrade as
well.
• Rules schema – your current, existing rules schema.
• New rules schema – the new rules schema. This schema will become the rules schema after the
upgrade.
• Temporary rules schema – a temporary schema on a separate database used for staging the rules
upgrade during the upgrade.
• Temporary data schema – a temporary schema on a separate database used for staging the data
tables with your data during the upgrade.
The generic process for upgrading a split-schema configuration is summarized in the following steps:
1. For upgrades to high-availability systems, disable rule creation on the rules schema.

54 | Pega Platform Upgrade Guide

 Appendices

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.

For High Availability systems: Preparing the cluster for upgrading

If you are using the recommended High Availability option, you must disable rule creation on the rules
schema to avoid losing any rules created during the upgrade period when switching over to the upgraded
schema. If you are not using the High Availability option, skip this section.
If you are performing an in-place upgrade, you can skip this section.

1. Log in as a user with the PegaRULES:HighAvailabilityAdministrator role.

2. Configure the HA cluster setting to support automatic rule migration:
a. In the header of Dev Studio, click Configure > System > High Availability > HA Cluster Settings.
b. Check Cluster Upgrading – Disable saving of rules.
c. Click Submit.

Creating three new schemas on two databases

To use two databases for an out-of-place upgrade, create a new database and three new schemas:
• Create a new, temporary database with two blank schemas, one for the temporary rules schema,
and one for the temporary data schema. Leave these new schemas empty. Pega does not support
quoted identifiers, so do not wrap your schema name with single quotes. Create each schema name in
accordance with the requirements of your deployment database type:
PostgreSQL databases force unquoted identifiers to lowercase.
• Create the new rules schema in your original database. Leave this new schema empty. Pega does not
support quoted identifiers, so do not wrap your schema name with single quotes. Create each schema
name in accordance with the requirements of your deployment database type:
PostgreSQL databases force unquoted identifiers to lowercase.

Pega Platform Upgrade Guide | 55

Appendices

Migrating the existing rules schema

Use the migrate script to migrate the rules tables and other required database objects from the existing
rules schema to the new temporary rules schema.
You will also use the migrate script later to generate and apply rules objects, such as functions and stored
procedures, after the upgrade, but the property settings will be different. The Deployment user performs
the migrations.
Note: Pega strongly recommends that you use the Pega-provided migration script. The use of
vendor tools to manage this step is not recommended, since there are additional manual steps
required to migrate the schema, not documented here, if you do not use the migrate script.
This process depends on whether the system has access to both the original and temporary databases.
For more information, see:
• Migrating the rules schema when the process includes access to both databases
• Migrating the rules schema when the process can only access one database
Note: To minimize the time required, run the migration scripts from the same data center as the
database server.

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

56 | Pega Platform Upgrade Guide

 Appendices

4. Configure the bulkmover directory:

pega.bulkmover.directory=full path to output directory
5. Configure a temporary directory:
pega.migrate.temp.directory=full path to temporary directory
6. Configure the operations to be performed by the utility as shown below:

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

7. Disable the operations as shown below:

pega.rules.objects.generate=false
pega.rule.objects.apply=false

8. Save the properties file.

9. Open a command prompt, and navigate to the scripts directory.
10. Type migrate.bat or ./migrate.sh to run the script.

Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory.

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

Pega Platform Upgrade Guide | 57

Appendices

c. Configure the target properties.

# 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

d. Configure the bulkmover directory:

pega.bulkmover.directory=full path to output directory

e. Configure a temporary directory:

pega.migrate.temp.directory=full path to temporary directory

f. Configure the operations to be performed by the utility as shown below:

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

g. Save the properties file.

h. Open a command prompt, and navigate to the scripts directory.
i. Type migrate.bat or ./migrate.sh to export the rules to the temporary directory.
2. On a system that can access the temporary (target) database, import the structure and content of the
schemas.
a. Copy the migrateSystem.properties file you created in step 1 to a system that can access the
temporary (target) database.
b. Verify the target, bulkmover, and temporary directory properties.
c. Configure the operations to be performed by the utility as shown below:

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

d. Save the properties file.

e. Open a command prompt, and navigate to the scripts directory.
f. Run migrate.bat or ./migrate.sh to import the structure and content of the schemas from the
temporary directory.

58 | Pega Platform Upgrade Guide

 Appendices

Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory.

Upgrade methods for the migrated rules schema

Use either the Installation and Upgrade Assistant or a command-line tool to upgrade the migrated rules
schema. Use a command-line tool to upgrade the migrated rules schema.

Upgrading by using the Installation and Upgrade Assistant

For a UI-based experience, use the Installation and Upgrade Assistant.
Because of the large volume of data, run the IUA on the same network as the database server. If this is
not possible, run the tool on a system with fast, direct access to the database server. The Deployment
user performs these steps.
The time needed to upgrade can vary widely based on network proximity to the database server.

1. Double-click the PRPC_Setup.jar file to start the IUA.

Note: If JAR files are not associated with Java commands on your system, start the IUA from the
command line. Navigate to the directory containing the PRPC_Setup.jar file, and type java -
jar PRPC_Setup.jar.
The IUA loads and the Pega icon is displayed in your task bar.
2. Click Next to display the license agreement.
3. Review the license agreement and click Accept.
4. Optional: If you are resuming after a previous failed upgrade and the Resume Options screen is
displayed, select either Resume or Start Over.
• If you select Resume, the system uses the previously entered database configuration information to
resume the upgrade from the last successful process. Continue these instructions at step 8.
• If you select Start Over, continue at step 5 to reenter the configuration information.
5. On the Installer Mode screen, choose Upgrade and click Next.
6. Choose your database type and click Next.
7. Configure the database connection. The JDBC drivers allow the Pega Platform application to
communicate with the database. Specify the new rules schema name for the Rules Schema Name
field and the temporary data schema for the Data Schema Name field.
Note: Some of the fields on the Database Connection screen are pre-populated based on
the type of database you selected. If you edit these or any other fields on this screen, and then
later decide to change the database type, the IUA might not populate the fields correctly. If this
occurs, enter the correct field values as documented below, or exit and rerun the IUA to select
the intended database type. If you are resuming after a failed upgrade, some pre-populated
values might be disabled.
• 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 temporary rules schema name.
• Data Schema Name — Enter the temporary data schema name.
• Customer Schema Name — Leave it blank.

Pega Platform Upgrade Guide | 59

Appendices

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.

Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory.

Upgrading out-of-place by using the command line

To use the command line to configure the setupDatabase.properties file, the Deployment user must
run either upgrade.bat (for Windows) or upgrade.sh (for Linux).

1. If you have not done so already, edit the setupDatabase.properties file.

a. Open the setupDatabase.properties file in the scripts directory of your distribution image:
Directories.distributionDirectory\scripts\setupDatabase.properties.
For more information about the setupDatabase.properties file, see Database connection
properties and script arguments.
b. Configure the connection properties. Use the temporary rules schema name for the rules schema
and the data schema. Even if your system includes a separate customer data schema, leave it blank

60 | Pega Platform Upgrade Guide

 Appendices

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

Migrate to the new rules schema. Use the migrate.bat or migrate.sh script again for this process,
but with different properties in the migrateSystem.properties file. The Deployment user runs these
scripts.
• If the system can access both databases at the same time, follow the instructions in Migrating to the
new rules schema when the process includes access to both databases.
• If there is a firewall or other security restriction and the system can only access one database at a time,
follow the instructions in Migrating to the new rules schema when the process can only access one
database.
Note: Pega strongly recommends that you use the Pega-provided migration script. The use of
vendor tools to manage this step is not recommended, since there are additional manual steps
required to migrate the schema, not documented here, if you do not use the migrate script.
This process depends on whether the system has access to both the original and temporary databases at
the same time.
Note: To minimize the time required, run the migration scripts from the same data center as the
database server.

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=

Note: If pega.target.data.schema is blank, the rules schema is used by default.

Pega Platform Upgrade Guide | 61

Appendices

3. Configure the target 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
pega.target.data.schema=existing data schema

4. Configure the bulkmover directory:

pega.bulkmover.directory=full path to output directory
5. Configure a temporary directory:
pega.migrate.temp.directory=full path to temporary directory
6. If the system has access to both the original and temporary databases, configure the operations to be
performed by the utility as shown below:

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

7. Save the properties file.

8. Open a command prompt, and navigate to the scripts directory.
9. Type migrate.bat or ./migrate.sh to run the script.

Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory.

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

62 | Pega Platform Upgrade Guide

 Appendices

pega.source.jdbc.password=password
pega.source.rules.schema=temporary rules schema
pega.source.data.schema=

Note: If pega.target.data.schema is blank, the rules schema is used by default.

c. Configure the bulkmover directory:

pega.bulkmover.directory=full path to output directory
d. Configure a temporary directory:
pega.migrate.temp.directory=full path to temporary directory
e. Configure the operations to be performed by the utility as shown below:

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

f. Save the properties file.

g. Open a command prompt, and navigate to the scripts directory.
h. Type migrate.bat or ./migrate.sh to export the rules.
2. On a system that can access the temporary database, import the rules to the temporary database.
a. Copy the migrateSystem.properties file you created in step 1 to a system that can access the
temporary database.
b. Verify the target, bulkmover, and temporary directory properties. Configure the target properties:

pega.target.rules.schema=new rules schema

pega.target.data.schema=existing data schema

c. Configure the operations to be performed by the utility as shown below:

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

d. Save the properties file.

e. Open a command prompt, and navigate to the scripts directory.
f. Type migrate.bat or ./migrate.sh to import the rules.

Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory.

Importing applications and other rule changes for highly available

systems
If you plan to import applications or other rule changes in a high available system, doing so during an out-
of-place upgrade rather than after the upgrade improves performance.

Pega Platform Upgrade Guide | 63

Appendices

1. Open the prpcUtils.properties file in the Pega_HOME\scripts\utils directory.

2. Configure the following property:
import.oop.upgrade=true
3. Save and close the file.
4. Import the application or other rule change. For more information about using the prpcUtils script, see
Using scripting with direct connection to the database and the prpcUtils tool.

Upgrading the data schema

Run the script to upgrade the data schema.

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

2. Shut down the application server and ensure that no other processes are using the data schema.
3. Open a command prompt, and navigate to the scripts directory.
4. Run upgrade.bat (for Windows) or ./upgrade.sh (for Linux), passing in the --dataOnly argument
and true parameter, for example:
upgrade.bat --dataOnly true

Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory.

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.

Optional: Manually installing user-defined functions

(UDFs) if you did not opt to automatically install UDFs
The user-defined functions (UDFs) enable the Pega Platform to read data directly from the BLOB without
creating and exposing columns. Skip this section if you installed the UDFs when you deployed Pega
Platform.
There are several ways you might have bypassed generating and installing the UDFs when you deployed:

64 | Pega Platform Upgrade Guide

 Appendices

• Setting either bypass.pega.schema=true or bypass.udf.generation=true in the

setupDatabase.properties file
• Setting pega.target.bypass.udf=true in the migrateSystem.properties file
• Selecting Bypass Automatic DDL Application from the Installation and Upgrade Assistant
Before you install the UDFs, verify that you have the appropriate user permissions.
For more information about user permissions, see your Pega Platform installation guide.

1. Edit the setupDatabase.properties file.

a. Configure the connection properties.

# 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

b. Save and close the file.

2. On the rules schema, run the following commands to remove any partially installed UDFs:

DROP FUNCTION rules-schema-name.pr_read_from_stream;

DROP FUNCTION rules-schema-name.pr_read_decimal_from_stream;
DROP FUNCTION rules-schema-name.pr_read_int_from_stream;

3. Optional: If you have a split-schema, on the data schema run the following commands::

DROP FUNCTION data-schema-name.pr_read_from_stream;

DROP FUNCTION data-schema-name.pr_read_decimal_from_stream;
DROP FUNCTION data-schema-name.pr_read_int_from_stream;

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 postgres

Switching to Hazelcast embedded mode from Apache

Ignite client-server mode
If you were using Apache Ignite in client-server mode, you must switch to Hazelcast in embedded mode
because Apache Ignite is no longer supported. You can switch back to embedded mode from client-server
mode during a rolling restart.
Perform a rolling restart to keep your system always available during the upgrade. You remove nodes
from the load balancer, shut them down, upgrade, and start them again one by one. You do not add them
back to the load balancer until you have upgraded half of the nodes.
To perform a rolling restart, complete the following steps.

1. Prepare the database.

Pega Platform Upgrade Guide | 65

Appendices

a. Disable rule saving. For more information, see Disabling rule creation on the rules schema.
b. Migrate the PegaRULES schema to a temporary schema. For more information, see Migrating the
existing rules schema.
c. Upgrade the new rules schema, for example, a framework or application upgrade. For more
information, see Upgrading the migrated rules schema.
d. Copy the new rule schema to the production database. For more information, see Migrating to the
new rules schema.
2. Upgrade half of the nodes one by one.
a. Configure the load balancer to disable a node.
• Disabling the node does not allow new connections, but it allows existing users and services to
complete work.
• Quiescing a Pega Platform node that has not been disabled in the load balancer results in error
conditions for users of that Pega Platform node, because new users cannot log in. The Pega
Platform must be disabled in the load balancer so that new users are redirected to another
active Pega Platform node.
b. Quiesce the Pega Platform node, by using the Autonomic Event Services (AES) or high availability
landing pages. For more information, see Cluster management.
c. Ensure that all requestors are passivated and the system run state is set to "Quiesce Complete", by
using the HA Cluster Management landing page.
d. Shut down the node.
e. Upgrade the data source to connect to the upgraded schema (to reflect changes made in step 1).
For more information, see Upgrading the data schema.
f. To switch back to embedded mode from client-server mode, modify the prconfig.xml file and
remove the following settings that were added during the switch to client-server mode.

<env name="cluster/clientserver/clientmode" value="true " />

<env name="identification/cluster/protocol" value="ignite " />

g. Start the node.

3. Perform any needed post-upgrade activities and tests. For more information, see Post-upgrade
configuration.
4. After you upgrade half of the nodes, disable the remaining non-upgraded nodes in the load balancer.
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.

66 | Pega Platform Upgrade Guide

 Appendices

Reversing an out-of-place upgrade

You can revert to a previous release after upgrading performing an out-of-place upgrade with minimal
downtime.
Reversing an upgrade requires the original (pre-update) rules schema, which is available only if you
perform an out-of-place upgrade.

Limitations
You can reverse upgrades in many situations, but there are limitations.
Reversing an upgrade is not supported for:
• In-place upgrades
• Single-schema systems
• Multitenancy systems
• Multi-hop upgrades, for example:
◦ You can:
1. Upgrade from Pega 7.2 to 8.5.
2. Reverse the upgrade to return Pega 7.2.
◦ You cannot:
1. Upgrade from Pega 7.2 to 7.4 (first hop).
2. Upgrade again from Pega 7.4 to 8.5 (second hop).
3. Reverse the upgrade back to Pega 7.2.

Upgrade reversal details

To reverse an upgrade, run the reverse.bat (for Windows) or reverse.sh (for Linux) script on the pre-
upgrade rules schema to revert the changes to the data schema.
Upgrading the data schema creates a Reverse_ timestamp.xml file. The reverse.bat (for Windows) or
reverse.sh (for Linux) script uses the Reverse_ timestamp.xml file to re-create the data schema. If you
upgrade your system more than once, there might be multiple versions of the Reverse_ timestamp.xml
file. The setupDatabase.properties file specifies the correct Reverse_ timestamp.xml file.
The reverse process restores database functions, procedures, and views in the data schema. New or
altered columns, constraints, indexes, and tables are left intact. The process creates the CLI-Reverse-
Log- timestamp.log file in the scripts/logs directory.
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.

Object Type How created Added or Modified Status after Reversal

Tables, Columns, -- -- Ignored

Indexes

Procedures and Views Pega Platform shipped Added Dropped

Pega Platform Upgrade Guide | 67

Appendices

Object Type How created Added or Modified Status after Reversal

-- Pega Platform shipped Modified Restored

Functions Pega Platform shipped Added Dropped

-- Pega Platform shipped Modified Restored

-- Manually Added Ignored

-- Manually Modified Ignored

Data instances Pega Platform shipped Added Deleted

-- Pega Platform shipped Modified Restored

-- Manually Added Ignored

-- Manually Modified Ignored

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. 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 create and drop statements.
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.

68 | Pega Platform Upgrade Guide

 Appendices

5. Reconfigure the application server:

a. Restart the application server.
b. Verify that the prweb application is configured to use the correct rules and data schema names.
c. Deploy the prweb application.
6. To verify that the reversal was successful, check the version of Pega Platform on the log-in screen.

Troubleshoot upgrade errors

Use the information in this section to troubleshoot upgrade errors.
Error logs are displayed in the Installation and Upgrade Assistant window and are also Error logs are
stored in the Pega-image\scripts\logs directory.

Resuming or restarting after a failed deployment

If the deployment fails, you can opt to either resume or start over:
• Resume — The system uses the previously-entered configuration information to resume a failed
deployment from the last successful step. This is the default behavior.
• Start Over — The system discards all previously-entered configuration information, drops the
database schema, and starts the deployment from the beginning.

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.
• To start over, set automatic.resume=false.
4. Repeat the deployment. Use the same procedure that you used for the initial deployment.

Removing duplicated rules if rules schema objects were not applied

correctly
If the rules schema objects were not applied successfully, run the migration recovery scripts to remove
duplicate rules.
The migration recovery scripts remove duplicate rules created as a result of a faulty split schema
migration, where indexes and primary keys were not created on rules tables. To check for this issue, see if
your rules tables, such as pr4_base and pr4_rule, are missing primary key indexes.

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.

Pega Platform Upgrade Guide | 69

Appendices

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.

PEGA0055 alert — clocks not synchronized between nodes

The Pega Platform validates time synchronization to ensure proper operations and displays a PEGA0055
alert if clocks are not synchronized between nodes.
For information about how to reference a common time standard, see the documentation for your
operating system.

Upgrading from Pega Platform version 6.3 SP1 or

earlier: Starting from a single-schema configuration
If you are upgrading from Pega Platform version 6.3 SP1 or earlier, use this section to upgrade your
system, which starts with a single schema. Pega Platform now requires separate schemas for rules and
data.

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.

Schemas used depends on the number of databases

Upgrading with one database Upgrading with two databases

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

70 | Pega Platform Upgrade Guide

 Appendices

Upgrading with one database Upgrading with two databases

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.

1. Create two or three schemas as directed,

Number of databases system can access Upgrade 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. If you are upgrading with access to two databases, migrate and generate the rules schema objects. For
details, see Migrating to the new rules schema.
5. Upgrade the data schema. See Upgrading the data schema.

Pega Platform Upgrade Guide | 71

Appendices

6. To review the upgrade log files, see Reviewing log files.

72 | Pega Platform Upgrade Guide