Five Reasons to Adopt the Application Services Framework

PeopleSoft's Integration Broker has support for REST and JSON. But, it is clear from the metadata, design, and history that Integration Broker favors SOAP and XML (Web Services). Is there a better alternative? YES! As of PeopleTools 8.59, we have a module designed specifically for REST: the Application Services Framework (ASF).

Here are five reasons you should consider ASF for your next integration project:

1. URL Design

REST focuses on objects and data. In an enterprise system, business objects might be Employees, Students, or Vouchers. In ASF, we might call these root resources. Continuing with the Voucher example, we might have the following URLs:

• .../ap/vouchers
• .../ap/vouchers/000000012567

When constructing an Application Service, we would have the "ap" service, which would then have a "vouchers" root resource. We could then define URI templates for:

• vouchers (get a list of all vouchers)
• vouchers/000000012567 (get a specific voucher)

We would further define HTTP methods, such as GET, PUT, PATCH, or POST, to fetch, update, or create business objects within the respective collections.

The Application Services framework helps us design URLs by first thinking about the module → then the collection → and then the specific object (generic to specific).

When we browse the Internet, we expect to find an organized collection of documents (endpoints) conveniently filed in meaningful folders. Computers browse the Internet, and those computers should expect an organized collection of business "documents" as well.

2. 201 Created Success Status Code

Web Services and SOAP use a protocol within a protocol. The typical Web Service request uses HTTP as the transport protocol and SOAP for the transaction protocol. Therefore, a Web Service might return a 200 HTTP status code to report success even though the SOAP transaction failed.

REST HTTP status codes have meaning. HTTP status codes in the 200 range represent successful responses. The most important HTTP status codes for a PeopleSoft developer are 200, 201, 202, and 204. These are the ONLY HTTP success status codes supported by ASF. Integration Broker REST-based Service Operations, on the other hand, support several other 200-level status codes, but with one critical omission: REST-based Service Operations do not support 201. 201 is the status code for "created." Assuming a PUT or a POST, the proper response may be a 201 - Created. This is critical. If the service handler immediately creates a transaction, then it should return a 201. The Application Services Framework supports this, but traditional REST Service Operations do not.

3. 401 Unauthorized Bad Request Status Code

PeopleSoft takes control of the HTTP Authorization header for several reasons. Here are a couple:

• To determine if the requester is authorized to access the requested service.
• To assume the identity of the user making the request, allowing PeopleCode to run as the proper user.

If PeopleSoft determines the requester does not have access (based on roles and permission lists), then PeopleSoft will return the 401 Unauthorized HTTP status code. This happens at the Integration Broker level, and it is fantastic!

But what if your business logic needs to return a 401 Unauthorized? Traditional REST-based Service Operations do not allow this.

Consider the following example. Let's say that a user is authorized for our /ap/vouchers service (the example above). That user might be authorized to access certain vouchers, such as .../ap/vouchers/000000012567, but not .../ap/vouchers/000000012568. This is called row-level security. In this scenario, we should return a 401 - Unauthorized. The user is authorized for the service, but not the data.

Traditional REST-based Service Operations do not allow you to return a 401 Unauthorized EVER. ASF does. 401 is an acceptable failure response from an Application Service.

4. OpenAPI

Metaphorically speaking, OpenAPI is the WSDL of REST. ASF generates OpenAPI specifications for us. We can plug these OpenAPI URLs or downloaded descriptors into various consumers, including Oracle Digital Assistant, Oracle Integration Cloud, Oracle Visual Builder, and more!

5. PeopleCode

ASF was designed to expose Application Classes as REST services. The framework includes an API designed to construct single-row and multi-row responses. The API was designed for REST with support for HTTP status codes and HTTP methods.

6. (Bonus) Metadata Design

ASF metadata consists of:

• Module
• Root Resource
• URI Templates
• Parameters
• Result States
• HTTP Headers

