Prerequisites
Ensure you are an admin of your Workday account before starting.
After logging into Workday, search for "View API Clients"
If you can not see this menu item, you are not an admin of the Workday account.
If you do not see this menu item, figure out who your Workday Admin is and ask them to give your account sufficient permissions or to take over the integration process.
Overview
Estimated, overall setup time: 30 minutes.
Fundamentally, there are 3 main steps you have to complete to set up the integration:
1. You have to create a new integration system user and security group for that user,
2. You have to assign the required permissions to the security group and activate the changes,
3. (Optional, rarely needed: You have to generate a new API client.)
That's it! The rest of this document is a step-by-step walkthrough of everything you need to know and do to set up the integration.
Find your Workday Service URL
Click on the "Search" field at the top and enter "View API Clients"
Click on the task "View API Clients" that just appeared
At the top of the page that just appeared find and copy the "Workday REST API Endpoint".
The URL should follow the following schema: https://{domain}/ccx/api/v1/{tenant}.
Add an integration system user (ISU)
Click on the "Search" field at the top and enter "Create Integration System User"
Click on the task "Create Integration System User" that just appeared
In the dialog that just opened, enter a username and generate a secure password.
You can leave the other fields untouched.At the bottom of the dialog, click "OK"
Add the ISU to your list of system users
While the newly created ISU will work for linking your Workday account, its password will expire after some time unless you add it to your list of system users.
Search for the task "Maintain Password Rules" in the top bar:
Next, add your created ISU to the list of "System Users exempt from password expiration"
Create a security group and assign the ISU to it
Click on the "Search" field at the top and enter "Create Security Group"
Click the task "Create Security Group" that just appeared
On the page that just appeared locate the dropdown "Type of Tenanted Security Group" and select "Integration System Security Group (Unconstrained)"
For the "Name" enter the value of the "User Name" when creating the ISU earlier (in this case it would be test_isu, but yours will be different)
At the bottom of the page, click "OK"
On the next page, the only thing you have to do is go to the field "Integration System Users" and add the user you created earlier. You can do this by clicking on the field and typing in the name of the ISU (in this case "test_isu")
After that, go ahead and click "OK"
Add the required permissions to the security group
Click on the "Search" field at the top and enter "Maintain Permission for Security Group"
Click on the task "Maintain Permission for Security Group" that just appeared
In the window that just appeared, make sure you have the option "Maintain" selected
Click the field "Source Security Group", enter the name of the group (in this case test_isu) and hit enter. Then click on the security group to select it.
Click "OK"
In the window that just appeared, you can add the permissions you want for the ISU. You can find the list of permissions needed in the connection flow.
Note: The list of permissions here is only an example. Please check your own permissions in the connection flow.
For each permission, repeat the following process:
Make sure the tab "Domain Security Policy Permissions" is selected
Click on the icon with the "+" on it
Click on the cell in the column "View/Modify Access"
If the permission says "Get:", select "Get Only". Otherwise select "Get and Put"Click on the cell in the column "Domain Security Policy",
type in the name of the policy (i.e. "Integration: Build"), hit enter and click on the item that just appeared in a list
Activate your changes
After making any changes to your Workday security policy settings, make sure to apply those changes by executing the "Activate Pending Security Policy Changes" task. Without that, none of your changes with take effect.
Click on the "Search" field at the top and enter "Activate Pending Security Policy Changes"
Click on the task "Activate Pending Security Policy Changes" that just appeared
In the window that just appeared, add any comment for applying the changes (i.e. "Grant ISU test_isu necesssary permissions for integratons"
Click "OK"
In the new window, check the box "Confirm"
Click "OK"
Create an API client
Note: The following section is not always necessary! Please read the below carefully before proceeding. This step is only necessary if you want to do the following:
HRIS: If you want to read/write absence (time off) data, or read/write custom employee objects from your Workday instance.
ATS: If you want to read offers or screening question data from your Workday instance.
In all other cases you can skip the steps below.
Click on the "Search" field at the top and enter "Register API Client for Integrations"
Click on the task "Register API Client for Integrations" that just appeared
In the window that just appeared, enter a "Client Name", i.e. "test_isu API client"
Make sure the option "Non-Expiring Refresh Tokens" is turned on
For the field "Scope (Functional Areas)", enter the values that are displayed to you within the connection flow.
For ATS integrations, some of the following scopes will be required:
- "Recruiting", "Tenant Non-Configurable", "Adaptive Planning for the Workforce", etc...
- Please do not use the above permissions. All the relevant permissions will be listed in your connection flow.
For HRIS integrations, some of the following scopes will be required:
- "Tenant Non-Configurable", "Staffing", "Time Off and Leave", etc...
- Please do not use the above permissions. All the relevant permissions will be listed in your connection flow.
Click "OK"
Please note: The above scopes are an example. Please use the permissions that are requested inside of your connection flow.
In the new window, copy the Client ID and Client Secret for later use, then do not click "Done"
Still on the same page, click the three dots at the top, then "API Client" > "Manage Refresh Tokens for Integrations"
In the new window, enter the name of the ISU that you created earlier
Click "OK"
In the new window, check the box for "Generate New Refresh Token"
Click "OK"
In the new window, copy the refresh token and store it for later use
Troubleshooting "Invalid username or password!" issues
If you are experiencing trouble logging in due to an error "Invalid username or password!", try the following:
Search for "Manage Authentication Policies" in the top bar.
Click on "Edit" next to the policy
Create a new "Authentication Rule" by clicking on the + in the top left
Assign the Security Group that was made earlier to this new rule, and name the rule something relevant.
Click the + next to "Authentication Condition Name", name it something relevant.
Ensure that the "Allowed Authentication Types" is either set to "Specific: User Name Password", or "Any".
Finally, search for "Activate All Pending Authentication Policy Changes" in the top bar, then confirm the changes made.
Documentation of possible permissions
View/Modify Access | Security | Explanation |
Get Only | Worker Data: Public Worker Reports | Reading public information about a worker. Public means any worker within the organisation can view this information about another worker (for example first name, last name etc.) |
Get Only | Worker Data: All Positions | Reading position related information of a worker. For example manager, location, job title etc. Also allows us to read status data about the worker. |
Get Only | Worker Data: Workers | Retrieving any worker data from Workday's webservices |
Get Only | Person Data: Mobile Phone | Needed if reading worker's mobile phone number |
Get Only | Person Data: Home Address | Needed if reading worker's personal home address |
Get Only | Person Data: Date of Birth | Needed if reading worker's date of birth |
Get Only | Person Data: Ethnicity | Needed if reading worker's ethnicity |
Get Only | Person Data: Marital Status | Needed if reading worker's marital Status |
Get Only | Person Data: Home Email | Needed if reading worker's personal Email |
Get Only | Person Data: Work Email | Needed if reading worker's work Email |
Get Only | Person Data: Gender | Needed if reading worker's gender |
Get Only | Person Data: ID Information | Needed if reading identifiers such as SSN and National ID. Used exclusively to read the SSN. |
Get Only | Worker Data: Current Staffing Information | Needed if reading information about the status of a worker. Used for termination_date, employment_status |
Get Only | Worker Data: Employment Data | Needed if reading employment related data. Used for termination_date, employment_status |
Get Only | Worker Data: Compensation by Organization | Needed if reading compensation data for workers. Used for pay_currency, pay_period and pay_rate in employments. |
Get Only | Worker Data: Current Staffing Information | Needed if reading information about the status of a worker. Used to determine termination_date |
Get Only | Worker Data: Employment Data | Needed if reading employment related data. |
Get Only | Manage: Organization Integration | Needed if reading group information (cost centers and companies) |
Get Only | Worker Data: Organization Information | Needed if reading which worker is in which group (cost centers, departments, and companies) |
Get Only | Manage: Location | Needed if reading job locations |