PeopleTools Upgrade: The Complete Step-by-Step Guide (2024)

A PeopleTools upgrade is one of the most significant infrastructure tasks a PeopleSoft administrator will perform. Unlike an application patch — which updates business logic — a PeopleTools upgrade replaces the core technology layer that runs PeopleSoft: the web server components, application server binaries, Process Scheduler, Integration Broker engine, and the PeopleSoft Internet Architecture (PIA).

Done correctly, a PeopleTools upgrade is a structured, repeatable process. Done carelessly, it causes extended downtime, broken customizations, and failed integrations. This guide walks you through every phase — from initial planning to production cutover.

Why Upgrade PeopleTools?

PeopleTools upgrades are driven by several factors — Oracle’s support lifecycle, security compliance requirements, access to new features, and compatibility with modern infrastructure.

PeopleTools Version History & What’s New

Pre-Upgrade Planning & Assessment

A successful PeopleTools upgrade is 60% planning and 40% execution. Skipping the assessment phase is the most common reason upgrades fail or require extended rollback periods.

1. Review the Certification Matrix

Before anything else, check My Oracle Support (MOS) Doc ID 764222.1 — the PeopleTools Certification Matrix. This tells you which versions of Oracle DB, WebLogic, JDK, and OS are certified with your target PeopleTools release. Misaligned infrastructure is the most common cause of upgrade failures.

2. Run Change Impact Analyzer

Change Impact Analyzer (CIA) compares your current PeopleTools environment against the target version and identifies all customizations that will be impacted. Run CIA before finalising your upgrade timeline — it will surface any custom objects that need remediation after the upgrade. We cover CIA in detail in a dedicated section below.

3. Pre-Upgrade Checklist

Understanding DPKs (Deployment Packages)

Since PeopleTools 8.56, Oracle delivers PeopleTools releases and patches as Deployment Packages (DPKs) — automated installation bundles that replace the old manual component-by-component installation process. DPKs use Puppet for server components and Python scripts for client components.

Change Assistant — The Upgrade Engine

Change Assistant (CA) is Oracle’s lifecycle management tool that drives PeopleTools upgrades. It orchestrates the sequence of upgrade steps — running database scripts, applying Data Mover scripts, executing Application Engine programs, copying files — and tracks the status of each step so upgrades can be paused and resumed.

Change Assistant works with Update Manager to identify what needs to be applied and in what order. For a PeopleTools-only upgrade, CA uses a pre-built upgrade job template that walks you through every step required to take your environment from the source PT version to the target.

Configuring Change Assistant for an Upgrade

After installing the new PT client via DPK, configure Change Assistant before starting the upgrade:

1. Open Change Assistant → Tools → Options
2. Set PS_HOME to the new PeopleTools home directory
3. Set PS_APP_HOME if using separate app home
4. Configure database connection (DB name, type, server, credentials)
5. Set the Staging Directory — where CA will write working files
6. Configure Application Server and Process Scheduler connection details
7. Run a connection test and verify all components are reachable

Step-by-Step Upgrade Process

The following is the standard process for a PeopleTools-only upgrade (not an application upgrade) from PT 8.59 or 8.60 to PT 8.61 on an on-premises Linux environment.

# Extract the DPK
unzip LINUX_8.61.xx_DPK_INFRA.zip -d /opt/dpk_install
cd /opt/dpk_install

# Run bootstrap script (interactive)
sudo ./psft-dpk-setup.sh --env-type midtier \
  --deploy-only --deploy-type all \
  --psft-db-name HRPRD \
  --psft-db-type oracle

# Extract Client DPK to C:\tools_client
# Then run:
cd C:\tools_client
python psft-dpk-setup.py --install-type standalone

# Set new PS_HOME environment variable
export PS_HOME=/opt/oracle/psft/pt/ps_home8.61

# Recreate app server domain config
psadmin -c configure -d APPDOM

# Recreate Process Scheduler domain config  
psadmin -p configure -d PRCSDOM

# Recreate web server (PIA) domain
psadmin -w configure -d peoplesoft

Database Scripts & Data Conversion

The database script phase is the heart of a PeopleTools upgrade — and the point of no return. Once database scripts begin executing, a clean rollback requires restoring from the backup taken before the upgrade started.

Post-Upgrade Tasks & Validation

The upgrade is not complete when CA finishes its last step. Post-upgrade validation is essential before opening the system to users.

Post-Upgrade Checklist

Change Impact Analyzer

Change Impact Analyzer (CIA) is installed as part of the PeopleTools Client DPK. It scans your PeopleSoft environment and identifies all customized objects that are impacted by the PeopleTools upgrade — showing you exactly what will change before you commit to the upgrade.

Rollback Strategy

A rollback plan is not optional — it is a requirement for any production upgrade. The key principle is: the only reliable rollback from a PeopleTools upgrade is a full database restore. Database scripts make changes that cannot be easily reversed manually.

Troubleshooting Common Issues

DPK Bootstrap Script Fails

Check the Puppet log at /tmp/psft_dpk_setup.log and the Puppet report in /etc/puppet/psft/DPK_INSTALL/logs/. Common causes: insufficient disk space, missing OS packages (libstdc++, gcc), or SELinux policies blocking the installer. Verify prerequisites listed in the DPK release notes before running the script.

Change Assistant Step Fails

Click the failed step in CA → View Log to see the full error output. Most CA step failures are either database errors (check the AE/SQR log for SQL errors) or connectivity issues (CA cannot reach the App Server or database). Fix the root cause and restart just the failed step — you do not need to restart the entire job.

Domains Won’t Start After Upgrade

The most common cause is that psappsrv.cfg or psprcs.cfg was copied from the old version without updating the PS_HOME path. Verify the PS_HOME setting in your domain configs points to the new PT installation. Also check the Tuxedo log (TUXLOG.MMDD) for boot failures.

Pages Rendering Incorrectly After Upgrade

Clear all caches — App Server object cache, browser cache, and the PIA cache directories under PS_CFG_HOME/webserv/<domain>/applications/peoplesoft/PORTAL.war/. If specific pages are broken, check whether custom objects identified by CIA were properly remediated after the upgrade.

Frequently Asked Questions