# Workday setup

Connect Workday to Axiad Mesh to bring in the user data needed to fill out your
environment and let Axiad find correlations, risks, and gaps in your population.

Workday connects through the **unified HRIS connector**. This page covers the
Workday-side configuration you complete first — an Integration Systems User, an
API client, and a refresh token. Once that's done, you add the connector in Mesh
by following [Connect your HR system](../connect-your-hr-system.md).

## Workday configuration steps

> **warning**

These steps reflect Axiad's current understanding of the configuration. Because
Workday is a third-party product, there may be slight variations between your
experience and what this guide describes. We work hard to keep things as up to
date as possible, but depending on the versions in use and the latest updates,
there may be some mismatches.

If you find any significant differences or anything that doesn't make sense,
let us know through Axiad support.

To configure Workday for API access, complete the following steps. You can then
connect Workday in Mesh.

### Create an Integration Systems User and security group

1. In Workday, create an **Integration Systems User (ISU)** and set up its
   credentials.
2. Create an **Integration Systems Security Group (Unconstrained)**.
3. Bind the newly created ISU to the new security group.

   ![Workday Integration Systems Security Group configuration](/img/imported/workday-connector-integration/workday-security-group.png)

4. Add **Domain Security Policies** to the **Integration Systems Security
   Group** as follows:
   - Under **Domain Security Policies permitting View access**, add
     **View: Supervisory Organization**.
   - Under **Domain Security Policies permitting Get access**, add:
     - **Manage: Location**
     - **Manage: Organization Integration**
     - **Worker Data: Current Staffing Information**
     - **Worker Data: Public Worker Reports**

   ![Workday domain security policy permissions for the security group](/img/imported/workday-connector-integration/workday-domain-permissions.png)

### Create an API client

1. In Workday, locate the **Register API Client for Integration** task.

   :::warning Important

   Be sure to select **Register API Client for Integration** rather than just
   **Register API Client**. Axiad Mesh requires the former because it uses the
   OAuth 2.0 Client Credentials grant flow.

   :::

2. Set the **Client Name** to a friendly name that's meaningful to the
   integration.
3. Set the **Client Grant Type** to **Authorization Code Grant**.
4. Check the **Support Proof Key for Code Exchange (PKCE)** option.
5. Set the **Access Token Type** to **Bearer**.
6. Set the **Redirect URI** to a syntactically valid URL. The integration
   doesn't use this value, but the client configuration requires one.
7. Set the **Refresh Token Timeout** to your preferred number of days.
8. Check the **Grant Administrative Consent** option.

   ![Workday Register API Client for Integration form](/img/imported/workday-connector-integration/workday-api-client.png)

9. Select the scopes that this API client can access. The required scopes are:
   - **Organization and Roles**
   - **System**
10. Check the **Include Workday Owned Scope** option.
11. Complete the creation, then copy the **Client ID** and **Client Secret**
    values. You need them for the Axiad Mesh configuration steps.

### Generate a refresh token for the API client

1. In Workday, locate the **View API Clients** report.
2. In the **API Clients for Integrations** tab, locate your newly created API
   client.
3. Click the three-dot menu button next to the client's name, hover over
   **API Client**, and then click **Manage Refresh Tokens for Integrations**.
4. In the **Workday Account** field, add the **ISU** account that you created
   in [Create an Integration Systems User and security group](#create-an-integration-systems-user-and-security-group).

   ![Workday Manage Refresh Tokens for Integrations dialog](/img/imported/workday-connector-integration/workday-refresh-token.png)

5. Click **OK** to generate the refresh token.
6. Copy the refresh token — you'll supply it when you connect Workday in Mesh.

## Which permissions the connector needs

The security group you created above has to reach the domains Mesh reads from.
Enable these functional areas:

- Person Data
- Contact Information
- Staffing
- Core Compensation
- Time Off and Leave, if you want absence data in Mesh

Within them, the domains that matter are:

| Area | Domains |
|---|---|
| Person | Personal Data, Personal Information, ID Information, Date of Birth, Gender, Marital Status |
| Contact | Home and Work Contact Information — address, email, phone — and Public Work Email Address |
| Worker | Workers, All Positions, Current Staffing Information, Employment Data, Public Worker Reports, Organization Information |
| Compensation | Compensation — All Worker's Positions Past and Present |
| Time off | Worker Data: Time Off, and Time Off Balances |

Mesh uses HR data for identity correlation and risk assessment, so person,
contact, and worker domains are the useful ones. Compensation and time off are
optional — Mesh reads what the security group can see, and nothing more.

> **caution**

Workday returns only what the security group is permitted to see, so an omitted
domain shows up as absent fields or absent workers rather than as an error. If
the first collection is thinner than expected, re-check this list.

## Add it in Mesh

With the Workday-side configuration complete, add the connector in Mesh. Workday
connects through the unified HRIS connector — there is no separate Workday
connector to configure.

Follow [Connect your HR system](../connect-your-hr-system.md), and select
**Workday** as your provider when the connection window asks. You'll supply the
API client credentials and refresh token from the steps above during that
provider authorization step.