All of these are common and expected REST metadata concepts. Traditional REST Service Operations, on the other hand, include Messages, Services, Service Operations, and Documents; metadata structures that are more appropriate for Web Services than REST.

What to learn more? Create a free account at jsmpros.com and explore our free webinar replays to learn the basics of the Application Services Framework. Next, join us for our three-day live virtual Integration Tools Update course. Prefer to learn at your own pace? This same material is available on demand! Watch the videos whenever and wherever you like, and then complete the hands-on activities on your own server.

Have you Considered the Application Services Framework?

 We recently asked the PeopleSoft LinkedIn Community:

Which would you choose to expose a PeopleSoft REST endpoint?

Here were the responses:

The answers surprised me. On the one hand, the IB Service/Service Operation approach was the only option until PeopleTools 8.59. This makes it familiar. However, the Application Services Framework was specifically created for REST. Unlike traditional IB Services and Service Operations, which were designed for SOAP and Web Services, the Application Services Framework focuses on HTTP concepts, such as URL design, status codes, data structures, and more. Here are some benefits the Application Services Framework offers over traditional IB Service Operations:

• Generates an OpenAPI specification for import by consumer applications.
• Provides additional HTTP status codes.
• Uses a PeopleCode API that aligns more closely with REST service design.
• Eliminates irrelevant metadata creation, such as Message Definitions and Documents.

The Application Services Framework is a REST-specific, REST-focused layer over the top of service-oriented Integration Broker metadata. If you haven't done so already, we recommend reviewing the Application Services Framework. It definitely simplifies REST Service development.

The Application Services Framework is part of our standard Integration Tools training. Join us for our next class to learn more! Already a subscriber? Log in and Get Started!

Simple Code-only REST Request

PeopleSoft is a metadata-driven application. It stands to reason, therefore, that the solutions we create require metadata. Sometimes metadata, which is supposed to be configurable, forces us down an immutable (non-configurable) path. Integration Broker is a fantastic example of semi-mutable, bordering on immutable metadata. As we prototype, we often make changes. But the testing associated with prototyping locks various metadata pieces. Sometimes we just want to test without metadata and backfill after we choose the proper path.

Here is a very simple metadata-free REST request example I run from a local App Engine program for prototyping and testing purposes.

Now, an important question:

Once you have a working "simple" solution, do you backfill and update with proper Integration Broker metadata?

Let us know your thoughts in the comments below!

At JSMpros, we teach Integration Tools concepts regularly. Check out our website to see what we are offering next!

Metadata-less Integration (Easy REST)

 As PeopleSoft customers move to REST, I've noticed an interesting trend: choosing code over metadata. Most of the examples I've seen online are labeled Easy or Simple. Some of the examples use fully supported documented approaches, whereas others use undocumented internal testing methods. Here are some of my favorites:

• Consuming a REST Service
• A Simple REST Call
• Easy REST Requests
• PeopleCode to Call REST APIs

Based on those examples, REST PeopleCode really is easy! But what does that say about the metadata approach? Is it hard? Is it complex? To answer that, let's review the metadata definitions necessary to craft a REST request:

• UR Document (if the target has parameterized URLs)
• URI Message (if the target has parameterized URLs)
• Request Document (if POST, PUT, or PATCH)
• Request Message (if POST, PUT, or PATCH)
• Response Document
• Response Message
• Service
• Service Operation
• Service Operation Security

And when you are done with the metadata configuration, you must still write code to invoke the REST request. Interestingly, invoking a REST metadata-based request requires roughly the same amount of PeopleCode as a "simple" or "easy" PeopleCode request.

So what does all that Metadata buy us? In other words, why choose metadata over pure code?

• Logging: We can set the log level in the routing.
• Security: OAuth and Basic Auth options can be set at the routing level.
• Parsing: Document-based messages will parse JSON, XML, and Rowsets for us.
• Maintenance: We can update/change URLs online rather than through PeopleCode (although a URL definition is a very simple way to maintain URLs across instances).

