Which orchestration type gives an outside system an API

An orchestration in a Workday Extend app is already an HTTP endpoint on the Workday Cloud Platform API Gateway. You make it callable from outside by adding a Synchronous or Asynchronous orchestration, defining its input and output parameters on the start and end steps, saving the app to App Hub, and giving the caller an OAuth access token. Workday's Orchestrate guide describes this as running an orchestration "headless", as a back-end API service with no user interface (Getting Started with Orchestrate).

The template decides how the caller experiences the call:

Template What the caller gets Use it for
TemplateSynchronousWhat the caller getsThe caller holds the connection open and receives the finished response in the same callUse it forQuick lookups and updates that return a result
TemplateAsynchronousWhat the caller getsThe orchestration acknowledges the launch and keeps running in the backgroundUse it forLarge volumes of data, or steps that wait on other events such as Trigger Business Process

Template behaviour comes from Steps: Create Extend App Orchestrations. The templates for Workday Business Process, Workday Home Card, Workday Integration System and Custom Agent Action are triggered by something else, not by an outside HTTP caller.

Limits that decide synchronous or asynchronous

Pick by how long the work takes, because the runtime limits differ sharply (Reference: Orchestration Runtime Limits):

  • A synchronous orchestration may run for 5 minutes. An asynchronous one may run for 48 hours.
  • The launch request message can be at most 20 MB.
  • One orchestration can have at most 300 steps, and Extend warns you at 200.
  • One process inside an orchestration may run 60 minutes in an app promoted to a production tenant and 45 minutes in one that has not been.

If the work can approach 5 minutes, build it asynchronous from the start. Changing the template later changes what every caller has to do: a synchronous caller waits for the output, an asynchronous caller gets a run ID and has to come back for the result.

A synchronous orchestration can also accept a multipart request. Select Request Contains Multi-Part Data in the properties of the Orchestration Start step.

Build the orchestration and find its URL

  1. In the Extend app on the Workday Developer Site, click + Add Orchestration and choose Synchronous Orchestration or Asynchronous Orchestration. Orchestration Builder adds the Orchestration Start and Orchestration End steps.
  2. Define the input parameters on the start step and the output parameters on the end step. These are the contract the outside system sees, so name them for the caller, not for your internal steps.
  3. Build the logic between them, then click Validate and Save to App Hub.
  4. Open the orchestration's Settings (gear) tab. The Orchestrate guide says the API URL for both synchronous and asynchronous orchestrations is found by selecting the Settings cog.

Workday's public extend-js-example sample builds the call as orchestrate/v1/apps/{appId}/orchestrations/{orchestrationId}/launch on the API gateway host. It matches the documented cancel and verbose-logging endpoints, which sit under the same orchestrate/v1/apps/{appID}/orchestrations/ path. Treat the Settings tab as the authority for your orchestration's exact URL, and the gateway host as region-specific (next section).

Give the caller the right gateway and a token

Each Extend account belongs to one region, and each region has its own gateway. The United States gateway is https://api.workday.com (also https://api.us.wcp.workday.com); Germany, Singapore and the United Kingdom use api.eu, api.sg and api.uk under .wcp.workday.com. Calling another region's gateway can return 401: Unauthorized (Reference: Workday Extend API Gateways and Authorization Base URLs). Your profile on the Developer Site lists the gateway for your account.

Callers authenticate with OAuth 2.0. Register an API client in the Developer Site Console, then pick the flow that fits the caller (Concept: Authorization Flows):

  • A server-to-server job with no person involved uses the Client Credentials grant. Workday maps the client to an Integration System User, and that user is the subject of the access token. In the tenant you run Create Integration System User and Create Client Credentials Mapping, and the API client needs the right scope plus a user with the domain security that governs the operation (Authenticate Using the Client Credentials Grant Type).
  • A web or single-page app where a person signs in uses the Authorization Code grant, with PKCE for public clients, or the Implicit grant for browser-only scripts.

Extend REST APIs accept bearer tokens only, and every access token expires after 60 minutes, so a scheduled caller requests a fresh token per run instead of storing one. The token request goes to the authorization base URL of the same region as the gateway.

A caller that signs in as a person runs with that person's security. A caller using Client Credentials runs as the Integration System User, so grant that user only the domains the orchestration's steps actually touch. For the setup and failure modes, see Workday integration system user and API client setup and ISU authentication errors.

Hand the caller an OpenAPI document

Once the orchestration is saved to App Hub, click Download OpenAPI on the Settings tab of Orchestration Builder. Workday downloads an OpenAPI document for that orchestration, which you can upload to a tool such as Postman or give to the team building the outside system (Export OpenAPI Specifications for Orchestrations). Use it, not a hand-written description, as the source for the request body and parameter names. The Workday documentation does not give a fixed request-body format apart from your own start-step parameters.

What an asynchronous caller gets back

A launch request returns the orchestration instance ID in the X-Orchestrate-Id response header, and the same value appears in the logs. For an asynchronous orchestration that value is what a caller keeps. Asynchronous runs are not cancellable by default. To allow it, open Settings from the orchestration's three-dot menu, select Allow users to cancel the orchestration at a specified point, and place the Cancellation Barrier either at the end of the orchestration or at a step from which the run can no longer be cancelled. The caller can then stop a run with:

PUT https://api.workday.com/orchestrate/v1/apps/{appID}/orchestrations/{orchestrationName}/cancel/{orchestrationId}
Authorization: Bearer {token}

Use the gateway for your region in place of api.workday.com (Concept: Async Orchestration Cancellation). The Orchestrate guide says an asynchronous caller either polls for status or waits for a webhook callback, but it does not document a built-in callback. The approach we recommend is a Send HTTP Request step before Orchestration End that posts the result, with the run ID, to an endpoint the outside system owns, so the caller never has to poll.

How to prove the endpoint works

Call it once from a client that is not your browser session, using the same kind of token the real caller will use, and check three things:

  1. The response carries the output parameters you defined on the end step (synchronous), or an X-Orchestrate-Id header (asynchronous).
  2. On the app's Orchestration Activity dashboard, the run with that Run ID shows SUCCESS, not COMPLETED_WITH_ERROR or FAILED, and its View Logs link shows each step (Concept: Orchestration Activity).
  3. A token for a user without access to the data the steps read fails the way you want it to, rather than returning data.

If the call fails, the run's logs and the exact error are the starting point; see Workday Orchestrate errors. For calls that reach out from an orchestration to someone else's API, the direction is reversed and is covered in calling external APIs from Orchestrate.

Sources checked