Why sub-orchestrations cannot be called directly across apps
In Workday Orchestrate, a sub-orchestration is strictly scoped to the Extend App or Integration App in which it is defined. As stated in Workday’s Reference: Call Suborchestrations documentation, the Call Suborchestrations component only calls a sub-orchestration that is part of the same app. There is no cross-app dependency manifest or shared library import that allows App B to drag a Call Suborchestration step referencing App A onto its canvas.
Workday intentionally scopes every Extend App and Integration App as an independent, atomic deployment unit where all components inside the app share a single promotion lifecycle across Development, Implementation, Sandbox, and Production tenants. This creates an architectural trade-off whenever teams want to reuse common transformation, validation, or web service logic:
- Splitting into one app per integration isolates promotion lifecycles, but forces you to duplicate (via Import Orchestrations and Suborchestrations) and manually update shared sub-orchestrations in every app when logic changes.
- Combining 20–35 integrations into a single app lets every orchestration call the same sub-orchestrations and share Orchestration Credentials, but promoting the app promotes every orchestration in it—even if only one integration was ready for Production.
Pattern 1: Cross-app reuse via a versioned Synchronous Orchestration API
When multiple Extend apps must execute centralized security checks, audit logging, or business rules from a single auditable place without duplicating sub-orchestrations, expose the sub-orchestration through a Synchronous orchestration in a dedicated shared-services Extend app (App A) and call it over HTTP from dependent apps (App B, App C).
Step-by-step setup
- Build the reusable logic in App A: Keep the core steps inside a sub-orchestration (for example,
CalculateTaxWithholdingSub) or directly inside a Synchronous orchestration namedCalculateTaxWithholdingV1. - Expose the Synchronous Orchestration as an API: Configure the request and response schema on
CalculateTaxWithholdingV1and deploy App A to the target tenant. - Call App A’s endpoint from App B: In App B’s orchestration, use a Send Workday API Request step targeting App A’s synchronous orchestration REST endpoint (
/orchestrate/v1/apps/<appA_id>/orchestrations/CalculateTaxWithholdingV1/launch). - Configure authentication and domain permissions: Use
isuAuthfor background service-to-service calls orssowhen the initiating worker’s security context must be preserved. Ensure the calling user or Integration System User (ISU) is granted access to App A’s security domain.
Critical rules for cross-app API calls
- Never call a cross-app Synchronous Orchestration inside a high-volume loop. A sub-orchestration invoked natively inside the same app executes in milliseconds in-memory. Calling another app’s Synchronous Orchestration over HTTP adds network, authentication, and serialization overhead on every request. If you must process multiple records across apps, design the Synchronous Orchestration to accept a batch array in a single request rather than one record per HTTP call.
- Version by adding a new Synchronous Orchestration (
V2), not editingV1in place. Because App A, App B, and App C are promoted independently, changingCalculateTaxWithholdingV1‘s input or output contract breaks dependent apps the moment App A is promoted. CreateCalculateTaxWithholdingV2(calling an updated branch or v2 sub-orchestration), promote App A, and migrate App B and App C to theV2endpoint on their own schedules.
Pattern 2: Grouping O4I integrations and versioning with default parameters
In Orchestrate for Integrations (O4I), the Synchronous orchestration template is not available (O4I apps use the Workday Integration System template). When you have dozens of inbound or outbound integrations that share a common file format, Workday Web Services (WWS) pattern, and helper sub-orchestrations:
- Group integrations by domain, vendor, or business process into domain-level Integration Apps (for example, grouping all expense vendor integrations into one app rather than putting all 35 enterprise integrations into a single monolith).
- Use default input parameters on shared sub-orchestrations to evolve shared logic without breaking existing orchestrations in the same app.
Suppose five Integration System orchestrations in the same app call a shared sub-orchestration named ValidateAndTransformWorkerRow, and only one of those five integrations is ready to adopt a new validation rule for an upcoming release.
How to version a shared sub-orchestration in place
- Open
ValidateAndTransformWorkerRowin Orchestration Builder, click Configure Inputs on the Start step, and add a new input parameter namedschemaVersionof typeStringwith a default value of"1". - Existing Call ValidateAndTransformWorkerRow steps across the other four orchestrations do not need to be reconfigured; they automatically inherit the default
"1"value. - Inside
ValidateAndTransformWorkerRow, add a Branch on Conditions step (with Enable outputs turned on) that checks the version parameter:
| Branch | Condition Expression | Behavior |
|---|---|---|
| BranchIF (v2 logic) | Condition Expressiondata.Start.schemaVersion == "2" |
BehaviorRuns the new transformation and ends with a Create Values step outputting the standard return keys. |
| BranchELSE (v1 default) | Condition Expression(Default fallback) | BehaviorRuns the untouched production v1 steps and ends with a Create Values step outputting the exact same return keys and types. |
- Update only the target orchestration’s Call ValidateAndTransformWorkerRow step to pass
"2"forschemaVersion.
This allows you to promote the shared Integration App safely: the four unchanged integrations execute the exact same ELSE path they ran before, while the updated integration exercises the IF branch.
Component restrictions inside sub-orchestrations
Before moving steps into a shared sub-orchestration, verify that your components are supported in sub-orchestrations:
- Unsupported components: As documented in Add Suborchestrations, you cannot place Trigger Business Process or Send Workday RaaS Request steps inside a sub-orchestration. Keep those steps in the parent orchestration and pass their outputs into the sub-orchestration as explicit inputs.
- Supported checkpointing components: Trigger Integration and Retrieve Document are supported inside sub-orchestrations.
- Connector actions: A sub-orchestration that contains a Connector action can only be called from an orchestration built on the Custom Agent Action template; calling it from any other template fails the build.
How to verify shared sub-orchestration changes in the tenant
- Click Validate in Orchestration Builder on both the modified sub-orchestration and every parent orchestration that calls it to confirm that default parameters and branch output types match.
- Select the Call Suborchestration step in an unchanged parent orchestration, run Debug Step against your development tenant without overriding
schemaVersion, and verify in Debug Outputs that thev1branch executed and returned the expected structure. - Run Debug Step on the updated parent orchestration passing
schemaVersion = "2"and confirm that thev2branch output matches the contract before promoting the app through App Hub.