> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/hr-systems/workday.md). # Workday Connect Swarmia directly to Workday to sync time off and leaves, and match workers. Swarmia connects directly to Workday using credentials you create in Workday and paste into Swarmia. Once connected, Swarmia syncs time off and leaves of absence, and matches Workday workers to Swarmia authors. ## Requirements * **Swarmia organization admin.** Connecting Workday requires the [organization admin role](/settings/organization/managing-users-and-roles.md) in Swarmia. * **Workday administrator.** Creating the integration user and registering the API client takes security administration access in Workday. The two halves can be done by different people: a Workday admin produces four values, and a Swarmia organization admin pastes them in. * **Work email on every worker.** Swarmia matches Workday workers to Swarmia authors by their public primary work email. Workers without one won't sync, and their time off won't show up in Swarmia. ## Create the integration user in Workday Run these Workday tasks in order. 1. **Create Integration System User.** Name it **Swarmia**. Set a password that doesn't expire, so the connection doesn't break when a password policy runs. 2. **Create Security Group.** Choose **Integration System Security Group**, name it **Swarmia Integration**, and add the integration system user you just created. 3. **Maintain Permissions for Security Group.** Grant your new group **Get** access to the domains listed below. 4. **Activate Pending Security Policy Changes.** Permission changes don't take effect until you activate them. Skipping this is the most common reason a connection fails straight after setup. ### Constrained or unconstrained When you create the security group, Workday asks whether it's constrained. A **constrained** group is limited to selected supervisory organizations, so the integration user can only ever see people in those parts of your organization. An **unconstrained** group sees everyone. Either works. If you constrain the group, Swarmia only sees absences for workers inside the organizations you picked, and Workday doesn't report the people it left out. If time off is missing in Swarmia for part of your company, check this first. ### Domains Grant **Get** access to: * Worker Data: Public Worker Reports * Self-Service: Current Staffing Information * Worker Data: Time Off * Self-Service: Leave of Absence * Worker Data: Leave of Absence * FLW Service Grant all six, including the two leave of absence domains. Workday keeps long absences such as parental leave separately from ordinary time off, and Swarmia reads both. Without those two, someone on a six-month leave looks like they worked the whole time. ## Register the API client 1. Run **Register API Client for Integrations**. Name it **Swarmia**. 2. Select the scopes **Staffing**, **Time Off and Leave**, and **Tenant Non-Configurable**. 3. Set **Access Token Type** to **Bearer** and leave the refresh token as non-expiring. 4. Finish the task. Workday shows the **Client ID** and **Client Secret** once. Copy both now. 5. Run **Manage Refresh Tokens for Integrations**, choose the Swarmia integration system user, and generate a refresh token. Copy it. 6. Run **View API Clients** and copy the **Token Endpoint**. {% hint style="warning" %} **Workday shows the client secret once.** Copy it before you leave the page. To get a new one you have to generate new credentials, which changes the client ID too. {% endhint %} You should now have four values: the token endpoint, the client ID, the client secret, and the refresh token. ## Connect Workday in Swarmia 1. Go to **Settings** → [**HR system**](https://app.swarmia.com/settings/hr-system). 2. In the Workday row, click **Connect**. 3. Paste the token endpoint, client ID, client secret, and refresh token, then click **Connect**. Swarmia checks the credentials against your tenant before saving anything, and stores them encrypted. The status flips to **Connected** and the first sync starts in the background. If Workday rejects them, Swarmia tells you which part failed: * **The token endpoint.** It isn't a Workday address, or it isn't the one from **View API Clients**. * **The tenant.** Swarmia couldn't reach it. * **The credentials.** The client ID, client secret, and refresh token don't belong to the same API client, or the refresh token has been revoked. * **Access.** The credentials work, but the integration user can't read worker data. Check the domains, and check that you ran **Activate Pending Security Policy Changes**. {% hint style="warning" %} **Make sure the token endpoint is for your real Workday, not a test one.** Most companies have a test Workday as well as the real one, and its credentials work just as well. If you paste those, Swarmia connects without complaining and then syncs test data. Test addresses usually have `-impl-` in them. Swarmia warns you if it spots one, and the settings page always shows which Workday it's connected to. {% endhint %} ## What Swarmia syncs ### Time off * All time off from **2 years** before you connected to **1 month** ahead, refreshed every **24 hours**. * Only **approved** time off counts. Entries that are submitted, sent back, or not submitted don't. * **Canceled and denied time off is removed.** It disappears from Swarmia on the next refresh. * **Part days count as a full day.** Half a day, or a few hours off, is stored as a whole day. * **Every time off type counts.** Vacation, sick leave, and everything else are treated the same. Swarmia never reads balances, approvers, reasons, or comments. ### Leaves of absence Workday tracks long absences — parental leave, sabbatical, long-term sick leave — apart from day-to-day time off, so Swarmia reads them separately. * **Only fully approved leaves count.** A leave still working its way through approvals doesn't, and neither does one that was canceled or rescinded. * **An open leave runs to its expected return date.** Workday doesn't record the real last day until someone completes the return from leave, so until then Swarmia uses the expected one. If there isn't one either, the leave counts as ongoing and extends by a day with each refresh. * **The real end date replaces the estimate** as soon as the return is recorded in Workday. ### Worker data * **Work email and name only.** Swarmia uses them to match each Workday worker to a Swarmia author. * **Terminated workers are included**, so time off from before someone left stays in your historical reports. Swarmia doesn't read compensation, job details, org structure, or any other worker fields. ## Where the data shows up * **Developer effort metrics** — approved time off reduces a person's available days, so effort scores reflect when people are actually working. * **FTE counts** — feed into [investment balance](/features/focus/balance-engineering-investments.md) and [software capitalization](/features/capitalize-software-development-costs.md) reports. * **Work log** — time off appears when work log is grouped by author. See [Developer effort (FTEs)](/definitions/developer-effort-ftes.md) for how time off factors into the calculation. ## Check the connection status The [HR system settings](https://app.swarmia.com/settings/hr-system) page shows the host and tenant Swarmia is connected to, and the current status: * **Connected** — the integration is healthy and syncing. * **Disabled** — Workday stopped accepting the credentials, so syncing has stopped. If Workday rejects the credentials during a sync, Swarmia waits an hour in case it's a temporary outage. If they're still rejected after that, Swarmia disables the integration and emails your Swarmia organization admins. The time off Swarmia already has stays as it is. The most common causes are the integration system user being deactivated, the API client being deleted, or the refresh token being revoked. All three are routine Workday administration, and Workday doesn't tell Swarmia they happened. ## Rotate the credentials 1. In Workday, run **Manage Refresh Tokens for Integrations** and generate a new refresh token for the Swarmia integration system user. 2. In Swarmia, click **Reconnect** in the Workday card and paste the new values. The new credentials replace the old ones and syncing continues. Reconnecting the same way also fixes a disabled integration. To stop syncing, click **Disconnect** in the Workday card. Swarmia stops calling your tenant, and the time off it already has stays as it is. ## Related * [HR systems overview](/settings/integrations/hr-systems.md) * [Upload time off data via CSV](/settings/integrations/hr-systems/upload-time-off-data-via-csv.md) — alternative when a direct integration isn't an option. * [Time off API](/settings/integrations/swarmia-apis/time-off-api.md) — push time off into Swarmia programmatically. * [Developer effort (FTEs)](/definitions/developer-effort-ftes.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.swarmia.com/settings/integrations/hr-systems/workday.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.