Skip to content
KiweelyKiweelyKiweely

How Workday Stores Custom Plan Names, Reason Codes, and Translated Labels Across APIs

Workday separates UI label overrides (Maintain Custom Labels) from tenanted object translations (Translate Business Object). Across REST, WQL, RaaS, and SOAP APIs, descriptor strings resolve dynamically from the caller’s language and locale hierarchy while IDs stay invariant.

  • Checked against Workday on
  • Applies to Workday Translations & APIs
  • 6 min read
  • Published
  • By Kiweely
On this page

Workday manages tenant terminology across two distinct configuration layers—delivered UI term overrides (Maintain Custom Labels / Maintain Non-English Custom Labels) and tenanted business object data translations (Translate Business Object / Translations Hub)—and resolves human-readable descriptor strings in REST, WQL, RaaS, and SOAP responses dynamically according to the authenticated caller’s language and locale hierarchy.

Integrations and custom employee screens break when developers hardcode string comparisons against descriptor values (such as "Vacation" or "Transfer > Move to another Manager"), or wonder why French-Canadian and Spanish workers receive US English plan names when requests run through a single US-English Integration System User instead of user-delegated OAuth 2.0.

Layer 1 vs. Layer 2: Custom UI Labels vs. Tenanted Object Translations

Before reading labels over an API, distinguish where a term actually lives inside Workday configuration:

Dimension Delivered UI Label Overrides Tenanted Business Object Translations Custom Report & RaaS Labels
DimensionPrimary Admin Tasks Delivered UI Label OverridesMaintain Custom Labels (English) & Maintain Non-English Custom Labels + Maintain Non-English Custom Label Overrides Tenanted Business Object TranslationsEdit Tenant Setup - Global, Translations Hub, Translate Business Object, or globe In-Context Translation icon Custom Report & RaaS LabelsRelated Actions on report: Translation > Translate Instance & Custom Report > Translate
DimensionRequired Security Domain Delivered UI Label OverridesCustom Label Management and Custom Label Management for Non-English (System functional area) Tenanted Business Object TranslationsData Translation and Data Translation: In-Context Translation (System functional area) Custom Report & RaaS LabelsData Translation + Custom Report Administration (System functional area)
DimensionWhat It Renames Delivered UI Label OverridesDelivered platform nouns (singular, plural, possessive) within a Term Context—e.g., Contingent Worker -> Contractor, or Spanish registro de entrada -> registro de ingreso Tenanted Business Object TranslationsCustomer-created instances: Absence Plan names, Benefit Plan names, Job Change / Termination Reasons, Organizations, Questionnaires, Text Blocks Custom Report & RaaS LabelsReport Name, Column Heading Overrides, Prompt Labels, Sort Group Overrides, Instructions
DimensionEffect on REST / SOAP Schema Keys Delivered UI Label OverridesNone. Workday does not apply custom labels to security or integration schema property names Tenanted Business Object TranslationsPopulates descriptor (REST/WQL) and wd:Descriptor (SOAP) in the caller’s resolved display language Custom Report & RaaS LabelsTranslates RaaS UI headers/prompts; XML element tags stay fixed to the report’s XML alias

Critical Nuances on Maintain Custom Labels and Non-English Overrides

  1. Integrations and Existing Report Titles Stay Unchanged: Workday explicitly does not replace terms inside security administration or integration definitions, and creating a custom label for Contingent Workers does not automatically rename an existing custom report titled Custom Report for Contingent Workers.
  2. Two-Task Activation for Non-English Custom Labels: When overriding a Workday-delivered term in another language (for example, Spanish (Neutral) under the Time Core context), entering an Override Value and clearing Disabled on Maintain Non-English Custom Labels triggers a background preparation job. Once that job finishes, you must open Maintain Non-English Custom Label Overrides and select Use Proposed Value (or Use All Proposed Values) for the override to appear on self-service tasks (and via the Get_Non-English_Custom_Label_Overrides SOAP operation).
  3. Search Index Timing: Newly saved custom labels appear in Workday search results only after the Friday server restart index rebuild (or an explicit Rebuild Search Index run, which Workday recommends avoiding during peak hours).

