WorkOS Docs Homepage
Integrations

Workday

Learn about syncing your user list with Workday.

This guide outlines how to synchronize your application’s Workday directories.

To synchronize an organization’s users and groups provisioned for your application, you’ll need the following information from the organization:

  • The Workday Custom Report JSON endpoint
  • The Workday Custom Group Report JSON endpoint
  • Username for accessing the Custom Report endpoint
  • Password for accessing the Custom Report endpoint

Note: The Workday integration isn’t enabled by default in the WorkOS Dashboard or Admin Portal. Please reach out to support@workos.com or via your team’s WorkOS Slack channel if you would like Workday enabled.

It’s recommended that the organization creates an Integration System User within Workday. The Integration System User will be used to access Custom Reports.

A screenshot of the "Create Integration System User" form in the Workday Dashboard.

If you’ve finished the setup, and everything works as expected but fields are missing from the Report, ensure that the user created has access to access to the fields.

A screenshot showing user access to a report in the Workday Dashboard.

Create a new security group in Workday. Set the Type of Tenanted Security Group to Integration System Security Group (Unconstrained). Then add a name for the Security Group and select OK.

A screenshot showing the "Create Security Group" form in the Workday Dashboard.

Next, for Integration System Users, add the integration system user you created in the previous step, and select OK.

A screenshot showing where to add the Integration System User in the Workday Dashboard.

Next, you’ll need to add domain security policies to the newly created security group. You can access this on the Security Group Settings → Maintain Domain Permissions for Security Group page.

A screenshot showing where to find the "Maintain Domain Permissions for Security Group" option in the Workday Dashboard.

You’ll need to permit the following domain security policies to have “Get” access under Integration Permissions:

  • Person Data: Work Contact Information
  • Workday Accounts
  • Worker Data: Active and Terminated Workers
  • Worker Data: All Positions
  • Worker Data: Business Title on Worker Profile
  • Worker Data: Current Staffing Information
  • Worker Data: Public Worker Reports
  • Worker Data: Workers
A screenshot showing Integration Permissions in the Workday Dashboard.

To activate these new security settings, you need to go to the Activate Pending Security Policy Changes page and click OK.

A screenshot showing the Activate Pending Security Policy Changes page in the Workday Dashboard.

Then, select the Confirm checkbox to finish activating.

A screenshot showing where to confirm the Active Pending Security Policy Changes in the Workday Dashboard.

You will need to create two Custom Reports. The first Custom Report will be used for syncing User information. The second report will be used for syncing Group information.

When creating the report, make sure to select the Advanced report type and to have the Enable as Web Service box checked.

A screenshot showing the "Create Custom Report" page in the Workday Dashboard.

You need to add information for certain fields to the report. You can do this by directly adding columns to the report for the attributes in Workday with column heading names specified as follows:

CSV HeaderStatusDescription
employee_idRequiredA unique ID representing the user
first_nameRequiredThe first name of the user
last_nameRequiredThe last name of the user
emailRequiredThe primary work email for the user
usernameRequiredA unique human readable user name
job_titleRequiredThe job title of the user
group_nameRequiredThe name of the primary group the user belongs to
employee_typeOptionalThe type of employee
employment_start_dateOptionalThe date the user started working
department_nameOptionalThe name of the department the user belongs to
manager_emailOptionalThe email of the user’s manager
division_nameOptionalThe name of the division the user belongs to
cost_center_nameOptionalThe name of the cost center the user belongs to
work_address_streetOptionalWork street address
work_address_localityOptionalWork city
work_address_regionOptionalWork state
work_address_postal_codeOptionalWork postal/zip code
work_address_countryOptionalWork country
A screenshot showing an example of Custom User Report in the Workday Dashboard.

Along the same lines as the User Report, WorkOS looks for the following information in the Group Report:

CSV HeaderStatusDescription
group_nameRequiredThe name of the group.

If an Integration System User was created, the organization will want to have that user added as an authorized user. This can be found under the Share tab from within a Report.

A screenshot showing the "Share" tab in the Workday Dashboard.

Now that the Report itself is setup and access to it had been configured, the organization will need to get the RaaS endpoint. The page with the endpoints can be found under Actions → Web Service → View URLs.

A screenshot showing where to find the view URLs option in the Workday Dashboard.

Once on the URLs page, the one that WorkOS will need is listed under the JSON section.

A screenshot showing the View URLs Web Service page in the Workday Dashboard.

Login to your WorkOS Dashboard and select “Organizations” from the left hand navigation bar.

Select the organization you’ll be configuring a new Directory Sync Connection with.

Click “Add Directory”.

A screenshot showing where to find the "Add Directory" button in the WorkOS Dashboard.

Select “Workday” as the directory type, and then input the Company Name.

Click the “Create Directory” button.

A screenshot showing the "Create Directory" button in the WorkOS Dashboard.

Click “Update Directory” to input the organization’s Custom Report JSON endpoints, username and password.

A screenshot showing where to find the "Update Directory" button in the WorkOS Dashboard.

Then, click “Save Directory Details”.

Now, whenever the organization assigns users or groups to your application, you’ll receive Dashboard updates based on changes in their directory.

A detailed guide to integrate the WorkOS API with your application can be found here

How often does the Workday directory perform a sync?

The Workday directory polls in every 30 minutes starting from the time of the initial sync.