Source: https://atomicwork.docs.pageloop.ai/integrations/hrms/workday # Workday # Workday Automate employee onboarding, offboarding, and role changes with synced HR data — and automate HR tasks like leave requests and time off from within your workflows. > **At a glance** > > | | | > | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | **What Workday is** | A Human Capital Management (HCM) system — the system of record for employees, staffing, and HR data. | > | **What Atomicwork supports** | **1. Employee sync** — powers onboarding, offboarding, and mover workflows. **2. Leave & staffing actions** across Absence Management, Team Management, and Time Tracking. **3. Call API** — call any Workday endpoint from a workflow. | > | **Authentication** | OAuth 2.0 (Authorization Code Grant) via a dedicated Integration System User (ISU). Requires Client ID, Client Secret, Tenant Name, REST API Base URL, and Authorization Base URL. | > | **Sync cadence** | Starts immediately when you enable sync, then runs automatically every 24 hours. | > | **Configured in** | Atomicwork → **Settings > Enterprise integrations > App store > Workday** | > | **Access required** | Org admin on Atomicwork; Security Administrator access in Workday (or equivalent) to complete setup. | ## Overview Workday is an HCM system — the system of record for your employees. The most common reason to connect it is to automate employee lifecycle work: when someone joins, changes role, or leaves in Workday, Atomicwork automatically triggers the matching onboarding, mover, or offboarding workflow — whether that's granting or revoking access, requesting a laptop, creating tickets, or any other task the workflow covers. It does this by **syncing workers** from Workday, through [Importing people into Atomicwork](/product/identity-access-management/people-roles-and-teams/importing-people-into-atomicwork). Beyond the lifecycle, workflows can also act on Workday's **leave and staffing data** — reading leave balances, submitting time-off requests, and looking up worker details across the Absence Management, Team Management, and Time Tracking modules. And the **Call API** capability lets any workflow call any Workday endpoint on demand, for anything the built-in actions don't cover. ## What you can automate There are three ways to put Workday to work in Atomicwork: ### Employee sync Syncing workers from Workday powers the full employee lifecycle: - **Onboarding (joiner)** — when a new hire appears in Workday, kick off onboarding: grant access, request a laptop or other equipment, create the right tickets, and more. - **Movers** — react to role, location, or organization changes with the right access and resource updates. - **Offboarding (leaver)** — when someone leaves, run offboarding: revoke access, reclaim equipment, and close out accounts. ### Out-of-the-box actions Ready-made actions you can drop into workflows without any custom code, from three configurable modules — **Absence Management**, **Team Management**, and **Time Tracking**: | Action | Description | | ---------------------------- | ------------------------------------------------------------------------------ | | **Get leave balances** | Retrieve leave balances for a specific worker. | | **Get eligible leave types** | Retrieve eligible absence types for a worker, filterable by category. | | **Apply for time off** | Submit a time-off request for a worker, across multiple dates. | | **Get valid time off dates** | Validate which dates are valid for time off for a worker. | | **Get worker details** | Retrieve detailed worker info, including job, location, and organization data. | | **List workers** | Retrieve all workers, with optional search and pagination. | ### Call API For anything the out-of-the-box actions don't cover, the **Call API** action reaches any Workday endpoint. ## Before you begin Make sure you have the following before you start: - **Security Administrator access in Workday** (or equivalent) — required for the setup tasks. - **Org admin access** on Atomicwork to connect the integration. During setup you'll create a dedicated Integration System User (ISU), a security group, and a registered API client, and grant the required permissions. By the end, you'll have gathered these connection details to enter in Atomicwork: | Field | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Client ID** | The OAuth 2.0 Client ID from the Workday API Client registration. | | **Client Secret** | The OAuth 2.0 Client Secret from the Workday API Client registration. | | **Tenant Name** | The Workday tenant name, for example `acme_impl1`. | | **REST API Base URL** | The base URL for Workday REST APIs. If your login URL is `https://acme.workday.com`, this is likely `https://acme-services1.workday.com`. | | **Authorization Base URL** | The base URL for Workday OAuth authorization, for example `https://acme.workday.com`. | See [Finding your connection values](#finding-your-connection-values) for how to derive the two base URLs and the tenant name. ## Permissions Workday checks access at two layers, and you grant them in two different places during setup. You need **both**: - **Scopes** — added when you **register the API client** (Setup step 3). They control what the integration can _request_. - **Domain permissions** — added to your **security group** (Setup step 4). They control what data the ISU can _read_. The domains below are required — grant all of them. Scopes depend on which capabilities you enable. ### For user sync - **Scopes (step 3):** Staffing, System (System is required for WQL, which sync uses to read worker attributes). - **Domains (step 4)** — grant all of the following with **Get** access: | Domain | Access | | ------------------------------------------- | ------ | | Workday Query Language (enables WQL itself) | Get | | Worker Data: Public Worker Reports | Get | | Worker Data: Workers | Get | | Worker Data: Current Staffing Information | Get | | Person Data: Personal Data | Get | | Person Data: Work Contact Information | Get | | Person Data: Home Contact Information | Get | - **Report/task permission (step 4b):** the **Workday Query Language** domain also needs your security group added to its **Report/Task Permissions** with **View** access. This is separate from the **Get** domain permission above — without it, WQL queries are rejected even though the domain is granted. ### For out-of-the-box actions In step 3, add the scope that matches the actions you'll use: - **Leave and time-off actions** (Get leave balances, Apply for time off, and similar) → **Time Off and Leave** - **Worker and staffing actions** (Get worker details, List workers) → **Staffing** ### For Call API In step 3, add the scope that matches the Workday endpoint you're calling. **Domains for actions and Call API are tenant-specific.** Grant them in step 4 as needed — if a request is denied, the Workday error names the exact domain to add, or run **View Security for Securable Item** on the relevant web service to find it. ## Setup Setup has two phases: prepare your Workday tenant (steps 1–4), then connect in Atomicwork (step 5). ### 1. Create the Integration System User (ISU) The ISU is the dedicated service account behind the integration — all Workday API calls run under it, keeping the integration independent of any personal account. 1. In Workday, search for and open the **Create Integration System User** task. 2. Enter a user name, such as `ISU_Atomicwork`. 3. Set a strong password and store the credentials securely — you'll need them during authorization. 4. Set **Session Timeout Minutes** to `0`. 5. Leave **Require New Password at Next Sign In** unchecked. 6. Leave **Do Not Allow UI Sessions** unchecked — the account must be able to sign in through the browser during authorization. 7. Click **OK**. ### 2. Create the security group and add the ISU An ISU has no access on its own. Permissions are granted to a security group, and the ISU inherits them by being a member. 1. In Workday, search for and open the **Create Security Group** task. 2. Set **Type of Tenanted Security Group** to **Integration System Security Group (Unconstrained)**. Unconstrained access is required so the integration can access all workers, not only those in specific organizations. 3. Enter a name, such as `ISSG_Atomicwork`, and click **OK**. 4. On the next screen, add your ISU (for example `ISU_Atomicwork`) under **Integration System Users**. 5. Click **OK**, then **Done**. ### 3. Register the API client You need an account with administrator or integration security permissions for the **Register API Client** task to appear in Workday search. 1. In Workday, search for and open the **Register API Client** task. This opens the **Edit API Client** screen. 2. In **Client Name**, enter `Atomicwork` (or another label you'll recognize). 3. In **Client Grant Type**, select **Authorization Code Grant** — the OAuth flow Atomicwork uses. 4. In **Access Token Type**, select **Bearer**. 5. In **Redirection URI**, enter this exactly — it must match Atomicwork's value precisely or the connection will fail: ```text https://esd.atomicwork.com/api/external-oauth/public/install ``` 6. In **Scope (Functional Areas)**, add the scopes listed in [Permissions](#permissions) for the capabilities you plan to use. For employee sync, add both **Staffing** and **System**. 7. Enable these checkboxes: - **Non-Expiring Refresh Tokens** — keeps the connection alive so it doesn't need re-authorizing later. - **Grant Administrative Consent** — approves the integration for the whole org, so individual users aren't prompted. - **Include Workday Owned Scope** — required for the selected scopes to work fully. 8. Leave everything else at its default: **Support Proof Key for Code Exchange (PKCE)** unchecked, **Allow User Delegation** unchecked, **Enforce Customized Access Token Expiry** unchecked, **Allow Integration Messages** unchecked, **Disabled** unchecked, **Locked Out due to Excessive Failed Signon Attempts** unchecked, **Restricted to IP Ranges** empty, **x509 Certificate** empty, and **Refresh Token Timeout (in days)** `0`. 9. Click **OK**. Workday displays the generated **Client ID** and **Client Secret** — copy the **Client Secret** immediately, as it's shown only once. ### 4. Grant domain permissions and activate Client scopes control what the integration can _request_; domain permissions control what the ISU can _read_. Workday requires both. #### 4a. Grant the domain permissions 1. In Workday, search for and open the **Maintain Permissions for Security Group** task. 2. Select your security group (for example `ISSG_Atomicwork`), set **Operation** to **Maintain**, and click **OK**. 3. On the **Domain Security Policy Permissions** tab, add every domain listed in [Permissions](#permissions) — one domain per row, each with **Get** access. All of them are required; the integration fails if any is missing. 4. Click **OK**. #### 4b. Add the security group to the WQL Report/Task Permissions Employee sync reads worker attributes through Workday Query Language (WQL). The **Get** permission from step 4a grants access to the domain's data, but WQL is also a securable report/task — so your security group has to appear in the domain's **Report/Task Permissions** table with **View** access as well. **Maintain Permissions for Security Group** doesn't expose that table, so edit it from the domain itself: 1. In Workday search, enter **Domain Security Policies for Functional Area** and open the report result. 2. For **Functional Area**, enter **System**, then click **OK**. 3. In the list of domains, find and click **Workday Query Language**. Its details open, including the **Report/Task Permissions** table — scroll down to confirm which groups are currently listed. 4. Next to **Domain Security Policy: Workday Query Language**, click the **Related Actions** menu (**•••**). 5. Go to **Domain Security Policy > Edit Permissions** (wording varies slightly by Workday version). 6. In the edit screen, scroll to the **Report/Task Permissions** table — it's separate from **Domain Security Policy Permissions**, and may appear as its own section or tab. 7. Add a row and select your security group (for example `ISSG_Atomicwork`). 8. Tick **View** for that group. 9. Click **OK**, then **Done**. #### 4c. Activate the changes Search for and open **Activate Pending Security Policy Changes**, enter a comment, tick **Confirm**, and click **OK**. Permission changes from both 4a and 4b stay inactive until activation is complete. ### 5. Connect Workday in Atomicwork 1. In Atomicwork, go to **Settings > Enterprise integrations > App store > Workday**. 2. Click **Connect**. 3. Enter your **Client ID**, **Client Secret**, **Tenant Name**, **REST API Base URL**, and **Authorization Base URL**. 4. You're redirected to Workday's authorization page. Sign in with the **ISU** credentials from step 1 (for example `ISU_Atomicwork`, or `ISU_Atomicwork@` if prompted) — not a personal account — and grant consent. This binds the integration to the ISU so all API calls run under it. 5. After you grant consent, you're redirected back to Atomicwork and the connection is established automatically. #### Finding your connection values The **REST API Base URL**, **Authorization Base URL**, and **Tenant Name** all come from the endpoint rows on the Workday API client page. For example: ```text Workday REST API Endpoint: https://wd2-impl-services1.workday.com/ccx/api/v1/ibmsrv_pt1 Authorization Endpoint: https://impl.workday.com/ibmsrv_pt1/authorize ``` From those rows: - **Tenant Name** is the last path segment of the REST API Endpoint — here, `ibmsrv_pt1`. - **REST API Base URL** is the REST API Endpoint with everything after `.com` removed — here, `https://wd2-impl-services1.workday.com`. - **Authorization Base URL** is the Authorization Endpoint with everything after `.com` removed — here, `https://impl.workday.com`. In short: for both base URLs, keep only up to `.com` and delete everything after it. The tenant name is the short code repeated in those URLs. ### Manage the connection If the refresh token expires due to prolonged inactivity, or your credentials change, reconnect the integration at **Settings > Enterprise integrations > App store > Workday**. ## Behaviors and limits Design your workflows around these behaviors: - **Worker IDs are Workday UUIDs**, not employee numbers. Use the **List Workers** action to find the correct UUID for a worker. - **Both permission layers are required.** A capability fails if either the API client scope or the matching domain permission is missing. - **Employee sync uses WQL** (Workday Query Language), which requires the **System** scope, **Get** access on the Workday Query Language domain, _and_ your security group listed with **View** access in that domain's **Report/Task Permissions**. - **Pagination.** The **List Workers** action supports optional search and pagination. - **Tokens.** Non-expiring refresh tokens are enabled during setup, but prolonged inactivity can still expire the token — reconnect if that happens. ## Troubleshooting | Error | Cause | Resolution | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **Worker not found** | The worker ID is a Workday internal UUID, not the employee number. | Use the **List Workers** action to find the correct UUID. | | **Leave type requires reason** | Some leave types require a reason. | Use **Get Eligible Leave Types** to check whether a reason is required, and provide the reason ID. | | **Position-based leave type** | Some leave types require a position ID. | Use **Get Leave Balances** to find the position ID associated with the worker. | | **Token expired** | The refresh token expired due to prolonged inactivity. | Reconnect the integration at **Settings > Enterprise integrations > App store > Workday**. | | **Connection fails during authorization** | The Redirection URI in the API client doesn't exactly match Atomicwork's value, or you signed in with a personal account instead of the ISU. | Confirm the Redirection URI matches exactly, and sign in as the ISU. | | **An action is denied** | The matching domain permission isn't granted or wasn't activated. | Grant the domain the error names (or find it via **View Security for Securable Item**), then run **Activate Pending Security Policy Changes**. | | **Employee sync fails or returns no workers, but the WQL domain is granted** | The security group has **Get** on the Workday Query Language domain but isn't in the domain's **Report/Task Permissions** with **View** access. | Complete [step 4b](#4b-add-the-security-group-to-the-wql-reporttask-permissions), then activate the pending security policy changes. | ## Related - [Importing people into Atomicwork: setting up sync from multiple sources](/product/identity-access-management/people-roles-and-teams/importing-people-into-atomicwork#setting-up-sync-from-multiple-sources) - Need help? Contact for assistance with your Workday integration.