Thursday, January 21, 2021

Integration Broker OnError Method

Do you know what happens when an Integration Broker handler App Class throws an Exception? REST, SOAP, or plain XML over HTTP all behave mostly the same. By default, PeopleSoft returns the error message to the client. This is great! It means you and I don't have to write error handlers, right? Actually, I hadn't given it much thought until working with REST. With REST, I want to leverage HTTP status codes. For example, if a REST client requests data that doesn't exist, I want to return a 404 status code. But if you throw an exception from an OnRequest REST handler, the default Integration Broker OnError handler returns a 200 (success) status code and an HTML content type. An exception should not return a 200. Fortunately, we can override the REST HTTP response code through the recently documented OnErrorHttpResponseCode and OnErrorContentType properties of the the Request Handler interface (see MOS document 2026747.1 for more details). You set these properties from a handler's OnError method, which is the method Integration Broker invokes when the handler method throws an exception. So here is a snippet from our Integration Tools Update course:

method OnRequest
   If (%SqlRows = 0) Then
      throw CreateException(0, 0, "Item not found");

method OnError
   /+ &request as Message +/
   /+ Returns String +/
   /+ Extends/implements PS_PT:Integration:IRequestHandler.OnError +/
   REM Create fault response;
   %This.OnErrorHttpResponseCode = 404;
   %This.OnErrorContentType = "application/json";
   Return "<response string goes here>";

Notice the code throws an exception when no rows are found. When OnRequest throws an exception, Integration Broker invokes the OnError method, and the OnError method returns a hard-coded 404. So, let's think about this a little more... as you see, the OnError handler ALWAYS returns 404. What if something else goes wrong? Shouldn't I see another status code? Great question! That's a topic we'll save for another post. But let's address a different issue. What happens if your OnError handler throws an exception? PeopleSoft drops the OnError handler and returns the response it would have returned without an OnError handler, meaning a status code of 200 with HTML content type. It's sort of like PeopleSoft invoked your OnError method, which threw an exception and PeopleSoft said, "Oh, just kidding," and reverted to its default behavior.

Now, let's say you are testing your OnError handler, but it seems like Integration Broker is ignoring you. I mean, no matter what status code you set in your OnError method, PeopleSoft returns a 200. First, if this is happening to you, chances are high, your OnError method is throwing an exception. But how can you troubleshoot this? Here is my debugging strategy: Open a file object and print lines. For each line in the OnError handler, I print a line to my log file. I can then open the log file and see when PeopleSoft stopped printing to my log (I'm basically tracing my own code).

OK. Now, let's say you have all of the bugs worked out of your OnError handler, and you are ready to move to production. How can you ensure PeopleSoft will return a 400-level status code if the OnError handler throws a runtime exception? Wrap your code with a try block to catch errors. You then retain control over the HTTP response code and content type.

Are you interested in learning more about Integration Strategies? We believe Integration is one of the most important PeopleTools technologies for today's distributed enterprise. Visit to see when we are offering our next Integration Course. Have a group of developers to train? Contact us for special group pricing!