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

# Workday

> Connect to unify employee, org, and compensation data for workforce planning and people analytics.

## Workday Integration Setup Checklist

**To:** Workday Administrator / HRIS Team

**Subject:** Technical Requirements for SOAP API Integration (Talent & People Analytics)

Please execute the following steps in the **Production** environment to provision SOAP API access for the integration.

**Why SOAP API?** The Workday SOAP API provides point-in-time historical queries and event streaming capabilities that are not available in the REST API. This enables comprehensive historical data backfill and efficient change tracking.

## Quick Overview

* **Time Required:** 30-45 minutes
* **Complexity:** Moderate
* **Steps:** 6 configuration steps

### What You'll Create:

* Integration System User (ISU) with username/password
* Security Group with 100+ field permissions
* Web service access to Staffing, HR, and Compensation APIs

### What We'll Extract:

* 100+ worker fields including: employment dates, job data, organization assignments, compensation (salary), personal info, management chain
* Historical snapshots (52 weeks of data)
* Daily incremental updates via transaction logs

## Security Configuration

*All permissions should be assigned to a dedicated service account, not a specific human user.*

<Steps>
  <Step title="Create Integration System User (ISU)">
    * **Task:** `Create Integration System User`
    * **Username:** `ISU_HumanIntelligence` (or similar)
    * **Settings:** Set "Session Timeout Minutes" to **0** (prevents session expiry)
    * **Action:** Set a strong password and store it securely (this will be used for API authentication)
  </Step>

  <Step title="Create Security Group">
    * **Task:** `Create Security Group`
    * **Type:** `Integration System Security Group (Unconstrained)`
    * **Name:** `ISSG_HumanIntelligence`
    * **Members:** Add the ISU created in Step 1
  </Step>

  <Step title="Assign Domain Security Policies (Data Access Permissions)">
    * **Task:** `Maintain Permissions for Security Group`
    * **Target:** Select the ISSG created in Step 2
    * **Action:** Grant **Get** (Read-only) access to the following domains

    Review and approve based on your internal data governance and which Workday modules are in use:

    | Category     | Domain Name                                  | Permission Type | What Fields This Unlocks                                                                                                                                                                                                                                                                                                                                                    |
    | ------------ | -------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Core HR      | Worker Data: Public Worker Reports           | Get             | **CRITICAL:** Employee names, email, phone, worker ID, basic personal information. Without this, you get empty responses.                                                                                                                                                                                                                                                   |
    | Core HR      | Worker Data: Current Staffing Information    | Get             | **CRITICAL:** Employment status (active/terminated), hire date, termination date, 30+ employment dates (severance, probation, resignation, retirement, etc.), termination reasons, rehire eligibility, employee type.                                                                                                                                                       |
    | Core HR      | Worker Data: All Positions                   | Get             | **CRITICAL:** Job titles (position & business title), job profiles, job families, management levels, job categories, work shift, time type (FT/PT), FTE percent, location, position ID, **organization assignments** (cost center, company, business unit, supervisory org).                                                                                                |
    | Core HR      | Worker Data: Staffing                        | Get             | **CRITICAL:** Core staffing data including assignments, global mobility, creditable service, employee contracts, flexible work arrangements, job family on worker profile, and additional staffing attributes.                                                                                                                                                              |
    | Core HR      | Worker Data: Staffing Information            | Get             | Staffing details for the worker's current position and employment record.                                                                                                                                                                                                                                                                                                   |
    | Core HR      | Worker Data: Historical Staffing Information | Get             | Historical staffing records required for point-in-time and backfill queries.                                                                                                                                                                                                                                                                                                |
    | Core HR      | Worker Data: Organization Information        | Get             | Organization hierarchy and org unit membership (inherits Worker Data: Organizations).                                                                                                                                                                                                                                                                                       |
    | Core HR      | Worker Data: Management Chain                | Get             | Manager name, manager ID, reporting hierarchy. Required for org chart analysis.                                                                                                                                                                                                                                                                                             |
    | Compensation | Worker Data: Compensation                    | Get             | **CRITICAL FOR SALARY DATA:** Salary amount, currency, frequency, total base pay, total salary & allowances, primary compensation basis, compensation effective date, compensation grade (for promotion detection), compensation step, compensation package, progression dates. **Without this permission, compensation fields return empty even if structure is present.** |
    | Talent       | Worker Data: Skills and Experience           | Get             | Skills, certifications, education, work history                                                                                                                                                                                                                                                                                                                             |
    | Talent       | Worker Data: Performance Reviews             | Get             | Performance reviews, ratings, goals                                                                                                                                                                                                                                                                                                                                         |
    | Recruiting   | Candidate Data: Job Application              | Get             | Applicant tracking & pipeline data (if using Workday Recruiting)                                                                                                                                                                                                                                                                                                            |
    | Benefits     | Worker Data: Benefit Enrollment Options      | Get             | Benefits elections, plan participation (optional)                                                                                                                                                                                                                                                                                                                           |
    | Time Off     | Worker Data: Time Off                        | Get             | PTO balances, time off requests (optional)                                                                                                                                                                                                                                                                                                                                  |

    ### Permission Priority Guide:

    * **Must Have (Integration Will Fail):** Public Worker Reports, Current Staffing Information, All Positions, Staffing, Staffing Information, Historical Staffing Information
    * **Critical for Salary Analysis:** Compensation
    * **Important for Org Charts:** Management Chain, Organization Information
    * **Optional (Enable as Needed):** Skills and Experience, Performance Reviews, Candidate Data: Job Application, Benefit Enrollment Options, Time Off
  </Step>

  <Step title="Assign Web Services Permissions (SOAP API Access)">
    * **Task:** `Maintain Permissions for Security Group`
    * **Target:** Select the ISSG created in Step 2
    * **Action:** Grant **Get** access to the following **Web Service** domains

    | Web Service Domain     | Permission | Priority | Purpose                                                                                                           |
    | ---------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
    | Staffing               | Get        | REQUIRED | Core worker data, employment records, org structure. This is the primary web service for `Get_Workers` operation. |
    | Compensation           | Get        | CRITICAL | Enables compensation data fields. Without this, salary/pay data returns empty.                                    |
    | Recruiting             | Get        | Optional | Applicant and candidate data (only if using Workday ATS)                                                          |
    | Talent and Performance | Get        | Optional | Performance management, goals, skills                                                                             |
    | Payroll                | Get        | Optional | Payroll results and pay slips                                                                                     |
    | Financial Management   | Get        | Optional | General ledger, journal entries                                                                                   |
    | Absence Management     | Get        | Optional | Time off balances and requests                                                                                    |

    <Warning>
      **Critical Note:** These web service permissions are **separate** from domain permissions and are required for SOAP API calls to succeed. You need BOTH domain permissions (Step 3) AND web service permissions (Step 4).
    </Warning>
  </Step>

  <Step title="Activate Security Changes ⚠️ CRUCIAL STEP ⚠️">
    * **Task:** `Activate Pending Security Policy Changes`
    * **Action:** Review and confirm all pending changes

    <Warning>
      **⚠️ CRITICAL:**

      * API calls will fail or return empty data until this is completed
      * Wait 5-10 minutes after activation for changes to propagate
      * This is the #1 reason integrations fail during setup
      * If test script shows structure but no data, you likely forgot this step
    </Warning>

    ### How to Verify Changes Were Activated:

    1. Search for task: "View Security Policy Changes"
    2. Check "Awaiting Activation" tab - should be EMPTY
    3. Check "Activated" tab - your changes should appear with today's date
  </Step>

  <Step title="Create API Client">
    *This step provisions OAuth 2.0 credentials, which are required for token-based authentication rather than the less-secure ISU Basic Auth.*

    * **Task:** `Register API Client for Integrations`
    * **Client Name:** `HumanIntelligence`
    * **Client Grant Type:** `Client Credentials` (server-to-server, no user interaction required)
    * **Non-Expiring Refresh Tokens:** Yes
    * **Scope (Functional Areas):** Select the same functional areas granted in Step 3 — at minimum: **Staffing, Core Compensation, Worker Profile and Skills, Performance Enablement, Recruiting, Benefits, Time Off and Leave**
    * Click **OK** to save

    After saving, record the following immediately:

    | Credential    | Notes                                                        |
    | ------------- | ------------------------------------------------------------ |
    | Client ID     | Visible in the client summary page                           |
    | Client Secret | **Shown only once** — copy it immediately and store securely |

    <Warning>
      **⚠️ IMPORTANT:** The Client Secret cannot be retrieved after you leave this page. If lost, you must generate a new one. Store it in your password manager or secure vault before navigating away.
    </Warning>

    ### To generate a Refresh Token (if needed for Authorization Code flow):

    1. Navigate to **View API Clients** and locate `HumanIntelligence`
    2. Use the **Manage Refresh Tokens for Integrations** task
    3. Select the ISU created in Step 1 as the user
    4. Click **Generate New Refresh Token** and record the token value

    Include Client ID, Client Secret, and Refresh Token in the Phase 2 handover alongside the ISU credentials.
  </Step>
</Steps>

## Phase 2: Handover

### Required Credentials:

1. **Tenant Name** (e.g., `acme_corp`)
2. **Workday Host** (e.g., `services1.wd501.myworkday.com`, `wd2-impl.workday.com`)
3. **OAuth Client ID**
4. **OAuth Client Secret**
5. **OAuth Refresh Token**

<Note>
  **Note on API Versions:** Workday typically supports the last 3-4 major versions. If v44.0 doesn't work, try v43.0 or v42.0. Check available versions at: `https://{your-host}/ccx/service/{tenant}/Staffing/`
</Note>

### Save Credentials in the Human Intelligence Portal

Once you have collected all credentials above, log in to the Human Intelligence integrations portal and enter them directly:

1. Go to **[https://app.humanintelligence.com/integrations](https://app.humanintelligence.com/integrations)**
2. Sign in with your administrator account
3. Locate the **Workday** integration and click **Connect**
4. Enter each credential from the list above into the corresponding fields
5. Click **Save** to securely store the credentials

<Warning>
  **⚠️ IMPORTANT:** Do not transmit credentials via email or unencrypted channels. The portal stores all credentials encrypted at rest. If you are unable to access the portal, contact your Human Intelligence account representative for an alternative secure handover method.
</Warning>