Table of Contents

Creating custom screens with the digital experience APIs

Pega Platform™ provides a robust and configurable user interface for your Pega applications, as well as mashup functionality that you can use to embed Pega frames in your non-Pega application.  In addition, Pega provides REST APIs that you can use to populate your non-Pega user interface with the results of Pega rules.  When you use the Pega REST APIs, your application users to access Pega business functionality in a familiar interface.

These REST APIs are known as digital experience APIs because they leverage Pega user interface rules (harnesses and sections) together with Pega business rules to return JSON-equivalent structures that you can render with your native interface.  By using the digital experience APIs, you can be guided by the Pega UI rules but not constrained by them. For detailed specifications of the digital experience APIs, refer to the Application category in the Pega API documentation.

For example, the following figures show a Pega application where the user enters an address for a new account, and an equivalent screen that was built with the React JavaScript library and is backed by the Pega digital experience APIs.

Thumbnail

Pega application screen and custom application screen built with React and Pega APIs

Common scenarios

The following examples use the digital experience APIs to build screens that enable users to do the following common tasks:

Pega user interface requirements

The digital experience APIs support Pega harnesses and sections that satisfy the following criteria:

  • Harnesses must use a Screen Layout as the top container, as shown in the following figure.
    Thumbnail

           Harness with top level screen layout

  • To enable the digital experience APIs to retrieve all of the relevant records of a case, the section pyNewCaseMain must be included. Use it with the New harness to prompt for all the fields of the case. Use it with the Review harness to display the fields as read-only.
  • Visibility expressions must consist of When rule references only.
  • Sections must be autogenerated.
  • Section rules must use one of the following layout options:
    • Dynamic layout
    • Repeating dynamic layout
    • Table
    • Embedded Section

Creating a case

Typically, the first step of case creation is to offer the user a list of case types from which to choose.  Use this API to get the case types for the current application:

  • GET /casetypes

Listing case types

Below is a sample response from GET /casetypes, which shows the MyCo-PAC-Work-ExpenseReport case type as requiring fields to be entered by the user on the case creation screen.

 "caseTypes": [ { "ID": "MyCo-PAC-Work-ExpenseReport", "name": "Expense Report", "CanCreate": "true", "pxObjClass": "Pega-API-CaseManagement-CaseType", "startingProcesses": [ { "ID": "pyStartCase", "name": "Add Expense", "requiresFieldsToCreate": "true", "pxObjClass": "Pega-API-CaseManagement-Process" } ] } ]

Response from GET /casetypes

The properties in this response that you are likely to use are described below.

CanCreate property

GET /casetypes returns all of the case types in an application.  This might include case types that the user can’t create directly.  You should filter the list of case types presented to end users so they see only the case types that they can create, which have CanCreate set to true.

A CanCreate value of true is equivalent to a selected check box in the Cases & Data tab in an application rule, as shown below. 

Thumbnail

Case type CanCreate is true for Passenger Vehicle on application rule

The CanCreate value also corresponds to the Show in ‘New’ menu check box on the Settings tab of Case Designer, as shown in the following figure:

Thumbnail

Case type CanCreate is false on case type rule for SUV

requiresFieldsToCreate property

Each case type returned from GET /casetypes also includes the requiresFieldsToCreate property, which identifies whether the user needs to enter values during case creation.   When requiresFieldsToCreate is true, the user must enter values in the case creation screen, which is also known as the New harness. A value of true corresponds to a cleared value for the Skip ‘Create’ view when users create a new case check box on the case type form, as shown in the following figure.

Thumbnail

requiresFieldsToCreate is true on case type

Showing the creation screen

When requiresFieldsToCreate is true, the next step is to show the creation screen.  To show the creation screen, use this API:

  • GET /casetypes/{caseTypeID}

The following example shows a portion of a response from GET /casetypes/{caseTypeID} for the MyCo-PAC-Work-Timesheet case type, when the case creation screen is populated from the creation_page element:

 { "caseTypeID": "MyCo-PAC-Work-Timesheet", "creation_page": { "pageID": "New", "appliesTo": "MyCo-PAC-Work", "visible": "true", "name": "Creation page", "groups": [ { "layout": { ... } } ] } }

 Response from GET /casetypes/{caseTypeID}

The information needed for the screen that creates the case is in the response element creation_page.  For more details about how to render a page, see The digital experience API request and response elements.

As the user fills out the creation form, it might be helpful to return to the server to see if any values entered require additional fields to be displayed.  In other words, if this had been a directly connected Pega interaction, a value the user entered could trigger a section refresh and a visible when.  

For example, consider an accident report.  The user enters the age of each witness.  For a witness whose age is under 18, additional fields should appear for specifying the witness’s parent.  To add fields, use the following API when the user enters a value and moves on to the next field (typically the ‘onblur’ HTML event): 

  • PUT /casetypes/{caseTypeID}/refresh

