Overview
Estimated, overall setup time: 30 minutes.
Fundamentally, there are 3 main steps you have to complete to set up the integration:
-
You have to create a new integration system user and security group for that user,
-
You have to assign the required permissions to the security group and activate the changes,
-
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.
Integration Prerequisites
Ensure you are an admin of your Workday account before starting.
- Log into Workday and 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.
Permission Requirements
See below the full list of permissions that Ravio could require.
| 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.)Always needed when reading any worker data |
| 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.Always needed when reading any worker data |
| Get Only | Worker Data: Workers | Retrieving any worker data from Workday's webservicesAlways needed when reading any worker data |
| 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: Work Email** | Needed if reading worker's work Email |
| Get Only | Person Data: Gender | Needed if reading worker's gender |
| 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. This is generally also used for variable pay. |
| 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 |
**For the anonymous workflow, any employee PII data is not required to maintain anonymity in the Ravio app.
Step by Step Integration Setup
This is a step by step guide on how to use Workday’s standard APIs to integrate with Ravio.
If you've opted for the Anonymous Flow with Ravio, follow the standard instructions up to Step 4. At that point, switch to the Anonymous instructions (there will be a reminder!).
If you have any fields (usually level or grade information) that we need access to and that you store in Custom Objects, permissions for these need to be provided separately, as Workday stores them differently. Please follow the steps in the Custom Objects section and send your Ravio contact the "System ID" at the end.
This integration process should take around 30 minutes for a Workday admin to complete.
Step 1 - Workday Service URL
In the search bar at the top, search for and navigate to the ‘View API Clients’ report.
At the top of the page find and copy your Workday REST API Endpoint.
Save this in a document as it will be required later!
Step 2 - Create a new integration service user (ISU)
In the top search field, enter "Create Integration System User". Then, click on the task with the same name that appears.
In the dialog that just opened, enter a username and generate a secure password that meets your organisation’s password requirements. Ensure Require New Password at Next Sign In is not checked then click OK.
Make sure to save these login details somewhere secure!
Step 3 - Add newly created 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. This will break the integration between Ravio and Workday and will require manual work to get this working again.
-
Search for the task "Maintain Password Rules" in the top bar:
-
Once on that task add your created ISU to the list of "System Users exempt from password expiration". This will stop the integration from breaking when the password expires.
Step 4 - Create a new Security Group and assign the new ISU
Search for "Create Security Group" in the search bar then click on the associated task that appears.
On the page locate the dropdown "Type of Tenanted Security Group" and select "Integration System Security Group (Unconstrained)".
For the "Name" enter the same username you entered when creating the ISU earlier (in this case it would be test_isu, but yours will be different), then click OK.
On the next page, the only thing you have to do is go to the field "Integration System Users" and add the ISU 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).
Step 5 - Assigning the required permissions
If you have signed up for the Anonymous Flow, please make sure you do not give permissions for any Name data (First Name / Last Name / Full Name etc).
Ravio now supports the automatic ingestion of Variable Pay data from Workday!
If you want to gain access to this, simply grant us access to the category where the variable pay data is stored in your Workday instance. This is typically the ‘Worker Data: Compensation by Organization’ category, but if you have a custom category for this please ensure it’s included to benefit from this!
Step 5 - Assigning the permissions directly to the Security Group
Search for "Maintain Permission for Security Group" and click on the task that appears.
In the form that appears, make sure to select Operation = Maintain and make sure the security group you created is in the Source Security Group.
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. The permissions we need at listed at the bottom of this page, they are different for full onboarding and for anonymous onboarding. The image below is an example.
For each permission, repeat the following process:
- Make sure the tab "Domain Security Policy Permissions" is selected and click on the icon with the "+" on it:
-
Click on the cell in the column "View/Modify Access", select "Get Only".
-
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
Repeat for all required permissions. You can see full details of what permissions Ravio may require and why we need them in the Permission Requirements section below.
Permission Requirements
See below the full list of permissions that Ravio could require.
| 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.)Always needed when reading any worker data |
| 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.Always needed when reading any worker data |
| Get Only | Worker Data: Workers | Retrieving any worker data from Workday's web services. Always needed when reading any worker data |
| 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: Work Email | Needed if reading worker's work Email |
| Get Only | Person Data: Gender | Needed if reading worker's gender |
| 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 |
Step 6 - 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.
To do this, search for the "Activate Pending Security Policy Changes" task.
In the window that just appeared, add any comment for applying the changes (i.e. "Grant ISU test_isu necessary permissions for integrations"). We recommend that this is as decsriptive as possible to allow others to see the tasks provided.
In the new window, check the box "Confirm". These changes are now active.
Step 7 - Create an API client
Click on the "Search" field at the top and enter "Register API Client for Integrations".
In the window that just appeared, enter a "Client Name", i.e. "ravio_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.
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
Step 8 - Enter the credentials into Ravio
Enter the below information when prompted in the app
Enter the REST API endpoint you found above into the Ravio onboarding screen. This is the Workday Service URL from Step 1.
Enter the Client ID, Client Secret and Refresh Token for the API Client we created above.
