Workday HCM Setup Guide

Prerequisites

Administrator access to your Workday tenant. You need it to create the integration user and grant it permissions.
A dedicated Workday Integration System User (ISU) for Matia. You'll create one in Step 1. Matia expects an ISU rather than a personal or administrator account.

Authentication options

Pick one of the two methods before you start, since a few Workday settings depend on it:

Method in Matia	What you enter	Workday setup
Access Token	ISU username and password	Steps 1, 2, 3 and 5 (Step 6 is optional)
OAuth	Client ID, Client Secret, and Refresh Token	Steps 1 to 5 (Step 6 is optional)

Both methods also need your Workday Tenant and Workday Hostname (see Step 5).

Setup Guide

Step 1: Create the Matia integration user and security group

Sign in to Workday as an administrator.
Run the Create Integration System User task (search for create user).
Choose a User Name and Password, and keep Require New Password at Next Sign In unchecked.
Set Do Not Allow UI Sessions based on your authentication method:
- Access Token: check it.
- OAuth: leave it unchecked. The OAuth flow needs the user to be able to open a UI session.
Click OK, then Done.
Run the Create Security Group task.
Set Type of Tenanted Security Group to Integration System Security Group (Unconstrained), give the group a Name, and click OK.
Add the integration user from this step to the group and click OK.

Step 2: Allow the group to authenticate

Run the Manage Authentication Policies task and click Add Authentication Policy.
Under Restricted to Environments, pick the environments Matia should reach, and check Authentication Policy Enabled.
In the Authentication Allowlist, add a rule with an Authentication Rule Name, the Security Group from Step 1, and an Authentication Condition Name with its Authentication Conditions.
Under Allowed Authentication Types:
- Access Token: choose Specific and select User Name Password.
- OAuth: choose Any.
Click OK.
Run Activate All Pending Authentication Policy Changes, add a comment, check Confirm, and click OK.

Step 3: Grant read access to the data Matia syncs

Matia reads from the Workday Human Resources, Staffing, Payroll, and Time Tracking web services. The security group needs Get access to the domains behind the data you plan to sync:

Workers, including personal data, contact details, positions, leave status, and worker events
Positions, organizations, job profiles, job families, and job categories
Payroll results
Calculated time blocks

Open the Security Group Membership and Access report and select the security group from Step 1.
From the group's related actions (...), choose Security Group > Maintain Domain Permissions for Security Group.
Under Integration Permissions, add the relevant domains to Domain Security Policies permitting Get access, then click OK and Done.
Run Activate Pending Security Policy Changes, add a comment, check Confirm, and click OK.

Tip: Domain names vary between tenants. To see which domains protect a specific object, open it in the View Security for Securable Item task, click View Security, and look at the domains listed for its Get operations.

Step 4 (OAuth only): Create an API client and refresh token

Skip this step if you use Access Token.

Run the Register API Client for Integrations task.
Enter a Client Name, e.g. Matia.
Keep Non-Expiring Refresh Tokens checked. If you set a Refresh Token Timeout instead, the connection stops working when the token expires and you'll have to paste a new one into Matia.
Under Scope (Functional Areas), select the functional areas that match the domains you granted in Step 3. The View Security for Securable Item task shows the functional area for each object. Leave Include Workday Owned Scope unchecked.
Click OK, then copy the Client ID and Client Secret. Workday shows the secret only once.
From the client's related actions, choose API Client > Manage Refresh Tokens for Integrations.
For Workday Account, select the integration user from Step 1, check Generate New Refresh Token, and click OK.
Copy the Refresh Token.

The Client ID, Client Secret, and Refresh Token must all come from the same API client. Matia uses the refresh token to request short-lived access tokens on its own, so there is no sign-in popup during setup.

Step 5: Find your tenant and hostname

Open any Workday Web Services endpoint URL for your tenant. It follows this pattern:

https://<hostname>/ccx/service/<tenant>/Human_Resources/...

Workday Tenant is the segment right after /ccx/service/.
Workday Hostname is the host only, e.g. impl-services1.wd5.myworkday.com. Leave out https:// and any path, since Matia builds the full URL for you.

Note: Use the web services host, which contains -services1 (or -services2, -services3, and so on). The host you see in the browser when using Workday, e.g. impl.wd5.myworkday.com, won't work.

Step 6 (Optional): Set up custom and calculated fields

Do this only if you want Workday custom or calculated fields on worker data. In Matia they appear in the worker, worker history, and calculated time block tables.

Run the Create Integration System task, name it, choose New Using Template with the Cloud Integration template, and click OK.
From the integration system's related actions, choose Integration System > Configure Integration Services, check Enable All, and click + under Custom Integration Services.
Create an Integration Field Override Service, set its Business Object to Worker, list the fields you want to expose, and click OK until the configuration is saved.
From the related actions again, choose Integration System > Configure Integration Field Overrides, pick the service you just created, map each field under Override External Field, and click OK.
Copy the Integration System ID.

Step 7: Complete configuration in Matia

Choose Access Token or OAuth as the authentication method.
Enter the Workday Tenant and Workday Hostname from Step 5.
Enter the credentials for your method:
- Access Token: the integration user's Username and Password from Step 1. Enter the username alone, without @<tenant>. Matia adds the tenant for you.
- OAuth: the Client ID, Client Secret, and Refresh Token from Step 4.
(Optional) Turn on Sync Custom and Calculated fields and enter the Integration System ID from Step 6.
Enter an Asset Name.
(Optional) Enter a Description.
(Optional) Assign Tags.
Select an Owner.
Verify that your Workday HCM account is successfully connected by clicking Test Connection.
Click Connect.

Note: Test Connection checks your credentials and hostname by reading job families. It doesn't check every domain, so a missing permission may only show up during the first sync as a "not authorized" error. If that happens, add the missing domain in Step 3 and activate the change.

Troubleshooting

Authentication failed: Check that you're using the integration user, not an administrator account, and that the authentication policy from Step 2 is active. For OAuth, confirm the Client ID, Client Secret, and Refresh Token all belong to the same API client.
Task submitted is not authorized: The security group is missing a domain. See Step 3.
Syncs fail on Saturday mornings: Workday runs weekly maintenance on Saturdays from 02:00 to 06:00 (UTC-5). Syncs that run during that window can fail with a 503 error. Syncs after the window ends are not affected.