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!

Consuming Enormous Datasets with PeopleSoft

Integration Broker is built on the DOM concept, which means it parses data into an in-memory structured document before transforming, processing, or transmitting it. This is fantastic for small and incremental integrations designed to keep two systems synchronized on a per-transaction basis. However, it fails when processing datasets that exceed the amount of available system memory.

An alternative is to use a SAX or stream-based parser that emits events. This type of parser only consumes the memory necessary to emit the next event. Stream-based parsers are highly efficient for one-way, one-time reads through large datasets. Unfortunately, Integration Broker does not support stream-based processing.

While reviewing PeopleSoft's Java class path, I noticed the Jakarta JSON stream-processing Java library. You can find a simple PeopleCode example of processing a JSON file using Jakarta JSON streams in our blog post JSON Stream Processing with PeopleCode. Now that we know how to use Jakarta's stream processing, the next challenge is reading an input stream from an external service. Since Integration Broker does not support streams, we need alternatives. Here are a few Java-based alternatives that readily integrate with PeopleCode through delivered APIs:

• Java Sockets
• Java HttpURLConnection
• Apache HttpClient

Although PeopleCode offers incredible support for Java, the real challenge lies with method and constructor overloading. PeopleCode identifies target Java methods and constructors through parameter count, not parameter type. Java overloading doesn't play well with PeopleCode. The solution I use to overcome method overloading is to leverage Java's support for JavaScript as a translation layer or a "glue." PeopleSoft exposes all functions and objects to Java. Therefore, all PeopleCode functions and objects are also available to JavaScript.

The following is a sample JavaScript that can run from PeopleCode to stream load data into a PeopleSoft table. It uses Jakarta for stream processing and Apache HttpClient to connect to the external service. Both of these external libraries are included with PeopleTools. Notice the use of PeopleCode functions, such as CreateSQL, as well as Java objects such as HttpGet.

I use PeopleCode similar to the following to run JavaScript from PeopleCode. You can find several examples of using Java's ScriptEngineManager on our blog.

Local JavaObject &manager = CreateJavaObject("javax.script.ScriptEngineManager");
Local JavaObject &engine = &manager.getEngineByName("JavaScript");
Local String &script = "JavaScript goes here";
Local Any &result;

&engine.eval(&script);

&result = &engine.get("result");

At JSMpros, we teach PeopleTools and PeopleCode tips like this in every class. Check out our online schedule to see what we're offering next. Would you prefer to learn at your own pace? Purchase a subscription to access all of our on-demand content at discounted rates!

Five Ways to Consume a REST Service with PeopleSoft

PeopleSoft includes facilities for providing and consuming REST. A service provider is a listener. A provider waits for requests and responds accordingly. To provide web services, we must register metadata with Integration Broker. The process is pretty well fixed. Consumption, on the other hand, is much more flexible. Consuming a REST service means invoking (or calling) someone else's listener. The consumer initiates the conversation. In a consumption scenario, we might be sending data, receiving data, or both.

Here are five ways a PeopleSoft developer might invoke a REST service:

1. Metadata

This is the traditional PeopleSoft approach and follows the same pattern as providing services through Integration Broker. Here are a few of the metadata items a developer would create:

• Documents,
• Messages,
• Service, and
• Service Operation.

After creating and registering somewhat reusable metadata, the developer would then write PeopleCode to:

• Create Document structures,
• Invoke the service, and
• Parse the response.

Even though this approach requires the most effort and offers the least reuse, it takes full advantage of Integration Broker's capabilities, including logging, security, etc.

Metadata, in general, offers the following benefits:

• Reuse (ability to use the same definition multiple times),
• Documentation (describes an object),
• Reporting (query and analysis), and
• Transformation (ability to upgrade and transform based on architecture changes).

Pure code solutions are much harder to query and transform. Metadata is what allowed PeopleSoft to switch from a Windows-based Client/Server solution to its Pure Internet Architecture in (mostly) one release. Metadata is what allowed Integration Broker to transform from an XML-focused solution into an SOA solution in one release (the 8.48 transform). If these benefits sound appealing, then metadata may be the right choice for you.

2. Application Services Framework

