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.

3

The best practice is not to create a second connector just because the API is inconsistent. The real fix is to normalize the response into a consistent structure, because for a paginated collection the API should ideally always return an array, even when there is only one record. If the provider cannot change that, then in Pega you should treat it as a parsing-normalization problem, not as two separate integrations.

Recommended approach is to use one Connect-REST and map the raw response in a way that lets you inspect and normalize it before final mapping. A common workaround discussed in Pega is to map the varying JSON payload to a text property, then based on the structure convert it into the clipboard shape you want, for example always into a Page List with one or more rows.

and what you did I think is the right direction. Using a single Connect-REST and normalizing the payload before parsing is much cleaner than maintaining separate integrations for single-record and multi-record pages. It keeps the downstream mapping stable and avoids unnecessary branching.

Using pxConvertStringToPage after converting “value”: { … } into “value”: [ { … } ] is also a practical workaround, especially when the provider returns inconsistent JSON for the same paginated resource. Once the JSON is normalized, Pega can treat it as a consistent list structure and your existing mapping becomes reusable

About the runtime error, Your activity error is a standard rule resolution problem. The activity PROCESS_SINGLE_RECORD is being invoked in the context of INTLayer-SingleHR, but the rule is defined on the subclass INTLayer-SingleHR-FetchSingleEmployeeAPIImpl, so Pega cannot resolve it from the current primary class unless the calling context matches or the activity is placed on an ancestor/shared class. So to avoid that error, either define the activity on a class visible to the caller, such as INTLayer-SingleHR or call it from the correct primary page context/class or avoid the activity entirely and do the normalization in response mapping/data transform logic, which is the recommended approach.

For this scenario, I would recommend:

  • Do not create a second Connect-REST just for one-record pages
  • Do not branch to a separate single-record implementation class unless the API is truly a different endpoint
  • Use one connector and a normalization layer after the response
  • If possible, map raw JSON to text first, then parse/convert consistently into a Page List
  • Keep the final consumer of the data unaware of whether the source returned one record or many.