Recently, I had an opportunity to design a solution for my client where a new Constellation application would integrate with an existing UI-Kit (traditional UI) application via Pega APIs (out-of-the-box) to implement case management / routing / approval use case between the two very different UI design systems (Constellation=React based vs. UI-Kit=traditional server based).

This article introduces a common design pattern, which can be leveraged for a use case where two independent Pega applications with the two very different UI design systems need to work with each other seamlessly.

Pega Infinity version used: 24.1.3

Client use case

Client has an existing UI-Kit application that has been running in Production for several years.  They're considering to onboard a group of new users to Pega who will be assigned with a questionnaire to complete.  Their submitted answers will be reviewed by the existing UI-Kit users who will then either approve or reject them.  Once rejected, the questionnaire will be routed back to the responsible user.  This reject & rework process can be repeated until the answers are approved by the UI-Kit users.  Once approved, the UI-Kit application will continue with additional processing based on the answers captured.

Design approach

Our proposed approach is to build a new Constellation application to onboard the new users and create/assign them  questionnaire cases in Constellation (instead of onboarding the new users to the existing UI-Kit application and adding a new questionnaire case type to UI-Kit).  This new Constellation application will focus on authoring, routing, and answering a questionnaire and use Pega APIs (OOTB) to integrate with the existing UI-Kit application that will manage the rest of the business process.

Integration architecture

The integration architecture should be self-explanatory in the diagram below.  This model requires to build REST connectors to invoke Pega APIs.  We used Create REST integration wizard in Pega Platform to auto generate the REST connector and related integration rules (in Org-Int-** layer) and the data models including data page (in Org-Data-** layer), which handles the request/response mappings and the API invocation.  Generating the rules in the Enterpriser Layer will promote a broader reuse.

High-level implementations

Step 1 (Constellation) - A questionnaire author creates a questionnaire case type in App Studio.

A sample questionnaire:

We created a parent case type (Questionnaire Manager) that will create the questionnaire as a child case and manage the entire routing of the questionnaire case.  Note that 'Questionnaire' is a special case type that is mainly limited to questionnaire-related features, thereby the need to create the QM- parent case, which is a standard case type.

Step 2 (UI-Kit) - The UI-Kit application initiates the overall business process and is calling Pega API (POST /api/v1/cases) to create a new questionnaire case in Constellation.

Sub Manager (SUB-) is a standard case type created in the UI-Kit application, and this is responsible for initiating, reviewing and approving/rejecting the questionnaire.

The 'Create Questionnaire > API: Create questionnaire' step is referencing a data transform, which in turn references a data page that invokes Pega API (POST /api/v1/cases) to create a new questionnaire case in Constellation.

Data transform:

Data page:

Connect REST:

Here are the sample API request and response parameters.  Notice that, in the request, we passed the case type class name (XXX-SubGrantee-Work-QuestionnaireManager) defined in the Constellation application, and in the response, we received the pzInsKey of the new Questionnaire Manager case (QM-177) created on the Constellation side.  The new questionnaire case is created as a child case of QM-177.

Step 3 (Constellation) - Verify that the QM-177 case is created in the Constellation application and started its case life cycle.

As shown below, QM-177 is successfully created.  Also, notice that the UI-Kit Case ID (SUB-192) is passed from the UI-Kit application and displayed in the Constellation application.  This shows that we can seamlessly exchange information between UI-Kit and Constellation via Pega API.

QM-177 started its case life cycle successfully.  As shown below, the new child questionnaire case (S-29565) is created and assigned to "[email protected]" (=pyAssignedOperator is also passed in the API request from UI-Kit) while the parent QM-177 case proceeded to pause on the Wait step (until the child questionnaire case is completed).

Step 4 (Constellation) - Login as '[email protected]' Operator ID and complete the questionnaire case assigned.

'[email protected]' logs in and finds the new questionnaire case assigned.

The user completes the questionnaire and submits it.

Step 5 (Constellation) - Once the questionnaire is completed, QM-177 case proceeds to invoke Pega API (POST /api/v1/assignments/{ID}) to resume the waiting case on the UI-Kit application and waits on the 'Wait for approval' step.

