# Workday
Connecting Workday gives SureCloud read access to your Workday tenant's worker records, organisational structure, and security group assignments. SureCloud uses this data to monitor joiner-mover-leaver (JML) processes — identifying employees who have recently joined, changed roles, or been terminated — and to cross-reference HR records with access provisioning evidence from connected identity providers. SureCloud collects worker status, employment dates, cost centre and manager hierarchy data, and security group memberships to provide a continuous, HR-authoritative view of who should have access to what and whether that access has been actioned.
{% hint style="info" %}
SureCloud connects to Workday using OAuth 2.0 with a Workday Integration System User (ISU) service account. This is the method recommended by Workday for system integrations and avoids tying the connection to a named employee account.
{% endhint %}
## Authentication and setup
{% stepper %}
{% step %}
#### Create an Integration System User (ISU)
In Workday, navigate to **Create Integration System User** (search for this task in the search bar). Configure the following:
* **User Name**: `SureCloud_CCM_ISU`
* **Password**: generate a strong password and record it securely
* **Do Not Allow UI Sessions**: checked — prevents interactive login with this account
* **Session Timeout Minutes**: 0 (no timeout for integration sessions)
Click **OK**.
{% endstep %}
{% step %}
#### Create a Security Group for the ISU
Navigate to **Create Integration System Security Group (Unconstrained)** and create a group named `SureCloud CCM Security Group`. Add the `SureCloud_CCM_ISU` user as a member.
Then navigate to **Maintain Permissions for Security Group** and grant the following domain security policy permissions as **Get** (read) only:
| Domain | Purpose |
| ----------------------------------------- | ----------------------------------------------------------------- |
| Worker Data: All Position Data | Read worker position, department, and manager hierarchy |
| Worker Data: Current Staffing Information | Read employment status and hire/termination dates |
| Worker Data: Personal Data | Read worker name and contact information for identity correlation |
| Worker Data: Workers | Enumerate all workers (active, inactive, and terminated) |
| Security Groups and Membership | Read Workday security group assignments |
| Staffing: Termination | Read termination records for offboarding evidence |
| Organisation: Organisation | Read organisational unit structure |
Navigate to **Activate Pending Security Policy Changes** and confirm the activation.
{% hint style="warning" %}
Workday security policy changes require activation before they take effect. If you skip this step, the ISU will not have the permissions needed and Test Connection will fail.
{% endhint %}
{% endstep %}
{% step %}
#### Register an API Client for SureCloud
In Workday, search for **Register API Client for Integrations**. Configure:
* **Client Name**: `SureCloud CCM`
* **Client Grant Type**: Client Credentials
* **Access Token Type**: Bearer
* **Token Expiry**: 3600 seconds (SureCloud refreshes automatically)
* **Scope**: `Human Resource Data` (select the applicable functional areas)
Click **OK**. Workday will display the **Client ID** and **Client Secret** — copy both immediately.
{% hint style="warning" %}
The client secret is only shown once. If it is lost, navigate to **View API Client** and regenerate the secret, then update it in **SureCloud → Integrations → Workday → Edit Connection**.
{% endhint %}
{% endstep %}
{% step %}
#### Identify your Workday REST API base URL
Your Workday REST API base URL is in the format:
`https://wd2-impl-services1.workday.com/ccx/api/v1/{tenant_name}`
The tenant name is visible in the URL when you are logged in to Workday (e.g. `https://impl.workday.com/yourcompany/...` — the tenant name is `yourcompany`).
For production tenants, the API URL format is:
`https://services1.myworkday.com/ccx/api/v1/{tenant_name}`
{% endstep %}
{% step %}
#### Enter credentials in SureCloud
In SureCloud, navigate to **Integrations → Workday → Connect** and provide:
* **Workday REST API base URL**
* **Client ID**
* **Client Secret**
* **Tenant name**
Click **Test Connection**, then **Save**.
{% endstep %}
{% endstepper %}
## Endpoints
| API Call | Use Case |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `GET /workers` | Enumerate all workers including active, on leave, and terminated; read employment status and hire dates |
| `GET /workers/{id}` | Retrieve full worker record including position, manager, cost centre, and employment dates |
| `GET /workers/{id}/staffingInformation` | Read current staffing details including termination date and reason |
| `GET /organizations` | Enumerate organisational units; read hierarchy structure for access scoping |
| `GET /workers/{id}/securityGroupMemberships` | Read Workday security group assignments per worker |
| `GET /securityGroups` | List all Workday security groups and their member counts |
| `GET /businessProcesses?type=Hire` | Read recent hire events for joiner tracking |
| `GET /businessProcesses?type=Terminate` | Read recent termination events for leaver tracking |
| `GET /businessProcesses?type=Change_Job` | Read role change events for mover tracking |
## Pagination
The Workday REST API uses offset-based pagination via `offset` and `limit` query parameters. SureCloud requests pages of up to 100 records and increments the `offset` by `limit` until the response `total` count is reached.
```json
{
"total": 3841,
"data": [
{
"id": "abc123",
"descriptor": "Alice Nguyen",
"employmentStatus": "Active",
"hireDate": "2022-03-14"
}
],
"next": "/workers?limit=100&offset=100"
}
```
## Required permissions
All domain security policy permissions must be set to **Get** (read) only. No **Put** or **Post** permissions are required. SureCloud does not write to or modify any Workday records.
The ISU must be a member of the security group with the domain permissions above, and the security policy changes must be activated before the connection will succeed.
## Polling frequency
| Data type | Collection interval |
| ----------------------------------------- | ------------------- |
| Worker records and employment status | 24 hours |
| Hire, termination, and role change events | 6 hours |
| Organisational structure | 24 hours |
| Security group memberships | 24 hours |
## Troubleshooting
Test Connection fails with "Invalid client" or "Unauthorized"
The Client ID or Client Secret is incorrect, or the API Client registration in Workday is not associated with the ISU's security group.
1. In Workday, search for **View API Client** and confirm the `SureCloud CCM` client exists and is active.
2. Confirm the Client Grant Type is set to **Client Credentials** — authorization code flow is not supported for this integration.
3. If the client secret was regenerated, update it in **SureCloud → Integrations → Workday → Edit Connection**.
Worker records are returning but termination dates are missing
Termination dates are returned as part of the staffing information object, which requires the **Staffing: Termination** domain permission with **Get** access. If termination data is missing, confirm this domain permission is included in the `SureCloud CCM Security Group` and that pending security policy changes have been activated.
Security policy changes are not taking effect after saving
Workday requires an explicit activation step for security policy changes. In Workday, search for **Activate Pending Security Policy Changes**, review the pending changes, and click **OK** to activate. Without this step, newly granted permissions will not apply to the ISU.
Business process events (hires, terminations) are not appearing
Business process event collection requires the **Worker Data: Current Staffing Information** domain permission. Additionally, Workday business process events are only available for a limited look-back window via the REST API. SureCloud queries business processes within a rolling 30-day window — events older than this window will not be retrieved via this endpoint.
For historical JML evidence beyond 30 days, Workday reports or the Prism Analytics API may be required. Contact SureCloud support for guidance on extended historical data collection.
Workday REST API reference Workday Integration System User guide
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/workday.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.