---
title: "Reuse and version Workday sub-orchestrations — Kiweely"
description: "Why sub-orchestrations are app-scoped in Workday Orchestrate, how to expose shared logic via Synchronous Orchestrations, and how to version with parameters."
url: https://kiweely.com/guides/workday-orchestrate-reuse-sub-orchestrations-across-apps
---

# Reusing and versioning sub-orchestrations across Workday Extend and O4I apps

Sub-orchestrations cannot be called directly across different Workday Extend or Integration apps. Expose shared cross-app logic through a versioned Synchronous Orchestration REST endpoint, or version shared sub-orchestrations inside a single O4I app using default input parameters and branching.

-   **Checked** against Workday on November 6
-   Applies to **Workday Orchestrate**
-   5 min read
-   Published November 6
-   By Kiweely

## 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

1.  **Build the reusable logic in App A:** Keep the core steps inside a sub-orchestration (for example, `CalculateTaxWithholdingSub`) or directly inside a **Synchronous** orchestration named `CalculateTaxWithholdingV1`.
2.  **Expose the Synchronous Orchestration as an API:** Configure the request and response schema on `CalculateTaxWithholdingV1` and deploy App A to the target tenant.
3.  **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`).
4.  **Configure authentication and domain permissions:** Use `isuAuth` for background service-to-service calls or `sso` when 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 editing `V1` in place.** Because App A, App B, and App C are promoted independently, changing `CalculateTaxWithholdingV1`‘s input or output contract breaks dependent apps the moment App A is promoted. Create `CalculateTaxWithholdingV2` (calling an updated branch or v2 sub-orchestration), promote App A, and migrate App B and App C to the `V2` endpoint 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:

1.  **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).
2.  **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

1.  Open `ValidateAndTransformWorkerRow` in **Orchestration Builder**, click **Configure Inputs** on the **Start** step, and add a new input parameter named `schemaVersion` of type `String` with a default value of `"1"`.
2.  Existing **Call ValidateAndTransformWorkerRow** steps across the other four orchestrations do not need to be reconfigured; they automatically inherit the default `"1"` value.
3.  Inside `ValidateAndTransformWorkerRow`, add a **Branch on Conditions** step (with **Enable outputs** turned on) that checks the version parameter:

| Branch | Condition Expression | Behavior |
| --- | --- | --- |
|  **IF** (v2 logic) | `data.Start.schemaVersion == "2"` | Runs the new transformation and ends with a **Create Values** step outputting the standard return keys. |
|  **ELSE** (v1 default) |  *(Default fallback)* | Runs the untouched production v1 steps and ends with a **Create Values** step outputting the exact same return keys and types. |

1.  Update only the target orchestration’s **Call ValidateAndTransformWorkerRow** step to pass `"2"` for `schemaVersion`.

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

1.  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.
2.  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 the `v1` branch executed and returned the expected structure.
3.  Run **Debug Step** on the updated parent orchestration passing `schemaVersion = "2"` and confirm that the `v2` branch output matches the contract before promoting the app through **App Hub**.

## Sources checked

-   [Add Suborchestrations](https://developer.workday.com/documentation/GUID-3f9210c4-d46a-4162-bcb2-32f382bbe8ec)
-   [Reference: Call Suborchestrations](https://developer.workday.com/documentation/GUID-fe0c208b-1a29-4eb5-bdea-628fc2480de3)
-   [Import Orchestrations and Suborchestrations](https://developer.workday.com/documentation/GUID-35b17bb0-a0b2-4314-8282-93c5fda2dcd7)
-   [Concept: Integration App Lifecycle](https://developer.workday.com/documentation/GUID-ff44b82e-ff86-46d5-aeab-7a694bd8a974)
-   [Reference: Branch on Conditions](https://developer.workday.com/documentation/GUID-925c6c89-cd46-4d9d-858d-cc07fe5d2b8b)
-   [Creating Integrations Using Workday Orchestrate: Modular Orchestration Design](https://doc.workday.com/workday-education/en-us/course-manuals/creating-integrations-using-workday-orchestrate/modular-orchestration-design.html)

## Related guides

[All guides](https://kiweely.com/guides)

-   [### Overcoming ‘Message length should be lesser than 1MB in size’ and ‘Orchestration is too large to be saved’ Embedding a large BIRT .rptdesign XML layout in Create Text Template hits ‘Message length should be lesser than 1MB in size’, while large canvases hit ‘Orchestration is too large to be saved’. Load BIRT designs via intsys.attachmentContent(), delete disabled steps, and split into sub-orchestrations.](https://kiweely.com/guides/workday-orchestrate-1mb-message-limit-too-large-to-save)
-   [### Why Workday sub-orchestrations and BP orchestrations show Completed when an API call fails By default, Send Workday API Request sets isSuccess to true whenever Workday returns a response, even a SOAP fault or validation error. Use a custom HTTP retry policy, Continue on Conditions with isSoapFault(), or an Integration System orchestration with Add Integration Message to surface failures.](https://kiweely.com/guides/workday-orchestrate-sub-orchestration-completed-on-api-error)
-   [### Logging in Workday Orchestrate: Log, Log to File, Add Integration Message and verbose logging The Log step writes to the app logs on the Developer Site, kept 30 days. Add Integration Message writes to the integration event in the tenant. Log to File builds a named CSV log you attach with Store Document. Verbose logging is a time-limited REST switch for troubleshooting.](https://kiweely.com/guides/workday-orchestrate-logging)
-   [### Branch on Conditions outputs must match: fixing Enable outputs, and when to use Continue on Conditions instead With Enable outputs on, every IF and ELSE branch must hand on the same output names and data types, because later steps read one output from the branch step. End each branch with a Create Values step setting the same keys, or use Continue on Conditions when a path should stop.](https://kiweely.com/guides/workday-orchestrate-branch-outputs-must-match)

### More guides on Orchestrate

[All 86 guides](https://kiweely.com/guides#orchestrate)

-   [Picking up SFTP files from subfolders and reading IDs from PDF filenames in Orchestrate](https://kiweely.com/guides/workday-orchestrate-sftp-subfolders-pdf-files)
-   [Sending email from Orchestrate: the Connect sendMessage API and email connectors](https://kiweely.com/guides/workday-orchestrate-send-email)
-   [How to keep large Workday Orchestrate loads inside the runtime limits: templates, checkpoints, batches and child runs](https://kiweely.com/guides/workday-orchestrate-runtime-limit-large-loads)
-   [How to rebuild an XSLT transformation in Workday Orchestrate](https://kiweely.com/guides/workday-orchestrate-replace-xslt)
-   [RaaS calls in Orchestrate: namespaces, unexpected character errors, 401s and empty reports](https://kiweely.com/guides/workday-orchestrate-raas-errors)
-   [How to process a CSV file in Orchestrate for Integrations, from Document Retrieval to the output file](https://kiweely.com/guides/workday-orchestrate-process-csv-file)
-   [Loading and reading Prism Analytics tables from a Workday orchestration](https://kiweely.com/guides/workday-orchestrate-prism-datasets)
-   [OAuth 2.0 and refresh tokens for third-party APIs in Workday Orchestrate, using the Workday credential store](https://kiweely.com/guides/workday-orchestrate-oauth-refresh-tokens)

### From the blog on Orchestrate

[All posts](https://kiweely.com/blog)

-   [Orchestrate, an iPaaS, or Kiweely Roots](https://kiweely.com/blog/orchestrate-ipaas-or-kiweely-roots)
-   [Codex for Orchestration JSON: Catching the 25-Second Sync Trap Before Deploy](https://kiweely.com/blog/codex-orchestration-json-25-second-sync-trap)
-   [Keep in Studio, Move to Orchestrate, or Rebuild as an Extend App? A Practical Triage Matrix](https://kiweely.com/blog/migrating-legacy-workday-studio-integrations-to-orchestrate-decision-matrix)

## Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

[Start for free](https://kiweely.com/download) [See how it works](https://kiweely.com/vine/how-it-works)

## Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.
