Implementing case types using Digital Experience APIs for Pega Customer Service Case Management Edition

From PegaWiki
This is the approved revision of this page, as well as being the most recent.
Jump to navigation Jump to search

Implementing case types using Digital Experience APIs for Pega Customer Service Case Management Edition

Description Learn how to render a Customer Service case in an external desktop using Pega's Digital Experience APIs
Version as of 8.7
Application Pega Customer Service
Capability/Industry Area Service Cases / Tasks

In Release 8.7, you can implement a service case in an external desktop by using Pega's Digital Experience (DX) APIs with Pega Custoner Serivce Case Management Edition.


Many customer service applications include case management capabilities to route work across different teams and departments. What is missing is the seamless automation and execution of the actual work. Without a complete solution, the agents must toggle between screens to manage different processes. This leads to a disjointed experience and a channel journey breakdown that results in an unhappy customer experience.


Pega Customer Service Case Management Edition (CME) closes this gap by using a center-out business architecture strategy that leads to accelerated resolution. Case Management Edition enables you to embed Pega’s case management capabilities into your existing desktop and all your service channels. Although there are multiple ways to embed a case into another CSR desktop or web portal by using DXv1 APIs, two options were considered for leveraging Case Management Edition.

Recommended design methodologies[edit]

  • Parallel flows: Add the parallel process that is customized for the “External desktop” beside an existing flow for the Pega Customer Service desktop, the Interaction portal. This gives a unified view of the case life cycle and its ability to run in different channels. The parallel process is part of the core rulesets, similar to the corresponding Interaction portal flow.
  • Rebuild UX: This process involves rebuilding the UI/UX rules in a CME-specific ruleset to isolate the rules that are required for Case Management Edition. This ruleset is then added to the implementation application stack to render the version of the CME case type. This process includes maintaining the UI/UX rules that have been rebuilt in this separate ruleset so that there is a clear line of separation and easier implementation for Case Management Edition users.

Implementing case types[edit]

This section describes how to implement case types by using DX v1 APIs. In the example, the React starter pack was used.

Step 1: Identify the UI framework[edit]

Developers who prefer to use other modern UI frameworks such as React and Angular can leverage open APIs to dynamically use Pega design capabilities as a REST-enabled service to power their front-end UI framework of choice.

For this example, download the React starter pack from Pega Marketplace.

Capabilities of the React starter pack[edit]

For the CME case type implementation, the React starter pack component was used. It provides a Case Worker portal that is built with a React framework that communicates with Pega Infinity by using the Pega Digital Experience APIs.

For the latest list of supported controls, layouts, and action sets, see the file under your React starter pack installation directory in

…\ pega-react path.

To view the implementation notes and key release updates, see ...\pega-react\docs.

Step 2: Add the CME ruleset[edit]

Add the CME ruleset to the Customer Service implementation application stack, which was created and included in Release 8.7 and above.

Step 3: Establish the connection[edit]

Establish the connection between the UI framework and the Pega instance by setting the endpoints. In the React starter pack, set the endpoints in the endpoints.js file, as shown below:

Step 4: Set the context for the service case[edit]

For an external desktop agent to launch any service case, the context for the customer and account is required.

If you are using the React starter pack, set the context as highlighted below by passing the context parameters in the application settings on the home page of React:

Step 5: Update authentication and authorization settings[edit]


When using DX v1 APIs, the “api” service package is used, which offers the following three types of authentication:

  •     Basic
  •   OAuth 2.0
  •    Custom

Based on your requirement, update the api service package accordingly.

You can invoke the Pega API REST services by using HTTP or HTTPS. Although the use of secure HTTPS is recommended for test and production environments, if an HTTP URL is used for testing, ensure that you clear the Require TLS/SSL (REST only) checkbox in the service package rule.


Ensure that you include the PegaRULES:PegaAPI ruleset in the operator’s access group.

Note: To use screen flows and the Back and Next buttons, you must use v2 APIs. Ensure that you also make the required changes to the “applicationservice package when using v2 APIs. Use the same authentication mechanisms for both v1 and v2 APIs.

For information about security settings in DX API, see Security settings for DX API.

For information about the supported capabilities of the DX API v1, see Supported UI capabilities.

Common observations with v1 DX APIs[edit]

