PeopleTools 8.52: PeopleSoft Integration Broker

Understanding PeopleSoft Integration Broker

This chapter provides overview information about PeopleSoft Integration Broker and discusses:

Integration gateway architecture.
Integration engine architecture.
Services.
Inbound and outbound request flows.

Important! PeopleSoft Integration Broker interacts with a wide variety of third-party products. This PeopleBook is not an authoritative source of information about any third-party product. Most third-party products are delivered with their own documentation, which you should use as the primary source for information about them. This PeopleBook provides guidance that enables you to determine the configuration settings that PeopleSoft Integration Broker requires to work with third-party products. It does not address all configuration permutations. Examples of settings and data relative to a third-party product may not be correct for your particular situation. To properly configure PeopleSoft Integration Broker, you must apply your own expertise and obtain the most accurate and current information about third-party products.

Introduction to PeopleSoft Integration Broker

PeopleSoft Integration Broker is a middleware technology that:

Performs asynchronous and synchronous messaging among internal systems and third-party systems.
Exposes PeopleSoft business logic as web services to PeopleSoft and third-party systems.
Consumes and invokes web services from third-party and PeopleSoft systems.

PeopleSoft Integration Broker enables you to perform these integrations among internal systems and third-party integration partners, while managing data structure, data format and transport disparities. Because of its modular design, you can reuse many elements that you develop for integrations.

PeopleSoft Integration Broker consists of two subsystems: the integration gateway and the integration engine. The integration gateway resides on a PeopleSoft web server, and the integration engine is installed on an application server as part of the PeopleSoft application.

Web Services

PeopleSoft Integration Broker enables you to provide web services to other PeopleSoft systems and external integration partners by generating Web Services Description Language (WSDL) documents and Web Application Definition Language (WADL) document from integration metadata. PeopleSoft supports providing WSDL documents and WADL documents to the PeopleSoft WSDL repository. The system also supports providing WSDL documents to Universal Description, Discovery, and Integration (UDDI) repositories.

The system enables you to consume WSDL documents from other PeopleSoft and third-party systems, and automatically creates integration metadata based on the consumed WSDL documents for processing integrations. You can consume WSDL documents from other PeopleSoft systems, UDDI repositories, WSDL URLs, and Web Services Inspection Language (WSIL) URLs.

Integration Gateway

The integration gateway is a platform that manages the receipt and delivery of messages passed among systems through PeopleSoft Integration Broker. It supports the leading TCP/IP application protocols used in the marketplace today and provides extensible interfaces to develop new connectors for communication with legacy, enterprise resource planning, and internet-based systems.

Additional features include:

Backward compatibility for Extensible Markup Language (XML) links and PeopleSoft Application Messaging.
Listening connectors and target connectors that transport messages between integration participants and the integration engine.

Note. This feature also enables you to build your own connectors to complement those delivered with PeopleSoft Integration Broker.
Basic logging information concerning message receipt, delivery, and errors.
Connection persistence with continuous open feeds to external systems through connectors, with full failover capabilities.
Transport protocol and message format management so that when messages reach the integration engine, they have a PeopleSoft-compatible message format.

See Also

Integration Gateway Architecture

Integration Engine

The integration engine runs on the PeopleSoft application server. Rather than communicating directly with other applications, the integration engine sends and receives messages through one or more separately installed integration gateways.

The integration engine:

Uses a modular architecture, so it can treat gateways as black boxes and communicate with them using standard connectors.
Adapts elements of an existing integration to produce a new integration with only minor adjustments.
Handles messages containing data in a variety of formats. Formats include the PeopleSoft rowset-based message format, and nonrowset-based message structures including , XML document object model messages, Simple Object Access Protocol (SOAP) messages, and non-XML files.
Sends and receives messages asynchronously (like email) or synchronously (suspending activity to wait for a response).
Applies message transmission type and routing based on specifications that you define in a PeopleSoft Pure Internet Architecture component.
By developing and applying application engine transform programs, the application engine can transform message structure and translate data content according to specifications that you define in PeopleSoft Pure Internet Architecture components.

