Integration Broker Request flow

Incoming Request Flow:

This section describes the flow of a typical 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. Similarly, SOAP requests are passed into the application server in SOAP format. 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 subscription 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.

Outgoing Request Flow

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.