Two ways to reach an external API

An Extend page can call a third-party REST API directly as one of its endpoints, or launch an orchestration that calls the API for it. Workday documents both in Call External REST APIs in Extend Apps.

Call it from the page when the API speaks JSON over REST, uses no authentication or OAuth 2.0, and returns roughly what the page displays. Use an orchestration when the API needs a static key or another credential type, when the response needs reshaping, or when several calls have to be chained.

Calling it from the page

Three files take part: the AMD names the base URL, the SMD names the authentication, and the PMD uses both.

  1. In the app's AMD, add the API's base URL to dataProviders:
"dataProviders": [
  { "key": "partner_api", "value": "https://api.partner.example/v1" }
]

  1. In the SMD, add an entry to siteAuth.authTypes for the scheme the API uses (details in the next section).

  2. In the PMD, reference both on the endpoint. baseUrlType is the data provider key and authType is the SMD entry's id:

"endPoints": [
  {
    "name": "partnerOrders",
    "baseUrlType": "partner_api",
    "authType": "partnerAuth",
    "url": "<% '/orders?employee=' + queryParams.employeeId %>",
    "bestEffort": true
  }
]

bestEffort: true, which Workday's own example uses, stops the page from throwing an error when a widget fails: it renders without that widget or shows an "error" value in it. Use it for optional external panels, so a partner outage doesn't take down a Workday page.

A call that changes data on the other side goes in outboundEndPoints instead, and is submitted when the user clicks OK, like any outbound endpoint.

The partner's firewall also has to let Workday in. Workday lists the IP addresses to allowlist for third-party API connectivity, per region, in Reference: Workday Extend Basic Setup.

Choosing the authentication scheme

The default authType is Workday SSO, which means nothing to a third-party API. You must declare and name one of these in the SMD.

NoAuth sends no credentials. Use it for a genuinely public API. The SMD entry is just { "id": "noAuth", "scheme": "NoAuth" }.

OAUTH_CLIENT_CREDENTIAL is for an API that issues a token to the app itself. Store the client ID and secret with the Create External Client CredStore task in Workday, and set the SMD entry's referenceId to the External Reference ID you gave it there. Presentation Components then call the token endpoint, keep the access token in the user's session, and send it on later calls. providerType sets how the credentials go to the token endpoint, for example BASIC_AUTH for an Authorization: Basic header.

OAUTH2 (authorization code) is for an API that must see only the data the person is allowed to see on that system. Register the API client with the provider, using one of the Workday tenant redirect URLs from Reference: Tenant Redirect URLs for External OAuth Providers. Store the client credentials in an External Client CredStore and add the SMD entry. Then put an oauthButton or oAuthLoginButton on the page with authId set to the SMD id, so the user can sign in to the provider. oAuthLoginButton appears only until the user has signed in. redirectTaskReference and errorTaskReference decide where the user lands after a success or a failure.

{
  "type": "oauthButton",
  "label": "Connect your partner account",
  "authId": "partnerAuth",
  "redirectTaskReference": { "type": "taskReference", "taskId": "partnerOrders" },
  "errorTaskReference": { "type": "taskReference", "taskId": "partnerConnectionError" }
}

An API that wants a key in a header doesn't fit any page scheme cleanly. The endpoint headers attribute accepts only static values, so the key would sit in the PMD source of the app. Put that call in an orchestration and store the key as an orchestration credential.

When to use an orchestration instead

Launch an orchestration from the page when any of these apply. Workday's documentation names the first one, transforming third-party data:

  • The response needs reshaping, merging with Workday data, or several calls before the page can use it.
  • The API uses a credential the page can't hold safely, such as an API key or basic authentication. Orchestration credentials support API Key (sent as a header or query parameter), Basic Auth, OAuth and ISU types; see Create Orchestration Credentials.
  • The work takes longer than a page can wait. A page endpoint times out after 24 seconds and a whole page request after 60, and a synchronous orchestration launched from a page gets 25 seconds in total (Reference: Orchestration Runtime Limits). Long work belongs in an asynchronous orchestration that records its result for the user to see later.

The page then calls the orchestration's launch URL as an endpoint and receives clean JSON. Calling external APIs from Orchestrate covers the orchestration side, and showing an orchestration's error on the page covers what the user sees when the partner system fails.

Why you can't embed a third-party page

Workday's PMD tag reference has no widget that frames another website inside an Extend page. The tags that show content are text, rich text, images, video and attachments. The video tag plays only media stored in Workday Drive, and the image tag displays an image, not a page. So there's no supported way to put a partner's web page inside an Extend app.

Workday offers two documented alternatives.

Link out with externalLink. It shows a text link to any URL, and the url can be built in script, for example a partner deep link that carries the record's ID:

{
  "type": "externalLink",
  "label": "Shipment",
  "descriptor": "Track this shipment with the carrier",
  "url": "<% 'https://track.partner.example/shipments/' + request.trackingNumber %>"
}

Bring the data in instead of the page. Call the partner's API as described above and render the parts the user needs with Extend widgets, such as a grid of orders or a status field. That's more work than a frame, but the result follows Workday's security, works on the Workday mobile app where the widgets support it, and can feed an edit page.

The opposite direction is a different product. Showing Workday data inside your own site or tool is what Workday calls an External Extend app: your own UI, calling Workday APIs and orchestrations, with no presentation or model components and not running on the tenant.

Testing the failure paths as well as the happy path

  1. Open the page as a normal user. The external data should load with that user's scope: their orders for authorization code, or the app's view for client credentials.
  2. For OAUTH2, open the page as a user who hasn't connected yet. The sign-in button should appear, the provider's consent should return them to the redirectTaskReference page, and the data should then load.
  3. Make the external call fail, for example by pointing the data provider at a wrong path in a sandbox build. With bestEffort, the rest of the page should still render. Without it, the page should show your error handling, not a raw failure.
  4. For an outbound call, read the record back from the partner system after OK to confirm it was written once. If the page timed out, check before letting the user submit again.

Sources checked