PeopleSoft Integration Broker: The Complete Guide to Seamless Enterprise Integration

If you work with Oracle PeopleSoft, you’ve almost certainly encountered the need to connect your PeopleSoft environment with other enterprise systems — whether that’s Salesforce, Workday, SAP, or a homegrown application. PeopleSoft Integration Broker (IB) is the built-in middleware framework that makes this possible, and understanding it deeply can save your team weeks of rework and failed deployments.

This guide covers everything from the foundational architecture to advanced configuration patterns, written for PeopleSoft administrators, developers, and enterprise architects who need a reliable, production-grade reference.

What Is PeopleSoft Integration Broker?

PeopleSoft Integration Broker is an enterprise service bus (ESB) and messaging framework built directly into the PeopleTools platform. It enables PeopleSoft applications to communicate with external systems, third-party applications, and other PeopleSoft environments using industry-standard protocols including SOAP, REST, HTTP, and JMS.

Unlike external middleware solutions that sit between systems, Integration Broker is embedded within PeopleTools — meaning it shares the same security model, monitoring infrastructure, and development environment as the rest of your PeopleSoft application. This tight integration reduces operational complexity significantly.

Why Integration Broker Matters in 2024

Modern enterprises are running hybrid technology ecosystems. PeopleSoft-powered HR, Finance, or Campus Solutions systems must exchange data with cloud platforms, analytics tools, and partner systems in near-real time. Integration Broker is the primary mechanism Oracle supports for this — and it continues to evolve with REST-native capabilities added in recent PeopleTools releases (8.57+).

Core Architecture Explained

Integration Broker consists of several interconnected components that work together to route, transform, and deliver messages between systems. Understanding the architecture is essential before attempting any configuration.

The Integration Gateway

The Integration Gateway is a Java-based web application (deployed on a J2EE server like WebLogic or WebSphere) that acts as the entry and exit point for all messages. It handles protocol translation — converting incoming HTTP/SOAP/REST requests into the internal format that the Integration Engine understands, and vice versa for outbound messages.

The Integration Engine

The Integration Engine runs within the PeopleSoft application server domain and is responsible for processing messages according to the business rules you configure. It performs message routing, applies transformation logic (using XSLT or PeopleCode), enforces security, and manages queuing behavior.

Message Channels and Queues

Messages in Integration Broker are organized into channels (logical groupings) and processed through queues (which enforce ordering and concurrency rules). This two-tier organization gives you fine-grained control over throughput and ensures message ordering is maintained where required.

Key Components Deep Dive

Synchronous vs. Asynchronous Integration

One of the most important design decisions when implementing Integration Broker is choosing between synchronous and asynchronous patterns. The right choice depends on your use case’s requirements for real-time response, reliability, and throughput.

Synchronous (Request/Reply)

In synchronous mode, the calling system sends a request and waits for an immediate response before proceeding. This is ideal for scenarios where the caller needs data returned instantly — such as real-time payroll calculations, address validation, or balance inquiries.

Asynchronous (Fire-and-Forget / Publish-Subscribe)

Asynchronous integration decouples the sending and receiving systems. The sender publishes a message to a queue and moves on immediately — the receiving system processes the message independently. This pattern provides higher throughput, better fault tolerance, and natural buffering during peak loads.

Service Operations: The Building Blocks

Service Operations are the atomic unit of integration in PeopleSoft Integration Broker. Every integration you build — whether consuming an external API or exposing PeopleSoft functionality to another system — is implemented as one or more Service Operations.

Operation Types

• Asynchronous One-Way: Publishes a message with no reply expected. Used for outbound notifications and data pushes.
• Asynchronous Request/Response: Sends a message and eventually receives a callback. Both sides are decoupled.
• Synchronous: Blocking request that returns a response message. Similar to a web service call.
• REST-based: (PeopleTools 8.54+) Maps HTTP verbs (GET, POST, PUT, DELETE) to PeopleCode handlers for RESTful API design.

Creating a Handler with PeopleCode

Handlers are where your business logic lives. Below is a simplified example of an Application Class handler for an inbound asynchronous service operation:

import PS_PT:Integration:INotificationHandler;

class EmployeeDataHandler implements PS_PT:Integration:INotificationHandler
   method OnNotify(&MSG As Message);
end-class;

method OnNotify
   /+ &MSG as Message +/
   /+ Extends/implements PS_PT:Integration:INotificationHandler.OnNotify +/
   
   Local XmlDoc &xmlDoc;
   Local XmlNode &rootNode, &empNode;
   Local string &empId, &firstName, &lastName;
   
   /* Get the message XML */
   &xmlDoc = &MSG.GetXmlDoc();
   &rootNode = &xmlDoc.DocumentElement;
   
   /* Extract employee data */
   &empNode = &rootNode.FindNode("//EMPLOYEE_DATA");
   &empId    = &empNode.FindNode("EMPLID").NodeValue;
   &firstName = &empNode.FindNode("FIRST_NAME").NodeValue;
   &lastName  = &empNode.FindNode("LAST_NAME").NodeValue;
   
   /* Process the data — e.g., update a staging table */
   Local SQL &sql = CreateSQL(
      "INSERT INTO PS_INTG_STAGING (EMPLID, FIRST_NM, LAST_NM, PROCESS_DTTM) " |
      "VALUES (:1, :2, :3, %CurrentDateTimeIn)", 
      &empId, &firstName, &lastName);
   
end-method;

Setting Up Integration Broker Step by Step

