Import organizational data from Workday

You can import organizational data into Microsoft 365 with the Workday connector if your data is available in the Workday Simple Object Access Protocol (SOAP) API, and your data has no more than 100,000 users, using the process described below.

Otherwise, you can send data from Workday Enterprise Interface Builder (EIB) without calling the Workday SOAP API, using one of the two methods below:

  • Send data from Workday EIB to an Azure Blob Storage connection using these steps.

  • Send data from Workday EIB to an API-based connection using these steps.

Prerequisites

Before you can set up a connection between Workday and Microsoft 365, you'll need the following information about your Workday environment from your Workday admin:

  • Workday web services URL
  • Token URL
  • Username
  • ClientID
  • Complete steps within Workday described in later section

Summary of steps

Primary role Coordinate with Actions Resoures Estimated time
Microsoft 365 Global/Organizational Data Source Administrator App admin, such as Viva Glint Administrator or Insights Administrator Choose which services receive the data:

1. Go to Microsoft 365 Organizational Data Service > Data connections > New import > Workday connector

2. Apps and services include Viva Insights including Copilot Dashboard, Viva Glint, People Skills and Microsoft 365 Profile

3. Public Microsoft 365 attributes are automatically shared with all eligible Microsoft 365 and Viva apps and services
Choose apps and services to share data 5 minutes
Microsoft 365 Global/Organizational Data Source Administrator Workday admin In the Microsoft 365 admin center, start Workday set up and download the certificate This article 5 minutes
Workday admin N/A Configure Workday access. In Workday, create an Integration System User (ISU) and an unconstrained security group; grant Get-only permissions on the required worker/person domains; activate the security policy changes. This article 0.5 to 1 day
Workday admin Microsoft 365 Global/Organizational Data Source Administrator Register the API client in Workday and share credentials. Jwt Bearer Grant; paste the x509 certificate; scopes: Staffing, Contact Information, Worker Profile and Skills. Register an API client using this article 0.5 to 1 day
Microsoft 365 Global/ Organizational Data Source Administrator N/A Set up the connection

1. Enter the Workday Web Services URL, Token URL, Username and ClientID

2. Pick refresh (weekly or monthly). Each pull fetches all active users; inactive users are excluded.

3. Only if you want to test first: Turn on data staging
This article 5 minutes
Microsoft 365 Global/ Organizational Data Source Administrator Workday admin Mapping: Download and edit the default mapping or use it as is. Use AI mapping suggestions for quick mapping. Workday attribute mapping using this article 10 minutes
Microsoft 365 Global/Organizational Data Source Administrator App admin, such as Viva Glint Administrator or Insights Administrator Choose attribute access:

1. Decide which attributes are shared with which destination apps.

