> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workday

> Connect Serval to your Workday tenant so workflows can look up workers, manage time off and benefits, and automate HR requests through Workday's REST, WQL, and SOAP APIs.

## About Workday

Workday is a human capital management (HCM) platform. The Serval Workday integration is a per-tenant connection to your Workday environment: it gives Serval workflows live access to Workday's REST sub-APIs (30+ modules including Staffing, Person, Absence Management, Payroll, and Recruiting), Workday Query Language (WQL), and ten Workday Web Services (SOAP) services. It also ships two installable workflow bundles - Worker Lookup, and Time Off & Benefits - so common HR lookups work out of the box. Every connection is specific to your tenant: the REST API Base URL, Token Endpoint, and optional user-auth endpoints all belong to your Workday environment.

**Authentication:** Service account via OAuth 2.0 refresh-token grant, tied to an Integration System User (ISU) and an API Client for Integrations registered in your Workday tenant. An optional, feature-flagged per-user (3-legged) OAuth path lets certain actions run as the end user.

**Data sync:** On-demand only. Nothing is mirrored into Serval on a schedule - workflow actions and health checks call Workday live, and a fresh access token is obtained from your tenant's token endpoint for every call.

## What the Workday integration enables

| Capability                               | Description                                                                                                                                                                                                                                                                                                                             |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| REST requests across 30+ Workday modules | Typed request actions for Workday's REST sub-APIs, including Staffing, Person, Absence Management, Compensation, Payroll, Global Payroll, Recruiting, Talent Management, Time Tracking, Expense, Procurement, Projects, Custom Reports (RaaS), Workday Help, Prism Analytics, Student modules, Workday Connect messaging, and more.     |
| WQL (Workday Query Language) queries     | Run WQL queries against standard data sources such as allWorkers, allActiveWorkers, and allActiveAndTerminatedWorkers - used by worker lookups and the WQL health check.                                                                                                                                                                |
| SOAP (Workday Web Services) requests     | Typed SOAP actions for ten services: Staffing, Human Resources, Absence Management, Benefits Administration, Compensation, Integrations, Payroll, Performance Management, Recruiting, and Time Tracking. Common operations include Get\_Workers, Hire\_Employee, Terminate\_Employee, Get\_Job\_Postings, and Get\_Organization\_Goals. |
| Worker lookup and change-request helpers | Higher-level actions such as find worker by email or employee ID, find eligible absence types, get organization goals, and update a worker's primary home phone number or home address (including adding a home phone number where none exists).                                                                                        |
| Worker Lookup bundle                     | Six prebuilt workflows: Search for Workday Worker by Name, Get Workday Worker ID by Email, Get Workday Worker, List Workday Workers, Get Workday Worker Absence, and Get Workday Holiday Events. All default to no-approval.                                                                                                            |
| Time Off & Benefits bundle               | Four prebuilt workflows: Get User PTO Balance from Workday, Get Workday Eligible Absence Types, Lookup Workday Team Member Time Off Requests, and Get Workday Worker Benefit Elections. All default to no-approval.                                                                                                                     |
| Write workflows                          | Two additional prebuilt write workflows: Update Workday Worker Primary Home Phone Number and Update Workday Worker Primary Home Address. Both default to installer-approval.                                                                                                                                                            |
| Per-user (as-user) requests              | When the optional per-user OAuth app is configured, a user-scoped variant of the REST request action calls Workday as the acting user with their own credential (currently the Request sub-API). The user must have connected their personal Workday account first.                                                                     |

