Option 5: Create an integration from an external source like Workday for API-based import

1. Register a new app in the Microsoft Entra admin center

Applies to: Microsoft 365 Global Administrator

1. From the Microsoft admin center's left rail, select All admin centers. This option appears as the last one on the list.

   

2. Select Microsoft Entra.

3. On the left, under Entra ID, select Overview.

   

4. Create a new app registration:

   1. In the top toolbar, select Add > App registration.

      

   2. On the resulting screen:

      1. Give your app a name.

      2. Under Supported account types, leave the first option, Accounts in this organizational directory only ([Your organization] only - Single tenant), selected.

      3. At the bottom of the screen, select Register.

         

   3. When you arrive back at the Overview page, copy the Application (client) ID and Directory (tenant) ID. Keep these IDs handy. You'll need to provide them later.

      

5. Remove existing API permissions:

   1. On the left, select API permissions.

   2. For each listed API / Permissions name, select the ellipsis (...) to the right of the API, such as Microsoft Graph.

   3. Select Remove permission.

      

   4. Confirm removal. When you remove permissions for these items, you're making sure the app only has permissions for what it needs.

6. (Optional) If you'd like to manually add the required API permission instead of doing it automatically in step 4 above:

   1. Select Add a permission.

   2. Select APIs my organization uses.

   3. Search for "Organizational Data in Microsoft 365," and select it.

   4. Select Delegated permissions.

   5. Under Permissions, select access as user.

   6. Select Add permissions.

      

   7. Under Configured permissions, select Grant admin consent.

7. Give the Data source admin the app ID and the tenant ID.

2. (Optional) Manually add required user permission

Applies to: Microsoft 365 Global Administrator

If you'd like to manually add the required user permission instead of doing it automatically in step 4, follow the steps below.

1. In the Microsoft Entra admin center, on the left, select Enterprise apps.

2. Remove the "Application type" search filter.

   

3. Search for "Organizational Data in Microsoft 365," and select it.

   

4. Under Manage on the left, select Users and groups.

5. Select Add user/group.

   

6. Under Users and groups, select None Selected.

7. Search for and select the user or email address that you'll use to retrieve OAuth tokens from the token script.

   

8. Select Select, then at the bottom select Assign.

3. Create a client secret

Applies to: Microsoft 365 Global Administrator

First, navigate back to your app registration in the Microsoft Entra admin center. Find your app registrations under Entra ID on the left.

1. In the app registration in the Microsoft Entra admin center, under Manage on the left, select Certificates & secrets.

2. Select Client secrets, then select New client secret.

   

3. Enter a description for the secret and set an expiration date. Then select Add.

   

4. On the Certificates & secrets page, select the copy icon to copy the secret to your clipboard. Save it securely for later use when setting up the import.

   

4. Set up the import in the Microsoft 365 admin center

Applies to: Microsoft 365 Global Administrator or Organizational Data Source Administrator

1. Start the import from the Data Connections page on the Microsoft 365 Organizational Data Service page (Home > Setup > Migration and imports > Microsoft 365 Organizational Data Service > Data Connections).

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 API-based setup.

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 data. You can change your selections at any time within Settings. Learn more.

5. The Preparation and setup panel lays out the rest of the steps to complete the connection. Some of these steps, such as the creation of the app registration, have already been completed using the process described above. You'll need to prepare a header .csv file to map your imported attributes to the apps with which you're sharing data. If you don't already have a template for this file, select Download template to get started.

6. On the Set up API-based connection page, select User ID. Under User ID, enter the User Principal Name (UPN) or object ID of the user that you'll use to retrieve OAuth tokens from the PowerShell script. The UPN is normally the same as the email address of the user. Under App ID, enter the app ID from the app registration. The first time the connector is provisioned, a global admin must complete this step. After provisioning, the API connector Data Writer role is automatically assigned and you can see it in the Microsoft Entra admin center.

   • 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 how.

7. On the Import headers for attribute mapping page, upload the .csv file you created in the previous step for attribute mapping.

   • Make sure the headers in the .csv header file match your .csv data file. If you have more fields in your .csv header file than in your .csv data file, or vice versa, processing for your import will fail.

8. Map your reserved attributes to your imported data. This means you'll match attributes from your .csv file to their corresponding attributes for the apps with which you're sharing data. Any imported attributes that you don't match to reserved attributes are used as custom attributes and can't be renamed. Learn more. To automatically map columns and skip manual mapping, use reserved attribute names with the "Microsoft_" prefix, such as Microsoft_PersonEmail, in your .csv column headers. See the complete list of reserved attribute names.

9. View the global attributes that are used for all Microsoft 365 apps and services. These are attributes pulled from your imported data that are automatically used by all eligible apps. At the bottom of the page, select Next.

10. On the last page, review all the details, apps, and attribute mapping for your connection. If everything looks correct, select Connect.

Your organizational data is validated against the requirements for use with Viva and Microsoft 365 services. 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 Organizational data page in the admin center. When the validation is complete, you see a message that your data is in use and managed by Viva and Microsoft 365. Once validation is complete, the organizational data is made available to the apps and services you selected.

5. Run the PowerShell solution to retrieve tokens

Applies to: Organizational Data Source Administrator

Running this solution generates the tokens you need to then create the API integration in your external source like Workday. See the solution on GitHub.

1. Download this PowerShell script.

2. Open Windows PowerShell 5.1 or PowerShell 7 to run the script:

   1. Navigate to the script location: cd path/to/folder

   2. In Windows PowerShell 5.1: powershell -File .\OrganizationalDataTokens.ps1

   3. In PowerShell 7: pwsh -File .\OrganizationalDataTokens.ps1

