The 10-Step Process for Developing PeopleSoft Component Interfaces

If you’ve worked with PeopleSoft long enough, you’ve seen it: a developer gets a requirement to load data, skips straight to writing PeopleCode, and burns two days fighting cryptic errors that would have been obvious with 30 minutes of preparation. Component Interfaces are powerful, but they punish you for skipping steps.

Over 20 years of PeopleSoft consulting, I’ve refined a 10-step process for CI development. I originally presented this in my Component Interface: A Developer’s Guide training. This post distills the process into a reference you can keep handy.

Why a Process Matters

A Component Interface wraps an entire component — all its business logic, field-change PeopleCode, defaults, validations, workflow, and messaging — and exposes it as an API. That’s the whole point: you get the business logic for free instead of replicating it with direct SQL.

But “wrapping a component” means every quirk of that component comes along for the ride. Fields that blank each other out. Grids that auto-generate dummy rows. Save validations that fire in a specific order. If you don’t understand these behaviors before you write code, you’ll spend your time debugging symptoms instead of solving the actual problem.

The process below front-loads the understanding so the coding phase goes smoothly.

The 10 Steps

1. Evaluate Whether CI Is Appropriate

Not every data operation needs a Component Interface. CI adds overhead — there’s a session connect, component buffer loading, and PeopleCode execution on every transaction. If the target component has minimal business logic (say, a simple lookup table with no field-change code, no workflow, and no validation beyond key uniqueness), a direct SQL insert or a CI-based approach might both work fine.

The more code that fires behind the component, the stronger the case for CI. Things that tip the scale toward CI: workflow triggers, Integration Broker messaging on save, complex field-change cascades, table structures where optional child rows only get inserted under certain conditions, and components that receive Oracle patches that could change underlying logic.

If you’d have to replicate 500 lines of PeopleCode to do the same thing with SQL — use the CI.

2. Become a Data Entry Expert on the Component

This is the step most developers skip, and it’s the one that costs the most time when skipped.

Before you open App Designer, open a web browser. Navigate to the component. Key data — the same data your program will be loading. Pay attention to everything:

• Which fields have prompt table validation?
• What field-change PeopleCode fires, and what does it set on other fields?
• What are the default values?
• Which grids already have a row waiting (the “dummy row”)?
• Do you need to insert rows, or use the existing dummy row?
• What happens when you enter bad data?
• Is there a required order for field entry?
• What does the save validation check for?
• Are you working in Add mode, Update/Display mode, or both?

Every component is different. The goal is to internalize the component’s behavior so that when you write CI code, you’re mentally simulating what the web user would do — because that’s exactly what the CI is doing under the hood.

3. Check for an Existing CI Definition

Before creating a new CI, check if one already exists. Open the target component in App Designer and do a Find Object References — if there’s already a CI defined against that component, you almost certainly want to reuse it.

The 1% exception: when calling a CI from a non-PeopleTools technology (Java, for example), you may have reasons to create a separate definition. Within PeopleTools code, reuse.

4. Create the CI Definition (If Needed)

If no CI exists, create one. The left pane shows the component structure; the right pane shows what the CI exposes. Drag fields from left to right as needed. Remember: new fields added to the component later do not automatically appear on the CI definition — you’ll need to drag them over manually.

5. Grant CI Security

CI security is granted on permission lists, not roles. The user whose session runs the CI code needs a permission list with access to that CI and its methods (Get, Create, Save, Cancel, Find).

This step gets missed constantly because developers test with a superuser account that has access to everything. Then the program fails when a real end user runs it. If you’re building an Application Engine that end users will execute, verify the security with a non-admin account.

6. Test with the CI Tester

The CI Tester (PeopleTools > Component Interfaces > Component Interface Tester) gives you a GUI view of the CI. Use it to:

• Confirm the CI definition isn’t corrupt (this still happens)
• Visually verify the structure — keys, properties, collections
• Attempt your target operation (create, get, update) and confirm you can save with a database commit
• See field-change effects visually (fields blanking out, defaults populating)

Do this before writing any PeopleCode. If it doesn’t work in the Tester, it won’t work in code, and you’ll have a much harder time figuring out why.

7. Plan Your Error Logging Strategy

Every error or warning that a web user would see on screen gets captured in the PSMessages collection. You need a plan for what to do with them.

Three standard approaches:

Log to a file — Quick and appropriate for one-time runs managed by a technical person. Just make sure someone actually reads the file.

Log to a table — The most scalable approach for recurring processes or non-technical users. Requires more development effort (staging tables, status fields, potentially a UI for reviewing errors), but pays off when you need reprocessing capability.

Log to the screen — Acceptable in narrow cases (a power user running a targeted operation), but never for self-service pages or batch jobs.

My default recommendation is table-based logging. Build a staging table with a status field (Ready, Success, Error, Do Not Load). When a row errors out, write the PSMessages text to an error field and set the status to Error. This lets users review failures, fix the source data, reset the status, and reprocess — without reloading the entire file.

8. Generate Template Code (But Don’t Trust It)

Drag the CI definition to a blank PeopleCode event. Save the generated template to a text file. That’s your reference copy.

The template is useful for two things: variable declarations and property names. Use it to copy Declare statements and property assignment syntax to avoid typos (PeopleCode is late-binding, so typos won’t surface until runtime).

Do not use the template’s logical structure. The template generates code that loops through existing collections — which makes no sense if you’re creating new data. It generates try/catch blocks that obscure control flow. It lays down a structure that rarely matches real business requirements.

Start from scratch. Let the requirements dictate your program’s flow. Pull individual lines from the template as needed.

9. Code the Application

With steps 1–8 complete, the actual coding is the straightforward part. You understand the component’s behavior, you’ve verified the CI works in the Tester, you know your error handling strategy, and you have the template for reference.

A few patterns worth internalizing:

Dummy row detection — Most CIs auto-generate a dummy row for each grid/scroll. Your code needs to detect and use the dummy row instead of blindly calling InsertItem. If you insert without checking, you’ll end up with a blank row and a data row — most components won’t accept that on save.

Create-then-Get fallback — When your requirement includes both creating new records and updating existing ones, try the Create method first. If it fails (because the key already exists), fall back to the Get method. This only works when the create keys and get keys are identical, which is component-dependent.

Cancel after Save — Every CI save must be followed by a Cancel before you can open the next record. Think of it as the CI equivalent of “Return to Search.”

10. Test, Rework, Test

Self-explanatory — but worth noting that CI testing should include negative cases. Feed it bad data. Feed it duplicate keys. Feed it records that trigger every validation on the component. Your error handling code gets exercised by failures, not successes.

The Terminology Bridge

One thing that trips up developers new to CI is the naming. The CI API uses its own terminology, borrowed from object-oriented conventions rather than PeopleTools conventions. Here’s the mapping:

Once this mapping clicks, PeopleBooks CI documentation becomes much more readable, and error messages like “Property DESCRIPTION does not exist” immediately translate to “the field isn’t on the CI definition.”