This API uses a PUT instead of a GET because your user interface will pass, in the post data, the values the user has entered in the content element.  The response is the same as for GET /casetypes/{caseTypeID}.

To submit the creation page form, call this API:

  • POST /cases

The fields on the creation page filled out by the end user are submitted as properties in the content element of the post data.

Skipping the creation screen

If requiresFieldsToCreate is false, then call this API when the case type is chosen to skip the creation screen and create the case:

  • POST /cases

The request body needs to specify a value for caseTypeID, but the content element can be empty, since this case type does not require any property values.

Return from case creation

Case creation returns the next assignment and next page properties, as shown in the following example:

 { "ID": "UARE-URTASKS-WORK B-10", "nextAssignmentID": "ASSIGN-WORKLIST UARE-URTASKS-WORK B-10!CREATION_FLOW", "nextPageID": "Perform", "pxObjClass": "Pega-API-CaseManagement-Case" }

Response from POST /cases

nextAssignmentID describes the identifier for the next assignment to show to the end user.  If the next assignment in the case flow is for a different user or is sent to a queue, this will typically be blank. 

nextPageID is the identifier for the next page to show to the end user; typically used when nextAssignmentID is blank. 

If nextAssignmentID has a value, then your custom screen should show the user that assignment.  See the section Choosing an assignment for more details.  If it is blank (for example, when the Confirm screen should be displayed), use nextPageID in conjunction with this API:

  • GET /cases/{caseID}/pages/{pageID}

The response to this API is identical to what appears under creation_page for GET /casetypes/{caseTypeID}; for example:

 { "pageID": "Confirm", "caseTypeID": "MyCo-PAC-Work", "name": "Confirm page", "groups": [ { "layout": { ... } } ] }

Response from GET /cases/{caseID}/pages/{pageID}

The example shows what can be built with this API by using the pageID “Confirm.”

Thumbnail

Bank application confirmation screen

See The digital experience API request and response elements for a detailed discussion on how to render a page.

Choosing an assignment

To enable a user to select an assignment, use either of the following APIs, which allow you to build a user interface for selecting an assignment: 

  • GET /assignments – Return a list of the current assignments for the current user.
  • GET /assignments/next – Return the next assignment for the current user.

After a user selects an assignment, your front-end user interface can call this API to get additional assignment details.  (The same information is returned in GET /assignments/next.)

  • GET /assignments/{assignmentID}

The GET /assignments/{assignmentID} API gives you the assignment’s related case identifier, as well as its list of actions, of which the first is the default.  After the user selects an action, you can put together a screen to show a form for completing the action, as shown in the following example:

Thumbnail

Screen for submitting a "create a bug" action

The preceding example uses the following APIs:

  • GET /cases/{caseID} – Build the stage display using the case ID
  • GET /assignments/{assignmentID} – Get the assignment instructions and list of actions
  • GET /assignments/{assignmentID}/actions/{actionID} – Display the view for the chosen action
  • PUT /assignments/{assignmentID}/actions/{actionID}/refresh – Refresh the form as fields are being filled out. The body content of the request is refreshed and returned in the response.
  • POST /assignments/{assignmentID}?actionID=[actionID] – Submit the form once completed. The body content of the request is refreshed and returned in the response.

GET /assignments/{assignmentID}/actions/{actionID} returns information about the selected action as shown in the following example:

 { "view": { … }, "caseID": "UARE-URTASKS-WORK B-9", "name": "Create a new bug", "actionID": "Create" }

Response from GET /assignments/{assignmentID}/actions/{actionID}

The view element contains the information needed to render a display for the action’s form.  For more about rendering views, see The request and response elements in the digital experience APIs.

Refreshing the form as it is being filled out is useful for reevaluating visible when rules and for refreshing repeating lists, just as it was with the creation page that was described earlier.

Submitting the assignment (using POST /assignments/{assignmentID}?actionID=[action name]) gives a response with the same properties as “POST /cases” to describe what screen to show next: nextAssignmentID and nextPageID.

To show additional gadgets for the case, such as the Pulse feed, the following API is useful:

  • GET /cases/{caseID}/views/{viewID}

Building a custom dashboard

You can build an entire dashboard by using the Pega digital experience APIs.

  • GET /assignments/next – Simulates a “Get most urgent” button to get the next assignment.
  • GET /casetypes – Builds a list of case types.  The case types that an end user can create have the CanCreate property set to true.
  • GET /cases/{ID}/pages/Review – Simulates a ‘find by ID’ textbox.
  • GET /data/Declare_pxRecents – Returns a list of recently accessed cases.
  • GET /data/D_OperatorID – Returns information about the current user.
  • GET /data/D_Worklist – Builds a worklist for the current user.
Thumbnail

Custom dashboard built using the digital experience APIs

 

Suggest Edit

100% found this useful


Related Content

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.