How Workday Determines Which Language an API Call Receives

Whenever a caller invokes a Workday REST endpoint, WQL query, RaaS report, or SOAP operation, Workday evaluates a strict six-level fallback chain for the authenticated Run As User to choose which language string populates descriptor fields:

  1. User’s Selected Preferred Display Language (set via Change Preferences or Edit Workday Account)
  2. User’s Selected Preferred Locale
  3. Selected Language of the Worker’s Primary Business Site Location
  4. Selected Locale of the Worker’s Primary Business Site Location
  5. Default Language of the Tenant
  6. Default Locale of the Tenant (typically English (United States))

Two additional tenant switches govern what happens when a specific plan name or reason code has not been translated into the worker’s target language yet:

  • Base Language Fallback & Allow Mixed-Language Transactions: Every Workday object stores a Base Language (viewable via the Base Languages report). On self-service views, untranslated items may be suppressed unless Allow Mixed-Language Transactions is checked on Edit Workday Account / Manage Workday Accounts (or no translation exists for a text block, in which case Workday falls back to the base language).
  • Base Value Edits (Hide Translations after Base Value Change): On Edit Tenant Setup - Global, if Hide Translations after Base Value Change is checked and an admin edits the English base name of a Time Off Plan or Question, Workday clears the active translation (Needs Translation status on Translate Business Object). Note also that for Effective-Dated Snapshot objects (such as Organization), creating a new effective-dated snapshot copies existing translations forward, whereas editing the base value on an existing translated snapshot deletes its translations.

[!IMPORTANT] Why User-Delegated OAuth Fixes Multilingual Self-Service Automatically If your external portal or assistant queries Workday through a shared Integration System User (RaaS user-delegated OAuth vs. ISU Basic Auth), every worker receives descriptor strings in the ISU’s language (almost always US English). When each worker authenticates via Register API Client (Authorization Code Grant with PKCE), Workday evaluates that worker’s Preferred Display Language and primary work location automatically—returning French, German, Spanish, or Japanese plan and reason names with zero external translation tables to maintain.

Reading Plan Names, Reason Codes, and Descriptors Across REST, WQL, and SOAP

Across every Workday API surface, Workday pairs an immutable identifier (id / WID or Reference_ID) with a localized human label (descriptor / @wd:Descriptor).

1. Workday REST APIs (absenceManagement, common, staffing)

Every object reference in a Workday REST response contains id (the 32-character Workday ID) and descriptor (localized for the current OAuth caller). Compare what GET /common/v1/jobChangeReasons or GET /absenceManagement/v5/workers/me/eligibleAbsenceTypes returns for two workers in the same tenant:

json
// Worker A (Preferred Display Language: English)
{
  "data": [
    {
      "id": "a18c426056a1100018b52d4e99c10042",
      "descriptor": "Annual Paid Vacation (Hours)"
    },
    {
      "id": "b7187dceedb34c8db3a8e15adf02a620",
      "descriptor": "Transfer > Transfer > Move to another Manager"
    }
  ]
}
json
// Worker B (Preferred Display Language: French - Canada, translated via Translate Business Object)
{
  "data": [
    {
      "id": "a18c426056a1100018b52d4e99c10042",
      "descriptor": "Vacances annuelles payées (Heures)"
    },
    {
      "id": "b7187dceedb34c8db3a8e15adf02a620",
      "descriptor": "Mutation > Mutation > Changement de gestionnaire"
    }
  ]
}

Notice that id (a18c426056a1100018b52d4e99c10042) is identical across both languages, including hierarchical Category > Subcategory > Reason strings configured on Maintain Event Categories and Reasons.

2. Workday Query Language (WQL)