What if you don't require these features? Perhaps choosing the simple PeopleCode approach is better? Let us know your thoughts in the comments!

We teach PeopleTools REST and Integration regularly through our three-day Integration Tools Update course. Check out our website to see what we are offering next!

Setting IB Request Content Type

In our Integration Day 2021 One-day Webinar, we showed how to send SMS from PeopleSoft through Twilio. What makes Twilio interesting is that Twilio expects URL encoded form data. As you may know from using Integration Broker, PeopleSoft is quite happy sending and receiving JSON or XML. But what about other content types, such as application/x-www-form-urlencoded? You may know that you can set most HTTP headers using something like:

&request.IBInfo.IBConnectorInfo.AddConnectorProperties("Content-Type", "application/x-www-form-urlencoded", %Header);

That's a mouth full! But the weirdest thing happens when trying that trick with URL encoded form data. PeopleSoft URL encodes the entire body! Wait, isn't that correct? No, actually. When you and I create the body, we create the proper key=value&key2=value2 pairs. Proper URL encoded form data would look something like this:

key=This+is+some+encoded+data&key2=value2

Keys, ampersands, and equals signs should not be encoded (unless part of the value). But PeopleSoft URL encodes everything as if there were no keys. Here is what that same string above looks like when PeopleSoft finishes with it:

key%3DThis%2Bis%2Bsome%2Bdata%2Bto%2Bencode%26key2%3Dvalue

It is just supposed to URL encode the values. Or better yet, just let us URL encode the values. What's the workaround?

&request.SegmentContentType = "application/x-www-form-urlencoded";

This solution is a little strange because we aren't using a multi-part, segmented message, but it works!

While performing research for this post, I came across MOS Doc ID 2187249.1, which asks for an enhancement to allow additional, hopefully even custom, Content Types, so it appears URL encoded form data isn't the only issue. But lucky for us, we have SegmentContentType as a workaround!

Are you interested in learning more about PeopleSoft Integration Broker and integration strategies? Join one of our live virtual top-rated Integration Tools Update courses!

REST-like PeopleSoft Services

As you survey the consumer web service landscape, you will notice a shift: fewer SOAP based services and more REST based services. I will refrain from sharing my true feelings about WSDL and SOAP to share with you the important stuff: how you can make REST-like calls into PeopleSoft. If you are not familiar with REST, then I suggest you read the Wikipedia REpresentational State Tranfer summary and then follow some of the external links for additional details.

