How to call a Studio integration from Orchestrate, and an orchestration from Studio

Orchestrate to Studio: the Trigger Integration step

An orchestration launches a Studio integration with the Trigger Integration step. The step starts the integration system you link, passes launch parameters and one optional input document, then pauses the orchestration until the Studio integration finishes and calls back with its status, messages and any attachments (Concept: Triggering Integrations). The Studio integration is the child; the orchestration is the parent.

The step works only in the Workday Integration System orchestration template. It can launch Workday-delivered packaged integrations, custom Studio integrations and other Workday Integration System orchestrations, but not EIBs. You can place it in the top-level flow, error handlers, branches, loops, batch loops and suborchestrations; you cannot place it in a join loop (Reference: Trigger Integration).

Configure the step

Auth. Choose Default Workday API Credential or Access Token from Initiating User. If the child integration system has an Integration System User configured, that ISU is the "run as" user and the user from the step is the "initiating" user, who must be allowed to launch the integration. If the child has no ISU, the user from the step is both, and needs permission to run and to launch it.

Launch Parameters. Click Manage Connections, connect to the tenant, search for the integration system by name and link it. Orchestration Builder imports the child's launch parameter definitions and groups them by service provider type. Give each parameter a value in Expression Builder, and use Send in Launch to decide whether it goes with the launch. Refresh Launch Parameters reimports the definitions after the Studio developer adds or removes a parameter; it resets defaults to the child's values but leaves your custom parameters, and imported parameters whose values you changed, alone. Linking is optional: you can configure the step by hand if the integration system is not on that tenant.

Document. Passing a document needs Document to Store, Document Title and Storage Expires In; leaving them out gives a validation error. Storage defaults to 7 days if you set no value, and the maximum is 1 year, for example zoneddatetime.now().plusMonths(1) for one month. The child sees only this one document and whatever it creates itself, never the parent's other documents. If the Studio integration expects its input to look as if it came from the integration system's retrieval service, set Add "Retrieved" Workday Tag to a boolean expression that evaluates to true.

Settings. Overall, connect and response timeouts, the response type, and a retry policy, which you define first on the HTTP Retries tab of the orchestration's Settings.

What the step returns and what it does not retry

After the Studio integration completes, the step exposes its status information, its integration messages and its event attachments to the steps that follow. The callback only fires when the integration's own business process finishes its configured steps, so a Studio integration whose process is waiting on a later step keeps the orchestration paused (Concept: Integration Events and Integration Process Events).

The retry policy retries only a failure to trigger the integration. It does not rerun a Studio integration that started and then failed. To relaunch a failed child, branch on its status downstream or attach an error handler that triggers it again (Concept: Triggering Integrations). Use Conditional Outputs on the error handler when later steps should carry on with the failure recorded, and read its isSuccess output before touching the step's outputs; reading the outputs of a failed step rethrows the error (Handle Errors).

Trigger Integration is one of the steps that checkpoints the run, so each wait for a child starts a new process and resets the 60-minute (production) or 45-minute (non-production) limit on a single process. The orchestration as a whole still has to finish within the Workday Integration System orchestration limit of 48 hours (Concept: Orchestration Processes, Reference: Orchestration Runtime Limits).

Studio to Orchestrate: no step, so use the orchestration's endpoint

Workday's documentation describes no Orchestrate-side or Studio-side component for launching an orchestration from Studio. The documented route in is the orchestration's REST endpoint on the Workday Cloud Platform API Gateway, called with an OAuth token. Workday says Studio integrations that need Extend REST resources should use the Client Credentials grant: register an API client, create an Integration System User, run Create Client Credentials Mapping to tie the client ID to that user, then post to the token endpoint and use the returned access token. The ISU is the subject of the token (Authenticate Using the Client Credentials Grant Type).

Give the Studio integration its own API client. Workday advises against reusing the simplified ISU API client that Extend apps use (Concept: ISU Authentication).

The orchestration to call is a Synchronous or Asynchronous orchestration in an Extend app; see exposing an orchestration as an API for its URL, region gateway, limits and OpenAPI document. Choose Synchronous only if the work fits in its 5-minute limit. Workday documents the token flow and the endpoint but not a Studio-specific wiring of the two, so what follows is our recommended approach: build the call in Studio like any other outbound REST request, and take the body and parameter names from the OpenAPI file downloaded from the orchestration's Settings tab.

The other way to run orchestration logic from the Workday side is to make the orchestration the logic of an integration system. With the Workday Integration System template you create an integration system in the tenant and set its attributes to the orchestration's Orchestration Name and Application Reference ID. That integration system then invokes the orchestration, passes data to it and receives the output (Getting Started with Orchestrate), and it is launched the way any integration system in the tenant is launched, with no gateway call or API client involved.

How to prove each direction

For Orchestrate to Studio, look at the integration event in the tenant, then at the orchestration's run. The child appears as a child integration event of the orchestration's main event with its own status and messages. In the orchestration, confirm that the steps after Trigger Integration read the child's status before using its attachments, and that the launch parameters recorded on the event are the ones you sent.

For Studio to Orchestrate, fetch a token with the Studio integration's client ID and secret, call the endpoint from the Studio integration, and check that the orchestration's run shows the instance ID returned in the X-Orchestrate-Id response header. If the call returns 401: Unauthorized, check that you called the gateway of the account's region before checking the credentials (Reference: Workday Extend API Gateways and Authorization Base URLs). Further reading: Orchestrate or Studio for a new integration and Orchestrate errors.