Component Interface Quality Audits

When you create a new CI Definition, Application Designer allows a number of inconsistencies that are not caught by its built-in validation and can lead to CI quality issues. The following SQL queries can be used to audit Component Interfaces for common quality issues related to menu registration, item property names, and collection names.

Run these queries to make sure your CIs are clean before you start writing or generating code against your CI ecosystem. If you are building a new CI from scratch, these audits fit naturally into step-level checks in The 10-Step Process for Developing PeopleSoft Component Interfaces .

Ensure Menu Registration

You always want to attach a menu to your CI definition. There can be menu-specific code that will not fire correctly if a menu is not attached. This is particularly important for Event Mapping , where a missing menu can silently prevent mapped PeopleCode from firing — see Find Component Interfaces with NO Menu Attached for the event-mapping angle on this same check. The following SQL will identify any CIs in your project that do not have a menu attached.

-- Make sure that a Menu name is attached to the CI.
-- Replace {{INSERT_YOUR_PROJECT_NAME_HERE}} with the name of your project.
-- SHOULD RETURN ZERO ROWS
select a.bcname,
       a.menuname
  from psbcdefn a
 where menuname = ' '
   and exists (
   select 1
     from psprojectitem b
    where  a.bcname = b.objectvalue1
      AND b.projectname = '{{INSERT_YOUR_PROJECT_NAME_HERE}}')
      ;

Ensuring CI Properties Match Record Fields

Component Interfaces expose records and fields from the underlying component as collections (records) and properties (fields). When you create a new CI definition, Application Designer may assign item names that do not match the underlying field names. The query below flags those mismatches so you can rename them.

-- Replace {{INSERT_YOUR_PROJECT_NAME_HERE}} with the name of your project.
-- Make sure Item Property Names match field name
-- This should return zero rows if all property names match field names.
-- Any Rows returned here indicate a mismatch between the property name on the CI item and the field name on the record.
--    In Application Designer right click on the property and rename.
SELECT * FROM PSBCITEM A
WHERE 
     fieldname <> BCITEMNAME AND BCTYPE <> 3

and exists (
   select 1
     from psprojectitem b
    where  a.bcname = b.objectvalue1
      AND b.projectname = '{{INSERT_YOUR_PROJECT_NAME_HERE}}')
      ;

The next SQL checks for collection names that do not match the underlying record name. This is important because it can cause confusion for developers using the CI and can lead to errors when trying to access properties on the CI.

-- Replace {{INSERT_YOUR_PROJECT_NAME_HERE}} with the name of your project.
-- Make sure Collection Names match Record names
-- This should return zero rows if all collection names match record names.
SELECT * FROM PSBCITEM  A
WHERE RECNAME <> BCITEMNAME AND BCTYPE = 3

and exists (
   select 1
     from psprojectitem b
    where  a.bcname = b.objectvalue1
      AND b.projectname = '{{INSERT_YOUR_PROJECT_NAME_HERE}}')
      ;

Reducing the Risk of Breakage Due to Changes in the Underlying Component

As a general guideline, you want to remove any fields from the CI that are not necessary for your integration. This reduces the surface area of your CI and makes it easier to maintain. Any time a code change by Oracle or your internal teams makes changes to the underlying component, it can potentially break your CI if it relies on fields that are not necessary for your integration. Removing unnecessary fields reduces this risk and makes your CI more resilient to changes in the underlying component. For a concrete example of how an Oracle-side change to a search record can silently break a CI’s Find method, see Component Interface Error — Unknown key of uninstantiated object .

You only need fields in the CI that you update through it or read from it. All other fields should be removed to reduce the risk of breakage and confusion for developers using the CI.

In particular, any fields that are read-only on the underlying record should be removed from the CI, as they cannot be set through the CI and will only cause confusion for developers using the CI.

Cleaning Up Read-Only Properties

Properties in a CI can be defined as read-only. These are generally things that are not needed at all for the purpose of the integration. There are some rare exceptions, such as creating a new person where you need the underlying component to return the new EMPLID, CRSE_ID, CLASS_NBR, or VOUCHER_ID. In such cases, you might need to keep that one field so your integration can read it. However, as a general rule, the read-only fields you want are at the very top level zero, and you typically don’t need any other read-only properties. Removing these reduces your surface area, so the first step is removing any read-only fields that are not needed.

-- Replace {{INSERT_YOUR_PROJECT_NAME_HERE}} with the name of your project.
-- Make sure to remove any read-only properties that are not needed for the integration.
-- This should return zero rows if all read-only properties that are not needed have been removed.
SELECT * FROM PSBCITEM  A
-- Read Only
WHERE BCACCESS = 2

and exists (
  select 1
    from psprojectitem b
    where  a.bcname = b.objectvalue1
  AND b.projectname = '{{INSERT_YOUR_PROJECT_NAME_HERE}}')
 ;

Collections and Properties Tied to Derived Records

Generally, in most Component Interfaces (CIs), you are interacting with underlying properties that are mapped to record fields existing in the database. These are the fields you are modifying to create entries or update records in the underlying CI.