While there are implementation differences, at its core, the difference between REST and SOAP is the focus. The focus of SOAP is the operation, not the data. The focus of REST is the data. I find this difference most evident when working with a Component Interface (CI). With a CI, you set key values, call Get (or Create), change values, and then call Save. The entire time you are working with that CI, you are working with a single transaction instance. The focus of the CI is the state of the data. The operations (get, create, save) are secondary. Service Operations are exactly opposite. Service Operations focus on method execution. The data (the transaction in this case) is just a parameter. OK, maybe this isn't the "core" of the REST specification, but as one who has tried working with a CI in a Web Service Data Control, it is enough for me to want to throw out web services. Don't misunderstand me at this point. I'm not blaming web services, the CI WSDL, or the Web Service Data Control. I'm sure they all have their place in development projects. It is my experience, however, that they mix together like chlorine bleach and ammonia (please, oh please don't mix these two chemicals!).

There are several implementation details that differ between REST and SOAP. As a user interface (think Ajax) developer, my preferred implementation detail is the ability to call services with a URL as an HTTP GET or POST. Yes, you can make SOAP calls with JavaScript, but I find it a lot more difficult to package up a SOAP envelope with JavaScript than to just make an HTTP GET or POST with jQuery.

As noted by the Cedar Hills Group PeopleSoft REST Wiki, there is a lot more to REST than just URL's, and a true REST URL doesn't use Query Strings for parameters. If you want more REST, then you will have to wait for PeopleTools 8.52 or build something yourself (stand-alone REST gateway, MyRestListeningConnector, etc). If, like me, your greatest interest is executing Service Operation Handlers from URL's, then review the PeopleBooks HTTP Listening Connector. It contains the URL call specification for PeopleSoft service operations. With an "Any to Local" routing, the basic form looks like this: http(s)://my.peoplesoft.server/PSIGW/HttpListeningConnector?Operation=EXECTHISOPERATION. If you prefer, you can pass transaction keys, etc as query string parameters, and then read those parameters in PeopleCode. Here is how (assuming &MSG is the message parameter to your OnRequest handler):

   Local &connectorInfo = &MSG.IBInfo.IBConnectorInfo;
   Local number &qsIndex = 0;
   Local string &qsValue;
   
   For &qsIndex = 1 To &connectorInfo.GetNumberOfQueryStringArgs()
      If (&connectorInfo.GetQueryStringArgName(&qsIndex) = "THE_QS_PARM_NAME") Then
         &qsValue = &connectorInfo.GetQueryStringArgValue(&qsIndex);
      End-If;
   End-For;

No, I'm not fond of having to iterate over each query string argument either, but that is what the API requires. I packaged this up in a Query String helper class and create an instance of it for each request that uses query string arguments. Here is my Helper class:

class IBQueryStringHelper
   method IBQueryStringHelper(&connectorInfo As IBConnectorInfo);
   method getParameterValue(&parameterName As string) Returns string;
   
private
   instance IBConnectorInfo &m_connectorInfo;
end-class;

method IBQueryStringHelper
   /+ &connectorInfo as IBConnectorInfo +/
   %This.m_connectorInfo = &connectorInfo;
end-method;

method getParameterValue
   /+ &parameterName as String +/
   /+ Returns String +/
   Local number &qsIndex = 0;
   
   For &qsIndex = 1 To &m_connectorInfo.GetNumberOfQueryStringArgs()
      If (&m_connectorInfo.GetQueryStringArgName(&qsIndex) = &parameterName) Then
         Return &m_connectorInfo.GetQueryStringArgValue(&qsIndex);
      End-If;
   End-For;
   Return "";
end-method;

What about the result? Does it have to be XML? No. I have used two ways to create non-XML results from Integration Broker. The first is by creating a JSON response directly in PeopleCode. It is this use case that prompted me to write the PeopleCode JSONEncoder. A service operation handler can return non-XML by wrapping the result in a psnonxml attribute like this:

   Local Message &result_msg = CreateMessage(Operation.MY_SERVICE_OPERATION, %IntBroker_Response);
   Local string &json;
   
   REM ** Do some processing to generate a json response;
   
   Local string &nonXmlData = "<?xml version=""1.0""?><data psnonxml=""yes""><![CDATA[" | &json | "]]></data>";
   Local XmlDoc &doc = CreateXmlDoc(&nonXmlData);
   
   &result_msg.SetXmlDoc(&doc);
   Return &result_msg;

The second method I use to create non-XML results is through a transformation. Using XSL, it is possible to transform an XML document into JSON -- although JSON-safe encoding might be more difficult.

If you use a debugging proxy (such as Fiddler) to inspect the results of an Integration Broker response, you will notice Integration Broker always returns the Content-Type header value text/xml. Unfortunately, this means you have to help jQuery understand the results because it won't be able to determine the response type based on the Content-Type header. When PeopleTools 8.52 arrives at your office, you will be able to specify different MIME types. For now, I find it satisfactory to just set the $.ajax dataType parameter to "json." If you absolutely need to set the Content-Type header and don't have PeopleTools 8.52, then I suggest looking into a reverse proxy with header rewrite capabilities (Apache, for example).

No, unfortunately, this post didn't show you true REST. If you are choosing REST for Ajax because it is easier to make a URL based request to a REST service than to build a SOAP header to send to a Web Service (like me), then this post hopefully offers you enough information to get started. If you require more of the REST specification than I've shown here, then you will probably have to wait for PeopleTools 8.52.