Should You Expose a Component Interface as a Web Service

PeopleTools has the ability to expose a Component Interface (CI) as a web service. Here are a few places where you can read about that:

• The PeopleSoft Wiki site has a good article on creating Component Interface based Web Services
• Of course, there is also the PeopleBooks section called Creating Component Interface-Based Services

Those are great articles. You should read them and have this in your toolbox. What I want to cover in this essay is “Should you do expose a CI as a web service?”. In my opinion, the short answer is: No you should not.

As with any technical approach, there are pros and cons to taking a certain path. At first glance it might sound like a good idea and a quick fix to take a CI and expose it as a web service. However, after reflecting on some of the detail of this approach, you may give it a second thought.

Pros of Exposing CI as a Web Service

• It is a quick win to expose some functionality to a third party.
• For existing CI definitions, new web services can be exposed without writing any code.
• It requires very little knowledge of PeopleSoft web service configuration steps and configurations like messages, services, routings, etc.

Cons of Expose CI as a Web Service

• When you expose one CI, it actually does not generate one web service. It generates many different service operations. One for each CI method: Create, Find, Get, Update, UpdateData, User Defined. Additionally, each of these service operations has their own message names.
• Because the raw data CI methods are exposed, the client has to understand the state of the PeopleSoft component data to know what method to call. For example, in an effective dated component the client would have to know if the current effective dated rows exists so that it knows if it needs to call the “update” or “updatedata” (correction mode) web services.
• This approach exposes the raw data structure of a component to third party. With every change of a field or record name in the underlying component that may impact the message schemas for the web services. It can also break the web service-to-CI linkage (see PeopleBooks).
• Subtle changes by Oracle Support during patches can impact your third party adversely. For example, when oracle adds fields, removes fields, or adds scroll levels. Let’s say they add a new required field to the component. This may break your 3rd party code.
  • It can be almost impossible with PeopleTools technology and Oracle documentation practices to understand downstream impacts of component changes. There is nothing in the development technologies that gives you a clear picture that changing “x” will impact “y” web service. Or applying bundle “12345” will have 15 impacts on a,b, and c objects. Yes there are some tools to do this research but they are not perfect.
• Since patches and bundles can impact the structure of the CI-based web services invoked by a third party, the third party code will have to change its API client at the same time of your bundles. This causes two independent systems to be more tightly coupled. What happens when that third party has different development time-lines as your PeopleSoft team or that 3rd party is a ghost ship with no one supporting it?
• You can’t add error handling code or shim code to fix issues and add functionality.
• Since you do not create the handler code, you cannot add additional logic to the web service to buffer the external system from changes.
• It can be hard using the CI web services to manipulate complex component structures. This really only works for extremely simple components.

When It May Be a Good Idea

• For custom components and CI that have you control over and are not impacted by bundles from Oracle.
• For very simple components without effective dating or 2nd or 3rd level scrolls/grids.

When It Is NOT a Good Idea

• Components that are likely to change during bundles and patches.
• Complex components with several scrolls or grids.
• Components with effective dating.
• Integration scenarios where the client code needs to update 2nd and 3rd level scrolls/grids only.

Alternative Approach

When integrating with a 3rd party here is what I always recommend.

• I generally like to expose only a “get” operation and one operation that handles creates, updates and correction mode updates. So 2 web services in total.
  • The update/create/correction service operation handler can buffer the third party from having to know the state of the data. The third party can send in the data and the handler code can determine if the data exists already and perform an add (create), update, or correction (updateData).
• Determine a simple data structure with only the fields that the client code knows about. I don’t like to burden the 3rd party with esoteric PeopleSoft fields that can be defaulted or pulled from a configuration table.
• Use the above data structure to create a custom message and service operations with the minimal amount of fields for the integration.
• Write a service operation handler to actually handle the inbound request message to perform the desired action: “get” or create/update.
  • This is what I refer to as “shim” code as it acts as a buffer between the raw PeopleSoft data/CI structure and the third party. Since this handler code is written in PeopleCode and controlled by the PeopleSoft team, they can coordinate bundle changes that impact the behavior of the structure a component interface and not burden the third party with those changes.
  • This handler/shim can also contain business logic about that component that the third party may not need to know about. Do you have a specific business unit that has a different way of updating the component than the others? Is there some legacy data that should ever be touched? Is there a special logic around the first effective date that should be used? That logic can be owned by PeopleSoft instead of the 3rd party.

The end result of this alternative approach is:

• Less risk of bundles/patches/customization in PeopleSoft breaking the integration with the 3rd party.
• Provide a more stable API interface for 3rd party.
• Less logic on the 3rd party about how to update the PeopleSoft data. (Most 3rd parties do not understand PeopleSoft.)
• One web service was delivered to perform creates/updates/corrections where as the CI exposed as web service would have created many different operations.
• Less risk that configuration and business process changes in PeopleSoft will impact the third party as handler/shim code can absorb those changes.

Additional Reading

• Information Hiding
• Law of Demeter
• Synchronous HTTP Post to PeopleSoft Integration Broker using Python