Table of Contents

The digital experience API request and response elements

Understanding the request and response elements of the digital experience REST APIs is key to building a native user interface.  For more information, with examples, see Creating custom screens with the digital experience APIs.  The Pega API specification also provides details of the APIs that are shown under the Application category.

You can jump ahead to these sections:

Pages and views

The page element in a response body represents a full screen, and is built from a harness rule.  The value in the name property is the identifier of the page or harness. 

The view element in a response body represents part of a screen, and is built from a section rule.  The value in the viewID property is the identifier of the view or section. Some views represent an action form for the end user to complete.  Other types of views might be informational (for example, an audit trail) or functional (for example, a place to enter notes about the case).  A view can contain other views, just as a section can contain embedded sections. 

APIs that take an action parameter build the response from a flow action rule.  

When you build a custom user interface with the digital experience APIs, you can use the Live UI tool as you create and process cases in a Pega test environment.  Live UI shows you the page and view identifiers that you need as parameters for the APIs.

The following APIs return a page, or harness:

  • GET /casetypes/{case type ID} –  Returns the New harness in the creation_page element.
  • PUT /casetypes/{case type ID}/refresh – Refreshes and then returns the creation_page element, or New harness.  The body content of the request is refreshed and returned in the response.
  • GET /cases/{case ID}/pages/{page ID} – Returns the indicated page (harness) from the indicated case.  Some commonly used pageID values are Confirm, Review, and so forth.

The following APIs return a view, or section:

  • GET /assignments/{assignment ID}/actions/{action ID} – Returns the action’s section in the view element.
  • PUT /assignments/{assignment ID}/actions/{action ID}/refresh – Returns the action’s section in the view element. The body content of the request is refreshed and returned in the response.
  • GET /cases/{case ID}/actions/{action ID} – Returns the action’s section in the view element.
  • PUT /cases/{case ID}/actions/{action ID}/refresh – Returns the action’s section in the view element. The body content of the request is refreshed and returned in the response.
  • GET /cases/{case ID}/views/{view ID} – Returns a view (section) for a case.

The main building blocks of pages and views are groups and layouts.  A group is a set of related properties and other elements, and the layout within describes how they should be arranged.

Sample application

The following sample application, named UR Tasks, creates an instance of the Bug case type.  It illustrates how to use these APIs.

View, layout, and field elements

The following view is where the user creates a Bug case by using the sample application in a Pega test environment:

Thumbnail

Create a new bug view

The section rule that generates the view:

Thumbnail

 Create a new bug section

Top-level element

The following sample shows the structure of the top-level block that is returned from GET /assignments/{assignment ID}/actions/Create:

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

Top-level element in response from GET /assignments/{assignment ID}/actions/Create

The value of caseID is the assignment’s case; the other properties are built from the flow action, as shown in the following figure:

Thumbnail

Mapping from flow action rule to the top-level element

View element

The following sample shows the structure of the top-level view element when you create a new bug:

 "view": { "reference": "", "validationMessages": "", "viewID": "CreateTest1", "visible": true, "name": "CreateTest1", "appliesTo": "UAre-URTasks-Work-Bug", "groups": [ … ] }

 View element

The reference value is generally blank for a top-level view, as is validationMessages for the initial display.  The other properties are built from the section rule, as shown in the following figure:

Thumbnail

Mapping from section rule to the view element

Layout element

The top-level groups array has only one element, a layout, as shown in the following example:

 "layout": { "visible": true, "groups": […] "groupFormat": "Inline grid double", "layoutFormat": "SIMPLELAYOUT" }

The layout element within the groups element

The layout element that is returned from the API corresponds to the top layout of the section, as shown in the following figure:

Thumbnail

Details of the section rule

The supported layouts return the following values in the layoutFormat property:

  • Screen Layout – SCREENLAYOUT (for the top level of pages)
  • Dynamic Layout – SIMPLELAYOUT
  • Repeating Dynamic Layout – REPEATINGROW
  • Table – TABLELAYOUT 

The groupFormat value, which describes how the group is formatted, depends on the type of layout.

The Bug layout and the Followers layout are returned in two layout elements under groups, as shown in the following example:

 "groups": [ { "layout": { "visible": true, "titleFormat": "h2", "groups": […], "groupFormat": "Stacked", "layoutFormat": "SIMPLELAYOUT", "title": "Bug" } }, { "layout": { "reference": "Followers", "sourceType": "Property", "fieldListID": ".Followers", "referenceType": "Group", "header": { "groups": [...] }, "testID": "201805150916060124116", "groupFormat": "Grid", "readOnly": false, "layoutFormat": "REPEATINGROW", "title": "Followers", "rows": [] } } ],

Bug layout and Followers layout

In this example, the values in the Bug layout are built from the layout in the section rule, as shown in the following figure:

Thumbnail

Bug layout mapping

The values in the Followers layout are built from the layout in the section rule, as shown in the following three figures:

Thumbnail

Followers layout mapping (1 of 3)

Thumbnail

Followers layout mapping (2 of 3)

Thumbnail

Followers layout mapping (3 of 3)

Field element

The layout element contains field elements, which contain properties that are shown on the screen in various types of controls.  In the following example, the Bug Description text area is shown:

 "field": { "validationMessages": "", "visible": true, "labelReserveSpace": true, "readOnly": false, "control": { "modes": [ { "controlFormat": "Standard" } ], "actionSets": [], "type": "pxTextInput" }, "label": "Bug Description", "type": "Text", "required": false, "reference": "BugDescription", "labelFormat": "Standard", "testID": "2018032908342404285ff0e7b0-2ec9-48be-bd1a-6ec106332f3351", "value": "", "maxLength": 0, "expectedLength": "", "fieldID": "BugDescription" }

Field element for the bug description text area

The values within the field element are built from the control properties, as shown below.

Thumbnail

Mapping from a text input control to a field element

All types of controls can be returned as field elements and include the following properties:

  • controlFormat – A style for the control.
  • mode – A container element for additional information about the control.

Some control types include additional values.

The pxAutoComplete, pxDropDown, and pxRadioButtons controls also include the following values:

  • listSource – The source of the choice values: promptlist, locallist, or datapage
  • When the listSource is datapage, the following values are included:
    • dataPageID – When listSource is datapage, this is the data page ID. You call GET /data/{datapageID} to obtain the values for the list.
    • dataPageValue – The property to use in the results obtained from the data page for the value of the option
    • dataPagePrompt – The property to use in the results obtained from the data page for the visible text of the option. The following example is for a data page:
       "control": { "modes": [{ "dataPagePrompt": "TeamName", "dataPageValue": "TeamName", "listSource": "datapage", "dataPageID": "D_GetTeams" }], "type": "pxDropdown" }, 

      Example of pxDropdown populated from data page

  • A pxDropdown control having a listSource of promptlist or locallist also includes the following values:
    • The list of dropdown values in key/value pairs, in the options element, for example:
       "control": { "modes": [{ "listSource": "promptlist", "options": [{ "value": "Critical", "key": "Critical" }, { "value": "High", "key": "High" }, { "value": "Medium", "key": "Medium" }, { "value": "Low", "key": "Low" }] }], "type": "pxDropdown" }, 

      Example of pxDropdown populated from list

  • A pxRadioButtons control also includes the following values:
    • orientation – Horizontal or vertical alignment for the buttons
    • wrapAfter – The number of radio buttons after which the other buttons are placed in the next row or column

 A pxAutoComplete control whose listSource is datapage is built from the fields shown in the following figure:

Thumbnail

Mapping for a pxAutoComplete control

The pxLink control includes the following values:

  • linkImageSource – ‘none’, ‘image’, ‘property’, or ‘styleclass’ 
  • linkImage – Used if linkImageSource is ‘image’
  • linkImagePosition – Used if linkImageSource is ‘image’
  • linkProperty – Used if linkImageSource is ‘property ‘
  • linkStyle – Used if linkImageSource is ‘styleclass’ 
  • linkType – ‘none’, ‘email’, ‘phone’, or ‘url’
  • linkData – The email address, phone number, or url that corresponds to the linkType

A pxLink control is built from the fields as shown in the following two rule form figures:

Thumbnail

Mapping for a pxLink control (1 of 2)

Thumbnail

 Mapping for a pxLink control (2 of 2)

The following example shows a link to the Yahoo website that uses a check mark icon class:

 "control": { "modes": [{ "linkStyle": "pi pi-checkmark", "linkData": "www.yahoo.com", "linkImagePosition": "left", "linkType": "url", "linkImageSource": "styleclass" }], "actionSets": [], "format": "Standard", "type": "pxLink", "label": "link text" }, 

Example of pxLink control

The pxIcon control includes the following values:

  • iconSource – ‘standardicon’, ‘image’, ‘exturl’, ‘property’, or ‘styleclass’ 
  • iconStandard – Used if iconSource is ‘standardIcon’.  The value equals one of the values in the dropdown on the Standard icon dropdown list on the rule form.
  • iconImage – Used if iconSource is ‘image’
  • iconURL – Used if iconSource is ‘exturl’
  • iconProperty – Used if iconSource is ‘property’
  • iconStyle – Used if iconSource is ‘styleclass’

The following example uses the standard delete icon:

 "control": { "modes": [{ "iconStandard": "pxIconDeleteItem", "iconSource": "standardicon" }], "actionSets": [], "format": "Standard", "type": "pxIcon" }, 

Example of pxIcon control

Suggest Edit

80% 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.