Handling Pagination Edge Case: Single Record Returned as Page Instead of List in Connect‑REST

General
1

Hi Team,

We are consuming an external REST API in Pega where records are returned using pagination.

Observed behavior:

  • When a page contains multiple records, the response element is returned as a list.

  • When the last page contains only one record, the same element is returned as a single page instead of a list.

  • This causes parsing issues in Pega as the structure changes dynamically based on record count.

Current Design (Dummy Class Names)

INTLayer
├── HRData
│   ├── FetchEmployees
│   ├── FetchEmployeesAPI
│   ├── FetchEmployeesAPI_Query_GET
│   ├── FetchEmployeesAPI_Request
│   └── Value
└── SingleHR
    ├── FetchSingleEmployeeAPIImpl
    ├── FetchSingleEmployeeAPI
    ├── FetchSingleEmployeeAPI_Request
    ├── FetchSingleEmployeeActivity
    └── Value

Proposed Handling

  • We identify that the last page contains a single record.

  • In this case, we invoke an Activity defined under the single‑record API implementation class (e.g., FetchSingleEmployeeAPIImpl) to handle the different response structure.

Issue Faced at Runtime

When invoking the activity, we receive the following error:

Failed to find a 'RULE-OBJ-ACTIVITY' with the name 'PROCESS_SINGLE_RECORD' 
that applies to 'INTLayer-SingleHR'.

There were 2 rules with this name in the rulebase, but none matched this request.
The rules were defined on subclasses:
- INTLayer-SingleHR-FetchSingleEmployeeAPIImpl

Questions

  1. What is the recommended way in Pega to handle REST responses where the same element sometimes comes as a list and sometimes as a single page, especially in pagination scenarios? It has 181 properties that are being returned for each record.

  2. Do we need to implement a separate Connect‑REST for single‑record responses, or is there a best practice to handle this dynamically within the same integration?

  3. How should the Applies‑To class and activity placement be structured to avoid the class‑resolution error shown above?

  4. Are there any OOTB Pega patterns or mapping techniques (e.g., data transforms, response mapping, or parse strategies) recommended for this scenario?

Any guidance or best practices would be greatly appreciated.

Thanks in advance.

2

We were able to identify the fix for this one as below.

Normalize the response structure before parsing so that the element is always treated as a list, regardless of the record count.

What Worked Reliably

  1. Use a single Connect‑REST

    • Do not create separate integrations for single vs multiple records.

    • Avoid branching logic based on record count.

  2. Normalize the response

    • If the response contains:

      JSON

      “value”: { … }

      convert it to:

      JSON

      “value”: [ { … }

    • If it is already a list, leave it unchanged.

  3. Parse using pxConvertStringToPage

    • Call it via Activity → Java step (Method = Call).

    • Pass a Page (not a Page List) as the target.

    • Pass the normalized JSON array string as input.

    • Pega automatically creates a Page List from array JSON.