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 and later
Application Pega Customer Service
Capability/Industry Area Service Cases / Tasks

In Release 8.7 and later, you can implement a service case in an external desktop by using Pega's Digital Experience (DX) APIs with Pega Customer Service 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 pages to manage different processes. This process leads to a disjointed experience and a channel journey breakdown that results in an unhappy customer experience.


Pega Customer Service Case Management Edition closes this gap by using a center-out business architecture strategy that leads to an 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

To better understand the design methodologies, refer to the following information:

For the external desktop CSR flow that is discussed in the Primary stages in the Customer Service generic template section of the Pega Customer Service Implementation Guide, extend the CaptureCaseDetails process as needed. Extension points are available in the case template to extend the flows in the service case layer.

Rebuild UX: This process involves rebuilding the UI/UX rules in a CME-specific ruleset to isolate the rules that are required for Pega Customer Service Case Management Edition. This ruleset is then added to the implementation application stack to render the version of the Case Management Edition case type. The 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.

Parallel flows: Create a specialized (parallel) flow for the external desktop and rebuild the UX so that it complies with the v1 APIs. This flow is invoked when a case is launched or processed by using DX APIs. In the event that the solution supports both an external-CSR desktop and the Interaction Portal, there are two parallel flows: one for the external-CSR desktop UI and another for the Interaction Portal UI as applicable. You can place the code constructs in the same ruleset or application because the flow that is used for the DX APIs is different from the base flows (Interaction Portal).

Using parallel flows for a self-service application

If you are building a self-service application, ensure that you build it on the implementation application (Case Management Edition application).

The following is an example of creating a self-service flow for a case type by using a parallel flow.

Create a parallel flow for a self-service application (customer view)

Create a parallel flow for a self-service application and rebuild the UX for the customer view based on the case type requirement. Because the customer and CSR views are different for a case type, a parallel flow is beneficial.

Configuring the parallel flow

  1. In the navigation pane of App Studio, click Case types, and then click the required case type.
  2. Add the customer flow as a parallel process in the Intake stage. This process takes inputs from the customer based on the case type. Actions menu.jpg
  3. Click the More options menu to add a parallel flow for the self-service users (customers).
    Self service.jpg
  4. Select Add parallel process > New process. It creates a new flow in the background with a specified name. Because it is specific to a customer, you need to add a condition. Use the IsThisSelfService When rule for the parallel flow as specified in the following figure. Note: To display the IsThisSelfService When rule in App Studio, mark the IsThisSelfService When rule in the context of the service case class. Add flow.jpg
  5. To design the self service flow (adding pages and processes), click the Flow icon as highlighted in the following figure: Flow.jpg
  6. Configure the customer flow with the required pages, and then click Save to commit the changes.

Back Office Portal

As part of Case Management Edition, the Pega Back Office Portal is also available for customers use. For more information about the Back Office Portal, see What's new for portals.

Implementing case types

This section describes how to implement case types by using DX v1 APIs.

Step 1: Identify the UI framework

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

Step 2: Add the Case Management Edition ruleset

Add the Case Management Edition ruleset to the Customer Service implementation application stack, which was created and included in Release 8.7 and later. Ensure that you locate your base application in the following table and add the corresponding rulesets to your implementation application.

Base application Ruleset stack
Pega Customer Service PegaCS-Cases-CME
Pega Customer Service for Communications PegaCSC-Cases-CME


Pega Customer Service for Financial services PegaCSFS-Cases-CME


Pega Customer Service for Insurance PegaCSIns-Cases-CME


Pega Customer Service for HealthCare PegaCSHC-Cases-CME


Add the PegaCS-Cases-CME ruleset, and then add the implementation-specific Case Management Edition ruleset as shown in the previous table.

If you are implementing the self-service application by using Case Management Edition, then build the self-service application on the implementation application that has the Case Management Edition rulesets that are listed in the previous table.

Step 3: Establish the connection

Establish the connection between the UI framework and the Pega instance by setting the endpoints.

Step 4: Set the context for the service case

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

Step 5: Update authentication and authorization settings


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 “application” service 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

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.

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

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 Pack, click the link in the following table to view a specific 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

The following table lists the common issues and workarounds:

Common issues and workarounds
Issue Reason Workaround
The read-only grids display the Add and Delete buttons. This behavior is the same in all screens wherever read-only grids are used.

This issue was fixed in React Start Pack 8.8. However, if you are using Pega Case Management Edition 8.7, you must make modifications to the React Starter Pack.

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 Starter Pack 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.

  • To log additional fields in the Pega API Rest Service Info statements, update the DebugPegaAPIc dynamic system setting to true.
  • 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.