Workday HCM Connector Setup

Overview

The Workday HCM connector extracts workforce data -- workers, positions, compensation, supervisory organizations -- from Workday using Report-as-a-Service (RaaS). VersionForge authenticates via OAuth 2.0 using a refresh token, which is exchanged for short-lived access tokens automatically.

This setup requires a Workday Integration System User (ISU) with appropriate domain security permissions. Plan for approximately 30 minutes of Workday tenant configuration.

Prerequisites

• Workday tenant (production, sandbox, or implementation)
• Security Administrator or IT Administrator access to create ISUs and modify security policies
• A RaaS custom report configured for extraction (see RaaS Configuration)

Credential Fields

| Field | Required | Description | |-------|----------|-------------| | tenantUrl | Yes | Your Workday tenant URL (e.g., https://impl.workday.com/yourcompany). | | clientId | Yes | OAuth 2.0 client ID from the API Client registration. | | clientSecret | Yes | OAuth 2.0 client secret. | | refreshToken | Yes | Long-lived refresh token issued during the OAuth grant flow. |

Setup Steps

1. Create an Integration System User (ISU)

   In Workday, search for the Create Integration System User task. Create a user with a descriptive name like ISU_VersionForge. Set a strong password and check Do Not Allow UI Sessions -- this user should only authenticate via API.

   ISUs are exempt from password expiration policies by default. This prevents your integration from breaking when password rotation cycles run.

2. Create an Integration Security Group

   Search for Create Security Group. Choose type Integration System Security Group (Unconstrained). Name it ISSG_VersionForge. Add the ISU you created in Step 1 as a member.

3. Configure Domain Security Permissions

   Search for Security Group Membership and Access and edit the ISSG_VersionForge group. Grant Get access to these domain security policies:

   • Worker Data: All Positions -- position assignments, job profiles
   • Worker Data: Workers -- core worker records
   • Worker Data: Compensation -- compensation plans, amounts
   • Worker Data: Organization Information -- supervisory org assignments
   • Reports: Deliver Reports -- required for RaaS access

   After modifying security policies, run the Activate Pending Security Policy Changes task to apply them.

4. Register an API Client

   Search for Register API Client for Integrations. Provide a client name (e.g., "VersionForge"), select the ISU as the owner, and choose Authorization Code as the grant type. Set the redirect URI to your VersionForge instance's OAuth callback URL. Save and copy the Client ID and Client Secret.

5. Generate a Refresh Token

   Use the Workday OAuth 2.0 authorization flow to obtain a refresh token. Navigate to:

   https://{tenantUrl}/oauth2/{tenant}/authorize?client_id={clientId}&response_type=code&redirect_uri={callbackUrl}
   

   After authorizing, exchange the authorization code for an access token and refresh token using the token endpoint. Store the refresh token -- VersionForge uses it to obtain new access tokens automatically.

6. Configure the Credential in VersionForge

   In the VersionForge UI, go to Administration > Credentials > Add Credential. Select Workday HCM as the connector type. Enter tenantUrl, clientId, clientSecret, and refreshToken.

Test Your Connection

Click Test Connection on the credential detail page. VersionForge exchanges the refresh token for an access token and calls the Workday organizations endpoint to verify API access. A successful test confirms:

• The refresh token is valid and the ISU account is active
• The token endpoint URL is correctly derived from your tenant URL
• The ISU has domain permissions to read organizational data

Common Issues

HTTP 401 on token exchange -- The refresh token may have been revoked or the client secret changed. Re-run the OAuth authorization flow to generate a new refresh token.

HTTP 403 on RaaS report -- The ISU's security group is missing the "Reports: Deliver Reports" domain permission or lacks access to the specific RaaS report. Verify both the domain permission and the report-level sharing settings.

Tenant URL format -- The tenant URL must include the company path segment (e.g., https://impl.workday.com/yourcompany). VersionForge extracts the tenant slug (yourcompany) from the URL path to construct the OAuth token endpoint.