Building a Workday Extend app that uses Custom Business Objects (CBOs), file attachments, or custom business processes involves two platform mechanics that catch developers by surprise when moving beyond a first prototype: how Workday generates Graph API queries and mutations from your model components, and what happens—both to the Weekly Service Update schedule and to your tenant-level security and credentials—when you promote that app in AppHub from a Development tenant to Implementation, Sandbox, and Production.

Here is a practical guide to the exact rules Workday documents for the Extend Graph API and the AppHub promotion lifecycle.

1. How Extend model components map into the Workday Graph API schema

When you deploy an Extend app containing model components (Business Objects, Attachment Objects, or Event Business Objects) to a tenant, Workday automatically adds or updates corresponding query and mutation operations in the tenant's Graph API schema (refresh your browser after deployment to see the updated schema in Graph API Explorer).

To guarantee global uniqueness across all apps in the tenant, Workday prefixes every generated Graph API query and mutation with your app's Reference ID:

Operation type Generated Graph API naming pattern Notes from Workday's Developer Guide
Read query <app reference id>_<BusinessObject name>
<app reference id>_<Attachment name>
<app reference id>_<EventBusinessObject name>		 Requires passing the dataSource argument (even if empty when unfiltered, e.g., dataSource: {<appRefId>_<pluralDataSource>: {}}).
Business Object mutations <app reference id>_create<BusinessObject name>
<app reference id>_update<BusinessObject name>
<app reference id>_delete<BusinessObject name>		 update requires both input and the target record's id (type: "WID", id: "...") passed as GraphQL variables.
Attachment mutations & downloads <app reference id>_create<Attachment name>
<app reference id>_create<AttachmentsCollection name>
<app reference id>_update<Attachment name>
<app reference id>_delete<Attachment name>		 Submitted as multipart/form-data with attachmentContent referencing the file part name (such as "file0"). Queries return metadata and downloadID; actual binary downloads use the Attachments REST API (https://api.workday.com/attachments/v1/graphql/{downloadID}).
Event Business Object mutation <app reference id>_create<EventBusinessObject name> Generated automatically for each Extend business process; initiates the business process event for the specified businessProcessTarget WID and returns warningValidations and criticalValidations.

Two Graph API naming traps when importing or naming apps

  1. Importing an app into a different developer account: Because every query and mutation name embeds <app reference id>_, if you export an Extend app from one developer account (such as a personal Open Developer Program account) and import it into a customer's company developer account where the app receives a different Reference ID, you must update every Graph API query and mutation name in your pages and orchestrations to match the new Reference ID.
  2. Reference IDs or field names starting with a number: Workday advises always starting your app Reference ID and field names with a letter. If an app Reference ID or field name begins with a number, the Graph API schema automatically prepends App_ before the number, which will break any PMD page or orchestration query that omits the App_ prefix.

2. Workday Graph API limits to design around

Before wiring a PMD page or an Orchestrate flow to the Graph API, account for Workday's documented limits:

  • Response page limit: Default is 20 rows per page; maximum is 100 rows per page.
  • Related business object instances: Querying a multi-instance field as a related business object returns a maximum of 500 instances. If the related business object contains more than 500 instances, the Graph API request returns an error rather than truncating silently.
  • Request timeout and complexity: Queries and mutations time out at 3 minutes (returning an error alongside only the fields processed so far) and fail if nested too deeply.
  • Rate limiting (HTTP 429 Too Many Requests): Workday rate-limits Graph API requests when query volume or complexity affects tenant health; orchestrations and external callers should implement exponential back-off retries and caching.
  • File attachment size: Maximum 30 MB per file attachment (subject to the allowed file types in Edit Tenant Setup - System; note that if you use the fileUploader PMD widget, the widget's own size limits override the 30 MB Graph API limit).

3. Promoting an Extend app through AppHub: Development → Implementation → Sandbox → Production

Once your app is validated and tested on a WCP Development tenant, promoting it in Developer Site → Console → Apps → Promotions follows a strict progression (Development → Promote to Implementation → Promote to Sandbox → Promote to Production), with four operational rules that trip up deployments (see our guide on why an Extend app validates but won't deploy or promote):

  1. Weekly Service Update deadline for Model Components: While presentation updates become available quickly after promotion (up to 1 minute cache update on Implementation tenants, and up to 15 minutes on Sandbox and Production tenants), new and updated model components deploy to Implementation tenants as part of Workday's Weekly Service Update. You must promote your app before Workday's weekly promotion deadline for those model components to land in the upcoming service window—and remember that model components promoted past Development follow strict immutability and deprecation rules (see safeguarding Extend data model updates).
  2. External client credential store refresh tokens (HTTP 500 in Sandbox Preview): When promoting to Sandbox, Workday requires you to create refresh tokens on the external client credential store in both your Sandbox and Sandbox Preview tenants. If you create business objects in Sandbox Preview without configuring refresh tokens in Sandbox Preview, accessing those business objects throws an HTTP 500 error.
  3. One-time Install vs. Tenant Refresh wipes: Clicking Install next to a target tenant in AppHub is required once per tenant. However, if an Implementation tenant is refreshed from a tenant where the app was not installed—or if Workday refreshes your Sandbox tenant from Production before you have installed the app in Production (see what a Workday Sandbox refresh wipes)—you must reinstall the app on that tenant.
  4. Tenant configuration that AppHub promotion does NOT copy: Promoting and installing an Extend app moves the app bundle, not your tenant-side security and workflow setup. On each target tenant (or after a refresh wipe), you must configure or migrate the app's Business Process Definitions, Business Process Security Policies, Custom Tasks, and Domain Security Policies (and run Activate Pending Security Policy Changes).

Building, validating, and testing Extend apps with kiweely

In kiweely, you can go from a plain-English requirement to a deployed Workday Extend app in one conversation: the agent designs your AMD, PMD, WQL, Graph API queries, and orchestrations, runs Workday's own validation on every revision, deploys to your Development tenant once you approve, configures the required tenant security policies, and tests the running app in a visible browser across each user role (see our Extend page).