How the Integration Broker Handles Incoming Requests (Understanding PeopleSoft Integration Broker Part 2)
Let’s discuss how the integration broker handles incoming requests. It is assumed that you’ve already read the Part 1 of this series – Understanding PeopleSoft Integration Broker.
There is a series of events which happen when a PeopleSoft Integration Broker receives incoming requests.
1) 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 request is written exactly as it is received. This helps capture the message as it was sent and before normalization occurs.
2) The connector then attempts to populate an internal request message class with the particulars from the received message. Incoming messages have 2 parts – credentials and mesage body. It is interesting to note that a message without credentials cannot be processed . If the gateway receives such a message – an error will occur and an error message will be returned to the requestor. No parsing happens at this step – just the validation.
3) Next the message is served to the PeopleSoftTargetConnector. This connector has two major responsibilities: it serializes the message to a string, and sends that string via a JOLT connection to the app server.
All communication between the gateway and the app server is done via the use of Multipurpose Internet Mail Extensions (MIME) messages. Typically the MIME message will only have two sections – message body and the credentials in XML format.
4) PeopleSoftTargetConnector transforms the message in a standard format, which is understood by both the gateway and the application server. All messages must eventually resolve to this format before they can be sent to the app server for processing, else the appserver won’t be able to understand them. This format effectively isolates the app server from the protocols supported by the gateway; there is no information present about what listening connector was initially invoked by the external request.
5) Once the MIME message has been built, it is written to the gateway log. The MIME response is then parsed back into a gateway request object, and is then returned to the ListeningConnector.
6) 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.
An important point to keep in mind is that even though the MIME request to the appserver may appear in the gateway log file, the actual request may not have made it to the app server, since the log entry is written before the message 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.
7) When the MIME request is received by the application server, the message is parsed and is used to build a request object. The Assuming the message parses without error, the application server must pre-process the message before the request can actually be handled. Pre-processing involves:
- authenticating the message, depending on the authentication scheme configured. If the request fails authentication, an error is returned.
- determining if there is a transaction corresponding to the request in the Node Transaction table. Aside from Ping messages, all incoming messages must resolve to a single, unique entry in this table. If a suitable transaction cannot be found for a request, an error occurs.
- determining the message handler to invoke. Currently, there are three message types supported by the integration broker: Ping, Synchronous, and Asynchronous. The message type determines the handler code to invoke. Synchronous messages are passed to sync-specific code, and async messages are passed to the publish/subscribe subsytem.
Once messages have been passed to their respective handlers, further processing is dictated by the data and PeopleCode specific to a particular system. Async requests will be published, and subscription PeopleCode will be executed. Synchronous messages may invoke PeopleCode, or in the case of Hub configurations the request may immediately be routed to another external system.
8) Regardless of how the request is processed, a response message must be returned by the app server to the gateway in the same thread of execution. The connection between the gateway and the app server is essentially synchronous, independent of the type of the message being exchanged. When the gateway sends a request to the app server, it expects and must get a response.
In the case of synchronous messages, the generation of the response is blocked by the processing of the request. A response cannot be generated until the message runs to completion. There may be a noticable delay in receiving the response, depending if PeopleCode is being run or if the request message is being sent out of the broker to an external system for additional processing.
Unlike sync requests, there is no blocking in case of async requests. A response is generated for an asynchronous request as soon as the request is written to 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 message. Receipt of such a response is not a guarantee that any applicable subscription PeopleCode has been successfully run.
Response messages are converted to the MIME standard by the app server, and are returned to the gateway.
9) As soon as the MIME response is received by the PeopleSoftTargetConnector, 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 ListeningConnector.
10) The reponse object is returned to the ListeningConnector, upon which the response is mapped to a response suitable for the given protocol. From the viewpoint of the ListeningConnector, the processing of request messages is done synchronously. A request is received by a ListeningConnector 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.