You develop transform application engine programs in PeopleCode or Extensible Stylesheet Language Transformation (XSLT) code.

These specifications can be reused for other integrations.
Handles security features such as authentication, nonrepudiation, and cookies.

See Also

Integration Engine Architecture

Integration Gateway Architecture

This section discusses:

Architecture components.
Connectors.
Gateway manager.
Gateway services.

Architecture Elements

You use an integration gateway to receive and send messages among integration participant systems.

Listening connectors receive incoming messages and deliver the incoming requests to the gateway manager, which is a dispatcher for messages that flow through an integration gateway. The gateway manager determines which target connector to use to properly deliver the messages to their intended recipients. The target connector then delivers the messages to the intended recipients using the recipients’ preferred protocols.

Integration gateway architecture

Connectors

Listening connectors and target connectors transport messages between integration participants and the integration gateway. These connectors support asynchronous and synchronous message handling. Many connectors are configurable at the integration gateway and system levels.

Listening Connectors

Listening connectors receive incoming data streams and perform services based on the content of the stream. They are invoked externally by other PeopleSoft systems and third-party systems.

Target Connectors

Target connectors initiate communication with other PeopleSoft systems or third-party systems. A target connector might not receive a response from the target system during each operation, but every transmission requires a low-level acknowledgment.

PeopleSoft Integration Broker Connector SDK

The integration gateway provides a fully extensible model for developing new connectors built to the interface specification of the PeopleSoft Integration Broker software development kit (SDK) by PeopleSoft customers, consultants, and application developers.

Using the Integration Broker Connector SDK

Gateway Manager

The gateway manager processes every message that flows through an integration gateway and maintains links to the other major integration gateway components, including target connectors, listening connectors, and each of the gateway services.

Listening connectors invoke the gateway manager when they receive a request. The gateway manager uses the messaging objects IBRequest and IBResponse to determine how to route each request.

The gateway manager uses a number of the gateway services during this stage to perform operations such as message validation. The gateway manager then invokes the appropriate target connector based on the content of the message object and waits for a reply from the target connector. When the reply is received, the gateway manager forwards the reply to the calling listening connector.

If an error occurs, the gateway manager uses the error handling service and works with the service to prepare an error reply for the listening connector.

Gateway Services

This section describes the gateway services that the gateway manager uses.

XML Parsing

Most IBRequest objects and IBResponse objects that are processed in the system contain a content section that represents the actual business content sent.

Most of the time, these content sections contain XML data. Consequently, often connectors must parse and traverse XML. The standard Java XML objects are cumbersome for manipulating XML, so the integration gateway includes an XML parsing service consisting of objects that provide an intuitive interface for manipulating XML objects. This service is delivered as a set of three classes: XmlDocument, XmlNode and XmlNodeList.

See PeopleTools 8.52: PeopleCode API Reference PeopleBook

Integration Broker Objects

Two objects comprise the messaging objects service in the integration gateway:

IBRequest
IBResponse

These objects represent the request and response that enter and exit PeopleSoft Integration Broker.

See Understanding Supported Message Structures.

Connector Management

The connector management service is a composite of several services that manage connectors. The gateway processes each IBRequest to determine the appropriate connector to call in each situation. This is primarily a message routing function that has varying levels of complexity abstracted from the connectors. The connector management service also processes the IBResponse returned by each connector.

WS-Security

WS-Security is an extension to the concept of the SOAP envelope header that enables applications to construct secure SOAP message exchanges. It also provides a means for associating security tokens with messages.

See Implementing Web Services Security.

Error and Service Operation Logging

Most components in the system use a standard error logging interface.

Each PeopleSoft-delivered connector uses the logging API in the same fashion, ensuring that an administrator can quickly drill down on problems or simply review the logs to see the IBRequest object, the IBResponse object, and even the raw data exchanged with integration participants.

See Managing Error Handling, Logging, Tracing, and Debugging.

Error Handling

The integration gateway provides a standard error handling interface that is exposed to each connector. This service provides error handling and error logging for most connectors delivered with PeopleSoft Integration Broker.

Message Validation