2. Public Microsoft 365 attributes are automatically shared with all eligible Microsoft 365 and Viva apps and services
Attribute access and sharing 5 minutes
Microsoft 365 Global/Organizational Data Source Administrator (Optional - Test only) N/A Only if you want to test first: Turn on data staging to review the validation details before sharing the data with downstream apps. Export the ingested data file to confirm it looks right. After reviewing, you need to approve data sharing within 48 hours, after which the ingested file is no longer available. Validate in staging 1 hour
Microsoft 365 Global/Organizational Data Source Administrator N/A Validate and publish. Allow up to 24 hours to process. The first upload can take up to 72 hours. 5 minutes
Microsoft 365 Global/Organizational Data Source Administrator Workday admin Troubleshoot common errors and how to fix them
  • Validation errors and warnings
  • Viva Glint errors
  • 1 hour

    Overview video tutorial

    Setup steps video tutorial

    1. Set up your Workday connection

    Applies to: Microsoft 365 Global Administrator

    1. Start the import from Microsoft 365 Organizational Data Service > Data Connections. (Learn how to access the Microsoft 365 Organizational Data Service.)

      1. You can also start the import by selecting Copilot on the left, then select Connectors.

      2. Under Connectors, select Your connections.

      3. Select Add connection.

      4. At the bottom of the page, under Legal + Human resources & recruiting, and next to Workday, select Add.

      Screenshot of the page to start the Workday connection.

    2. Select Get started (if this is the first time you're importing data), or New import (if you've already imported data).

    3. On the Select connection type page, select Start Workday setup. You can create multiple instances of the Workday connector. Each Workday connector instance is recommended to have unique credentials.

    4. Select the apps and services with which you'd like to share data. By default, all public reserved attributes are shared across Microsoft 365 and Viva apps and services. Use this page to select apps with which to share application-specific and custom attributes and select Next to move forward. You can change your selections at any time within Settings. Learn more.

      • Under each app, select View app specific attributes to see a list of attributes that can be accepted by that app. You'll set attribute-specific access later.
    5. On the Set up Workday connection details page, on the right, select Download certificate. A x509 certificate file will download called "publicKey.pem." Open the file in a text editor and copy its contents. Share this with the Workday admin.

      • This page also includes a .csv mapping file for mapping your Workday attributes to their required fields in the Viva apps you selected in Step 4 above. Learn more about how Workday sends data to Microsoft 365 and the default field mapping. If the default field mapping works for your needs, you don't need to use the .csv file. But, if you'd like to customize the mapping, select Download default mapping, and make your edits to the file.
    6. Under Set up Workday connection details:

      1. Enter a name for your connection.

      2. Contact your Workday admin to complete the steps in Workday described below.

      3. Enter the Workday Web services URL, Token URL, and ClientID provided by the Workday admin.

      4. For username, enter the name of the ISU created by the Workday admin.

      5. Under Refresh schedule, select how frequently you want Workday to send data to Microsoft 365: weekly or monthly.

      6. Confirm you agree to the terms of transferring data using the Workday API. Select Next.

        Screenshot of the page to set up the connection.

    7. On the Set up Workday connection settings page, if you're sharing data with Viva Glint, under Enable full imports for Viva Glint, select Turn on full imports for Viva Glint if this connector provides the complete list of users who should remain active in Viva Glint and you need to update the active user population. Every import from this connector is processed as a full import in Viva Glint until you turn off this setting. Users missing from the import are marked "inactive" in Viva Glint, including active users from other connectors that aren't included in this connector. Turn off if other connectors provide additional active users.

    8. On the Set up Workday connection settings page, if you'd like to review the details about the quality of your ingested data before making it available to downstream apps, select Turn on data staging. Learn more.

    9. On the Upload attribute mapping page, select Download default mapping to access a .csv file with the list of reserved attributes and the recommended mapping. You can edit this file to customize the mapping. Once you've reviewed the file and made your edits (if any), at the bottom of the screen, select Browse to upload it.

      • Or, if you're using the default mapping, you don't need to upload a .csv file. Select Next at the bottom of the page.
    10. Review the details for your reserved attribute mapping. To make changes, go back to the Upload attribute mapping page and upload a new .csv file. If everything looks good, at the bottom of the page, select Next.

    11. If you've imported any custom attributes, review them on the next page. These can't be renamed and you can't change their data type. To make changes to the names, go back to the Upload attribute mapping page and upload a new .csv file. If everything looks good, at the bottom of the page, select Validate mapping.

    12. Next, if you sent any app-specific or custom data to any destination, choose which apps can access the attributes you mapped, then view the global attributes that are used for all Microsoft 365 apps and services. Learn how.

    13. On the last page, review all the details, apps, and attribute mapping for your connection. If everything looks correct, select Connect. Once validation is complete, the organizational data will be made available to the apps and services you selected.

      Note

      If you set up periodic exports, your data will be validated for Viva and Microsoft 365 services requirements. Validation takes a few hours; however, it can take up to three days for your complete data upload to be available in the profile store. You can check the validation status on the Data connections page in the Microsoft 365 admin center. When validation is complete, a message will say your data is in use and managed by Viva and Microsoft 365.

    2. Steps within Workday

    Applies to: Workday admin

    1. Open Workday. Search for "Create Integration System User" and select it. This is a system user not associated with a real person.

      Screenshot of the search field for Create Integration System user.

    2. Under Create Integration System User, fill out each field, then select OK.

      Screenshot of the page to Create Integration System User.

    3. Create a security group. In Workday, search for "Create Security Group" and select it.

    4. Select Integration System Security Group (Unconstrained).

      Screenshot of the page to create a security group.

    5. Add the Integration System User to this group.

    6. Search for "Maintain security group" and select Maintain Permissions for Security Group.

      Screenshot of the page to maintain permissions for the security group.

    7. Next to Operation, select Maintain. Next to Source Security Group, select your created security group.

      Screenshot of the page to select your created security group.

    8. Select the "+" icon to add a new Domain Security Policy Permission.

      1. Leave the Selected checkbox selected.

      2. Next to View/Modify Access, select Get Only.

      3. For Domain Security Policy:

        1. Add Worker Data: Public Worker Reports
        2. Add Worker Data: Organization Information
        3. Add Person Data: Private Work Email Integration
        4. Add Person Data: Skills
        5. Add Worker Data: Current Staffing Information

        Screenshot of the page to add domain security policies.

    9. Search for "Activate Pending Security Policy Changes" and select it.

    10. Add a descriptive comment about the change and select OK.

    11. Select Confirm, then select OK. You now have a new system user with the proper permissions they need to get worker data.

    3. Register an API Client

    1. Search for "Register API Client" and select it.

      Screenshot of the page to search for an API client.

    2. Fill out the following fields:

      1. Give the client an appropriate name, such as "VivaConnectorClient."
      2. For the client grant type, select Jwt Bearer Grant.
      3. For x509 certificate:
        1. Select Create x509 Public Key.
        2. Give the certificate an appropriate name, such as "VivaX509Certificate."
        3. Paste the contents of the publicKey.pem file shared by the Global admin from the earlier step.
        4. Select OK.
        5. Ensure this certificate is selected for the field x509 Certificate.
      4. For Integration System User, enter the user you created earlier.
      5. Leave the access token type as "Bearer."
      6. Under Scope (Functional Areas), search for and select "Staffing," "Contact Information," and "Worker Profile and Skills."
      7. Leave Include Workday Owned Scope cleared.
      8. Select the default values for the remaining fields.
    3. Select OK.

      Screenshot of the API client window.

    4. A few new fields should populate below Restricted to IP Ranges. Save the following information and share it with the Global admin to enter in the Microsoft 365 admin center:

      1. "ClientID"

      2. Your Workday Token URL, such as https://wd3-impl-services1.workday.com/ccx/oauth2/contoso4/token.

      3. Your Workday web services URL, such as https://wd3-impl-services1.workday.com/ccx/service/contoso4. Microsoft 365 Organizational Data Service uses the Get Workers Operation Details web service, which is part of the Human_Resources Extensible Markup Language (XML)/SOAP web service.

        Note

        This isn't the same as the Workday REST API Endpoint. If you're not familiar with your Workday web services URL, you can create it by copying your Token Endpoint, replacing "oauth2" with "service," and removing "/token" from the end.

    Make changes to the connection or data

    1. Go to Microsoft 365 Organizational Data Service > Data Connections. (Learn how to access the Microsoft 365 Organizational Data Service.)

    2. Select the Workday connector you want to edit, then select Review connector configuration.

    3. To change which apps can access your data, select Edit data access selections on the first page, and make your changes, using the same process as described above.

    4. Continue the process and advance through the screens, making any changes you need to on the appropriate page, such as your credentials, attribute access, and mapping. Skip any pages that don't require updates.

    5. When you're done, review your new connection details on the Finish setup page. If everything looks good, select Connect.

    One-time imports

    You can run an on-demand import outside of your configured schedule. This doesn't change the schedule. To do so:

    1. Select Microsoft 365 Organizational Data Service > Data Connections, then select Workday connector to go to the connector details page.

    2. Select Run one-time import.

    3. Select Full import. (Incremental imports aren't supported.)

    Import behavior and data refresh types

    When using the Workday connector, data ingestion allows full imports only, not incremental imports. Each scheduled import refreshes the entire dataset from Workday for all active users. Inactive users are excluded. A full import is triggered:

    • When you initially set up the connector

    • When you update the attribute mapping file

    • When you perform a full import through a one-time import action

    How Workday sends data to Microsoft 365

    When you connect Workday to Microsoft 365, Workday sends over a set of predefined source columns if using the default mapping file. These columns are mapped to fields in Microsoft 365. You can change these predefined fields by updating the mapping file.

    Field mapping

    The table below shows how Workday fields correspond to Microsoft 365 fields in the default mapping file. Learn more about Microsoft 365 fields including data type and formatting requirements.

    Attribute Workday field
    Microsoft_PersonEmail /wd:Worker/wd:Worker_Data/wd:Personal_Data/wd:Contact_Data/wd:Email_Address_Data/wd:Email_Address
    Microsoft_ManagerEmail /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Manager_as_of_last_detected_manager_change_Reference/wd:ID[@wd:type="Employee_ID" or @wd:type=\"Contingent_Worker_ID"][1]
    Microsoft_DotLineManagersEmailAndLabel ExternalSource_PersonIdentifier, ExternalSource_DotLineManagersIdAndLabel, Microsoft_PersonEmail
    Microsoft_Organization (Department) /wd:Worker/wd:Worker_Data/wd:Organization_Data/wd:Worker_Organization_Data[1]/wd:Organization_Data/wd:Organization_Name
    Microsoft_Layer No mapping from Workday
    Microsoft_LevelDesignation /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Job_Profile_Summary_Data/wd:Management_Level_Reference/wd:ID[@wd:type="Management_Level_ID"]
    Microsoft_JobDiscipline /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Job_Profile_Summary_Data/wd:Job_Family_Reference/wd:ID[@wd:type="Job_Family_ID"]
    Microsoft_CompanyOfficeLocation /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Business_Site_Summary_Data/wd:Location_Reference/wd:ID[@wd:type="Location_ID"]
    Microsoft_CompanyOfficeCountryOrRegion /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Business_Site_Summary_Data/wd:Address_Data/wd:Country_Reference/wd:ID[@wd:type="ISO_3166-1_Alpha-3_Code"]
    Microsoft_CompanyPostOfficeBox No mapping from Workday
    Microsoft_CompanyOfficeStreet /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Business_Site_Summary_Data/wd:Address_Data/wd:Address_Line_Data
    Microsoft_CompanyOfficeCity /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Business_Site_Summary_Data/wd:Address_Data/wd:Municipality
    Microsoft_CompanyOfficeState /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Business_Site_Summary_Data/wd:Address_Data/wd:Country_Region_Descriptor
    Microsoft_CompanyOfficePostalCode /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Business_Site_Summary_Data/wd:Address_Data/wd:Postal_Code
    Microsoft_Company /wd:Worker/wd:Worker_Data/wd:Organization_Data/wd:Worker_Organization_Data[1]/wd:Organization_Data/wd:Organization_Name
    Microsoft_CompanyCode No mapping from Workday
    Microsoft_FirstName /wd:Worker/wd:Worker_Data/wd:Personal_Data/wd:Name_Data/wd:Legal_Name_Data/wd:Name_Detail_Data/wd:First_Name
    Microsoft_LastName /wd:Worker/wd:Worker_Data/wd:Personal_Data/wd:Name_Data/wd:Legal_Name_Data/wd:Name_Detail_Data/wd:Last_Name
    Microsoft_DisplayName /wd:Worker/wd:Worker_Data/wd:Personal_Data/wd:Name_Data/wd:Preferred_Name_Data/wd:Name_Detail_Data/@wd:Formatted_Name
    Microsoft_JobTitle /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Business_Title
    Microsoft_SecondaryJobTitle No mapping from Workday
    Microsoft_UserSkillNames /wd:Worker/wd:Worker_Data/wd:Skill_Data/wd:Worker_Skill_Item/wd:Skill_Data[@wd:Inactive="0"]/@wd:Name
    Microsoft_EmploymentType /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Worker_Type_Reference/wd:ID[@wd:type="Employee_Type_ID" or @wd:type=\"Contingent_Worker_Type_ID"][1]
    Microsoft_EmployeeID /wd:Worker/wd:Worker_Data/wd:Worker_ID
    Microsoft_ManagerID /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Manager_as_of_last_detected_manager_change_Reference/wd:ID[@wd:type="Employee_ID" or @wd:type=\"Contingent_Worker_ID"][1]
    Microsoft_HireDate /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Status_Data/wd:Hire_Date
    Microsoft_EmploymentStatus /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Status_Data/wd:Active (1 is mapped to "Active" and 0 is mapped to "Inactive")
    Microsoft_GlintEmploymentStatus /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Status_Data/wd:Active (1 is mapped to "Active" and 0 is mapped to "Inactive")
    Microsoft_Phone /wd:Worker/wd:Worker_Data/wd:Personal_Data/wd:Contact_Data/wd:Phone_Data/@wd:Tenant_Formatted_Phone
    Microsoft_CostCenter /wd:Worker/wd:Worker_Data/wd:Organization_Data/wd:Worker_Organization_Data/wd:Organization_Reference/wd:ID[@wd:type='Cost_Center_Reference_ID'][1]
    ExternalSource_PersonIdentifier /wd:Worker/wd:Worker_Data/wd:Worker_ID
    ExternalSource_ManagerIdentifier /wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Worker_Job_Data/wd:Position_Data/wd:Manager_as_of_last_detected_manager_change_Reference/wd:ID[@wd:type="Employee_ID" or @wd:type=\"Contingent_Worker_ID"][1]
    ExternalSource_DotLineManagersIdAndLabel /wd:Worker/wd:Worker_Data/wd:Management_Chain_Data/wd:Worker_Matrix_Management_Chain_Data/wd:Management_Chain_Data/wd:Manager_Reference/(wd:ID[@wd:type="Employee_ID" or @wd:type="Contingent_Worker_ID"] | 'Dot-Line Manager')