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.

  


    flowchart LR
        subgraph "3rd Party Client"
            C1["API Client"]
        end

        subgraph "Integration Broker"
            SO1["Create Service (Component Add Action)"]
            SO2["Find Service Op (Component Find by Row ID)"]
            SO4["Update Service Op (Component Update Action)"]
            SO5["UpdateData Service Op (Component Correction Mode Action)"]
        end

        subgraph "PeopleSoft"
            CI["Component Interface"]
            COMP["Component<br/>(Pages, Records,<br/>PeopleCode)"]
        end

        C1 --> SO1
        C1 --> SO2
        C1 --> SO4
        C1 --> SO5

        SO1 --> CI
        SO2 --> CI
        SO4 --> CI
        SO5 --> CI

        CI --> COMP
        COMP -. Changes propagate and Break upstream .-> CI
        linkStyle 9 stroke:red,stroke-width:2px;
        CI -. Rippled CI changes .-> SO1  
        linkStyle 10 stroke:red,stroke-width:2px;

• 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.
  • You generally need to expose a GET message of the underlying data structure to allow the client to understand the state of the data in order to know which method to call for updates. This is more work and also exposes more of the underlying data structure to the client.
• 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).
  • You may not realized the breaking change until you try to use the web service after a bundle or patch. This is a major risk of this approach.
• 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? This is a major risk of this approach.
• 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.
• Components that call COBOLs via RemoteCall are almost never a good fit for CI exposure. The typical pattern in these components is a button in the UI that triggers a DoSaveNow to commit data to the database, and then the COBOL runs against that committed data. This workflow does not translate to a Component Interface context because DoSaveNow does not execute the same way in CI, and the commit timing is controlled differently. Special handling must be built to work around this.
  • Real-world examples in PeopleSoft Campus Solutions include Quick Post, the Admissions components around program/plan stacking and application processing, and the Enrollment Request component. None of these can be directly exposed as CI-based web services without significant custom intervention. For more detail, see Problems with Component Interface and COBOL RemoteCalls .
• CI-based web services expose cryptic, difficult-to-interpret errors to external clients. The CI is fundamentally a raw data structure, and the errors it surfaces can only be meaningfully interpreted by someone who understands PeopleCode, the underlying component structure, and the data security model. This makes CI-based web services particularly hostile to third-party developers who lack PeopleSoft expertise.
  • For example, if a component enforces data security and the client submits data for a row that is hidden from the service account’s security profile, the CI may throw an error stating the record was “not found” when the record does exist but is simply not visible to that user. Similarly, complex components can reject data due to sequence-of-entry issues or invalid property combinations, surfacing errors that provide no actionable context to the caller. You often need to proactively check for error conditions before they are surfaced by the CI. With a shim/handler layer in front of the CI, these scenarios can be anticipated and translated into well-structured error responses that give clients the information they need for corrective action or escalation, and those error responses can evolve over time as you learn more about what callers need.

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.
• Components that trigger COBOL RemoteCalls from buttons or save processing (common in Campus Solutions areas like Admissions and Enrollment).

Alternative Approach

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

  flowchart LR
    subgraph "3rd Party Client"
        C1["API Client"]
    end

    subgraph "Integration Broker"
        SO["Single Service<br/>Operation"]

    end

    SO -.- NOTE2["This structure stays stable even when the underlying component and CI structure changes. It also allows you to buffer the 3rd party from changes in the underlying component and CI structure."]

        style SO fill:#28a745,color:#fff
       style NOTE2 fill:#f8f9fa,stroke:#28a745,stroke-dasharray:5
    subgraph "PeopleSoft"
        H["Handler / Shim<br/>PeopleCode"]
        CI["Component Interface"]
        COMP["Component<br/>(Pages, Records,<br/>PeopleCode)"]
    end

    C1 --> SO --> H --> CI --> COMP

    H -.- NOTE["`Buffers:<br/>• Error Handling<br/>• CI/Component Changes<br/>• Adds additional Business Logic<br/>• Hides Raw Data Structure`"]

    style H fill:#28a745,color:#fff
    style NOTE fill:#f8f9fa,stroke:#28a745,stroke-dasharray:5

• 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.
• Ability to provide well-structured, contextual error responses. The handler/shim code can anticipate common error scenarios – such as data security restrictions, sequence-of-entry issues, and invalid field combinations – and translate them into clear error messages that external clients can act on without PeopleSoft expertise.
• 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
• Strategies to Integrate with PeopleSoft
• Problems with Component Interface and COBOL remotecalls