Messages that pass into PeopleSoft Integration Broker must contain certain elements to be processed. Because the integration gateway is the first component that processes messages sent to a PeopleSoft application, it performs basic validation—such as making sure that the message identifies its requestor and service operation name—to ensure that the integration engine and the target application can process them.

Integration Engine Architecture

The integration engine uses a variety of PeopleTools elements to create, implement, manage, and enhance integrations. Its modular architecture separates integration development activities from administrative activities.

The integration engine is a combination of PeopleSoft Application Designer definitions, PeopleSoft Pure Internet Architecture definitions, PeopleCode, and XSLT code, along with the underlying mechanisms that tie all these elements together. The underlying mechanisms include the request handlers that process both inbound and outbound messages according to the specifications in the development and administrative elements.

The integration engine resides on the PeopleSoft application server.

The following diagram shows the integration components that reside on the integration engine and the types of processing it performs.

Integration engine architecture

Service Operations

A service operation in the PeopleSoft system contains the processing logic for an integration and determines if the integration is to be processed synchronously or asynchronously. A service operation definition contains the following definitions:

Message. A message contains the payload of the integration.
XML message schema. Message schemas provide the physical description of the data that is being sent, including descriptions of fields, field types, field lengths, and so on.
Handler. A service operation handler contains the processing logic for the service operation.
Routing. A routing definition specifies the direction of the integration (inbound or outbound), routing alias names, transformations, and more.

Service Operation Types

PeopleSoft Integration Broker supports four types of service operations:

Asynchronous one-way.
Asynchronous request/response.
Asynchronous to synchronous.
Synchronous

Note. In this section the term transaction is used to describe the exchange of data between integration partners.

When PeopleSoft Integration Broker sends a service operation, the receiving system returns a response back to the sender. With asynchronous transactions, the response is automatically generated by the integration gateway, and it serves only to notify the sending system of the transmission status of the request . It is processed automatically by the application server, which uses that status information to update the Service Operations Monitor. With synchronous transactions, however, the response includes the content that is requested by the sending system, and it must be generated and returned by the receiving system.

Operation Types

PeopleSoft Integration Broker supports the operation types listed in the table.

For any operation type, the application must invoke PeopleCode, a component interface or data mover script to generate and send a service operation, or to receive and process a service operation.

Operation Type	Routing	Actions
Asynchronous — One Way.	Outbound.	The application generates and sends a request. One or more target system receives and processes the request.
Asynchronous — Request/Response.	Outbound.	The application generates and sends a request. The target system receives and processes the request. Sometime later the target system sends a response which contains the transaction ID from the original request. This ID serves as the correlation ID. The application processes the response using the correlation ID to map it back to the original request. The message sent back is a response in the form of a request.
Asynchronous to Synchronous.	Outbound.	The application generates and sends a request. A single target system receives and processes the request, then generates and sends a response. The application receives and processes the response.
Synchronous.	Outbound.	The application generates and sends a request. The application suspends activity and waits for a response. A single target system receives and processes the request, then generates and sends a response. The application resumes its activity and receives and processes the response.
Asynchronous — One way.	Inbound.	A source system generates and sends a request. The application receives and processes the request.
Asynchronous — Request/Response.	Inbound.	A source system generates and sends a request. The application receives and processes the request. Sometime later the application sends a response back to the source system. The response includes a unique identifier from the original request, which serves as a correlation ID. The source system processes the response using the correlation ID to map it back to the original request.
Asynchronous to Synchronous.	Inbound.	A source system generates and sends a request. The application receives and processes the request, then generates and sends a response. The source system receives and processes the response.
Synchronous.	Inbound.	A source system generates and sends a request. The source system suspends activity and waits for a response. The application receives and processes the request, then generates and sends a response. The source system resumes its activity and receives and processes the response.

See Also

Services Operation Types

Inbound and Outbound Request Flows

This section discusses how inbound and outbound service operation flow through the architecture components of PeopleSoft Integration Broker.

The PeopleSoft messaging architecture is discussed in greater detail in the Understanding Messaging chapter of this PeopleBook.

See Also

Understanding Messaging

Inbound Request Flow

This section describes the flow of a typical inbound request from an external system through PeopleSoft Integration Broker.