Anything defined in the [Workday API](https://community.workday.com/sites/default/files/file-hosting/restapi/index.html) can be accessed through Serval.

## Get your credentials

Setting up the connection requires a Workday administrator. You will create an Integration System User (ISU), grant it the security it needs, register an API Client for Integrations, and generate a refresh token. Workday's official API reference is the [Workday REST Services Directory](https://community.workday.com/sites/default/files/file-hosting/restapi/index.html).

<Tabs>
  <Tab title="Service account (required)">
    <Steps>
      <Step title="Create the Integration System User">
        In Workday, search for **Create Integration System User** and create the ISU (for example, `ServalIntegration`). The password cannot contain the characters `&`, `<`, or `>`.
      </Step>

      <Step title="Exempt the ISU from password expiration">
        Search for **Maintain Password Rules** and add the ISU to **System Users exempt from password expiration**.
      </Step>

      <Step title="Create a security group">
        Search for **Create Security Group**, choose the type **Integration System Security Group (Unconstrained)** (for example, `Serval Integration Group`), and add the ISU under Integration System Users.
      </Step>

      <Step title="Grant domain security policies">
        Search for **Maintain Permissions for Security Group** (Operation: Maintain; Source Security Group: your group) and add the Domain Security Policies your use case needs. The minimum for worker reads is **Worker Data: Public Worker Reports** with Get Only access.

        <Warning>
          Only grant the permissions you actually need. Every Serval action runs with the ISU's permissions.
        </Warning>
      </Step>

      <Step title="Activate the security changes">
        Search for **Activate Pending Security Policy Changes** and confirm.
      </Step>

      <Step title="Allow the group to authenticate">
        Search for **Manage Authentication Policies**, add your security group to an authentication rule with Allowed Authentication Types **User Name Password** or **Any**, then run **Activate All Pending Authentication Policy Changes**.
      </Step>

      <Step title="Register the API client">
        Search for **Register API Client for Integrations**. Set a name (for example, `Serval Workday API Client`), make it a confidential client, enable the **Refresh Token** grant, allow **Non-Expiring Refresh Tokens**, and save. Copy the **Client ID** and **Client Secret**.

        <Warning>
          The Client Secret may only be shown once. Copy it immediately and store it securely.
        </Warning>
      </Step>

      <Step title="Generate the refresh token">
        Search for **Manage Refresh Tokens for Integrations**, select your API client, add the ISU as the Authorized User, choose an expiration, generate, and copy the **Refresh Token** - it is not viewable again.

        <Tip>
          Choose **Never** for expiration if your policy allows. Every Serval-to-Workday call depends on this refresh token; if it expires, all Workday actions stop working until you update the connection.
        </Tip>
      </Step>

      <Step title="Copy the endpoints">
        Search for **View API Clients**, open your API client, and copy two values: the **REST API endpoint** (ends with `/ccx/api/<tenant>` - this maps to Serval's **REST API Base URL** field) and the **Token endpoint** (ends with `/ccx/oauth2/token` - this maps to Serval's **Token Endpoint** field).
      </Step>

      <Step title="Copy the SOAP WSDL URL">
        Search for **Public Web Services**, locate the SOAP service you use (for example, **Human Resources (Public)**), choose **Web Services → View WSDL**, and copy the service URL for Serval's **WSDL URL** field.
      </Step>

      <Step title="Find your tenant name">
        Your tenant name appears in your Workday URL (for example, `https://wd2-impl.workday.com/<tenant>/d/home.html`), or ask your administrator.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Per-user OAuth (optional)">
    The per-user path is purely additive - the service account keeps working unchanged if you skip this. It lets certain workflow actions run as the acting end user instead of the ISU.

    In your Workday tenant, register a **second** OAuth API client with the **Authorization Code** grant. Its redirect URL is Serval's callback endpoint for this flow. For Serval's main US cloud, register this exact value:

    ```
    https://svflow-auth-config.api.serval.com/workday/user/oauth/callback
    ```

    If your Serval tenant is on the EU shard, use `https://api.eu1.serval.com/v1/svflow-authconfig/workday/user/oauth/callback` instead (ask [support@serval.com](mailto:support@serval.com) if you're unsure which region you're on). Workday requires an exact redirect-URL match, so register it verbatim.

    Capture the client's Client ID and Client Secret, plus your tenant's authorize endpoint (for example, `https://wd2-impl-services1.workday.com/<tenant>/authorize`). You will enter these in the optional User-Auth fields on the Serval connect form.

    <Note>
      The per-user path is currently in limited release. The User-Auth fields only appear on the connect form once it's enabled for your team - contact **[support@serval.com](mailto:support@serval.com)** to turn it on. Workday OAuth is per-tenant - there is no global client, so the config lives on your connection.
    </Note>
  </Tab>
</Tabs>

## Connect in Serval

<Steps>
  <Step title="Open the Workday connect form">
    In Serval, add a new Workday connection. The form collects your tenant details, OAuth credentials, and SOAP fields.
  </Step>

  <Step title="Enter your Tenant Name">
    **Tenant Name** (required) - for example, `mycompany`. This becomes the connection's name in Serval. Saving without it fails with: `Invalid Workday configuration: tenant name is required`
  </Step>

  <Step title="Enter the OAuth credentials">
    **Client ID** (required), **Client Secret** (required), and **Refresh Token** (required) - from the API client and refresh token you created in Workday. All three are stored encrypted. Missing values fail with, respectively: `Invalid Workday configuration: client ID is required`, `Invalid Workday configuration: client secret is required`, and `Invalid Workday configuration: refresh token is required`
  </Step>

  <Step title="Enter the endpoints">
    **REST API Base URL** (required) - for example, `https://wd2-impl-services1.workday.com/ccx/api/mycompany`. It must start with `https://` and contain `/ccx/api/` - Serval derives every REST and SOAP endpoint from this one URL. Errors on create: `Invalid Workday configuration: REST API base URL is required` or `Invalid Workday configuration: REST API base URL must start with https://`. When editing: `REST API base URL must start with https://` or `Invalid REST API base URL format`

    **Token Endpoint** (required) - for example, `https://wd2-impl-services1.workday.com/ccx/oauth2/token`. Must start with `https://`. Errors on create: `Invalid Workday configuration: token endpoint is required` or `Invalid Workday configuration: token endpoint must start with https://`. When editing: `Token endpoint must start with https://` or `Invalid token endpoint format`
  </Step>

  <Step title="Enter the SOAP fields">
    **WSDL URL** (required by the form) - for example, `https://wd2-impl-services1.workday.com/ccx/service/amn1/Human_Resources/v28.2`. **ISU Username** (required by the form) - for example, `ServalIntegration`. **ISU Password** (required by the form) - stored encrypted.

    <Note>
      These three fields are required by the form but are not validated when the connection is saved, and they are not used to make requests - SOAP endpoints and authentication are derived from the REST API Base URL and OAuth credentials (see Gotchas and troubleshooting below).
    </Note>
  </Step>

  <Step title="(Optional) Configure per-user OAuth">
    If the per-user OAuth feature is enabled for your team, three optional fields appear: **User-Auth OAuth Client ID**, **User-Auth OAuth Client Secret**, and **User-Auth Authorize Endpoint** (placeholder `https://wd2-impl-services1.workday.com/<tenant>/authorize`). Leave them blank if this connection only uses the service account. These endpoints are validated when the user OAuth flow runs (not at save): both the authorize and token endpoints must be HTTPS URLs on `*.workday.com` or `*.myworkday.com`.
  </Step>

  <Step title="Save the connection">
    Save, then run the health checks below to verify everything works.
  </Step>
</Steps>

<Warning>
  Edit behavior differs by field type. The six secret fields (Client ID, Client Secret, Refresh Token, ISU Password, User-Auth OAuth Client ID, User-Auth OAuth Client Secret) display obfuscated (•••• plus the last 4 characters) and **keep their stored value** if you leave them blank or unchanged. The six non-secret fields (Tenant Name, REST API Base URL, Token Endpoint, WSDL URL, ISU Username, User-Auth Authorize Endpoint) are saved **exactly as submitted** - clearing one of them clears the stored value. The edit form prefills current values; don't delete them unless you mean to. The connection's display name and API domain update only when you submit a new, non-empty Tenant Name or REST API Base URL.
</Warning>

## Verifying the connection

Four health checks verify the connection on demand:

**List Workday Workers** - lists up to 10 workers through the Staffing API using the service-account credential, verifying REST connectivity and worker-read permissions.

* Success: `Successfully listed [number] workers`
* Failure: `Unable to list workers.` - on permission errors (401/403) it adds ` The API credentials may be invalid or the integration user may not have the required permissions.`; on Workday server errors (500/502/503) it adds ` Workday returned a server error. This is likely a temporary issue - please try again later.`

**List Supervisory Organizations** - lists up to 5 supervisory organizations through the Staffing API, verifying org-structure read access.

* Success: `Successfully listed [number] supervisory organizations`
* Failure: `Unable to list supervisory organizations.` - with the same conditional permission and server-error suffixes as above.

**Execute WQL Query** - runs a one-row WQL query (`SELECT worker, fullName FROM allWorkers LIMIT 1`) to verify Workday Query Language access.

* Success: `Successfully executed WQL query (returned [number] result(s))`
* Failure: `Unable to execute WQL query.` - with the same conditional permission and server-error suffixes as above.

**SOAP API - Get Workers** - calls the Staffing SOAP service's Get\_Workers operation requesting a single worker, verifying SOAP connectivity.

* Success: `Successfully connected to Workday SOAP API (retrieved [number] worker(s))`
* Failure: `Unable to connect to Workday SOAP API.` - with SOAP-specific suffixes: on authentication errors, ` The ISU username or password may be invalid. Please check your integration configuration.`; on forbidden errors, ` The ISU does not have permission to access the Staffing SOAP service. Please check Workday security group assignments.`; on WSDL errors, ` Could not connect to the WSDL URL. Please verify the WSDL URL is correct and accessible.`; on connection errors, ` Could not connect to Workday. Please verify the WSDL URL and network connectivity.`; otherwise the generic permission and server-error suffixes.

<Tip>
  If the two REST checks and the SOAP check pass but **Execute WQL Query** fails, your tenant likely has WQL disabled - the connection itself is fine. Worker lookups that depend on WQL (finding a worker by email or employee ID) will keep failing until WQL is enabled in your tenant, or those workflows are switched to the equivalent SOAP-based lookup (the Get\_Workers operation).
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Every Workday action suddenly fails at once">
    Serval fetches a fresh access token from your Token Endpoint on every single call - there is no token caching for the service account. If the refresh token expires, is revoked, or the API client secret is rotated in Workday, every Workday call fails immediately until you update the connection with new credentials. Use non-expiring refresh tokens where your policy allows.
  </Accordion>

  <Accordion title="The WQL health check fails but everything else passes">
    Some Workday tenants have WQL disabled. A failing Execute WQL Query check does not necessarily mean the connection is broken - if the REST and SOAP checks pass, the connection works. However, worker lookups that depend on WQL (such as finding a worker by email or employee ID) will not succeed until WQL is enabled, or those workflows are adapted to use the SOAP Get\_Workers operation instead - the switch is not automatic.
  </Accordion>

  <Accordion title="The SOAP check fails even though the form saved without errors">
    The backend only validates Tenant Name, REST API Base URL, Token Endpoint, Client ID, Client Secret, and Refresh Token at save time. WSDL URL, ISU Username, and ISU Password are required by the form but are stored without validation and never used when requests are made - a typo in them neither blocks saving nor breaks the SOAP check. When the SOAP check fails, look at the values that actually drive SOAP calls: the **REST API Base URL** (every SOAP endpoint is derived from it - see the next accordion), the OAuth credentials (Client ID, Client Secret, Refresh Token), and the ISU's security group permissions in Workday (the health check needs access to the Staffing SOAP service). Although the SOAP failure guidance mentions the ISU username and password, live SOAP requests authenticate with the same OAuth bearer token as REST requests - the ISU matters because it underpins the refresh token and the permissions model, not through the stored ISU Password field.
  </Accordion>

  <Accordion title="The REST API Base URL is the keystone field">
    Every REST and SOAP endpoint Serval calls is derived from the REST API Base URL at request time - the stored WSDL URL field is not used to build request URLs. The base URL must contain `/ccx/api/`; if it doesn't, SOAP endpoint derivation fails with an `Unexpected API domain format` error. If anything looks wrong across the board, verify this field first against the **View API Clients** task in Workday.
  </Accordion>

  <Accordion title="Editing the connection cleared a field">
    Only the secret fields keep their stored value when left blank during an edit. The non-secret fields - Tenant Name, REST API Base URL, Token Endpoint, WSDL URL, ISU Username, and User-Auth Authorize Endpoint - are written exactly as submitted, so submitting one of them empty blanks it out (clearing the Token Endpoint, for example, breaks every call). The connection's display name and API domain are only updated when you submit a new, non-empty value. The edit form prefills current values; leave them in place unless you intend to change them.
  </Accordion>

  <Accordion title="Per-user OAuth quirks">
    The three User-Auth fields only appear once the per-user OAuth feature is enabled for your team. The user-auth app is a separate Workday OAuth API client (Authorization Code grant) stored on the service-account connection - leaving the fields blank changes nothing about the service account. Both the authorize and token endpoints are validated when the OAuth flow runs (not when you save): they must be HTTPS on `*.workday.com` or `*.myworkday.com`, since the client secret travels to these URLs. If someone tries to connect their personal Workday account before the app is configured, the attempt fails with: `workday connection has no user-auth OAuth app configured (set the User-Auth OAuth Client ID/Secret)`. Other endpoint errors include: `workday connection is missing the user-auth authorize/token endpoint`, `workday user-auth authorize endpoint "<url>" must use https`, and `workday user-auth authorize endpoint "<url>" is not an allowed workday host`. An as-user workflow action fails at run time if the acting user has not connected their personal Workday account. User tokens are refreshed only near expiry and always against the exact connection that minted them.
  </Accordion>

  <Accordion title="Following an older setup guide?">
    Earlier versions of this documentation described SOAP support as "coming soon" and used different field names. SOAP is fully supported today, with ten Workday Web Services available. The current form labels are **REST API Base URL** (previously described as "REST API Endpoint") and **WSDL URL** (previously "Web Services Endpoint URL"). The WSDL URL should now be a full versioned service URL (for example, `https://wd2-impl-services1.workday.com/ccx/service/amn1/Human_Resources/v28.2`), not a bare `/ccx` address.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Workday integration.