Getting Integration Broker working end-to-end requires configuration at several layers. Here’s the sequence that ensures a clean setup:

Step 1: Configure the Integration Gateway

Navigate to PeopleTools > Integration Broker > Configuration > Gateways. Set the Local Gateway URL to your IB gateway servlet (typically http://<host>:<port>/PSIGW/PeopleSoftListeningConnector). Click “Load Gateway Connectors” to populate the available connector list, then ping the gateway to confirm connectivity.

Step 2: Activate the Local Node

Go to PeopleTools > Integration Broker > Integration Setup > Nodes and confirm your local node (typically named after your database) is set as the Default Local Node. Verify the Authentication Token Domain matches your environment’s domain for SSO.

Step 3: Define Remote Nodes

For every external system you’ll communicate with, create a Node definition. Set the Node Type to “External” for non-PeopleSoft systems, provide the connector information (usually the HTTP Listening Connector with the target URL), and configure authentication credentials.

Step 4: Create Message Definitions

Design your message schema under PeopleTools > Integration Broker > Integration Setup > Messages. Choose between rowset-based messages (auto-generated from PeopleSoft records) or non-rowset XML messages for more flexible schema design.

Step 5: Build the Service and Service Operation

Create a Service as a container, then add your Service Operations defining the operation type, associated request/response messages, and version. Activate the operation and configure the routing to map it to the appropriate node.

Step 6: Implement and Register the Handler

Write your Application Class handler and register it under the Service Operation’s Handlers tab. Set the handler type (OnRequest, OnNotify, etc.) and specify the class path.

Step 7: Test with Service Operation Tester

Use PeopleTools > Integration Broker > Service Utilities > Service Operation Tester to send test messages and validate the end-to-end flow before going to production.

Error Handling & Monitoring

Robust error handling separates a production-ready integration from a prototype. Integration Broker provides several layers of error management that you should understand and configure before go-live.

Asynchronous Error Queues

Failed asynchronous messages land in the error queue and can be monitored through PeopleTools > Integration Broker > Monitor > Asynchronous Services. The monitor shows message status (New, Started, Done, Error, Cancelled) and allows you to inspect message content and retry failed operations individually or in bulk.

Synchronous Error Responses

For synchronous operations, errors are returned in the response message. Your handler should set appropriate fault codes and messages using the IBFaultInfo class so calling systems receive meaningful error information rather than generic HTTP 500 responses.

Integration Gateway Logs

The gateway maintains detailed request/response logs at <PS_HOME>/webserv/<domain>/applications/peoplesoft/PSIGW.war/WEB-INF/logs/. Enable Message Logging in the gateway properties for non-production environments to capture full message payloads for debugging — but disable it in production to avoid performance overhead and log volume issues.

Dead Letter Handling Strategy

Define a clear operational procedure for messages that fail after maximum retry attempts. Options include automated routing to a dead-letter queue with email/ticketing notification, or periodic batch reprocessing jobs that pick up failed messages after root-cause remediation.

Best Practices & Performance Tips

Message Design

• Keep messages lean. Send only the fields required by the consuming system — avoid bulk message schemas that include every field from a PeopleSoft record.
• Version your messages from day one. Adding a version suffix (e.g., EMPLOYEE_SYNC_V2) makes backward-compatible evolution much easier.
• Use non-rowset messages for external system integration. Rowset-based messages are convenient for PeopleSoft-to-PeopleSoft communication but create tight coupling with internal record structures.

Channel & Queue Configuration

• Assign dedicated channels to high-volume integrations rather than using the default channel — this prevents one busy integration from starving others.
• Configure sequential ordering only where required. Unordered channels process messages in parallel (multiple queue workers) and are significantly faster.
• Set appropriate max-retry counts and retry intervals per queue. A transient network error might resolve in 60 seconds; a schema validation error will never self-heal.

Security

• Always use SSL/TLS for all external-facing gateway connections — never HTTP in production.
• Use WS-Security or OAuth tokens for service authentication rather than basic auth where possible.
• Restrict service operation access with permission lists and ensure the service operation is only accessible to the intended integration user IDs.

Performance

• For very high-throughput scenarios, deploy a dedicated Integration Broker application server domain separate from your interactive users’ domain.
• Monitor the Publication Contractor and Subscription Contractor processes in Process Monitor — these are the worker processes that drive async throughput and may need tuning.
• Use chunking for large data synchronizations rather than sending single massive messages — 500–1,000 record chunks are typically optimal.

Real-World Use Cases

HR Data Synchronization to Active Directory / Workday

A common pattern uses an asynchronous publish operation triggered by Component Interface save events. When an employee record is saved in HCM, a message is published containing the changed fields. A subscriber at the receiving system (Workday, AD, or an LDAP connector) processes the update asynchronously, typically within seconds.

Real-Time Payroll Tax Calculation

A synchronous service operation calls an external tax engine API mid-payroll calculation. The calling PeopleCode sends the employee’s earnings data, receives tax breakdown in the response, and applies the results — all within the same transaction.

Finance System Integration (ERP-to-ERP)

PeopleSoft Financials publishing journal entries or vouchers to an external general ledger. The integration uses asynchronous messaging with guaranteed delivery and sequential ordering within the GL channel to ensure entries are posted in the correct order.

REST API Exposure for Campus Mobile Apps

PeopleSoft Campus Solutions exposing student schedule, grades, and registration data via REST service operations that mobile applications consume directly — a growing pattern enabled by PeopleTools 8.57+ REST improvements.

Frequently Asked Questions