When querying WQL (/ccx/api/wql/v1/{tenant}/data), selecting any business object reference field returns { "id": "...", "descriptor": "..." } localized to the authenticated caller:

Works
SELECT timeOffPlan,
       timeOffType,
       unitOfTime
FROM eligibleTimeOffPlansForWorker

Rule for WHERE Clauses: Never write WHERE timeOffPlan = 'Annual Paid Vacation' in WQL or filter arrays in TypeScript by item.descriptor.includes("Vacation"). Filter by immutable WID or Reference_ID so renaming a plan on Edit Time Off Plan or switching user locales never breaks query predicates.

3. Workday Web Services (SOAP)

In SOAP responses (for example, Get_Time_Off_Plans in Absence_Management or Get_Workers in Human_Resources; see calling SOAP with user-delegated Bearer credentials), Workday includes the wd:Descriptor XML attribute on *_Reference elements when descriptors are not suppressed in the request header:

xml
<wd:Time_Off_Plan_Reference wd:Descriptor="Vacances annuelles payées (Heures)">
  <wd:ID wd:type="WID">a18c426056a1100018b52d4e99c10042</wd:ID>
  <wd:ID wd:type="Absence_Plan_ID">PTO_ANNUAL_HRS</wd:ID>
</wd:Time_Off_Plan_Reference>

Keep <wd:Include_Reference_Descriptors_In_Response>true</wd:Include_Reference_Descriptors_In_Response> inside bsvc:Workday_Common_Header whenever your application renders reference labels directly from SOAP responses.

Audit Checklist for Missing or Stale Translated Labels

  1. Verify Language Enablement: Open Edit Tenant Setup - Global and confirm the target language has Enabled checked in the Available Languages grid.
  2. Audit Base Value Resets: Run the Translation Base Value Change Audit report (or View Translatable Values for Language / Search Translatable Text from Translations Hub) to catch plan names or reasons stuck in Needs Translation or Needs Review after an English copy edit.
  3. Check Location vs. User Preference: Remember that localized country-specific fields (such as Maintain Local Termination Reasons or custom country names on Maintain Workday Delivered Country Names) filter availability by the worker’s primary work location, whereas the text translation of those values follows the worker’s Preferred Display Language.
  4. Test Under Real Worker Sessions: Sign in as a test worker whose Preferred Display Language is set to Spanish or French via user-delegated OAuth—or build multilingual employee screens in Kiweely Leaf (coming next), which reads each signed-in worker’s live tenant terminology and translated descriptors automatically without duplicating translation dictionaries outside Workday.

Frequently asked questions

Does Maintain Custom Labels change SOAP XML element names or REST JSON property keys?

No. Workday explicitly excludes security and integration schemas from Maintain Custom Labels overrides so API contracts remain stable. Overriding Contingent Worker to Contractor changes self-service UI labels, not JSON keys or WSDL element names.

Why did editing the English name of an Absence Plan or Question clear its French and Spanish translations?

When Hide Translations after Base Value Change is checked on Edit Tenant Setup - Global, editing the base language value of a tenanted translatable attribute clears its active display status and marks existing translations as Needs Translation until reviewed on Translate Business Object.

Why does a RaaS report or REST API return English plan names when called through an Integration System User?

Workday resolves object descriptors and custom report labels using the authenticated Run As User's Preferred Display Language and Locale hierarchy. Because an Integration System User typically defaults to US English, calling via an ISU strips individual worker language preferences—whereas user-delegated OAuth returns descriptors in each signed-in worker's language.

Should external applications filter business logic on the descriptor string or on the Workday ID / Reference ID?

Always key programmatic logic on the 32-character Workday ID (id) or Reference ID, and treat descriptor / @Descriptor strictly as a localized human display label. Descriptor strings change whenever a user switches display languages or an admin renames a plan.

Sources checked

Related guides

All guides

Let Workday check the work.

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

Get the next guide in your inbox.

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

We’ll email you once to confirm. Unsubscribe in one click from any issue.