PeopleSoft Web Server (PIA) Explained: Architecture, Servlets, Configuration & Administration

When a user logs into PeopleSoft, the first system they touch is the web server — specifically, the PeopleSoft Internet Architecture (PIA) running on Oracle WebLogic. Everything visible in the browser, every page render, every login, every navigation click — all of it flows through the PIA web tier before touching the Application Server or database.

Yet the web server is often the least understood component in a PeopleSoft stack. This article covers PIA from top to bottom — its architecture, the servlets it hosts, how WebLogic domain types affect your deployment, web profiles, key configuration files, SSL setup, and the administration tasks every PeopleSoft admin should know cold.

What Is PIA (PeopleSoft Internet Architecture)?

PeopleSoft Internet Architecture (PIA) is the web tier component of PeopleSoft’s three-tier architecture. It is a J2EE Enterprise Archive (.ear file) deployed on Oracle WebLogic Server, consisting of a collection of Java web applications (servlets) that collectively deliver the PeopleSoft browser-based user interface.

PIA’s job is to act as the intermediary between the user’s browser and the PeopleSoft Application Server. It receives HTTP/HTTPS requests from the browser, translates them into JOLT protocol calls to the Tuxedo Application Server, receives responses, and renders them as HTML pages back to the browser.

Web Server Architecture & Request Flow

Understanding how a request flows through the PIA web server is fundamental to troubleshooting performance issues and errors.

Step-by-step request lifecycle:

1. User’s browser sends an HTTPS GET/POST request to the WebLogic server (e.g., https://pshost/psp/ps/EMPLOYEE/HRMS/c/HRS_HRAM.HRS_APP_SCHJOB.GBL)
2. WebLogic routes the request to the PORTAL servlet, which is the primary entry point for all PeopleSoft page requests
3. The PORTAL servlet validates the user’s session cookie and web profile settings
4. PORTAL packages the request and sends it over JOLT (port 9000) to the Application Server
5. The App Server executes PeopleCode, retrieves data from the database, and returns structured response data
6. PORTAL receives the response and renders it as HTML/JavaScript — the complete page sent back to the browser

Oracle WebLogic Server — The PIA Platform

Oracle WebLogic Server is the J2EE application server that hosts PIA. PeopleSoft has used WebLogic as its primary and only supported web server since PeopleTools 8.50+ (replacing the earlier support for BEA WebLogic, IBM WebSphere, and Oracle Application Server).

WebLogic provides the J2EE container that runs the PIA servlets, manages HTTP sessions, handles SSL/TLS termination, provides connection pooling, and delivers the WebLogic Administration Console (default port 7001) for domain management.

Key WebLogic Concepts for PeopleSoft Admins

WebLogic Domain Types: Single vs Multi-Server

During PIA setup you choose between two WebLogic domain configurations. This is one of the most important decisions in your PeopleSoft web server architecture.

PIA Servlets & Web Applications Explained

PIA is deployed as a J2EE Enterprise Archive and is made up of multiple web applications (servlets). Each servlet has a distinct role. Understanding which servlet handles which type of request is essential for troubleshooting and for correctly targeting deployments in a multi-server domain.

https://<server>/psp/<site>/<portal>/<node>/c/<menu>.<component>.GBL
# Example:
https://pshost/psp/ps/EMPLOYEE/HRMS/c/MANAGE_PAYROLL.PAY_CALC_RUNCTRL.GBL

Servlet Quick Reference

Web Profiles & configuration.properties

A Web Profile is a PeopleSoft configuration object (stored in the database) that controls the behaviour of the PORTAL servlet — things like session timeout, SSL enforcement, debug logging, caching, and authentication settings. Every PIA site has one active web profile.

The Four Default Web Profiles

configuration.properties

The configuration.properties file is the bridge between the web server and the web profile stored in the database. It tells the PORTAL servlet which web profile to load, the database connection credentials, and the PIA site name.

# Location:
# PS_CFG_HOME/webserv/<domain>/applications/peoplesoft/PORTAL.war/WEB-INF/psftdocs/<site>/configuration.properties

# Key settings:
WebProfile=PROD                   # Which web profile to use
UserId=PTWEBSERVER                 # Portal servlet user (minimal access)
UserPassword={encrypted}           # Encrypted password
AuthTokenDomain=.yourdomain.com    # SSO cookie domain
SiteAlias=ps                       # Site name in URL (/psp/ps/...)
AppServerURL=//appserver:9000      # JOLT connection to App Server

Directory Structure & Key Files

Knowing the PIA directory structure is essential for locating logs, configuration files, and output directories.

PS_CFG_HOME/webserv/<domain>/
├── bin/                         # startWebLogic.sh, stopWebLogic.sh
├── config/
│   └── config.xml               # WebLogic domain configuration (auto-generated)
├── applications/
│   └── peoplesoft/
│       ├── PORTAL.war/
│       │   └── WEB-INF/
│       │       └── psftdocs/
│       │           └── ps/      # Site configuration
│       │               └── configuration.properties   ← Key file
│       ├── PSIGW.war/
│       │   └── WEB-INF/
│       │       └── integrationGateway.properties      ← IB Gateway config
│       └── PSEMHUB.war/
├── logs/
│   ├── PIA.log                  # WebLogic server log
│   ├── access.log               # HTTP access log
│   └── PSIGW/                   # Integration Gateway logs
└── servers/
    ├── PIA/
    │   └── logs/
    │       └── PIA.out          # Managed server stdout log

SSL/TLS Configuration

All production PeopleSoft environments must use HTTPS. There are two approaches to SSL termination in a PeopleSoft web server deployment:

Key SSL Settings in Web Profile

After enabling SSL, update these settings in your Web Profile (PeopleTools → Web Profile → Web Profile Configuration):

• Encrypt All Communications — Forces all pages to use HTTPS, redirects HTTP to HTTPS
• Authentication Domain — Set to your domain (e.g., .yourdomain.com) for SSO cookie sharing
• Secure Cookies Only — Ensures session cookies are only sent over HTTPS connections

Day-to-Day Administration Tasks

Starting and Stopping the Web Server

# Via psadmin (recommended)
psadmin -w start -d peoplesoft
psadmin -w stop -d peoplesoft
psadmin -w status -d peoplesoft

# Directly via WebLogic scripts
cd $PS_CFG_HOME/webserv/peoplesoft/bin
./startWebLogic.sh          # Start Admin Server + managed servers
./stopWebLogic.sh           # Graceful stop

# Check status
ps -ef | grep weblogic      # Verify Java processes running

Adding a New PIA Site

A single WebLogic domain can host multiple PeopleSoft sites (e.g., one for HRMS, one for FSCM). Each site has its own configuration.properties file and can use a different web profile and database.

Add a site via: psadmin → PeopleSoft PIA → PIA Management → Install Additional PeopleSoft Site. The new site is accessible at /psp/<sitename>/.

Clearing PIA Cache

# Stop the web server first, then clear:
rm -rf $PS_CFG_HOME/webserv/peoplesoft/applications/peoplesoft/PORTAL.war/WEB-INF/psftdocs/<site>/cache/*

# Or use PIA Admin menu:
# PeopleTools → Web Profile → Web Profile Configuration
# → Clear Cache button (available in PROD profile)

Monitoring Active Sessions

Monitor active HTTP sessions via the WebLogic Admin Console (port 7001): Servers → PIA → Monitoring → General. This shows active requests, open HTTP sessions, JVM heap usage, and thread pool status. Session Monitoring is automatically enabled for WebLogic.

Performance Tuning & Best Practices

JVM Heap Sizing

The WebLogic JVM heap size is the most impactful performance parameter. Set it in $PS_CFG_HOME/webserv/peoplesoft/bin/setDomainEnv.sh:

# Recommended production heap settings:
MEM_ARGS="-Xms2048m -Xmx4096m"

# For high-concurrency environments:
MEM_ARGS="-Xms4096m -Xmx8192m -XX:+UseG1GC"

Thread Pool Configuration

WebLogic’s default thread pool handles all HTTP requests. For PeopleSoft production environments, configure the Work Manager thread count in the WebLogic Admin Console → Environments → Work Managers. Default is 25 threads; increase to 50–100 for large user populations.

Key Best Practices

• Always use the PROD web profile in production — DEV profile disables caching and significantly degrades performance
• Use a reverse proxy (Apache/nginx) in front of WebLogic — never expose WebLogic directly to the internet
• Enable WebLogic connection compression (gzip) to reduce page payload sizes
• Place the WebLogic server on a dedicated host separate from the Application Server to isolate resource contention
• Configure WebLogic Cluster with multiple managed PIA instances for horizontal scaling and failover
• Target PSIGW to a separate managed server from PORTAL to isolate integration traffic

Troubleshooting Common Issues

PIA Won’t Start — WebLogic Fails to Boot

Check servers/PIA/logs/PIA.out for Java exceptions. Common causes: port conflict (port 7001 or 8000 already in use), incorrect PS_HOME in environment variables, stale lock file under servers/PIA/data/, or Java heap out-of-memory error (increase JVM heap).

Login Fails — “Unable to Establish Initial Session”

This error means PIA cannot connect to the Application Server over JOLT. Check: Is the App Server domain running? Is the JOLT port (default 9000) accessible from the web server host? Verify the AppServerURL in configuration.properties is correct. Firewall rules between the web server and app server host are the most common cause.

Pages Loading Slowly After Login

Check the WebLogic thread pool utilisation in the Admin Console. If thread count is maxed out, WebLogic is queuing requests — increase the Work Manager thread pool. Also check if the web profile is set to DEV (caching disabled) — switch to PROD profile if so. Review PIA.log for “Stuck Thread” warnings which indicate requests taking longer than 10 minutes.

PSIGW Returning HTTP 500 for Integration Calls

Check the PSIGW gateway log at PSIGW.war/WEB-INF/logs/ for the specific error. Enable Gateway Logging in integrationGateway.properties temporarily. Verify the gateway URL is correctly set in PeopleTools → Integration Broker → Configuration → Gateways.

Frequently Asked Questions