Feature Comments   Recommendations
Property validations When you are using v1 APIs, and you save a case, page validation occurs (this does not occur if the case is created by using the Interaction Portal).   Ensure that the case data adheres to the property validations.
Pre-processing in flow actions In a stateless architecture, avoid setting any fields that are not managed through the UI. This data is not committed to the case and is missing in subsequent requests. Invoke the pre-processing data transform in the flow by using the Run data transform shape.
Named pages Avoid using temporary pages because these pages will not be available for the API call that is used to fetch the section metadata for the specified assignment. Copy the temporary page data to a page property.
“Use page defined on property” or “Use data page” as page context For any embedded section, the use of page defined on property or data page is not suitable for a stateless architecture.   Use the clipboard page or the current page context.
Visibility conditions using expressions If you use expressions as visibility conditions in sections, it does not work as expected.   Change the visibility condition from expression to a when rule.
Default values in section Parameterized data pages as default values for any control in a section is currently not supported by API Set the value by using the Run data transform shape in the flow.
Support for master details in table layout Master details options such as modal dialog or expandable rows are not supported by v1 APIs in Pega 8.7 Add an embedded section in the rows of the table to display additional details.
Support for circumstancing   Circumstancing is not supported by v1 APIs Avoid circumstancing.

Common observations with React starter pack[edit]

Feature Comments   Recommendations
Layout support List of supported layouts are available in the file. Rebuild the UI for a better user experience by using the supported layouts.
Control(s) support   List of supported fields are available in file. Rebuild the UI for a better user experience by using the supported controls.
Actions List of supported actions such as refresh section, post value, and set value are available in the file. Rebuild the UI for a better user experience using the supported actions.
Dashboard widgets Currently, work list and work queue widgets are available. If you need to add a custom widget, modify the React starter pack accordingly.

Out-of-the-box case types available in Case Management Edition[edit]

Several Wiki articles are available with details of the design methodologies and the changes that were made to existing case types so that they work with v1 DX APIs and can be rendered in a React starter pack. For more information about how to render the case types in the React starter kit, click the link in the following table to view the specified article.

Application Case type Design methodology Wiki article
Pega Customer Service for Communications Add Mobile Device Rebuild UX Implementing Add Mobile Service for Pega Case Management Edition
Pega Customer Service for Healthcare Claims Inquiry Rebuild UX Implementing Claims Inquiry for Pega Case Management Edition
Pega Customer Service for Healthcare Patient Assistance Parallel flows Implementing Patient Assistance for Pega Case Management Edition
Pega Customer Service for Financial Services Replace Card Rebuild UX Implementing Replace Card for Pega Case Management Edition
Pega Customer Service for Financial Services Fee Inquiry Parallel flows Implementing Fee Inquiry for Pega Case Management Edition
Pega Customer Service for Insurance Personal Auto Claim Rebuild UX Implementing Personal Auto Claim for Pega Case Management
Pega Customer Service for Insurance Change Beneficiary Parallel flows Implementing Change Beneficiary for Pega Case Management
Pega Customer Service Make Payment Rebuild UX Implementing Make Payment for Pega Case Management
Pega Customer Service Statement Copy Rebuild Implementing Statement Copy for Pega Case Management

Common Issues and workarounds[edit]

The following table lists the common issues and workarounds:

Common issues and workarounds
Issue Reason Workaround
The read-only grids display the Add/delete button. This behavior is the same in all screens wherever read-only grids are used. An issue in the React starter pack version 1.4. There is no functionality attached or required with these buttons for the read-only grid. You can remove these buttons by deleting the <Table.Footer> element from the PegaForm.js file in the React starter pack installation.
Binary files are not supported Binary images and standard icon options are not supported in the React kit and only icon class are supported to configure any icon on the UI. Use icon classes.
Using a text area to enter comments for each selected claim in a modal dialog is not possible in the grid layout. Modal dialogs, which accommodate a larger text area to enter comments, are not supported in DX API v1. Introduce an editable comments cell in each row to capture notes.
The Confirm harness will not be rendered in DX API v1 due to lack of support for circumstanced rules. The new Confirm harness is a circumstanced rule. The Confirm harness has been customized for Case Management Edition in the CME ruleset so that it displays as expected for all service cases and for all appropriate channels.


This section provides information about how to handle issues that you might encounter during your implementation.

  • Update the DebugPegaAPIc dynamic system setting to true in order to log additional fields in the Pega API Rest Service Info statements.
  • Use the browser network logs to check the request response for a particular API. APIs can be traced in the Pega application.
  • If the service response status code is 400 (which can be identified by using browser developer tools), trace the service to understand more about the failure. To understand the sequence of services invoked, see Calling sequences for DX API endpoints.
  • While it is always recommended to understand the root cause of the server or API slowness, you can increase the timeout in the React starter pack by updating the path in .. \pega-react\src\_helpers\axios.js


You can embed Pega’s out-of-the-box case types into external desktops by leveraging the DX v1 APIs and making suitable changes in the UX. This requires little effort with significant outcomes leveraging Pega Case Management in a client UI of choice.