Okta will link a Workday person to an existing Okta user only on the value you told it to match. The value teams usually pick, employee ID, is not stable across a contingent-worker conversion or a pre-hire. Workday’s universal ID is the identifier built for that transition. Okta’s own Workday page says the same thing from the directory side.
The IDs Workday actually generates
Steps: Set Up Workday IDs says you configure sequence generators separately for pre-hires, employees, contingent workers, dependents, beneficiaries, and academic persons. You can also define a universal ID so one value follows a person through those types. The page names employees, pre-hires, prospects, and students as the transitions that universal ID is there to track.
The setup is Edit Tenant Setup - HCM, in the ID Sequence Generators section, for the employee, contingent worker, and similar definitions. The universal ID definition is selected on Edit Tenant Setup - System, under ID Definition for Universal Id. You can also create one from a worker’s related actions with Create Universal Id. The domain is Person Data: Universal ID. Maintain Custom Labels can rename it. None of that makes the employee ID equal the contingent worker ID. They stay separate sequences.
FAQ: How do I import worker IDs during a hire? is the path for an ID that originates outside Workday. Put a Verify Proposed Employee ID step on Hire, or Verify Proposed Contingent Worker ID on Contract Contingent Worker. Those steps pull the ID from the Put Hire Event Proposed Worker ID web service. This guide does not invent the request body of that service. If you do not use that step, Workday’s sequence assigns the new employee ID at hire, which will not equal a pre-hire sequence or a prior contingent worker sequence.
Pre-hires are their own records. Steps: Manage Pre-Hire Tracking covers creating them, including in bulk by web service, considering them for a position, and deleting them. They are not employees until Hire Employee or Contract Contingent Worker. A directory match that treats “any person ID Workday has issued” as the employee ID will attach the account to the wrong sequence. The early-account problem is pre-hire windows.
What Okta imports and what it matches
Okta’s Workday provisioning page documents a base profile of 20 attributes and a default map from appuser.employeeID to Okta employeeNumber. The same page’s writeback examples use employeeID as the Workday value when Workday is allowed to source the user. Read it here: https://help.okta.com/en-us/content/topics/provisioning/workday/workday-provisioning.htm
Okta’s import-matching article says you can match an imported user on any attribute mapped from the app user onto the Okta user, and it gives Workday Employee ID as the example for a scheduled import: https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-matching-imported-users.htm
Matches are case sensitive. Exact matches can be auto-confirmed. Everyone else waits for a person. If nothing matches, Okta creates a user.
Okta Workflows’ Search Workers action uses a different label for a related value. Its Worker ID output is “the Employee ID or Contingent Worker ID for the worker,” and it also returns a Worker Resource ID and a Person ID. That page is https://help.okta.com/wf/en-us/content/topics/workflows/connector-reference/workday/actions/searchworkers.htm . Calling all three “the Workday ID” is how a joiner lands on a new Okta user while the old contingent worker is still assigned.
| Workday value | What it identifies | Okta’s documented use |
|---|---|---|
| Workday valueEmployee ID | What it identifiesThe employee sequence | Okta’s documented useDefault appuser.employeeID, mapped to employeeNumber. The matching example in Okta’s import article. |
| Workday valueContingent worker ID | What it identifiesThe contingent worker sequence | Okta’s documented useIncluded in what Okta Workflows calls Worker ID, beside the employee ID. A different sequence in Workday. |
| Workday valueUniversal ID | What it identifiesOne secondary ID across person types, after you configure it | Okta’s documented useOkta’s conversion support. Okta says mapping it into the Okta profile is optional and is not required for the conversion feature itself. |
| Workday valuePre-hire ID | What it identifiesThe pre-hire sequence, if you generate one | Okta’s documented useNot an employee ID. A pre-hire interval can import this person early. See the next section. |
Contractor to employee, and the duplicate Okta user
Okta’s provisioning page is direct. Contractor and full-time worker are separate Workday entities with unique Workday IDs. You link them by putting the same secondary ID on both. That secondary ID is the universal ID.
- Universal ID, once configured in the tenant, applies to newly created workers. Existing workers get it only if you update their profiles. Okta says you can do that update with Workday’s API. This guide does not invent that request.
- Without a universal ID, Okta cannot tell that a contractor was converted, and you get duplicate workers.
- If a pre-hire interval is on and universal ID is not, Okta imports both the contractor and the future full-time pre-hire. They have different Workday IDs, so the Import tab shows a duplicate.
- With universal ID, incoming pre-hires that share it with an active worker are filtered out. When the contractor is deactivated, the full-time user with the same universal ID is the one Okta selects. Okta then deactivates and reactivates the Okta user. In Okta’s words, that terminates the contractor and hires the employee.
The Okta settings for that behavior are Provisioning, To Okta, User Creation and Matching: auto-confirm exact matches, and auto-confirm new users. Workday as a profile source has to be the highest-priority profile source, above the directory where accounts are created, or Workday will not win the attribute write. Those steps are on the same Okta page.
Incremental imports bring workers Okta sees as updated since the last incremental import. Okta says a change to an effective-dated custom attribute, by itself, does not trigger that import. Full imports bring base attributes and both non-future and future effective-dated custom attributes, including changes the incremental import omitted. Okta calls a weekly full import common practice. A joiner whose only change was an effective-dated custom field can wait for that full import even when the employee ID is already the match key.
Real Time Sync is the path Okta documents for a termination that cannot wait for the next import. You configure a Workday business process to send the trigger. Immediate termination reasons are a regular expression against Workday’s Termination_Subcategory_ID. Workers whose reason matches, with a termination date of the current date, are processed when the event arrives. The details are on the Okta page above. Day-one and last-day timing, including the pre-start interval, is pre-hire windows and day-one access.
The Workday account that reads this
Workday Configurable Security says to create one integration system user and one integration system security group per integration system, and to give that user the domains that integration needs. An unconstrained group can see all workers. A constrained group sees the organizations you assign. Okta’s best-practices page says constrained security groups are supported for limiting who is imported: https://help.okta.com/en-us/content/topics/provisioning/workday/best-practices.htm
A single integration system user that can read payroll, benefits, and every worker is the overpowered account that chapter tells you to avoid. Roots’ statement of the same idea is in the next section.
Where Roots fits
Kiweely Roots (coming next) includes Okta in identity: joined on day one and closed on the last. Directory feeds are fixed, tested, and turned back on, with a note to the owner. Payroll, benefits, and tax are the feeds that wait for approval after a Sandbox proof. Each integration has its own API client, scoped to what it reads. Register interest on the Roots page and say whether the match key today is employee ID or universal ID. Roots does not merge Workday’s employee and contingent worker sequences. That remains the universal ID setup above.
A match checklist
New hire, never worked here.
Match on the employee ID Workday assigned or imported through Verify Proposed Employee ID. Confirm the Okta user does not already exist from a pre-hire import under a different sequence.
Contractor becoming an employee.
Configure universal ID in Workday first. Okta will not recognize the conversion without it, and a universal ID configured later does not backfill existing workers by itself.
The attributes updated and the Okta user did not.
If the only edit was an effective-dated custom attribute, Okta’s incremental import will not pick that worker up. Run the full import Okta describes, or wait for the weekly one, and confirm Workday is the highest-priority profile source.