Upgrading an existing Workday Extend application is fundamentally different from editing application source code. While page layouts (PMD) and orchestrations can be revised, replaced, or rolled back between versions, data model changes are often irreversible once deployed to a tenant.

When an Extend app defines a Custom Business Object (CBO) and stores records in a tenant, modifying attribute types or removing fields can permanently break existing data or block promotion.

This guide explains how Workday handles data model changes and outlines the safe deprecation patterns to follow when updating live applications.

1. The Immutability Rules of Extend Business Objects

Workday enforces strict schema backward compatibility to prevent data corruption in enterprise tenants:

  • Field Deletion is Restricted: Once an attribute on a Custom Business Object has been promoted and contains persisted values, removing that attribute from your Application Metadata Definition (AMD) will trigger validation errors during tenant deployment.
  • Type Narrowing is Prohibited: You cannot change a text field to an integer, or convert a multi-select reference into a single-select reference, if records already exist.
  • Mandatory Field Constraints: You cannot introduce a new non-nullable (required) attribute on an existing object without providing a valid default or migration path, because existing rows will violate the schema.

2. Safe Field Deprecation Pattern (The Expand/Contract Model)

Instead of modifying or deleting an existing field directly, use the three-stage Expand/Contract pattern:

Phase 1: Expand (Introduce the New Field)

  1. Add the new attribute to the Custom Business Object definition in your application metadata with an updated, descriptive name (for example, targetCompletionDate instead of dueDate).
  2. Keep the legacy attribute in the model, but mark its description or UI presentation as deprecated.
  3. Update all Page Model Definitions (PMD) and Orchestrations to write to the new field while maintaining fallback reads from the legacy field if the new field is blank.
  4. Deploy this version to your Development and Sandbox environments and verify that new records populate the new attribute.

Phase 2: Migrate (Backfill Existing Records)

  1. If historical records need to reflect the new structure, write a data migration orchestration or run an administrative batch update to copy legacy field values into the new field format.
  2. Verify with a WQL query that all active instances now have the new attribute populated.
  3. Remove the legacy field from all user-facing PMD pages, reports, and API inputs so that no new transactions write to it.

Phase 3: Contract (Retire the Legacy Field)

  1. Remove any business logic or validation rules that depend on the legacy attribute.
  2. In the Application Metadata Definition, leave the legacy attribute present but unused, or mark it read-only in the application security definition.
  3. By leaving the physical attribute definition intact in the model, existing tenant records remain valid and will not fail tenant promotion checks.

3. Pre-Promotion Verification Checklist

Before promoting a new application version containing data model changes from Development to Sandbox or Production, verify these four checks:

  1. Schema Diff Inspection: Compare the old AMD data model definition against the new AMD file. Confirm that no existing attribute names or fundamental data types were altered in place.
  2. Nullable Check on New Attributes: Ensure every newly added attribute on existing Custom Business Objects is defined as optional (nullable) or has an automated default value assigned on create.
  3. WQL Query Regression: Run existing WQL queries against the updated object schema in Sandbox to confirm that field aliases, relationship paths, and filter clauses continue to return expected rows.
  4. Promotion Dry-Run: Use Workday's app deployment validation tool in your target tenant before initiating the final installation. Look for warnings regarding schema changes or dependency collisions.

Sources checked