# Workday

Connect Workday to Risotto with an API client and an Integration System User, then use the Workday runbook templates for time off and home address requests

Connect Workday as your HRIS to power employee self-service. Once Workday is connected:

- The support agent can look up the requester's employee record. Turn this on with **Agent access** on the **People** tab of [Support agent > Context](https://www.tryrisotto.com/docs/dashboard/settings/support-agent/context#people).
- The Workday runbook templates handle time off and home address requests. See [Set up time off and home address requests](#set-up-time-off-and-home-address-requests).

## Connect from the dashboard

Workday is in the **HRIS** category of [Settings > Integrations](https://www.tryrisotto.com/docs/dashboard/settings/integrations). The **Workday** dialog has two parts: the form, and an **Instructions** pane with the Workday setup steps. On a narrow screen, the instructions are collapsed under **Instructions**.

1. **Open the Workday dialog**

   Go to **Settings > Integrations** and click **Workday**. On the **API client** card, click **Connect**.

2. **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), saves the private key, and shows the certificate PEM. Click **Copy** to copy the certificate for your Workday tenant.

   *Product example: The Workday setup dialog in the Risotto dashboard, with the Generate certificate & private key button.*

   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.

3. **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`.

4. **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.

5. **Register an API client in Workday**

   Register an API client with these settings:

   - **Client Grant Type**: JWT Bearer Grant
   - **x509 Certificate**: the certificate that you registered in Workday
   - **Access Token Type**: Bearer
   - **Scopes (Functional Areas)**: the areas under [API client scopes](#api-client-scopes)

6. **Fill in the form and save**

   Enter the values under [Required information](#required-information) and click **Save**. A toast confirms "Workday settings saved". If you have not generated a certificate yet, Risotto shows "Generate a certificate and private key first" and saves nothing.

7. **Test the connection**

   Click **Test connection**. The button is available after you save, while the form has no unsaved changes. When Workday accepts the credentials, the dialog shows **Connected**. Otherwise it shows the error from Workday. Click **Close** to close the dialog.

After you save, the **API client** card shows the **Tenant URL**, **Tenant Name**, **Client ID**, **Integration system user** and a masked **Private key**. To change the values, click **Connected** on the card, then click **Configure...**.

## 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.

The private key is not a field. Risotto saves it when you click **Generate certificate & private key**.

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.

## 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 tool that needs it is on.

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:** Once these security domains and API scopes have been updated, run the
> **Activate Pending Security Policy Changes** task to ensure changes are
> applied.

## Set up time off and home address requests

Time off and home address requests use the Workday runbook templates in **Runbooks** > **Templates**. Each template needs Workday tools, which you create from the template's page.

| Template                        | What the agent does                                                                                              | Tools it needs                                                 |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Workday Time Off Request**    | Looks up the requester's balances and submits time off requests in Workday. Changes to booked time off go to HR. | **Get Workday Time Off Balance**, **Request Workday Time Off** |
| **Workday Time Off Balance**    | Looks up the requester's balances. Escalates every request to take, change, or cancel time off to HR.            | **Get Workday Time Off Balance**                               |
| **Workday Home Address Update** | Looks up the requester's home address, confirms the new address with them, and saves it in Workday.              | **Get Workday Home Address**, **Update Workday Home Address**  |
| **Workday Home Address Lookup** | Looks up the requester's home address. Collects a new address and escalates the change to HR.                    | **Get Workday Home Address**                                   |

Each pair matches the same requests, so turn on only one template of each pair. The other Workday templates are **Workday Support**, which gives guidance from your knowledge base and Workday's documentation, and **Workday Job Requisition Lookup**. If **Workday Support** is on, it also matches some time off and address requests. Remove those terms from its conditions, or turn it off.

1. **Find the Workday templates**

   Go to **Runbooks** and click **Browse templates**. Type `Workday` in **Search templates**. The **HR** group lists the time off and home address templates.

   *Product example: Runbook templates in the Risotto dashboard, searched for Workday, with the Workday HR templates listed.*

2. **Open a template**

   Click the template, for example **Workday Time Off Request**. The page shows the template's match condition, its agent instructions, the **Required tools**, and **Tips** in the side panel.

3. **Create the required tools**

   Under **Required tools**, click **Create** beside each tool that shows **Not set up**. The tool editor opens for that tool. Keep **Restrict to Requestor Only** on, so the tool works only on the requester's own record. To have a person review each time off request or address change before it reaches Workday, turn on **Requires Approval** on the request or update tool. Save the tool, and the dashboard returns to the template. If a tool shows **Disabled**, click **Enable**.

4. **Use the template**

   Click **Use this template**. The button is available once every required tool is ready. If your organization has more than one tool for a required tool, the **Choose tool instances** dialog asks which one to use: pick one for each and click **Continue**. The runbook editor opens with the template filled in. Save the runbook and turn it on, as in [Create a runbook](https://www.tryrisotto.com/docs/dashboard/runbooks#create-a-runbook).

   *Product example: The Workday Time Off Request template page in the Risotto dashboard, with the Use this template button.*

The templates act only for the requester. Before the agent submits time off or changes an address, it confirms the details with the requester and waits for their reply.

## Runbook tools

You can also add Workday tools to your own [runbooks](https://www.tryrisotto.com/docs/dashboard/runbooks). Create them on the [Tools](https://www.tryrisotto.com/docs/dashboard/tools) page:

| Tool                             | What it does                                                          |
| -------------------------------- | --------------------------------------------------------------------- |
| **Get Workday Employee Info**    | Reads the employee's worker record from Workday                       |
| **Get Workday Time Off Balance** | Reads the employee's balances and the time off types they can request |
| **Request Workday Time Off**     | Submits a time off request in Workday                                 |
| **Get Workday Home Address**     | Reads the employee's home address                                     |
| **Update Workday Home Address**  | Changes the employee's home address in Workday                        |
| **Get Workday Job Requisition**  | Reads the details of a job requisition                                |

- Each employee tool has a **Restrict to Requestor Only** option, which is on by default. When it is on, the tool works only for the requester of the ticket.
- **Request Workday Time Off** needs the employee's confirmation, given after the agent asks for it. It does not submit a request for a time off type the employee cannot use, for dates that already have time off, or for more time than the balance allows.

## Disconnecting

To disconnect Risotto from Workday, click **Connected** on the **API client** card, then click **Disconnect...**. In the **Disconnect from Workday?** dialog, click **Disconnect**. Risotto clears the saved Workday settings, and the Workday tools stop working.

Source: https://www.tryrisotto.com/docs/dashboard/settings/people/connect/workday