Created initially as a REST provider to support digital assistants, the Application Services Framework can now consume REST services. The Application Services Framework is a developer-friendly configuration layer tightly integrated with Integration Broker metadata. Rather than directly working with SOA-oriented metadata, the Application Services Framework allows developers to create solutions using REST terminology and REST patterns.

To use the Application Services Framework for consumption, a developer would:

• Register the target service with the Application Services Framework, which includes describing the URL, parameters, headers, and payload (both request and response).
• Write PeopleCode to invoke the endpoint service.

This is one of the most important chapters in our updated Integration Tools curriculum. You may find basic information (including code samples) on consuming a REST service in PeopleBooks.

3. %IntBroker.ConnectorRequestURL

If your request is a simple URL with no special headers (request or response headers) and any parameters may be passed through the URL, then this is the most straightforward approach:

Local string &response = %IntBroker.ConnectorRequestURL("http://rest.example.com/endpoint");

Unfortunately, this solution offers no logging, header control, or any typical Integration Broker or integration features. It is strictly for the simplest GET requests. Nevertheless, by using URL definitions, this alternative may be one of the better alternatives for cross-environment migrations.

4. Code-only

The challenge with the first option, Metadata, is that it requires creating, migrating, and maintaining a significant number of definitions that provide little (if any) value for REST. For example, the URL of a PeopleSoft REST consumer service becomes part of the metadata. If you have different targets between DEV, TEST, and PROD, then you must modify the metadata after every migration. Implementing a true PeopleSoft Metadata-focused solution (such as option 1) may require you to violate development best practices by making changes after each migration.

Since all approaches require PeopleCode, why not skip the Integration Broker metadata in favor of your own reusable best practice-based metadata? You may find an example of this approach in our blog post Simple Code-only REST Request. With this approach, you are responsible for managing URLs, Credentials, etc., but you may store them in a manner that allows for reuse and better migration management. For example, you might create URL definitions that point to different endpoints in DEV, TEST, and PROD.

It is important to note that this approach DOES use metadata, but it reuses generic PeopleTools-delivered definitions, so we don't have to create new definitions.

As mentioned earlier, code doesn't report or transform well, so this alternative may miss out on future automated transforms, such as the 8.48 automated transform. Likewise, integrations launched in this manner won't log details in the Synchronous Service Operation Monitor. Nevertheless, this approach is becoming one of our favorite alternatives to overly complicated metadata.

5. Java

Using Java allows a PeopleSoft developer to bypass Integration Broker altogether. We put this option last because it should be the choice of last resort. However, it is probably the most flexible option available, allowing for everything from simple low-level sockets to convenient libraries, such as Apache's HttpClient (now included with PeopleTools).

There are many reasons to choose this option, but here are the two most common:

• Processing binary data: Integration Broker is pretty much an XML workhorse. Everything passing through Integration Broker is wrapped in XML at some point. Unfortunately, that might not work well with binary data. Therefore, skipping Integration Broker may be appropriate.
• Processing large amounts of data: Integration Broker works with DOM. It requires all data to be loaded in memory at one time. This makes it a poor choice for handling large datasets. An alternative is to use stream processing with an event-based parser, such as a SAX parser. With Java, you can read bytes, process them through an event-based processor, and then discard the processed bytes.

The challenge with using Java directly from PeopleCode is that many Java methods and constructors use overloading. As a workaround, we devised a strategy for invoking Java through JavaScript from PeopleCode. With a small PeopleCode fragment, we can invoke a JavaScript, and JavaScript handles Java really well. Details about this strategy are available in our Blog Post JavaScript on the App Server: Scripting PeopleCode.

The following is a sample JavaScript we used at Reconnect 2024 to stream-processed a large amount of JSON data from a REST service.

At JSMpros, we teach all five options in our Integration Tools and Integration Tools Update courses. Check out our website for on-demand and live course offerings. Alternatively, subscribe to gain access to all of our on-demand courses.

Mock Service URLs for PeopleSoft Testing

 As you create, learn, and discover Integration Broker's capabilities, it is helpful to have mock APIs for testing purposes. Here is a list of my favorites.

