--- category: [Administration & Integrations, Platform and Product Extensions, Platform and Product Extensions/Integration, Administration & Integrations/Custom Integrations & Apps, Platform and Product Extensions/Workday Extend] keyword: [Extend, Presentation Components, widgets, tags, UI components] nav: wcp_docs parent_url: /wcp_docs/ title: endPoints layout: subsection wd_wcptag: endPoints --- Contains the inbound endpoints that fetch the data displayed on the widgets. Each endpoint uses the HTTP GET method. Use `endPoints` on view and edit pages. Jump to: - [Mobile Support](/wcp_docs/ujr1530565661647.html#section-mobile-support) - [Attributes](/wcp_docs/ujr1530565661647.html#section-attributes) - [PMD Scripting Methods](/wcp_docs/ujr1530565661647.html#section-pmd-scripting-methods) - [PMD Scripting Events](/wcp_docs/ujr1530565661647.html#section-pmd-scripting-events) ## Usage ## Calling Inbound Endpoints When loading a page, Presentation Components call all inbound endpoints defined in `endPoints[]`. To define an inbound endpoint, specify these required attributes: - `name` - The endpoint alias for referencing its data in the PMD. - `baseUrlType` - The base URL of the endpoint. Specify the data provider `key` in `dataProviders[]` in the App Metadata (AMD). - `url` - The relative endpoint URL. The full endpoint URL consists of the `baseUrlType` and `url` values. You can include path and query parameter bindings in the `url`. - `authType` - The endpoint authentication scheme. Specify the authType `id`, which is defined in `authTypes[]` in the Site Metadata (SMD). Workday REST APIs use `SSO`, which is the default authentication type. Note: Except for the `ISU` authentication scheme, you can specify the `scheme` value in the SMD as the `authType` value in PMDs. For the `ISU` authentication scheme, use the `id` value that's defined in the SMD. This example calls the `GET /workers/me` endpoint: ``` "endPoints": [ { "name": "worker", "baseUrlType": "workday-staffing", "url": "/workers/me", "authType" : "sso" } ] ``` This example defines the `workday-staffing` data provider in the AMD: ``` { "key": "workday-staffing", "value": "https://api.workday.com/staffing/v1" } ``` ## Excluding Endpoints If you define multiple endpoints in `endPoints[]`, the page concurrently invokes the endpoints when possible. You can use the `exclude` attribute to invoke an endpoint only on certain conditions. This sample `endPoints` contains multiple endpoints: ``` "endPoints": [ { "name": "charity", "baseUrlType": "app", "url": "<% 'charities/' + queryParams.charityId %>", "authType": "sso" }, { "name": "charityLogo", "baseUrlType": "app", "url": "<% 'charityLogos/' + charity.logo.id %>", "exclude": "<% empty(charity.logo) %>", "authType": "sso" } ... ] ``` The `charityLogo` endpoint retrieves the image of a charity from the `charity` endpoint. The `exclude` attribute on the `charityLogo` endpoint checks whether or not the selected charity image is empty. If the `exclude` attribute evaluates to true, the page doesn't call the `charityLogo` endpoint. ## Deferring Endpoints If you need to call an endpoint only after the user has interacted with a widget, defer calling that endpoint until you can evaluate the user interaction. Deferring an inbound endpoint typically applies to displaying data on a widget that depends on what the user selected or entered on another widget. This sample endpoint sets the `deferred` attribute to true. ``` { "name": "requisition", "baseUrlType": "workday-requisitions", "url": "<% '/requisitions/' + id %>", "authType": "sso", "deferred": true } ``` When the page loads, it doesn't invoke the `requisition` endpoint. The deferred endpoint executes only when a script calls the `invoke` method on that deferred endpoint. This sample `onRowSelect` event handler invokes the `requisition` endpoint: ``` // Event onRowSelect called on grid. var selectRow = function() { if (!reqGrid.selectedRows.isEmpty()) { detailsSection.visible = true; var id = reqGrid.selectedRows[0].childrenMap.idColumn.value; var detailList = requisition.invoke({'id': id}); requester.value = detailList.requester.descriptor; requisitionDate.value = detailList.requisitionDate; status.value = detailList.status.descriptor; } else { detailsSection.visible = false; } } ``` ## Getting Endpoint Response Headers To get the response headers from inbound endpoints, use the `responseHeaders` property of the endpoint name: `<% anEndPointName.responseHeaders.headerType[index] %>` `headerType[]` returns a list of values for the specified header type. If a header contains only a single value, use the `0` index. Example: To get the response status code from the HTTP header, use `<% sampleEndpointName.responseHeaders.statusCode[0] %>` This sample `text` becomes visible based on the statusCode from the endpoint response header. ``` { "type": "text", "value": "Got my vehicle registration!", "enabled": false, "visible": "<% fetchMyVehicleRegistration.responseHeaders.statusCode[0] == 200 ? true : false %>" } ``` This sample fetchMyVehicleRegistration endpoint is a WQL query on a sample Vehicle business object: ``` { "name": "fetchMyVehicleRegistration", "baseUrlType": "workday-wql", "authType": "sso", "url": "<% var query = 'SELECT licensePlate, year, make, model, registrationDate FROM ' + site.applicationId + '_vehicles WHERE owner =' + me.id + ' ORDER BY licensePlate ASC'; return 'data?query=' + query.urlEncode(); %>" } ``` ## Performance Notes - Number of inbound endpoints The maximum number of inbound endpoints in `endPoints` is 10. If you declare an endpoint but never reference it in the PMD, consider removing it to avoid negative impact on performance. - Maximum response data The maximum size of response data from an endpoint call is 25,000,000 bytes. If the size of the response data exceeds the maximum, Presentation Components: - Stop processing the response data beyond the maximum. - Write a `RestResponseTooLargeException` error in the log. - Return a page error with the internal server error 500. - Endpoint and request timeouts Presentation Components impose a 24-second timeout on each endpoint on a page. Individual endpoints exceeding the 24-second limit return a timeout error. In addition to the endpoint limit, Presentation Components also impose a 60-second timeout on a request. A request can include initial page loads, page submissions, and remote validations. (A single request can call multiple endpoints.) All of these operations must complete within 60 seconds; otherwise the page returns a timeout error. This measure protects the Workday tenant from poor performance. To avoid the request timeout, consider limiting the number of endpoints and ensure that you call performant endpoints on each page. - Collection endpoints When calling endpoints that return a collection, use appropriate filter and paging parameters. Use the `exclude` attribute of an endpoint for conditional invocation, which avoids unnecessary endpoint execution on page load. Use the `isCollection` attribute with caution. Don't use `isCollection` with extremely large sets of data. If `isCollection` is true, the data collection is created with many iterative requests, which can severely impact performance. Use endpoints that return more targeted results. ## Mobile Support Android, iOS ## Attributes - allowEmptyValue Data type: binding-Boolean Applies only if the `httpMethod` of the inbound endpoint is POST. If true, we send all fields to the endpoint even if a field is empty (`""`, `0`, or `[]`). If false, we don't include empty fields in the request payload. The default is false. - authType Data type: binding-String The id of the authentication scheme for authenticating the endpoint. The SMD of your app defines the authentication scheme id in the `authTypes` array. You can use different authentication types on different endpoints on the same page. The default is Workday Single-Sign On (SSO). Note: Except for the `ISU` authentication scheme, you can specify the `scheme` value in the SMD as the `authType` in PMDs. For the `ISU` authentication scheme, use the `id` value that's defined in the SMD. - baseUrlType Data type: string Specifies the base URL of the endpoint to invoke. We append the `url` attribute to `baseUrlType` to get the full API endpoint. Specify the `key` of a data provider declared in the `dataProviders` section of the AMD. - bestEffort Data type: boolean If true, the page doesn't throw an error when a widget encounters an error. Instead, the page continues to render the page without the widget or with the "error" value on the widget. The default is false. - deferred Data type: boolean If true, we don't call this endpoint at the time of rendering the page. Use this property to defer the endpoint invocation during page load. With PMD scripting, you can call the `invoke` method on this endpoint only when needed. The default is false. - exclude Data type: dynamicBinding-Boolean If true, the page doesn't call the endpoint. You can specify an expression that determines whether or not to exclude the endpoint from invocation. The default is false. This example excludes calling the endpoint if `selectedWorker` is empty: ``` "url": "<% '/workers/' + selectedWorker + '/serviceDates' %>", "exclude": "<% empty selectedWorker %>" ``` - failOnStatusCodes Data type: list of HttpStatusCode objects An array containing HTTP status codes that Presentation Components must treat as errors. When an endpoint returns a status code listed in `failOnStatusCodes`, Presentation Components returns a page error or routes the error to a configured custom error page. An array item consists of these attributes: - `code` - (Required) The HTTP error code to ignore. - `codeName` - (Informational only) Describes the status code. Use this field for your information only; it has no effect. Example: ``` "failOnStatusCodes": [ {"code": 403} ] ``` By default, Presentation Components treat these HTTP status codes as errors: - 301 - Moved permanently. - 302 - Found. - 303 - See other. - 307 - Temporary redirect. - 401 - Unauthorized. - 404 - Not found. - 407 - Proxy authentication required. - 408 - Request timeout. - 500 - Internal server error. - 503 - Service unavailable. For the standard descriptions of the status codes, see [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status). Presentation Components ignore all other HTTP status codes not included in the above list. If your app requires that any of the ignored status codes must fail, specify the status code in the `failOnStatusCodes` attribute. If you configured custom error pages in your app, Presentation Components route the errors to the custom error pages. See [Reference: Custom Error Pages](/wcp_docs/vfx1525988737823.html). To ignore any of the HTTP status codes in the above list, specify the status code in the `ignoreFailures` attribute. - graphQuery Data type: Map Specifies a query or mutation for the Graph API endpoint. You must set the `httpMethod` attribute to `POST`. Specify either `query` for an inline query or mutation, or `queryId` to reference a reusable Graph Query component. The `query` and `queryId` properties are mutually exclusive. `graphQuery` properties: - query A static string containing an inline query or mutation. The `query` string can contain variable placeholders (with the `$` prefix character), but it can't contain dynamic values. Specify the variable values in `variables`. To embed a literal string inside the `query` string, use escaped double quotes. - queryId A static string containing the ID of the Graph Query component you want to reference. The `queryId` must match the `id` of the Graph Query component. - parameters A script that returns a map, or a map containing parameters sent to the Graph Query component, where: - key A static string containing the parameter name, which should match the name in `parameters[]` inside the Graph Query component. - value An object containing the parameter value, which can be a script or any value including a boolean, string, number, native JSON map or native JSON array. Use `parameters` to send dynamic data to a Graph Query. Note that Graph Query components are self-contained modules and don't have page context. Use the parameters to send any app or page-specific variables. - variables A map containing dynamic values for the query or mutation, where: - key A static string containing the variable name, which should match the $placeholderVariable inside the `query` string. - value An object containing the variable value, which can be a script or any value including a boolean, string, number, native JSON map or native JSON array. If you intend to use a Graph Query component but it's easier to define dynamic query variables in the PMD endpoint, you can specify both `queryId` and `variables` in `graphQuery`. If you use `variables` with `queryId`: - If the Graph Query component also contains `variables`, the `variables` in the PMD overrides the Graph Query component variables. - The `variables` and `parameters` properties of `graphQuery` are mutually exclusive. Note: The Graph API endpoint can return the 200 status code with partial response and errors. Note that if the Graph API endpoint response contains `errors[]`, the page treats it as an error, even if the endpoint response status code is 200. For more information about Graph API, see [Workday Graph API](/wcp_docs/vyw1671061988370.html). - headers Data type: list of endPointHeader objects An array containing HTTP headers. Use the `headers` attribute if your REST API endpoint requires any HTTP header. Each item in the `headers` array contains the `name` and `value` of the HTTP header. You can only specify static values. Example: ``` "headers": [ { "name": "Accept", "value": "application/json" } ] ``` - httpMethod Data type: string The HTTP method for the inbound endpoint. Valid values: - `GET` - Default method. - `POST` Upon initial page load, we invoke a data retrieval POST endpoint only when the PMD page is accessed from an HTTP POST request. Example: A POST endpoint is invoked upon page load when the PMD is requested from a `button` with `"commandHttpMethod" : "POST"`. With PMD Scripting, you can invoke a POST endpoint as a deferred endpoint for data validation. For details, see "Data retrieval or validation with a POST inbound endpoint" under the `onSend` event in [Reference: PMD Scripting Events](/wcp_docs/tgy1581495452394.html). - ignoreFailures Data type: list of HttpStatusCode objects An array containing HTTP status codes to ignore. When the endpoint returns one of the specified non-200 HTTP status codes in `ignoreFailures[]`, we ignore the error. The response data includes the error code and message. The `bestEffort` attribute overrides `ignoreFailures`. If you set `bestEffort` to `true`, we ignore all unsuccessful HTTP codes (codes outside of the 200 code range). An array item consists of these attributes: - `code` - (Required) The HTTP error code to ignore. - `codeName` - (Informational only) Describes the status code. Use this field for your information only; it has no effect. Example: ``` "ignoreFailures": [ {"code": 404, "codeName": "Not found"} ] ``` Specify any of these HTTP status codes that Presentation Components can ignore. By default, Presentation Components treat these status codes as errors and ignore all other status codes not listed here: - 301 - Moved permanently. - 302 - Found. - 303 - See other. - 307 - Temporary redirect. - 401 - Unauthorized. - 404 - Not found. - 407 - Proxy authentication required. - 408 - Request timeout. - 500 - Internal server error. - 503 - Service unavailable. For the standard descriptions of the status codes, see [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status). If you don't include the listed status codes in `ignoreFailures`, Presentation Components treat them as errors. If you configured custom error pages in your app, Presentation Components route the errors to the custom error pages. See [Reference: Custom Error Pages](/wcp_docs/vfx1525988737823.html). To treat any of the HTTP status codes not listed above as error, specify the status code in the `failOnStatusCodes` attribute. - isCollection Data type: boolean If true, we call the endpoint with a page size of 100, and create a data collection with iterative endpoint requests until the data collection contains the total number of rows. Use `isCollection` to display a list of data on widgets like the dropdown. `isCollection` assumes that the endpoint has the `limit` and `offset` parameters for pagination. Although you would use `isCollection` only with endpoints that potentially retrieve data with more than 100 items, don't use it with extremely large sets of data. It can overwhelm the system as it fetches the entire data upfront. The `isCollection` attribute only applies to endpoints that use the `GET` method. - name Data type: string The unique name of this endpoint. Use this name to reference the endpoint in your PMDs. You can access the data returned by this endpoint with the syntax `name.someFieldName`. - responseErrorDetail Data type: responseErrorDetail Specifies the error summary field from the inbound endpoint. An endpoint HTTP response code other than 2xx triggers the page to display the error messages. Example: ``` "responseErrorDetail": { "errorSummary": "<% [error].addAll(errors.map(e => {e.error})).join('\\n') %>" } ``` - search Data type: boolean If true, the endpoint attaches query parameters to the URL, which are necessary for a faceted search. Set `search` to true only if you use the endpoint with the `facetedSearch` tag. The default is false. - url Data type: binding-String The relative endpoint URL of the REST API resource. We append the `url` attribute to `baseUrlType` to get the full API endpoint. You can only use HTTP/HTTPS as the URL protocol for an endpoint. Workday recommends always using HTTPS. - values Data type: list of value objects An array of outbound fields with their corresponding values. Only applies to inbound endpoints that use the HTTP POST method. Note: To invoke a POST inbound endpoint when the page loads, use a `button` widget with the `"commandHttpMethod": "POST"` attribute. In this example, we run a WQL query using the POST HTTP method. The `values` attribute contains the query. ``` { "name": "workerContactInfo", "baseUrlType": "workday-wql", "url": "data", "httpMethod": "POST", "values": [ { "outboundPath": "query", "value": "<% 'SELECT fullName, email_PrimaryWork, phone_PrimaryWork, workAddress_Full FROM allWorkers WHERE worker = \"' + currentWorker.id + '\"' %>" } ] } ``` Here's the resulting request body sent to the workerContactInfo POST inbound endpoint: ``` { "query":"SELECT fullName, email_PrimaryWork, phone_PrimaryWork, workAddress_Full FROM allWorkers WHERE worker = \"3aa5550b7fe348b98d7b5741afc65534\"" } ``` This sample `button` widget loads the viewWqlQueryPost page, which invokes the workerContactInfo POST inbound endpoint: ``` { "type": "button", "label": "Worker details", "action": "LINK", "commandHttpMethod": "POST", "taskReference": { "taskId": "viewWqlQueryPost" } } ``` - wqlQuery Data type: Map Contains the query for the WQL `GET /data` or `POST /data` endpoint. Specify either `query` for an inline query or `queryId` to reference a WQL Query component. The `query` and `queryId` properties are mutually exclusive. `wqlQuery` properties: - query A string script containing the WQL query. The query string can contain PMD script variables (enclosed in the `<% %>` notation). To embed a literal string inside the query, use escaped double quotes. - queryId A static string containing the ID of the WQL Query component. The queryId must match the id of the WQL Query component. - parameters An optional property used with queryId containing a map of parameters sent to the WQL Query component, where: - key A static string containing the parameter name, which should match the name in parameters inside the WQL Query component. - value An object containing the parameter value, which can be a script or any value including a boolean, string, number, native JSON map or native JSON array. Note: WQL Query components are self-contained modules and don’t have page context. Use the parameters to send any app or page-specific variables. - limit An optional property used with `query`. The `limit` property specifies the maximum number of objects in a single response. The maximum is 10,000. - offset An optional property used with `query`. The `offset` property specifies the zero-based index of the first object in a response collection. The default is 0. Use offset with the limit parameter to control paging of a response collection. ## PMD Scripting Methods - invoke() Return type: `Object` Description: Invokes an inbound endpoint without parameters, and returns the endpoint response. To reference the JSON fields in the returned object, save the returned object in a variable. For an example, see `invoke(Map arguments)`. - invoke(Map arguments) Return type: `Object` Description: Invokes an inbound endpoint with named parameters, and returns the endpoint response. To reference the JSON fields in the returned object, save the returned object in a variable. This sample script invokes the getWorkerById endpoint with the id parameter, and saves the returned object in workerData. It then uses the workerData.person.email field to populate the workerEmailAddress widget: ``` // Invoke endpoint and pass id as a URL parameter var populateEmail = function(selectedWorkerId) { if( !(empty selectedWorkerId)) { var workerData = getWorkerById.invoke({'id': selectedWorkerId}); workerEmailAddress.value = workerData.person.email; } }; ``` The sample getWorkerById endpoint with the id path parameter: ``` { "name": "getWorkerById", "baseUrlType": "workday-staffing", "url": "<% '/workers/' + id %>", "authType": "sso", "deferred": true, "responseErrorDetail": { "errorSummary": "<% [error].addAll(errors.map(e => {e.error})).join('\\n') %>" } } ``` This sample JSON shows the content of the workerData variable, which is the response data from the getWorkerById endpoint. ``` { "descriptor": "Logan McNeil", "id": "3aa5550b7fe348b98d7b5741afc65534", "person": { "email": "lmcneil@workday.net", "id": "9feb1da3167840a9852698a2f228f795", "phone": "+1415789-8904" }, ... } ``` ## PMD Scripting Events - onSend Triggers just before sending the request data to an outbound endpoint or a POST inbound endpoint. Specify a PMD script that returns either a List or a Map, which is the request JSON data. The `onSend` event handler can reference all widget values on the page, including composite widgets such as `grid` rows or `panelList` panels. You can use the `onSend` event handler with a POST inbound endpoint that performs data retrieval or deferred validation. This sample deferred endpoint is a POST validation endpoint that uses the `onSend` event handler to send the phone number to validate: ``` "endPoints": [ { "name": "phoneValidation", "baseUrlType": "workday-person", "url": "/phoneValidation", "httpMethod": "POST", "deferred": true, "onSend": "<% { 'completePhoneNumber': thePhoneNumber.value } %>" } ] ``` This sample `text` widget uses the `onChange` event handler to invoke the POST validation endpoint: ``` { "type": "text", "label": "Phone Number", "id": "thePhoneNumber", "onChange": "<% var result = phoneValidation.invoke(); if (! empty result.error) { self.setError(result.error); } else { self.clearError(); } %>" } ``` ### Related Information [Concept: Displaying Data](/wcp_docs/qau1572291138966.html) [Reference: Workday Extend API Gateways and Authorization Base URLs](/wcp_docs/dlh1653340161856.html) [App Catalog: Charitable Donations](/app-catalog/charitableDonations) [App Catalog: PMD Scripting](/app-catalog/pmdScripting) [App Catalog: Vehicle Registration](/app-catalog/vehicleRegistration)