Flow of an inbound request through PeopleSoft Integration Broker

After the incoming request has been received by the integration gateway, the flow through PeopleSoft Integration Broker is the same, regardless of the listening connector used. With this in mind, no specific listening connector will be discussed here. The scenario is simple: a request is sent into the gateway, which then passes it on to the application server. The application server processes the request, and returns a response.

Step 1: External System Sends a Request to PeopleSoft Integration Broker

The first step is that an external system sends a request to PeopleSoft Integration Broker. The external system can be another PeopleSoft system or a third-party system.

Step 2: Request is Received by the Listening Connector

When a request is received by a listening connector, the first thing that the connector does is write the request to the gateway log file. (The gateway’s integration properties file is used to set the logging level, which controls what is actually written to the log. If messages are not being seen in the log file, check to ensure that the log level is set correctly.) The request is written exactly as it is received. This is very useful in that it presents exactly what was sent on the wire, before the connector normalizes the service operation for use by the application server.

The connector then attempts to populate an internal request class with the particulars from the received request.

A term often used in conjunction with listening connectors is credentials. Incoming requests are thought to have two logical parts: the credentials and the body. The credentials can be thought of as the information required by PeopleSoft Integration Broker to process and deliver the payload of the message. The payload is located in the body. Since the credentials are separate from the body, the integration gateway does not need to parse or otherwise examine the request body for information on how to route it.

A request without credentials cannot be processed. If the integration gateway receives such a request an error will occur and an error message will be returned to the requestor.

Step 3: Request is Processed by the PeopleSoft Target Connector

In order for a request to be sent from the gateway to the application server, it must pass through the PeopleSoft target connector. This connector has two major responsibilities: it serializes the request to a string, and sends that string via a JOLT connection to the application server.

All communication between the gateway and the application server is done via the use of Multipurpose Internet Mail Extensions (MIME) messages. When the request is received by the connector, it builds a MIME message. Typically the MIME message will only have two sections. In the first, the credentials are stored in an XML document in a specific format. The second section stores the body.

At this point the request is in a standard format understood by both the gateway and the application server. All requests must eventually resolve to this format before they can be sent to the application server for processing. This format effectively isolates the application server from the protocols supported by the gateway; for the most part, there is no information present about what listening connector was initially invoked by the external request.

One credential element that may be present is the one for cookies. Obviously if this is set, the application server would be right in assuming that the request came through the HTTP listening connector. However, as a general rule the application server is isolated from the details of the protocol and the general broker code on the server does not care what listening connector was used for a given request.

Once the MIME message has been built, it is written to the gateway log.

Finally, the connector looks up the JOLT connection properties from the integration properties file and attempts to send the MIME to the application server. If these properties are not set up correctly, the gateway will be unable to send requests. This is a common source of error, so care should be taken when configuring this file.

An important point to keep in mind is that even though the MIME request to the application server may appear in the gateway log file, the actual request may not have made it to the application server, since the log entry is written before the service operation is sent. If a communication error occurs, the entry will still be present in the log file. However, if this situation occurs an exception will be thrown and an error log entry will also be created.

Step 4: Request is Received by the Application Server

When the MIME request is received by the application server, the system parses it into a request object. The MIME structure is not propagated into the server.

Assuming the request parses without error, the application server pre-processes it.

Pre-processing involves:

Authenticating the service operation, depending on the authentication scheme configured. If the request fails authentication, an error is returned.
Determining the direction of the service operation, by looking at the external alias on the routing definition that is associated with the service operation.
Determining the runtime handler to invoke. Currently, there are three handler types supported by the integration broker: Ping, Synchronous, and Asynchronous. The service operation type determines the handler code to invoke. Synchronous service operations are passed to sync-specific code, and asynchronous service operations are passed to the publish/subscribe subsystem.

Once a request has been passed to its respective handler, further processing is dictated by the data and PeopleCode specific to a particular system. Or in the case of hub configurations, the request may immediately be routed to another external system.

Step 5: Response is Returned by the Application Server

