About Workday
Workday is a human capital management (HCM) platform that manages employee data, benefits, and organizational information. Connect it to Serval to automate HR workflows and employee lifecycle management.What the Workday integration enables
| Capability | Description |
|---|---|
| Workflow Automation | Build Serval workflows to automate anything accessible via Workday’s REST APIs |
Support for building workflows with Workday’s SOAP (WSDL-based) APIs is coming soon.
Workday Configuration
Prerequisites
Before configuring the Workday integration in Serval, ensure you have:- Administrator access to your Workday tenant
- Permissions to create Integration System Users and Security Groups
- Access to domain security policy configuration
These steps require Workday administrator privileges. If you do not have these privileges, contact your Workday administrator. Workday recommends using Integration System Users (ISUs) for third-party integrations such as Serval.
Throughout this guide, we’ll use example names for entities you create to keep instructions clear:
- ISU username: “ServalIntegration”
- Security Group: “Serval Integration Group”
- API Client: “Serval Workday API Client”
Step 1: Create an Integration System User (ISU)
1
Create the ISU Account
- Log in to your Workday tenant
- In the search bar, type “Create Integration System User”
- Select the Create Integration System User task
- Fill in the account information:
- User Name: Enter a descriptive username (e.g., “ServalIntegration”)
- Password: Create a strong password
- Confirm Password: Re-enter the same password
Important: The password cannot contain &, <, or > characters.
2
Prevent Password Expiration
- Search for “Maintain Password Rules”
- Add the ISU username to the “System Users exempt from password expiration” field
- Click OK to save
This ensures your integration will not break due to password expiration.
Step 2: Create Security Group and Assign ISU
1
Create Security Group
- Search for “Create Security Group”
- Select Integration System Security Group (Unconstrained) from the Type dropdown
- Enter a descriptive name (e.g., “Serval Integration Group”)
- Click OK
2
Assign ISU to Security Group
- In the Integration System Users field, enter ServalIntegration (or your ISU’s name)
- Click OK to save
Step 3: Configure Domain Security Permissions
1
Set Permissions
- Search for “Maintain Permissions for Security Group”
- Set Operation to Maintain
- Set Source Security Group to Serval Integration Group (or your security group’s name)
- Add the Domain Security Policies required for your use case. See below for commonly used policies.
Only add the permissions you need for your specific integration requirements.
2
HRIS domain security policies
HRIS domain security policies
| Operation | Domain Security Policy | Notes |
|---|---|---|
| Get Only | Worker Data: Public Worker Reports | Minimum required permission |
| Get Only | Person Data: Name | |
| Get Only | Person Data: Personal Data | |
| Get Only | Person Data: Home Contact Information | |
| Get Only | Person Data: Work Contact Information | |
| Get Only | Person Data: Private Work Email Integration | Required to surface the work email of employees |
| Get Only | Person Data: Public Work Email Address Integration | Required to surface the work email of employees |
| Get Only | Worker Data: Compensation | |
| Get Only | Worker Data: Compensation by Organization | |
| Get Only | Worker Data: Workers | |
| Get Only | Worker Data: All Positions | |
| Get Only | Worker Data: Current Staffing Information | Required to surface the employment status of employees |
| Get Only | Worker Data: Employment Data | |
| Get Only | Worker Data: Compensation - All Workers’ Positions Past and Present | |
| Get Only | Worker Data: Organization Information | |
| Get Only | Manage: Organization Integration | Required to surface the organization hierarchy |
| Get Only | Reports: Pay Calculation Results for Worker (Results) | |
| Get Only | Worker Data: Payroll | |
| Get Only | Process: Export Time Blocks | Required to retrieve timesheet entries |
| Get Only | Worker Data: Time Off | Time Off access may require additional configuration. |
ATS domain security policies
ATS domain security policies
| Operation | Domain Security Policy | Notes |
|---|---|---|
| Get Only | Worker Data: Public Worker Reports | |
| Get Only | Worker Data: Workers | |
| Get Only | Worker Data: All Positions | |
| Get Only | Worker Data: Current Staffing Information | |
| Get Only | Job Requisition Data | |
| Get Only | Worker Data: Employment Data | |
| Get Only | Worker Data: Organization Information | |
| Get Only | Manage Pre-Hire Process: Manage Pre-Hires | |
| Get and Put | Manage Pre-Hire Data | |
| Get and Put | Candidate Data: Edit Job Application | |
| Get and Put | Job Requisitions for Recruiting | |
| Get and Put | Candidate Data: Personal Information | |
| Get and Put | Set Up: Pre-Hire Process | |
| Get and Put | Candidate Data: Other Information | |
| Get and Put | Manage Pre-Hire Process | |
| View and Modify | Candidate Data: Other Information | |
| Get and Put | Candidate Data: Job Application | Get is the minimum required permission |
| Get and Put | Move Candidate | |
| Get and Put | Prospects | |
| Get | Manage: Evergreen Requisitions | |
| Get | Job Postings | |
| Get | Job Postings External | |
| Get | Job Postings Internal | |
| Get | Questionnaire | |
| Get | Integration Build |
System Monitoring domain security policies
System Monitoring domain security policies
| Operation | Domain Security Policy | Notes |
|---|---|---|
| Get Only | System Monitor Administrator | Required for accessing system metrics and health data |
| Get Only | System Monitor Support | Alternative permission for system monitoring access |
| Get Only | System Health Dashboard | Required for system health monitoring capabilities |
3
Activate Security Changes
- Search for “Activate Pending Security Policy Changes”
- Review and confirm the changes
- Click OK to activate
Step 4: Configure Authentication Policy
1
Set Authentication Rules
- Search for “Manage Authentication Policies”
- Click Edit on the authentication policy
- Create or update an Authentication Rule with:
- Add Serval Integration Group (or your security group’s name)
- Set Allowed Authentication Types to User Name Password or Any
- Click OK to save
2
Activate Authentication Changes
- Search for “Activate All Pending Authentication Policy Changes”
- Confirm the changes to save the Authentication Policy
Step 5: Register an API Client for Integrations (OAuth 2.0)
1
Create the API Client
- Search for “Register API Client for Integrations”
- Click OK to start a new registration
- Fill in basic details (Name/Description). For the Name, use e.g., Serval Workday API Client.
- Set the client as a Confidential application (if prompted)
- Enable the Refresh Token grant
- Allow Non-Expiring Refresh Tokens
- Click Save to register
After registration, Workday shows the Client ID and Client Secret. The secret may only be shown once; store it securely.
If rotated later, you must update Serval.
Step 6: Associate the API Client with the ISU and Generate a Refresh Token
1
Generate Refresh Token for the ISU
- Search for “Manage Refresh Tokens for Integrations” (sometimes labeled “API Client: Manage Refresh Tokens”)
- Select Serval Workday API Client (or your API client’s name)
- Add an Authorized User and select ServalIntegration (or your ISU’s name)
- Choose an expiration (select Never if your policy allows) and Generate the refresh token
- Copy the Refresh Token and store it securely
You will not be able to view the refresh token again once you leave the page. This value is required in Serval as Refresh Token.
Step 7: Collect API Endpoints and SOAP Web Services Endpoint
1
Find REST and Token endpoints on View API Clients
- Search for “View API Clients” and open Serval Workday API Client (or your API client’s name)
- Copy the REST API endpoint (typically ends with
/ccx/api/mycompany, e.g.,https://wd2-impl-services1.workday.com/ccx/api/mycompany) - Copy the Token endpoint (typically ends with
/ccx/oauth2/token, e.g.,https://wd2-impl-services1.workday.com/ccx/oauth2/token)
These two values map directly to Serval fields REST API Endpoint and Token Endpoint.
2
Find SOAP Web Services Endpoint (WSDL)
- Search for “Public Web Services” in Workday
- If connecting HRIS, locate “Human Resources (Public)”
- Click the three dots (⋯) → Web Services → View WSDL
- When the WSDL page loads, scroll to the bottom
- Copy the full URL shown under Human_ResourcesService. It will look like
https://wd2-impl-services1.workday.com/ccx
Enter this as the Web Services Endpoint URL in Serval. This is the SOAP endpoint prefix, not the full WSDL document URL. Do not include
?wsdl.3
Determine Tenant Name
Your tenant name is typically visible in your Workday URL. For example, in
https://wd2-impl.workday.com/tenant/d/home.html, the tenant name is tenant.
You can also ask your administrator.Serval Configuration
Once you have completed the Workday ISU and API Client setup, follow these steps to configure the integration in Serval:1
Navigate to Workday Integration
- In Serval, go to Apps → Available → Workday → Connect
- The Workday configuration form will appear
2
Enter Configuration Details
Fill in the following fields with the information from your Workday configuration:
| Field | Where to find it | Example |
|---|---|---|
| Tenant Name | From your Workday URL or admin | mycompany |
| Client ID | From Step 5 (API Client registration) | 1234567890abcdef |
| Client Secret | From Step 5 (shown once at registration/rotation) | •••••••••••• |
| REST API Endpoint | From Step 7 (View API Clients) | https://wd2-impl-services1.workday.com/ccx/api/mycompany |
| Token Endpoint | From Step 7 (View API Clients) | https://wd2-impl-services1.workday.com/ccx/oauth2/token |
| Refresh Token | From Step 6 (generated for the ISU) | •••••••••••• |
| Web Services Endpoint URL | From Step 7 (Public Web Services → View WSDL) | https://wd2-impl-services1.workday.com/ccx |
| ISU Username | From Step 1 (ISU you created) | ServalIntegration |
| ISU Password | From Step 1 (ISU password) | •••••••••••• |
Ensure endpoints include the full path (e.g.,
/ccx/api/mycompany and /ccx/oauth2/token) exactly as shown on the View API Clients page, with the https:// prefix.3
Submit Configuration Form
- Click Submit to complete the integration setup