Sync versus Async Web Service Overview

As we will cover in-depth in their respective sections, there are 2 main interaction styles with web services.

• Synchronous
• Asynchronous

In this section, I want to discuss at a high level the difference between the two styles because this is often a point of confusion for someone starting new with web services in PeopleSoft.

There are different times when you create either a Synchronous or Asynchronous service. There are pros and cons to each side and there is no “correct” way to do it. It all depends on what you are building and the capabilities of the systems involved.

You also have consider if PeopleSoft is acting as the client (i.e. calling another web service) or the server (i.e. providing the web service).

• A Synchronous service is a request/reply where the providing server responds in real-time to the message call.
  • REST services can only be synchronous.
• An Asynchronous service is more like a “drop box” where the client sends a message and responds that the message was received. However, the processing of the message contents will happen at some later point.
  • PeopleSoft REST service cannot be asynchronous. However, you can implement a pattern that mimics asynchronous which we will discuss in other areas of this book.

Let’s take a look at each.

Asynchronous

Many of the delivered service operations from Oracle that synchronize data between different PeopleSoft systems are asynchronous. Some examples of these are:

• USER_PROFILE
• PERSON_BASIC_SYNC
• DEPT_SYNC
• DEPT_FULLSYNC

Yes these are asynchronous despite them having “sync” in their name. The “sync” stands for “synchronize”. So don’t get confused here.

These asynchronous services are often used to push events from one system to other systems. The other systems may not care about the contents of each individual message and may choose to ignore some when it gets around to looking at the contents. What are these events? They are updates to data in PeopleSoft components or batch processes. It could be that a new department was created or an effective dated change was made.

The “publisher” of these events just needs to write some code to create an asynchronous service operation. That event publishing PeopleCode does not know who (if anyone) will receive the messages. This is often written in SavePostChange PeopleCode. So you see in many instances of Oracle delivered code where there is publication code in SavePostChange PeopleCode. Depending on the system configuration, nothing may happen until you configure the routings to make the publishing system push those events. Oracle has designed these components to “emit” events so you can configure your PeopleSoft instance to notify other systems. The publication gets pushed to the integration broker and the broker determines who needs to receive the message. The component does not pause to wait for those publications to happen. They get put into a publication queue and will get pushed to the different systems at some point in the future. That is all handled by the integration broker. So in a PeopleSoft to PeopleSoft scenario, the publication of the events to the other systems is asynchronous because the actual communication to other systems is handled after the component saves. Additionally, the receiving side is also asynchronous because those systems will receive the message and put them in a queue for processing later.

Imagine that you have an HCM system and a Finance System. Let’s imagine that the HCM publishes the USER_PROFILE message from HCM to Finance. In the cases, below FIN is actually the provider/server and HCM is the client. Data updates occur (i.e. events) to the OPRID in HCM, and HCM will publish them to Finance.In PeopleSoft you can have a client “publish” a message to many providers. So let’s imagine you also have a Campus Solutions system that also needs to know about user changes. That can easily be added not by changing PeopleCode but by configuring a new routing to Campus. Again, the Campus database is actually the provider/server as well.

One thing I like about this model is that there is a complete separation between the code creating the events (SavePostChange PeopleCode) and the actual publication. As we will see in later sections, all the publication configuration is kept in the integration broker separately. There is also the ability to add different handlers to an operation to look at the message contents and determine based on the content where it should be published to. But I might be getting ahead of myself.

Asynchronous Provider

Let’s discuss creating a web service that is the asynchronous interaction style. Imagine that you need to provide a web service to a third party. So PeopleSoft is the server. The Asynchronous service is kind of like a “drop box”.

• When the client sends a message in, PeopleSoft will “store” the message content in some PeopleSoft IB tables and provide a response to the client that the message was received. However, PeopleSoft has not done anything with the message yet. This last point is extremely important to understand.

• The message is a request to potentially make something happen in PeopleSoft. At some point in the future, some handler code will get run to process the actually message content. The request sent by the client gets pushed to a “queue” and it will get processed when the integration broker has time to get to it.

• There is no guarantee that anything will actually happen with the message content.

  • There may be no handler code defined to run.
  • The queues could be paused and no action will be taken on the message.
  • Some administrator cancels the message.
  • An OnRouteReceive handler may inspect the message and decide it should not be processed.
  • The queue is very backlogged and it could take days for the message to be processed.

• The client has zero visibility into what happens to the message once it posts the message.

So based on these facts there are some specific use cases where you would use this style. The publishing side may be “emitting” events and PeopleSoft may care about some or all of those messages. However, they do not need to be processed in real-time as they are received. Since the process is queued up this style of messaging can scale pretty well with large numbers of messages.

Asynchronous Client

When PeopleSoft is acting as a client to an asynchronous web service again it is sort of like a drop box. PeopleSoft sends message to the web service provider and it gets an acknowledgement that the message was received but not yet processed. The only thing PeopleSoft knows is that the receiving system actually got the message. It has no idea what was done with the message if anything at all. You often get some sort of “message ID” that you can potentially use in another service to check the status of the request but that depends on the type of transaction it is and what the server offers.

Synchronous Services

Again, Synchronous web service in PeopleSoft are the typical “request/reply” message style where some code executes on the providing server while the client waits for a response. The client sends the “request” and “waits” until it gets a reply. This is very different from the asynchronous model. This is like a phone conversation where both sides must talk back and forth for a conversation to occur.

Synchronous Provider

If you are creating a web service for another system to act as the client and that client needs real-time information back then you need to go with synchronous service. Let’s imagine that you need to provide a web service to an external system that maintains email addresses for employees. That system may want to make a web service call to PeopleSoft when a new email address is created or changed. In this case, the web service may want to know if the update was successful before continuing. This is the request/reply model.

• The external system sends a request to PeopleSoft.
• PeopleSoft will take the request and process it while the client waits.
• Once the database is updated with the new email address, a response is given back to the client that it was successful.

You might also imagine a “query” service that runs some SQL against the database and returns information on the user. Imagine some sort of business expense system that needs to determine an employee’s HR information to determine if they have the proper authority to approve an expense report. The external business expense system may need to call into PeopleSoft using a web service to lookup the employee’s data. In this case you would want a synchronous web service.

Synchronous Client

When PeopleSoft is acting as a client to a synchronous web service, it will send some request to the external server and wait for a response. So imagine that you have some credit card processing web service that your PeopleSoft system was calling that was authorizing a charge. The end-user may be working with a page and some PeopleCode fires that triggers a back end web service call. The PeopleCode will “wait” for the external service to process the request and give a response. Based on the response of the web service, the PeopleSoft page may show a success or failure message and use the response data to update some data in PeopleSoft.

When to use Sync Versus Async

If you are going to be the client of a web service you don’t have a choice on how the interaction style is designed. So I don’t have a decision tree for you there. However, if you are creating new web service in PeopleSoft to other system to invoke then I can provide some guidance based on the points below.

• Does your client need the PeopleSoft data updated in real-time while it waits?
  • Yes - Use Synchronous
• Is your web service providing real-time queries of data in PeopleSoft?
  • Yes - Use Synchronous
• Will the system send a large amount of “events”/changes to PeopleSoft and they are “expensive” to process?
  • Yes - Use Asynchronous
• Do multiple pieces of code need to trigger in response to a message from a client?
  • Yes - Consider using Asynchronous with more than one handler.
• Does your client need a specific response message format?
  • Yes - Use Synchronous
• Do you have a “source” system that needs to notify many different systems about data changes?
  • Yes - Use Asynchronous because it has “fan out” functionality