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

# Workday

> Connect Workday as your HRIS to power employee self-service

Connect Workday as your HRIS to power employee self-service. Once connected, Risotto can look up employee information, retrieve PTO balances, and more. These actions are controlled by the [People Actions](/dashboard/settings/people/actions) settings.

## Connect from the Dashboard

Open **Settings → People → Connect** and click **Connect** on the **Workday** row. The configuration panel is titled "Configure the Risotto Workday integration for HR management using OAuth 2.0 JWT bearer authentication" and has two parts:

* An **Instructions** pane on the left with a **Generate certificate & private key** button and the Workday setup steps.
* A form on the right with the required fields listed below, a **Test connection** button, and a **Save** button.

<Steps>
  <Step title="Generate the certificate and private key">
    Click **Generate certificate & private key**. Risotto creates a self-signed certificate and PKCS#8 private key (RSA 2048, roughly 10-year validity) and displays the certificate PEM for you to copy into your Workday tenant.

    Each click creates a new key pair and replaces the previous one. If you click the button again, put the new certificate in Workday too. Workday refuses the connection if its public key does not match the key that Risotto saved.
  </Step>

  <Step title="Register the public key in Workday">
    Run the **Create x509 Public Key** task in Workday. Paste the certificate PEM
    from the previous step and set **Name** to `risotto_workday_integration_key`.
  </Step>

  <Step title="Create the Integration System User">
    Create an **Integration System User (ISU)** and assign the domain security
    and/or user security groups described under [ISU Security
    Configuration](#isu-security-configuration) so the user can read and update
    the worker data Risotto uses.
  </Step>

  <Step title="Fill in the connection form and save">
    Enter the required information below and click **Save**.
  </Step>
</Steps>

## Required Information

To connect Workday, provide:

* **Integration System Username** (required): The Integration System User account Risotto will authenticate as, for example `integration_user`
* **Client ID** (required): The API client ID, a UUID in the form `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
* **Tenant URL** (required): The host of your Workday API, without a path. Copy it from the **Token Endpoint** of the Risotto API client in Workday (run **View API Clients**).
* **Tenant Name** (required): The name of your Workday tenant. It is the part of the **Token Endpoint** after `/ccx/oauth2/`. Only letters, numbers, underscores, and hyphens are allowed.
* **X.509 Public Key**: Generated from the Risotto dashboard and uploaded to Workday

Risotto builds the token URL as `<Tenant URL>/ccx/oauth2/<Tenant Name>/token`. This URL must be the same as the **Token Endpoint** in Workday. For example, if the Token Endpoint is `https://wd5-services1.myworkday.com/ccx/oauth2/acme/token`, enter:

* **Tenant URL**: `https://wd5-services1.myworkday.com`
* **Tenant Name**: `acme`

<Note>
  Many Workday hosts start with a data center prefix such as `wd5-`, but some do
  not. Copy the host exactly as the Token Endpoint shows it. Do not add or
  remove a prefix.
</Note>

## ISU Security Configuration

The ISU must have domain security in Workday, and the API client must have matching functional area scopes. Without these, Risotto cannot read or write the corresponding worker data, even if the action is toggled on in the dashboard.

When a domain is missing, Workday refuses the request with a permission error. The tools **Get Workday Employee Info**, **Get Workday Home Address**, **Get Workday Time Off Balance**, and **Update Workday Home Address** then tell the agent that Workday is not configured correctly, and your admins get one alert for each tool: "Workday denied access to this data. Make sure the integration system user's security group has the required domain permissions in Workday." Add the missing domain to the ISU's security group in Workday.

### Domain Security Policies

Assign these to the ISU's integration security group. Domain names can vary slightly by tenant, search **Domain Security Policies** in Workday for the closest match.

**Worker lookup**

| Domain | Permission | Purpose |
| - | - | - |
| Worker Data: Public Worker Reports | Get | WQL queries to resolve workers by email |
| Worker Data: Workers | Get | Retrieve worker details (job title, manager, org) |
| Worker Data: Current Staffing Information | Get | Resolve person ID from worker ID via Staffing service |
| Worker Data: All Positions | Get | Current and historical position details |
| Staffing | Get | General staffing service access |
| System: Workday Query Language | Get | Execute WQL queries |
| System: Worker Event History | Get | Read worker event history |

**Personal data**

| Domain | Permission | Purpose |
| - | - | - |
| Person Data: Personal Data | Get | Get personal data |
| Person Data: Personal Information | Get | Get personal information fields |

**Home address**

| Domain | Permission | Purpose |
| - | - | - |
| Person Data: Home Contact Information | Get and Put | Read home addresses and update them within a change event |
| Person Data: Home Address | Get and Put | Secures *Change Home Contact Information (REST Service)* |
| Self-Service: Home Address | Get and Put | Secures *Change Home Contact Information (REST Service)* initiated on behalf of the worker |
| Person Data: Work Contact Information | Get | Read work contact information |

**Time off and absence**

| Domain | Permission | Purpose |
| - | - | - |
| Worker Data: Time Off | Get and Put | PTO balances, time off entries, eligible types, and submitting time off requests |
| Absence Management | Get and Put | Absence management operations |
| Worker Data: Absence Balances | Get | Retrieve PTO balances |
| Self-Service: Time Off and Leave Balances | Get | Retrieve time off and leave balances |

### API Client Scopes

When you register the API client in Workday, grant these functional areas:

* **Staffing**: worker lookup, initiate home contact information changes
* **Personal Data**: read personal information
* **Contact Information**: read and update home addresses
* **Time Off and Leave**: PTO balances, time off entries, eligible types, and time off requests
* **Absence Management**: PTO balances and time off requests
* **System**: WQL support and REST API routing
* **Tenant Non-configurable**: global scope required for WQL and People resources

<Warning>
  Note: Once these security domains and API scopes have been updated, run the
  **Activate Pending Security Policy Changes** task to ensure changes are
  applied.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.