3. Enter the following console values:

• App (client) ID: Find this ID in the registered app information in the Microsoft Entra admin center under Application (client) ID.

• Client secret: This is a secret string that the application uses to prove its identity when requesting a token. It's also referred to as application password. This secret is only shown for the first time when the client secret is created. To create a new client secret, follow these steps.

• Microsoft Entra tenant ID: Find this ID in the registered app information in the Microsoft Entra admin center under Directory (tenant) ID.

• Connector ID: This is the string at the end of the URL that appears when you select your API-based connector in the Microsoft 365 admin center, such as https://admin.cloud.microsoft/?#/featureexplorer/migration/M365OrganizationalDataService/connection-details/[Connector ID here].

4. The script will run and open a new browser window. Log in with the same user you entered under User ID (UPN or object ID) when setting up the import in the Microsoft 365 admin center.

5. On the HRIS Integration Configuration page, securely copy the following values, which you'll use to create the integration in your external source like Workday Enterprise Interface Builder (EIB):

• HTTP Address
• Access Token
• Refresh Token
• Refresh Token URL

Troubleshooting

Error: "Need admin approval" or "Invalid resource"

A global admin needs to follow Step 4.6 above to automatically provision the required API permission or Step 1.6 above to manually add the permission and grant admin consent.

Error: "Redirect URI mismatch"

A global admin needs to add http://localhost:5173/callback as a Web redirect URI in the Authentication page of the app registration:

Error: "Unauthorized" / HTTP 403 in your HRIS integration

• Verify the tokens aren't expired.

• Check that the refresh token URL uses your specific tenant ID (not "/common/").

• Make sure the User ID configured in the API-based connector matches the user used to login when running the script to retrieve tokens.

• Make sure the App ID configured in the API-based connector matches the App ID used when running the script to retrieve tokens.

Additional authentication and authorization resources:

• Microsoft Identity Platform Documentation

• OAuth 2.0 Authorization Code Flow

6. Create a custom report in Workday

Applies to: Microsoft 365 Global Administrator or Organizational Data Source Administrator

1. Open Workday, search for "Create custom report," and select it.

   

2. Enter a name for your report.

3. Next to Report Type, select Advanced.

4. Next to Data Source, select Workers for HCM Reporting.

5. Leave Optimized for Performance cleared to filter out workers that don't have an email address. Microsoft identifies workers by email address, so it's a required field.

   

6. At the bottom of the page, select OK.

7. To add manager email fields:

   1. Select the three-dot menu to the right of your report's name.

   2. Select Calculated Field for Report > Create Calculated Field.

      

   3. Enter a name for the new field, such as "Manager Email."

   4. Next to Business Object, enter "Worker."

   5. Next to Function, enter "Lookup Related Value."

      

   6. Select OK.

   7. On the next screen, next to Lookup Field, enter "Manager – Level 01."

   8. Next to Return Value, enter your desired email field, such as Public Primary Work Email Address.

      

   9. At the bottom of the page, select OK.

8. Add fields and customize the report based on your organization's needs:

   1. Select the three-dot menu to the right of your report's name.

   2. Select Custom Report > Edit.

   3. Next to Data Source Filter, enter "All Active Workers (All Types)."

   4. Under the Columns tab, select the "+" icon on the top left to add fields.

      

Example of mappings for most reserved fields listed here

• The Manager Email field references the calculated field you set up above.

• This is a best guess for the mapping of each field; there might be more suitable mappings for your tenant specifically.

• Any of the reserved fields linked above can be added here if they're not already. You can also add any custom fields you want with any name, and those can be imported into any apps that use custom fields.

Filter out workers that don't have an email by adding to the Filter tab, such as:

After you customize the report, select Advanced. Then, under Web Services Options, select Enable As Web Service.

7. Create the integration in your external source

Use these steps to create the API integration in Workday. Workday documentation can be found here.

1. At the top of the screen in Workday, search for "Create EIB," and select it.

2. On the Create EIB page:

   1. Enter a name for the integration.
   2. Select Outbound.
   3. Select OK.

3. Review and confirm the details on the General Settings page. If everything looks good, select Next.

4. On the Get Data page:

   1. Next to Data Source Type, select Custom Report.

   2. Next to Custom Report, select the report you want to integrate with your API-based connector.

   3. Under Details, next to Alternate Output Format, select CSV.

      

   4. At the bottom of the page, select Next.

5. On the Transform page, you don't need to make any changes. Select Next.

6. On the Deliver page:

   1. Next to Delivery Method, select HTTP/SSL.
   2. Next to HTTP Address, enter the address generated from the steps above.
   3. Next to Web Service Invocation Type, select OAuth 2.0.
   4. Next to Access Token, enter the access token generated from the steps above.
   5. Next to Refresh Token, enter the refresh token generated from the steps above.
   6. Next to Refresh Token URL, enter the refresh token URL generated from the steps above.
   7. Next to Client ID, enter the AppID/ClientID.
   8. Next to Client Secret, enter the client secret.
   9. Next to File Name, enter your desired file name, which must be .csv.
   10. At the bottom of the Deliver page, select Next.

7. Review the details on the Review and Submit page. If everything looks good, select OK.

8. Next to the name of your integration, select Actions.

9. Hover over Integration, then select Launch/Schedule Integration.

10. On the Launch/Schedule Integration page:

    1. Next to Integration, select the name of the integration you created.
    2. Next to Run Frequency, choose your desired frequency.
    3. Select OK.