• {JSON} Placeholder (REST: scroll to the middle to see the list of URLs)
• "Dummy" REST Api (REST: Employee services)
• Reqres (REST)
• CDYNE SOAP Services (Note: These often have "free for testing" license keys)
• Sample SOAP Server Time Service

Many of these services have secure and non-secure alternatives. The value of insecure testing is you don't have to import certificates. On the other hand, the secure versions help you prove your PeopleSoft certificate import skills.

Do you have some sample APIs you use? If so, please share them in the comments!

At JSMpros, we teach PeopleSoft REST and SOAP integrations regularly. Want to learn more? Check out our Integration Tools Update course to learn best practices and strategies for incorporating REST and JSON into your development process!

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!

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
   ...
   SQLExec(...);
   
   If (%SqlRows = 0) Then
      throw CreateException(0, 0, "Item not found");
   End-If;
   
   ...
end-method;

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>";
end-method;

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 ibupdate.jsmpros.com to see when we are offering our next Integration Course. Have a group of developers to train? Contact us for special group pricing!

Announcing PeopleSoft Integration Day! February 11, 2021

Announcing PeopleSoft Integration Day! Join me online Thursday, February 11, 2021 for a full day integration experience! Space is limited so register now!

Register Now!

Whether integrating with "The Cloud," Twilio, or Chatbots, odds are high you will use REST and JSON. With that in mind, we are excited to devote an entire day to sharing REST and SOAP integration strategies. Join us February 11, 2021 to learn about:

• REpresentational State Transfer (REST)
• JavaScript Object Notation (JSON)
• The Documents Module
• Producing and Consuming REST
• Testing tools, such as SoapUI
• Security, such as bearer tokens (JWT) and other authorization schemes
• Producing, consuming, and securing SOAP services

Who should attend this webinar?

• PeopleSoft Developers
• Project Managers
• Team Leads

The cost is $250 per person, which is nearly 70% off our standard daily rate. We are recording the event and are offering 60-days access to registered attendees. This is going to be so much fun! Bring your questions. We'll have time for Q&A. The Q&A panel will be available and monitored all day.

Do you have a group of 10 or more? Contact us at info@jsmpros.com for a quantity discount!

Register Now!

Announcing: Integration Tools Update Course

PeopleSoft Integration Tools is normally taught as a five-day introductory course designed to answer questions such as:

• What is Integration Broker?
• How do you configure it?
• What are Service Operations?
• How should I integrate with PeopleSoft?

But a lot of us already know the basics of Integration Broker. So last fall, we decided to add another course to our library: PeopleTools Integration Tools Update. This is a three-day class showing what's new with Integration Broker and covers topics such as:

• Producing and Consuming REST,
• Constructing Documents and understanding the role of Documents in integration,
• Creating structured and unstructured JSON responses,
• Understanding and implementing content negotiation,
• Responding to REST verbs,
• Using pre-built services such as Query Access Service,
• Securing integration points.

As we integrate Chatbots and Cloud solutions with PeopleSoft, it is critical that we understand PeopleSoft's modern integration capabilities.

Our next class begins April 14, 2020. Register now to reserve your seat!

How to Configure and Use Integration Broker

Integration Broker has become a critical service for PeopleSoft applications. If you are new to Integration Broker or are having trouble with Integration Broker configuration, then take a look at this new Integration Broker course published by my friends at CGI consulting. The course consists of an 84 page instructional PDF and a couple of source files. The course covers everything from configuration to using SoapUI. Here are some highlights:

• Setting up Integration Broker
• Publishing a CI based service
• Testing a web service (CI or otherwise) with SoapUI
• Calling a service from PeopleCode
• Application Class PeopleCode handlers
• Routing transformations
• JDeveloper XSLT Mapper
• App Engine Service Operation handlers
• And much, much more

One item I noticed that is NOT covered is creating custom listeners and targets using the Integration Broker SDK. Not to worry, though because I cover creating custom targets in my book PeopleTools Tips & Techniques.

The CGI Integration Broker course is a great read. I recommend downloading and saving a copy for future reference.

Going Mobile with PeopleSoft