When you create a new CI, often all the derived fields are included. These can range from related display labels from prompt tables to other elements that are not essential for the actual integration. These additional fields can increase the potential for errors when underlying code changes occur.

I typically remove all of these extraneous elements from the underlying CI. The general rule is that you should only include a derived record or derived field in the CI if it is necessary to manipulate that field. This could include a button that needs to be activated within a CI or a page that exposes a derived field for user interaction, which then triggers PeopleCode to transfer that field to an actual database-stored field.

These requirements are very specific to each CI, so it is crucial to thoroughly understand the underlying component to determine what is needed.

-- Replace {{INSERT_YOUR_PROJECT_NAME_HERE}} with the name of your project.
-- Make sure to remove any collections or properties tied to derived records that are not needed for the integration.
-- This should return zero rows if all collections or properties tied to derived records that are not needed have been removed. Any rows returned here indicate a collection or property tied to a derived record that can be removed from the CI.

SELECT * FROM PSBCITEM  A
WHERE BCACCESS = 2
and exists (
   select 1
     from psprojectitem b
    where  a.bcname = b.objectvalue1
      AND b.projectname = '{{INSERT_YOUR_PROJECT_NAME_HERE}}')
 and exists (

     select 1 from psrecdefn c where a.recname = c.recname and C.RECTYPE = 2
 )   
;

Missing Fields In the Underlying Record

When Application Designer creates a new CI from the underlying component, it does not always bring every field over from the underlying record. This may appear as a bug, but it has happened many times that a new CI is created without anyone noticing that not all of the field properties from the underlying records were inserted into the CI.

If the field is not in the CI, it cannot be updated. The SQL query below may also flag items that you intentionally omitted, so do not use it blindly.

There are times when a CI functions as a form of security. For example, if there is an integration that can update personal data but should not read or manipulate social security numbers, you would create a CI for that external integration partner and restrict them from updating those fields. There are other ways to secure this, but this is the general concept.

This SQL query will find CIs that expose a record where all fields from the underlying record are not present on the CI. Review this carefully and decide where you want to add fields.

-- Replace {{INSERT_YOUR_PROJECT_NAME_HERE}} with the name of your project.
-- Make sure all necessary fields from the underlying record are included in the CI.
-- This may return results that you actually want, so review carefully. Any rows returned here indicate a field on the underlying record that is not included in the CI. If that field is necessary for the integration, consider adding it to the CI.

SELECT
    BC.BCNAME          AS COMPONENT_INTERFACE,
    COLL.BCITEMNAME    AS COLLECTION_NAME,
    COLL.RECNAME       AS UNDERLYING_RECORD,
    RF.FIELDNAME       AS MISSING_FIELD,
    RF.FIELDNUM        AS FIELD_NUMBER,
    RF.RECNAME_PARENT  AS DEFINED_IN        -- subrecord origin if inherited
FROM PSPROJECTITEM PROJ
    INNER JOIN PSBCDEFN BC
        ON PROJ.OBJECTVALUE1 = BC.BCNAME
    INNER JOIN PSBCITEM COLL
        ON COLL.BCNAME = BC.BCNAME
       AND COLL.BCTYPE = 3                   -- 3 = Collection (scroll level)
       AND COLL.RECNAME <> ' '
    INNER JOIN PSRECFIELDDB RF               -- subrecord-flattened catalog
        ON RF.RECNAME = COLL.RECNAME
WHERE PROJ.PROJECTNAME = '{{INSERT_YOUR_PROJECT_NAME_HERE}}'
  AND NOT EXISTS (
        SELECT 1
        FROM PSBCITEM PROP
        WHERE PROP.BCNAME    = BC.BCNAME
          AND PROP.FIELDNAME = RF.FIELDNAME
          AND (
                (PROP.BCTYPE = 4 AND PROP.BCITEMPARENT = COLL.BCITEMNAME)
             OR PROP.BCTYPE IN (1, 2, 5)
          )
  )
ORDER BY BC.BCNAME, COLL.BCITEMNAME, RF.FIELDNUM;

Related Articles

• Criteria to Use Component Interface — decision criteria before building
• Should I Re-use an Existing Component Interface Definition or Create a New One? — scoping a new CI vs. reusing a delivered one
• Component Interface Error — Unknown key of uninstantiated object — a List Box Item gotcha that breaks the Find method
• Find Component Interfaces with NO Menu Attached — the event-mapping angle on the menu audit
• An Example of Using the CI Find Method — worked PeopleCode example of Find
• How to Change Search Records in Component Interface — when you need a different search record
• ScrollSort and Component Interface Lost Pointer — another silent CI failure mode worth auditing for
• Component Interface EditHistoryItems Gotcha — a property-level gotcha to watch for
• PeopleCode Events That Do Not Fire in Component Interface — event behaviors that change under CI
• Limitations of PeopleTools Component Interfaces and Web Services — broader boundaries to keep in mind