Advanced Endpoints

Overview

In this chapter, you will explore different types of endpoints.

Objectives

By the end of this chapter, you will be able to:

Create a deferred endpoint to request data after the initial page load.

Create a search endpoint to use with an instanceList widget.

Inbound Endpoints

The most common root variable used in PMD expressions is

endPointN

ame

. You can use the endpoint's

name

as a pointer to the endpoint's response object.

"endPoints": [
  {
    "name": "expenseData",
    "baseUrlType": "WORKDAY-EXPENSE",
    "url": "/entries",
    "authType": "sso"
  }
]

If you need a reference to the actual endpoint object itself, use

endpoints.endPointName

(e.g., for the endpoint object above,

endpoints.expenseData

).

endPoint Attributes

Attribute	Description
deferred	If true, page doesn't call the endpoint on page load. Can use to retrieve data after initial page load, e.g., when the user interacts with a page action button.
exclude	If true, the page doesn't call the endpoint. Allows invoking an endpoint on certain conditions.
isCollection	If true, retrieve data for all available rows in a single response. Note : Don't use isCollection with extremely large data sets. It can overwhelm the system as it fetches the entire data upfront, which will slow down your page.

Writing Expressions Against an Endpoint Response

A common use of expressions is to set values in widgets to display data on a page. Imagine you have a PMD page with an inbound endpoint named

worker

. The endpoint returns the following data:

{
  "primarySupervisoryOrganization": {
    "descriptor": "4300 Payroll (For BFT use)",
    "id": "31fd8a267e4b4375aa8ff594033193cf",
    "href": "https://api.workday.com/common/v1/supervisoryOrganizations/31fd8a267e4b4375aa8ff594033193cf"
  },
  "organizations": [
    {
      "descriptor": "4300 Payroll (For BFT use)",
      "id": "31fd8a267e4b4375aa8ff594033193cf",
      "href": "https://api.workday.com/common/v1/supervisoryOrganizations/31fd8a267e4b4375aa8ff594033193cf"
    }
  ],
  "location": {
    "descriptor": "San Francisco",
    "id": "d13a7c46a06443c4a33c09afbdf72c73"
  },
  "descriptor": "1099 Analyst_500.1",
  "dateOfBirth": "1962-07-25",
  "supervisoryOrganizationsManaged": "https://api.workday.com/common/v1/workers/ad3b6e21b21b100301e6c888e90816da/supervisoryOrganizationsManaged",
  "primaryWorkAddressText": "2489 Razorback Way, Allgood, AL 35013",
  "id": "ad3b6e21b21b100301e6c888e90816da",
  "primaryWorkEmail": "TestWorkEmail@workday.com",
  "businessTitle": "1099 Analyst",
  "isManager": false,
  "href": "https://api.workday.com/common/v1/workers/ad3b6e21b21b100301e6c888e90816da",
  "yearsOfService": "5"
}

Here are some expressions written against the response, including the values that the expression would return:

Expression	Value
<% worker.primaryWorkEmail %>	"TestWorkEmail@workday.com"
<% worker.isManager %>	false
<% worker.location.descriptor %>	"San Francisco"
<% worker.organizations[0].descriptor %>	"4300 Payroll (For BFT use)"

Limitations

There are a few limitations to keep in mind when calling endpoints on your app pages.

Each endPoint has a maximum of 25,000,000 byte response data. If your endPoint hits this limit, processing will stop, you will receive a

RestResponseRooLargeException

error in the logs, and an internal server error (500) will present for that page.

If an endPoint does not retrieve data in 24 seconds, a timeout error will occur.

Pages as a whole have a 60 second timeout. This can become an issue when you start dealing with multiple endPoints on a page.

Deferred Endpoints

By default, an inbound endpoint retrieves data on page load. Deferred endpoints allow you to call an endpoint after the initial page load. This typically applies to widgets that display data once a user selects or interacts with another widget.

To define a deferred endpoint, add the

deferred

attribute and set it to

true

.

{
  "name": "requisition",
  "baseUrlType": "workday-requisitions",
  "url": "",
  "authType": "sso",
  "deferred": true
}

In order to call a deferred endpoint, you need to invoke that endpoint with a PMD script. You can do this with a script block, or with an event at the widget level.

To invoke an endpoint use the endpoint's name and the

.invoke()

method. The

.invoke()

method returns the response from the deferred endpoint call. For example, to call the deferred endpoint above, you would use the following syntax:

const response = requisition.invoke();

Search Endpoints

By default, the search prompt on an

instanceList

widget searches the preloaded list from the

values

attribute.

But sometimes, the data source you are using to populate the values attribute has a massive number of objects. It is likely that your users only need a small subset of those values. To improve the performance of your page, you can provide a search endpoint for the

instanceList

widget.

A search endpoint uses the search value the user enters into the widget, makes a call to an endpoint, and returns a list of selectable values.

Search endpoints let you limit the scope of the search on a potentially large data source, which improves the load performance of the

instanceList

widget. When you use a search endpoint, you can avoid preloading a huge amount of data on the

instanceList

and only fetch the data requested by the user.

To provide a search endpoint, set these attributes on the

instanceList

widget:

searchEndPoint

Set

searchEndPoint

to the name of the search endpoint in the

endPoints

array.

The search endpoint should use the

instanceListQuery

variable as the query parameter.

instanceListQuery

stores the value entered by the user on the search prompt of the instanceList.

The search endpoint should be a deferred endpoint. Set

"deferred": "true"

.

searchResultValues

Set

searchResultValues

to the list of data returned by the search endpoint.

The list must contain the

id

and

descriptor

fields of each selectable value.

The example below defines an

instanceList

widget with a sample search endpoint:

{
  "endPoints": [
    {
      "name": "workerSearch",
      "baseUrlType": "workday-staffing",
      "url": "<% '/workers?search=' + instanceListQuery %>",
      "exclude": "<% empty instanceListQuery %>",
      "authType": "sso",
      "deferred": true
    },
  ],
  "presentation": {
    ...
    "body": {
      ...
    }
    "children": [
      {
        "type": "instanceList",
        "id": "instanceListWorkerSearch",
        "label": "Worker",
        "values": "<% workers.data %>",
        "multiSelect": false,
        "searchEndPoint": "<% endpoints.workerSearch %>",
        "searchResultValues": "<% workerSearch.data %>"
      },
      ...
    ]
  }
}

Mock Data

In App Preview, you can use mock data to test inbound and outbound data on a page without connecting to a tenant.

Mock data enables you to:

Quickly test logic and verify dynamic scenarios using realistic sample JSON responses without having to change the source code.

Protect against changing data in your tenant or in external systems.

Mock data is required for endpoints that have an

authType

of OAuth2 because tenant connection doesn't support that

authType

.

These types of endpoints support mock data responses:

PMD inbound endpoints.

PMD outboundDataUri endpoints.

Pod endpoints.

Note
:

outboundVariable

,

image

, and

imageCard

tags don't support mock data responses.

To configure mock data, you need the following components:

Term	Definition
Mock data response	Contains a MockResponse object that simulates a JSON response.
Mock data configuration	Contains mappings of endpoints to mock responses. For each endpoint in your app, App Preview returns the mock response for that endpoint instead of executing the endpoint.

Find specifics on these components and mappings on the Extend Developer site.