# Workday

Connect Workday so Suger AI can read your worker, organization, and time-off data.

---

## Overview

[Workday](https://www.workday.com) is an enterprise platform for human capital management and finance. Connecting it lets the Suger AI agent read your HR data — workers, organizations, job requisitions, compensation, and time off — and submit time-off requests, from a Suger workflow or chat.

### Org-Level vs User-Level

> **Org-Level**: Supported, using an OAuth client-credentials exchange against your own Workday tenant.
>
> **User-Level**: Not currently available. The API client is registered inside your own tenant rather than centrally, so there is no single Suger app your users could sign in to.

### How the connection works

The API client is registered in **your** Workday tenant. Suger exchanges its client ID and secret for an access token against your tenant's own token URL, and refreshes that token when it expires — Suger registers nothing on your behalf and holds no Workday client of its own.

```d2
shape: sequence_diagram
admin: "Your Workday admin"
workday: "Your Workday tenant"
suger: "Suger"
agent: "Suger AI agent"
admin -> workday: "Register an API client and grant security domains"
admin -> suger: "Client ID + Secret, token domain, tenant"
agent -> suger: "Run a Workday tool"
suger -> workday: "Exchange the client pair at your tenant's token URL"
workday -> suger: "Access token + expiry — Suger refreshes on expiry" { style.stroke-dash: 4 }
suger -> workday: "REST or WQL read"
workday -> agent: "Workers, organizations, requisitions, time off" { style.stroke-dash: 4 }
```

## Create Integration (Org-Level)

### Prerequisites

- A Workday tenant with REST API access enabled.
- Permission to run the **Register API Client** task (typically a security administrator).
- Your tenant's **host** and **tenant name**. These are not discoverable by Suger — expect to get them from whoever administers Workday. The host looks like `wd3-impl-services1.workday.com`; the tenant name is the short identifier in your Workday URLs.
- The Suger **Admin** role — connecting, disconnecting, and running an integration's actions are all admin-only in Suger.

### Authenticate by client credentials

1. In Workday, run the **Register API Client** task and register a client for integrations.
2. Grant it the security domains covering the data you want Suger to reach — Worker Data, Organization Information, Time Off, and so on. A missing domain makes the matching tool fail.
3. Copy the **Client ID** and **Client Secret**.
4. In the Suger console, open [Settings → Integrations](https://console.suger.io/settings?tab=integrations) and click **Connect** on **Workday**.
5. Enter:
   - **Token Domain** — your Workday host, for example `wd3-impl-services1.workday.com`.
   - **Tenant** — your tenant name.
   - **Client ID** and **Client Secret** — from step 3.
6. Save.

<!-- screenshot needed: the "Connect to Workday" dialog showing Token Domain, Tenant, Client ID and Client Secret — BLOCKED: the Workday connector is provisioned by the deploy-time migration, so the dialog cannot be reached in a local dev environment on this branch -->

:::info
The API client belongs to *your* tenant — Suger registers nothing on your behalf and holds no Workday client of its own. Revoking the client in Workday immediately breaks the connection.
:::

## Suger AI Tools

When Workday is connected, the Suger AI agent can read HR data through Suger's built-in tools (15 actions).

> **Org-level**: Every tool runs under the registered API client, so its security-domain grants set the ceiling on what the agent can reach.

| Capability | What the agent can do |
|------------|-----------------------|
| **Workers** | Read and list workers, and read one worker's compensation (e.g. `get-worker`, `list-workers`, `get-worker-compensation`) |
| **Organizations** | Read and list organizations, including supervisory organizations (e.g. `get-organization`, `list-supervisory-organizations`) |
| **Job requisitions** | Read and list job requisitions (`get-job-requisition`, `list-job-requisitions`) |
| **Time off** | Read a time-off detail, list a worker's time off and absence balances, and submit a time-off request (e.g. `list-worker-time-off`, `submit-time-off-request`) |
| **Custom queries** | Run a Workday Query Language (WQL) query, and read a custom object definition (`execute-wql-query`, `get-custom-object-definition`) |

:::info
Aside from `submit-time-off-request`, these tools are read-only. Workday is the newest of Suger's HR connectors and its tool set is deliberately narrow — `execute-wql-query` is the escape hatch for anything the typed tools don't cover.
:::

:::tip
Open the integration from **Settings → Integrations** to see the exact tool list for your connection on its **Actions** tab, and to try a call on the **Playground** tab. The Playground pre-fills only the inputs an action *requires* — add optional ones yourself when you need them.
:::

## Edit Integration

Editing is not supported. To rotate the client secret or point Suger at a different tenant, delete the integration and create it again.

## Delete Integration

Click the 🗑️ button next to **Workday** in the **Integrations** list. The stored client pair is destroyed with the integration record. Revoke the API client in Workday too if you want to cut access from that side.