+91-7678211866 info@peppertechsolutions.com
+91-7678211866 info@peppertechsolutions.com
A deep-dive reference for PeopleSoft administrators — every Tuxedo server process in the Application Server domain, its exact role, tuning levers, and how to troubleshoot it when things go wrong.
If you've ever run psadmin and looked at the list of server processes for an Application Server domain, you've probably seen names like PSAPPSRV, PSQCKSRV, PSQRYSRV, PSSAMSRV, and a handful of others — and wondered exactly what each one does and whether you need them all.
This article answers that question comprehensively. We'll go process by process, explaining the purpose of each, when it fires, what happens if it goes down, and how to configure it correctly for your environment. This is the reference guide every PeopleSoft admin needs bookmarked.
The PeopleSoft Application Server is the middle tier in PeopleSoft's three-tier architecture. It sits between the web server (PIA on WebLogic) and the database (Oracle, SQL Server, or DB2), and it is responsible for all business logic execution.
When a user navigates a PeopleSoft page, submits a form, or runs a query, the request travels from the browser → WebLogic PIA → Application Server → Database, and the response travels back the same chain. The Application Server executes PeopleCode, enforces security, manages sessions, handles caching, and translates user actions into SQL that hits the database.
Figure 1: Request flow through the PeopleSoft three-tier architecture
Oracle Tuxedo (formerly BEA Tuxedo) is the transaction-processing middleware that runs the Application Server. It acts as a process manager, message router, and load balancer for all the server processes defined in your domain.
Every Application Server domain is defined by a configuration file — psappsrv.cfg — which Tuxedo reads at boot time to know which processes to start, how many instances of each to run, and what service queue each process listens on. Tuxedo also monitors each process and can automatically restart it if it crashes.
The BBL (Bulletin Board Liaison) is Tuxedo's master process. It maintains the in-memory bulletin board — a shared data structure that tracks all registered services, available server processes, and their load. Every other Tuxedo server process registers with the BBL at startup. If the BBL dies, the entire domain goes down. It is automatically restarted by the Tuxedo monitor daemon.
In multi-node Tuxedo configurations (MP mode), the PBBR bridges bulletin boards across machines. In single-node SHM (Shared Memory) mode — which most PeopleSoft environments use — PBBR is not active.
PSAPPSRV is the workhorse of the entire Application Server domain. It is responsible for processing the vast majority of user-initiated requests that involve PeopleCode execution — opening pages, saving records, performing component-level business logic, and interacting with the database.
When a user opens a PeopleSoft component (a page), the PIA sends a request via JOLT to a PSAPPSRV process. PSAPPSRV loads the component definition from its cache (or the database if not cached), executes any relevant PeopleCode events (RowInit, SearchInit, FieldChange, SavePreChange, etc.), fetches the required data rows via SQL, and returns the rendered page data to PIA.
Because PSAPPSRV handles complex, multi-step operations that can involve many PeopleCode events and multiple database round-trips, it is typically configured with more instances than other server processes. Each instance handles one request at a time — there is no threading within a single PSAPPSRV process.
[PSAPPSRV]
;=======================================================
; Min Instances= Minimum server processes to start
; Max Instances= Maximum server processes (scale up)
; Service Timeout= Seconds before a hung request is killed
; Recycle Count= Requests before process auto-restarts (memory mgmt)
; Allowed Consec Service Failures= Before process is taken down
;=======================================================
Min Instances=3
Max Instances=7
Service Timeout=300
Recycle Count=5000
Allowed Consec Service Failures=2Recycle Count to 5,000–10,000 to automatically recycle processes and prevent memory bloat over time. If users are reporting slow page loads, check whether PSAPPSRV processes are near their max instances — you may need to increase Max Instances.
PSQCKSRV exists to handle a specific class of lightweight requests — primarily search operations, prompt lookups, and auto-complete field fills — that would otherwise compete for the same queue as heavier PSAPPSRV requests.
Without PSQCKSRV, a quick prompt lookup (e.g., looking up a list of departments as a user fills in a field) would sit in the same queue as a complex payroll page save. PSQCKSRV provides a dedicated fast lane for these low-cost operations, keeping the user experience responsive even when PSAPPSRV is under load.
PSQCKSRV executes PeopleCode but is optimised for short-duration requests. It has its own Tuxedo service queue separate from PSAPPSRV, so lightweight requests are never stuck behind heavy ones.
PSQRYSRV handles all requests coming from PeopleSoft Query Manager — the ad-hoc reporting tool built into PIA. When a user runs a PS Query (either interactively or via a scheduled process), the request routes to PSQRYSRV rather than PSAPPSRV.
This separation is critical for performance. PS Query requests are often long-running and can return large result sets. By isolating them to PSQRYSRV, Oracle ensures that a user running a report with hundreds of thousands of rows cannot starve out users doing interactive page work on PSAPPSRV.
PSQRYSRV also handles Connected Queries — a feature introduced in PeopleTools 8.51 that allows multiple related queries to be run together and joined at the application layer. These are even more resource-intensive, making the isolation benefit of PSQRYSRV even more significant.
PSSAMSRV is the Application Server's security authority. It is responsible for validating user authentication tokens, resolving permission lists, and caching security data so that every other server process doesn't need to make individual database calls to check permissions.
When a user first logs into PeopleSoft, PSSAMSRV validates their credentials (or the SSO token from the web server), retrieves their roles and permission lists from the database, and caches this security context. Subsequent requests from that user reference the cached security data in PSSAMSRV rather than hitting the database again — significantly improving performance at scale.
PSSAMSRV also handles Signon PeopleCode — any custom authentication logic that fires at login is executed here. If your organisation has custom authentication events (e.g., LDAP lookups, conditional access rules), they run through PSSAMSRV.
PSANALYTICSRV was introduced to support PeopleSoft's Pivot Grid framework — the embedded charting and analytics capability available from PeopleTools 8.52 onwards. When a user opens a page that contains a Pivot Grid or accesses the Pivot Grid Wizard, the rendering and data-aggregation work is handled by PSANALYTICSRV.
This process performs the analytics-layer processing — aggregating data across dimensions, computing totals, and preparing chart data — before returning it to PIA for rendering. Like PSQRYSRV, isolating this work prevents analytics-heavy operations from impacting interactive page performance.
If your PeopleSoft implementation does not use Pivot Grids or embedded analytics, PSANALYTICSRV can be disabled to free system resources. However, on deployments using PeopleSoft Insights or fluid analytics dashboards, it is essential.
PSBRKHND is the Application Server-side entry point for Integration Broker synchronous messages. When the Integration Gateway receives an inbound SOAP or REST request from an external system, it passes the message to PSBRKHND via JOLT. PSBRKHND then routes the message to the appropriate service operation handler for processing.
For synchronous service operations (those that return an immediate response), PSBRKHND manages the request-response cycle — it dispatches the message, waits for the handler to execute, and returns the response back through the gateway to the calling system.
PSBRKHND works in conjunction with PSPUBHND and PSSUBHND (described below) to form the complete Integration Broker processing pipeline within the Application Server domain.
PSSUBHND processes inbound asynchronous Integration Broker messages — messages that external systems have published into the PeopleSoft integration queues and that PeopleSoft needs to consume and act on. These are the "subscriber" side of PeopleSoft's publish/subscribe integration model.
When an external system sends a data payload to PeopleSoft (for example, a third-party HR system pushing employee updates), the message lands in the Integration Broker queue. PSSUBHND picks up these queued messages and executes the registered subscription PeopleCode handler — which might update records, trigger workflows, or call other components.
PSSUBHND processes messages asynchronously, which means the external sender does not wait for processing to complete. This decoupling is what allows high-volume integrations to operate reliably without creating bottlenecks.
PSPUBHND is the outbound counterpart to PSSUBHND. It handles the dispatching of outbound asynchronous Integration Broker messages — messages that PeopleSoft has published and that need to be delivered to external systems.
When PeopleCode publishes a message (for example, when an employee record is saved and PeopleSoft needs to notify an external payroll system), PSPUBHND picks up the published message from the queue, applies any configured transforms, and dispatches it to the target node via the Integration Gateway.
PSPUBHND also handles retry logic for failed deliveries — if a target system is temporarily unavailable, PSPUBHND will attempt redelivery according to the configured retry schedule, ensuring messages are not lost during transient outages.
JOLT (Java Object Linking and Tuxedo) is the proprietary protocol that PIA uses to communicate with the Application Server. The JOLT Station Listener (JSL) is the Tuxedo process that listens on a configured TCP port for incoming JOLT connections from WebLogic.
When a new PIA connection arrives, JSL spawns or assigns a JOLT Station Handler (JSH) to manage that specific connection's lifecycle. JSH acts as the persistent connection manager for one WebLogic-to-Tuxedo session — multiplexing individual service requests within that connection to the appropriate Tuxedo server processes.
The JOLT Relay Adapter (JRAD) is used in multi-machine Tuxedo configurations to relay JOLT traffic between machines. In single-machine SHM deployments it is typically not required.
The JSL port (default 9000) must be open between the WebLogic server and the Application Server host — this is one of the most common firewall-related issues when setting up a new PeopleSoft environment.
The Workstation Listener (WSL) and Workstation Handler (WSH) handle direct TCP connections from PeopleSoft two-tier client tools — primarily Application Designer, Data Mover, and Configuration Manager when running in two-tier mode (connecting directly to the App Server rather than through PIA).
In modern PeopleSoft environments, most user interaction is browser-based and goes through PIA. However, PeopleSoft administrators and developers regularly use Application Designer in two-tier mode for development, configuration, and patching work — and this is what WSL/WSH supports.
WSL listens on a configurable port (default 7000) for incoming tool connections. Each connection is assigned to a WSH instance for the duration of the session. Like JSL/JSH, WSL manages connection multiplexing and WSH manages individual sessions.
| Process | Full Name | Primary Function | Typical Instances | Critical? |
|---|---|---|---|---|
BBL |
Bulletin Board Liaison | Tuxedo master process; service registry & domain health | 1 (always) | 🔴 Yes |
PSAPPSRV |
App Server | PeopleCode execution, interactive page processing | 3–10 | 🔴 Yes |
PSQCKSRV |
Quick Server | Prompt lookups, search dialogs, lightweight reads | 2–4 | 🟡 High |
PSQRYSRV |
Query Server | PS Query Manager & Connected Queries | 2–3 | 🟡 High |
PSSAMSRV |
Security Access Manager | Authentication, permission lists, security cache | 1–2 | 🔴 Yes |
PSANALYTICSRV |
Analytics Server | Pivot Grids, embedded analytics dashboards | 1–2 | 🟢 Optional |
PSBRKHND |
Broker Handler | Synchronous Integration Broker message routing | 1–3 | 🟡 If using IB |
PSSUBHND |
Subscription Handler | Inbound async IB messages & subscription handlers | 1–3 | 🟡 If using IB |
PSPUBHND |
Publication Handler | Outbound async IB message dispatch & retry | 1–3 | 🟡 If using IB |
JSL / JSH |
JOLT Station Listener/Handler | PIA → App Server TCP communication via JOLT | 1 JSL / N JSH | 🔴 Yes |
WSL / WSH |
Workstation Listener/Handler | Two-tier tool connections (App Designer, Data Mover) | 1 WSL / N WSH | 🟡 For dev/admin |
All App Server process settings live in psappsrv.cfg, located in $PS_CFG_HOME/appserv/<domain>/. Here are the most important parameters every admin should know:
; ── Database Connection ──────────────────────────────────
[Database Options]
DBName=HRPRD
DBType=ORACLE
UserId=PS
UserPswd={encrypted}
ConnectId=people
ConnectPswd={encrypted}
ServerName=
; ── Cache Settings ───────────────────────────────────────
[Cache Settings]
CacheBaseDir=/u01/ps/cfg/appserv/HRPRD/CACHE
EnableServerCache=1
CacheDir=0
; ── Trace / Debugging ────────────────────────────────────
[Trace]
TraceFile=/u01/ps/cfg/appserv/HRPRD/LOGS/appsrv_%SERVER%.tracesql
TraceSQL=0 ; Set to 15 to trace SQL (dev only — never in prod)
TracePC=0 ; Set to 4076 to trace PeopleCode (dev only)
; ── PSAPPSRV ─────────────────────────────────────────────
[PSAPPSRV]
Min Instances=3
Max Instances=7
Service Timeout=300
Recycle Count=10000
Allowed Consec Service Failures=2
; ── PSQCKSRV ─────────────────────────────────────────────
[PSQCKSRV]
Min Instances=2
Max Instances=4
Service Timeout=90
Recycle Count=10000
; ── PSQRYSRV ─────────────────────────────────────────────
[PSQRYSRV]
Min Instances=2
Max Instances=3
Service Timeout=600
Recycle Count=10000
; ── JOLT ─────────────────────────────────────────────────
[JOLT Listener]
Port=9000
Min Handlers=3
Max Handlers=10
Min Connections=3
Max Connections=50A common rule of thumb is to start with 1 PSAPPSRV instance per 40–60 concurrent users and adjust based on monitoring. Use the PSADMIN "Server Status" menu or Tuxedo's tmadmin utility to watch queue depth — if requests are consistently waiting in the PSAPPSRV queue, increase Max Instances.
Each PSAPPSRV process consumes roughly 200–500 MB of RAM depending on your application's cache footprint. Size your App Server host with enough physical memory to accommodate all processes across all domains (including Process Scheduler) with headroom to spare. Swapping is fatal to App Server performance.
Setting a Recycle Count (e.g., 10,000 requests) causes processes to restart themselves periodically, which prevents memory fragmentation from accumulating over days or weeks of uptime. This is a lightweight operation — Tuxedo starts a replacement process before killing the recycled one, so there is no user-visible interruption.
The Service Timeout is the maximum number of seconds Tuxedo allows a single request to run before killing it. For PSAPPSRV, 300 seconds is the default and usually appropriate. For PSQRYSRV, you may want to extend this (e.g., 600–900 seconds) to accommodate long-running queries without premature timeout.
Check APPSRV_MMDD.LOG in the domain logs directory. The most common causes are incorrect database credentials in psappsrv.cfg, a missing or stale PID file, or a port conflict (another process already using the JSL or WSL port).
If PSAPPSRV processes are restarting frequently, look for Allowed Consec Service Failures being hit. This typically means a specific PeopleCode operation is throwing an unhandled exception and crashing the process. Enable TracePC temporarily in a non-production environment to identify the failing code path.
Use psadmin > 4 (Server Status) to see active vs. queued requests per process type. Sustained queue depth means you need more instances or your requests are running slower than expected. Profile slow SQL using TraceSQL=15 in dev to identify bottlenecks.
If users report permission changes not taking effect, flush the PSSAMSRV cache via psadmin > Purge Cache or bounce the PSSAMSRV process. This forces the security manager to reload all permission lists from the database on next request.
Check PSSUBHND and PSPUBHND process health first. Then review the IB Monitor at PeopleTools > Integration Broker > Monitor. Messages stuck in "Started" status usually indicate a handler crash — review the application server log for stack traces.
psadmin, select your domain, then choose option 4 (Server Status). This shows all configured processes, their current status (active/inactive), the number of running instances, and the current queue depth. You can also use Tuxedo's tmadmin tool directly for more detailed metrics.psadmin which handles the correct Tuxedo boot sequence. To stop cleanly, use the "Shutdown with timeout" option rather than killing processes manually — this allows in-flight requests to complete. Killing Tuxedo processes manually can corrupt the bulletin board and require a forced cleanup before the domain can restart.