Chapter 14 of my PeopleTools Tips & Techniques book walks you step-by-step through creating a mobile application. That chapter uses a CI based web service and Oracle ADF to demonstrate some of the simple drag-and-drop tools provided by Oracle. Even though the technique demonstrated appears simple, if you start to dig into the generated code and try to work directly with the Web Service Data Control, you will quickly see that JDeveloper does a very, very good job of hiding the real complexities behind web services. For this year's OpenWorld, I wanted to show just how simple it could be to create a mobile app for PeopleSoft. For my prototype, I chose to build a mobile worklist out of plain HTML, JavaScript, and CSS (it seems to me that plain HTML, JavaScript, and CSS is about as simple as web development gets). Without a server side technology like JDeveloper's ADF and JSF, I knew my mobile app would have to communicate with PeopleSoft using Ajax. As it turns out, most modern mobile browsers support XHR (as of BlackBerry 6, Torch, the BlackBerry browser is now WebKit - YEAH!!!), but I knew having a good mobile JavaScript library like jQuery would certainly help. A quick google search turned up xuijs, which happens to be modeled after jQuery. Using jEdit, my favorite syntax highlighting text editor, I prototyped the user interface, substituting Ajax URL's for local text files. After ironing out the server side requirements, I set about creating the Integration Broker App Class synchronous request handlers that my app would require. To make my HTML and JavaScript as simple as possible, I wrote my handlers to return data in JSON and JSONP format. While my JavaScript and PeopleCode may prove to be of some interest to you, I believe the most important concept from this exercise is the mechanism for calling Integration Broker from Ajax. To execute a web service from an HTTP GET (basic Ajax in REST-like fashion), you use a URL similar to:

http://your.peoplesoft.server/PSIGW/HttpListeningConnector?Operation=YOUR_OPERATION_NAME.v1&OperationType=Sync

Calling any service operation implies, of course, that you have a message, service, service operation, handler, and an any-to-local routing.

My point for sharing this is that we easily forget how simple an application can be. PeopleTools provides the integration architecture. It is up to us to pick a language we are comfortable developing with. If your organization prefers .Net over Java, then write your web based mobile app in .Net. The language doesn't matter. Pretty much any language can make an HTTP request to the Integration Broker and then process the response. The keys are:

• Knowing how to call Integration Broker
• Remembering that the mobile device has a much smaller screen

That is about all there is to building mobile applications. Pretty simple... right?

Base64 Encoding Binary Files

Several months ago I posted a handful of methods for base64 encoding strings. At that time I suggested that the next important step was base64 encoding binary files. This represents a challenge because PeopleCode does not offer methods for reading binary files. The following PeopleCode uses the Java API and the Apache Commons Codec library to show how to base64 encode a binary file. To run this example, download the commons-codec library and place the jar file in your local %PS_HOME\class directory. Next, create an App Engine with a PeopleCode step and insert the following PeopleCode:

Local JavaObject &f_in = CreateJavaObject("java.io.FileInputStream", "c:\temp\binaryfile.gif");
Local JavaObject &coder_in = CreateJavaObject("org.apache.commons.codec.binary.Base64InputStream", &f_in, True);
Local JavaObject &reader = CreateJavaObject("java.io.BufferedReader", CreateJavaObject("java.io.InputStreamReader", &coder_in));

Local string &b64Data = "";
Local any &line;

While True
   &line = &reader.readLine();
   If (&line <> Null) Then
      &b64Data = &b64Data | &line | Char(13) | Char(10);
   Else
      Break;
   End-If;
   
End-While;

Local File &b64File = GetFile("c:\temp\base64_encoded.txt", "A", "A", %FilePath_Absolute);
&b64File.WriteLine(&b64Data);
&b64File.Close();

The Java objects at the top of this listing read binary data from a file and transform that data into a base64 text listing, which is then stored in the variable &b64Data. For demonstration purposes, I wrote the contents of &b64Data to a file. In real life, you would add this contents to a CDATA node prior to sending a message through the Integration Broker.

Before running this code, replace c:\temp\binaryfile.gif with the full path to a real binary file on your workstation. After adding the PeopleCode listed above, disable restart and run your App Engine. When the App Engine completes, look in your local c:\temp directory for a file named base64_encoded.txt.