Regardless of how the request is processed, a response must be returned by the application server to the gateway in the same thread of execution. The connection between the gateway and the application server is essentially synchronous, independent of the type of the service operation type. When the gateway sends a request to the application server, it expects and must get a response.

In the case of synchronous processing, the generation of the response is blocked by the processing of the request. A response cannot be generated until the service operation runs to completion. There may be a noticeable delay in receiving the response, depending on the processing required by the OnRequest method or if the request is being sent out of the broker to an external system for additional processing.

Asynchronous requests behave differently. Unlike synchronous requests, there is no blocking. A response is generated for an asynchronous request as soon as the request is placed on the publication queue. Because of this, a response generated for an asynchronous request is not a response in the strictest sense of the term. Such responses should really be considered acknowledgments that the pub/sub system has received the request. Receipt of such a response is not a guarantee that any applicable notification PeopleCode has been successfully run.

Responses are converted to the MIME standard by the application server, and are returned to the gateway.

Step 6: Response is Received by the PeopleSoft Target Connector

As soon as the MIME response is received by the PeopleSoft target connector, it is written to the gateway log file.

The MIME response is then parsed back into a gateway request object, and is then returned to the listening connector.

Step 7: Response is Received by the Listening Connector

The response object is returned to the listening connector, upon which the response is mapped to a response suitable for the given protocol.

It should be emphasized that, from the viewpoint of the listening connector, the processing of requests is done synchronously. A request is received by a listening connector which then coverts it to a suitable format, makes a blocking call to the gateway to handle the message, and ultimately gets a response back all in the same thread of execution.

Outbound Request Flow

The following diagram shows an outgoing request through PeopleSoft Integration Broker.

Outgoing request through PeopleSoft Integration Broker to an external system

There are several scenarios that might result in a request being sent out of the broker. Requests can be sent in PeopleCode by using the Publish or SyncRequest methods of the Integration Broker class.

Regardless of how the request is created, the mechanism for sending it out of the broker is the same, and the flow is the same regardless of the specific outgoing target connector you invoke.

Step 1: Application Server Generates Request

Once an outgoing request has been generated, the application server must perform some basic processing before it can be sent out.

The application server looks at the request, and extracts the information about the node that it is being sent to.

If target connector information was not supplied via PeopleCode or as part of the routing, then the node name is then used to look up the name of the gateway to use, the target connector to use on that gateway, as well as any specific connector properties that need to be passed to the connector in order to handle the request. If this information is not found, an error will occur.

The application server modifies the outgoing request with the appropriate connector information.

The request is then converted to the MIME standard format, and is sent to the gateway over an HTTP connection.

The request must be sent to the PeopleSoft listening connector on the gateway. The application server uses the value of the Gateway URL defined for the given gateway. If this URL is not valid or does not point to the PeopleSoft listening connector, the application server will be unable to send the request.

Step 2: Request is Received by the PeopleSoft Listening Connector

When the MIME request is received by the PeopleSoft listening connector, it is written to the gateway log file.

The request is converted from MIME format to a gateway request object.

The connector then examines the request to determine what target connector the request is to be sent to; that target connector is then invoked.

Step 3: Request is Received by the Target Connector

The target connector validates the request. Each connector requires certain properties to be set, otherwise the request cannot be sent. For example, the HTTP target connector requires that the PrimaryURL be set. If any mandatory connector properties are missing or are invalid, an error will be thrown.

The target connector then converts the request into whatever format is required by the protocol.

The modified request is then written to the gateway log, and then sent out.

Step 4: Response is Received by the Target Connector

The response received by the target connector is written to the gateway log, and the response is used to build a gateway response object, which is then returned to the PeopleSoft listening connector.

Step 5: Response is Received by the PeopleSoft Listening Connector

The response object is then converted to the MIME standard format by the connector.

The MIME response is then written to the gateway log file, and is then returned to the application server.

Interactions with the gateway are always synchronous. If a request is sent to the gateway, a response should be expected.

Step 2 is an HTTP POST request made of the gateway, and the response created here in Step 5 is returned in response to that HTTP request. The HTTP connection is open for the duration of the processing for that request.

The response object is returned to the listening connector, upon which the response is mapped to a response suitable for the given protocol.