'Questionnaire > API: Proceed to approval' step references a data page to invoke the Pega API (POST /api/v1/assignments/{ID}), which will resume the SUB-192 case workflow on the UI-Kit side.

This API also requires a query string parameter (actionID), and we're passing "pyContinueAfterWait" in order to resume the flow of SUB-192 case (UI-Kit) that has been paused on the Wait shape.

After invoking the Pega API, QM-177 case proceeds to the next Wait shape to wait for approval by the UI-Kit user.

Step 6 (UI-Kit) - Verify that the SUB-192 case workflow resumed on the UI-Kit side and proceeded to the next stage & steps in its case lifecycle.

SUB-192 case proceeded to the 'Approve > API: Get answers' step, which uses a data page to invoke Pega API (GET /api/v1/data/D_GetAnswers) to retrieve the answers captured in the S-29565 questionnaire case in Constellation.

D_GetAnswers is a data page provided by the Constellation application, which sources the questionnaire answers using a report definition.

The data page requires one parameter (InsHandle, which is the questionnaire case pzInsKey).

After retrieving the answers from Constellation, SUB-192 case proceeds to the Approve/Reject step that displays the questionnaire answers.

The UI-Kit user enters a reason and clicks the 'Reject' button.

SUB-192 case will now jump to the Rejected alternate stage, invoke the Pega API (POST /api/v1/assignments/{ID}) to resume the waiting QM-177 case on the Constellation side, and pauses on the Wait step (until the rework is done by the questionnaire user in Constellation and get notified via Pega API).

Step 7 (Constellation) - QM-177 resumes the workflow and jumps to the Rejection stage to reopen and reassign the questionnaire case (S-29565) to '[email protected]' and waits on the Wait shape (until the questionnaire is completed again).

Note: we used the Work-Cover-.reopenWorkObject activity API (OOTB) to reopen the questionnaire case.  (Before calling the activity, set param.ChangeToStage=Questionnaire)

As shown below, QM-177 case reopened the S-29565 questionnaire case and reassigned to the '[email protected]' user and paused on the 'Wait for rework' step.  Notice that the reject reason was also passed from the UI-Kit application.

Step 8 (Constellation) - '[email protected]' logs in and finds the reopened questionnaire case.

The user opens the questionnaire case and provides the requested information including a more detailed comment. 

(The audit history shows that this questionnaire case was indeed reopened and reassigned)

When the user submits the questionnaire case, QM-177 (parent) proceeds to invoke Pega API to route the SUB-192 (UI-Kit) case back to the Approve stage.  QM-177 then jumps back to the 'Wait for approval' step.

Note: we initially used POST /api/v1/assignments/{ID} to resume the SUB-192 case paused on the Wait step but it was throwing an unexpected error (I suspect a product glitch as it should have worked as normally).  Instead, as a workaround, we called GET /api/v1/data/D_ResumeCase API where the D_ResumeCase data page is provided by the UI-Kit application and references the Work-.ResumeFlow activity (OOTB) to resume the waiting workflow and move the SUB-192 case back to the Approve stage.  This shows that there are multiple ways to wake up a case waiting on a Wait shape.

QM-177 case now waits on the 'Wait for approval' step.

Step 9 (UI-Kit) - Verify that the SUB-192 case is now back to the Approve/Reject step with the updated answers.

UI-Kit user opens the SUB-192 case, reviews the update answers and approves.

Step 10 - Verify that all cases are now resolved in the UI-Kit and Constellation applications.

• SUB-192 (UI-Kit): Resolved-Completed

• QM-1177 (Constellation): Resolved-Completed

• S-29565 (Constellation): Resolved-Completed

Additional information

• In this example, we used Traditional Pega APIs using basic authentication due to a client-side limitation in Dev environment, but I would recommend using DX APIs using OAuth 2.0 authentication if feasible.
• We used Create REST integration wizard in Pega Platform to auto generate the REST connector rule, data models, and data page used to invoke Pega API.  We still had to update the response data transform rule to include necessary response mappings.