Okta can import users and groups from Workday through its standard API. Three types of imports are supported:
Full imports bring in all workers and all base and custom attributes. Full imports are time-consuming but must be scheduled to perform reconciliation between the two systems and to bring attributes that aren't supported in the other import types. Typically, this task is performed once per week. The full import includes base attributes, non-future, and future effective dated custom attributes. It also includes any changes that incremental or Real Time Sync imports omitted.
Incremental imports bring data for workers that Workday identifies as updated since the last incremental import. Changes must be in the base or non-effective future dated custom attributes for the worker to be included. Changes to effective dated custom attributes alone don't trigger an incremental import. Included in the incremental import are base attributes, non-future, and future effective dated custom attributes. Incremental imports should be scheduled at an interval that supports regular business processes. Typically, this would be at least once per day and can be scheduled as frequently as once an hour. For more information, see Incremental imports.
Real Time Sync imports
Real Time Sync (RTS) is used to trigger an update from Workday to Okta in real time. It should be used for changes where timeliness is critical such as immediate termination of a worker. A business process must be configured in Workday to send the trigger to Okta to start this process. Included in the RTS import are base attributes, non-future, and future effective dated custom attributes. For more information, see Workday Real Time Sync.
The optimal configuration of these import types ensures optimal data accuracy and timeliness of data moving from Workday to Okta. When you configure imports, consider the features and limitations of each import type.
Okta supports two typical scenarios: import from Workday, and Workday-driven IT provisioning.
Import from Workday
Import from Workday to Okta includes users and groups. Imported Workday users are used to create Okta users, and imported Workday groups can be used to assign apps. Workday no longer managers users after they've been imported into Okta. Any updates made to the user in Workday won't change the associated Okta user.
Workday-driven IT provisioning
With Workday-driven IT provisioning, Okta integrates with Workday to drive IT provisioning. When a Workday user is imported into Okta, they continue to be managed by Workday. Updates and terminations made in Workday are reflected in Okta and downstream apps. This arrangement enables Workday to manage employee and contractor access to apps. Workday-driven IT provisioning is a superset of the functionality provided by imports from Workday. Therefor, the instructions for configuring Workday-driven IT provisioning are also relevant to import from Workday scenarios.
Okta imports only users who have the First Day Of Work and Hire Date attributes or fields populated in Workday
If you're using Active Directory and you have Profile Push enabled, see Configure Active Directory provisioning settings
With Workday-driven IT provisioning, Okta supports the following worker lifecycle events:
- A new Worker is hired in Workday
- Okta imports the new Worker and creates an Okta user profile
- Okta creates accounts in downstream apps (AD included)
- A Workday user’s attribute is changed in Workday
- Okta imports the attribute change
- Okta updates the attribute in downstream apps (AD included)
- A Worker is terminated in Workday
- Okta imports the status change
- Okta deactivates the Okta user and accounts in downstream apps (AD included)
- A terminated Worker is rehired in Workday
- The deactivated Okta user needs to be manually reactivated in Okta
- Okta imports and relinks the rehired Worker with the reactivated Okta user
Before you configure provisioning in Okta, ensure that these requirements are met:
- Add a Workday app instance and configure SSO
- Create an Integration System User in Workday
- Grant permission to an Integration System User
Add a Workday app instance and configure SSO
You already added a Workday app instance in Okta and configured SSO. See How to Configure SAML 2.0 for Workday.
For general information about applications and adding applications, see Add existing app integrations.
Create an Integration System User in Workday
Okta accesses the Workday APIs with a special type of Workday user known as an integration system user. To create one, enter create integration system user in the search box and click the resulting task. Follow the directions to create a username and password.
Grant permission to an Integration System User
Grant the Integration System User permission to access the web services needed for the Okta Workday integration through Workday Security Groups.
- To create a Security Group, enter create security group in the search box.
- Click Create Security Group in the search results.
- Select Integration System Security Group (Unconstrained) from the In the Type of Tenanted Security Group dropdown.
- Enter a name for the group.
- On the next page, add your integration system user to the list under Integration System Users. To return to this group for future edits, enter the security group name in the search box.
- To integrate with Okta, the security group requires appropriate access to these business domains:
- External Account Provisioning (permissions: Get and Put)
- Worker Data: Public Worker Reports (permissions: Get and Put)
- Worker Data: Work Contact Information (permissions: Get and Put)
- Worker Data: Current Staffing Information (permissions: Get)
- Worker Data: All Positions (permissions: Get)
- Worker Data: Business Title on Worker Profile (permissions: Get)
- Set the correct integrated permissions for each business domain:
- Enter Domain Security Configuration in the search box.
- Click the resulting report.
- Enter the business domain name in the search field, and then click OK.
- Select Domain > Edit Security Policy Permissions from the dropdown menu beside the domain name.
- Add your security group to the appropriate section under Integrated Permissions. Use the required permissions for the business domain (Get or Get and Put) to determine where to place the group.
Verify with Workday to make sure all the required permissions are configured for the security group
- Workday might alert you to activate the security policy changes. If you don’t activate the changes, the integration user account won't have the necessary permissions.
- Activate the changes:
- Search for Activate Pending Security Policy Changes.
- Click the resulting task.
- Enter a comment (required), and then click OK.
- Verify the changes that need to be activated.
- Configure Workday provisioning
- Enable Workday provisioning features in Okta
- Manage Workday Provisioning Groups
- Map Attributes
- Custom expressions
- Workday custom attributes
- Workday field overrides
- Custom attributes imported with a custom report
- Use Paginated Custom Reports (recommended)
Configure Workday provisioning
To set up the API integration, go to the Okta Provisioning tab in your Workday instance:
Select Enable API Integration and then configure the other fields, as required.
Note: You must configure values for API Username, API Password, and WebServices Endpoint. The remaining settings are optional.
- API Username: The format is: [integration system user name]@[tenant]. For example: wd_integration@oktademo. Find the tenant name in your Workday URL.
- API Password: The password for the integration system user which is used above.
- WebServices Endpoint: Find the tenant name in your Workday URL. To obtain the web services endpoint, look up the WSDL of any of the web services in your org:
- Search for public web services.
- Under Reports, select Public Web Services.
- From the Public Web Services list, select a service, open its dropdown menu and select Web Service > View WSDL. which displays the full WSDL in a separate window.
- Search the WSDL page for soapbind:address to see the web services endpoint corresponding to the web service that you chose.
- For the Okta configuration, you only need the URL up to the tenant name. For example, if the value in the WSDL window is https://implcc.workday.com/ccx/service/okta_pt1/Human_Resources/v19, then enter https://impl-cc.workday.com/ccx/service/okta_pt1.
- Integration System Id (optional): See Workday Custom Attributes.
- Department Field (optional): This value determines which worker attribute to use for the department attribute of the user in Okta. By default, the value is Business Unit.
- Pre-Start Interval (optional): This value determines how many days before the hire date you should have the user imported and activated in Okta. For more information, see Pre-Start Interval Details.
- Sync Personal Phones (optional): With this option, Okta can use personal phone numbers accessed from Workday if work phone numbers are otherwise unavailable.
- Only Import Workers with Workday (optional): This option allows you to import only Workday workers who have Workday accounts and automatically filter out workers who don't. By clicking this option, your next import includes only valid Workday workers.
- Immediate Termination Reasons (optional): If you use the Real Time Sync feature, use this text box to match the Termination_Subcategory_ID for each termination reason, as identified in the Workday Integration IDs. This field must be a Regex expression. See Workday Real Time Sync.
- Deactivate on Last Day of Work (optional): With this option, users are deactivated based on the last day of work instead of the termination date. The user deactivation takes place when their Last Day of Work matches the current date.
- Timezone aware terminations (optional): With this option, users are deactivated based on the current time in their time zone or location. See Time Zone Aware Deactivation for more details.
Enable Workday provisioning features in Okta
Select To Okta in the left panel, enable Profile Source, and set up import rules:
The User Import provisioning feature is automatically enabled when provisioning is enabled. Edit the settings for this feature as required.
For the Workday-driven IT Provisioning scenario, Okta recommends setting up scheduled import and automatic confirmation so that worker lifecycle events in Workday are periodically propagated to Okta without manual intervention. Note that imports can take a longer time to complete if there’s a large number of workers in Workday. Therefor, it’s not advisable to schedule imports too frequently.
The Workday integration supports incremental imports as part of Scheduled Imports. For details, see Incremental imports.
We recommend that you first import your users manually. Then, schedule your imports according to your import results. If the import takes too long, adjust the schedule.
Workday as Profile Source
Workday as a Profile Source should also be enabled in the Workday-driven IT provisioning scenario so that Workday manages the Okta users. Workday should be listed as the highest priority Profile Source, specifically above the Active Directory (AD) instance to which it will create users.
Pre-Start Interval Details
The Pre-Start Interval is an optional field for early provisioning of Workday users. It allows you to onboard a user account into Okta before the official Worker/Employee Date (the employee’s actual start date). The interval shows how many days before a Workday user’s Worker/Employee Date Okta evaluates the user for early import. If the feature is enabled, Okta evaluates the Workday PreHire Date; If it falls within the set interval, Okta imports the user.
For example, if you set the Pre-Start Interval in Okta to 7 days, and the PreHire Date of a Workday account is set to 7 days before the Worker/Employee Date, Okta imports the account. In this same scenario, if the PreHire Date is greater than the 7 day interval configured in Okta, Okta doesn’t consider it for import until the beginning of the window defined by the Pre-Start Interval.
Note the following points:
- If the Pre-Start Interval is not zero, future-dated Workday user updates are imported ahead of time by the number of days specified. For example, a Workday provisioning group membership change scheduled with an effective date 2 days in the future will be reflected in Okta immediately on the next import if the Pre-Start Interval value is set to 3.
- The Pre-Start Interval is ignored for termination date and attribute values imported via Custom Reports. If you need to set a Pre-Start Interval for new hires, but don't want other updates to happen ahead of time, create and import attributes from Custom Reports into Okta instead of using the base Workday profile attributes in Okta. You can also use Group Membership Rules based off of the Custom Report attributes for group assignment in Okta.
- You must have Profile Sourcing enabled to use the Pre-Start Interval option.
- A best practice is to configure the interval to encompass the largest amount of time likely to be required before the PreHire Date (the greatest amount of time needed for onboarding).
- The interval doesn’t define when a user will be imported; it specifies when they’re eligible to be imported if they have a PreHire Date.
Manage Workday Provisioning Groups
With Workday Provisioning Groups you can import workers into Okta in an organized way. Like Active Directory Security Groups, imported Workday Provisioning Groups can be seen under the People > Group tab. These groups can be used like any other Okta group: for app assignments, multifactor authentication (MFA) policy assignments, etc. The groups can also be used to drive provisioning into Active Directory and other applications. Provisioning groups must be created manually inside Workday. After you create them, the groups and associated memberships become part of the import into Okta.
- Grant Provisioning Group Admin privileges to a Workday Administrator
- Assign Workday Workers to Provisioning Groups
- Provision Users to Active Directory via Provisioning Groups
- Change Provisioning Groups
Grant Provisioning Group Admin privileges to a Workday Administrator
Before a Workday admin can manage Provisioning Groups, you ensure they have the correct privileges. If you typed provisioning groups in the Search bar and don’t see the option to Create Provisioning Groups, Delete Provisioning Groups, or Edit Provisioning Groups, this indicates that the admin doesn’t have the required privileges.
To add Provisioning Group access, follow these steps:
- Type domain security in the Search bar and select Domain Security Policies for Functional Area.
- Type System, then click OK.
- In the left pane, scroll down and expand the Security Administration folder. Then click Provisioning Group Administration.
- Next to Provisioning Group Administration in the right pane, click the ellipsis to reveal a drop-down menu and select Domain Security Policy.
- If the second item is Enable, the policy is currently disabled. To enable it, click Enable. There will be a confirmation box following the selection.
- If the second item is Disable, the policy is currently enabled. Move to the next step.
- Under the Report/Task Permissions list, ensure that the admin is a member of one of the Security Groups with view and modify permissions. If not, click the drop-down menu next to Domain Security Policy and select Domain Security Policy > Edit Permissions to add the right Security Group to the list. Ensure that both view and modify permissions are configured.
Assign Workday Workers to Provisioning Groups
Workday workers can be manually assigned to provisioning groups within Workday; however, provisioning groups are most effective when configured to have automated assignments based on conditional rules as defined in a business process within Workday. Because it involves modifying a business process inside Workday, a Workday HR administrator should perform this step. Contact Workday Support for more details.
Provision Users to Active Directory via Provisioning Groups
Okta can automate the creation, update, and deactivation of users from Workday to Active Directory (AD). Okta drives provisioning via Workday provisioning groups. In short, a Workday provisioning group is tied to one (or more) AD organization unit (OU) within Okta. When a user is created in Workday and assigned to a properly configured provisioning group, Okta imports that user from Workday and creates a user in AD under the corresponding OU.
Users can also be deactivated based on the time zone of their location, see Time Zone Aware Deactivation for more details.
To provision users to AD via provisioning groups:
- Sign in to Okta.
- Find the desired Workday provisioning group under People > Groups.
- Click the group.
- Click Manage Directories.
- Select the AD domains to associate with the Workday provisioning group.
- Select the AD OU within which you wish to provision accounts.
- Click Done.
- In the Okta AD Settings tab, enable Provision new Active Directory accounts from Okta.
Change Provisioning Groups
Adding an existing Worker to a different provisioning group in Workday results in a membership change in the associated group in Okta. However, the OU location of the associated AD user does not change. This is because Okta only adds AD users to a particular OU during AD user creation, updates do not apply.
Group Addition: Newly created Workday groups are synchronized into Okta only in the following scenarios:
- Full Import: This brings in any new Workday Provisioning groups and creates them in Okta.
- Incremental Import: This brings in any new Workday Provisioning groups and creates them in Okta
- RTS: The creation of a Workday Provisioning group alone doesn’t trigger an RTS event to create the group in Okta. However, after the Workday Provisioning groups have been created in Workday, any other RTS event that is triggered will also include the group information and create the new groups in Okta.
Group Removal: Groups deleted from Workday are removed from Okta only during a full import:
- Full Import: This removes any group from Okta that is linked to a Workday group that no longer exists.
- Incremental imports and RTS do NOT remove deleted Workday groups from Okta.
Group Name Changes: The following behaviors occur in Okta when a group name is changed from within Workday.
- Any RTS event that is triggered picks up the Workday group name change, and writes this new group name into Okta as a new and separate group within Okta.
- With RTS, if any user who is a member of the group is updated, that user is removed from the original group in Okta (with the old name), and added to the newly created Okta group (with the new name). If that user was getting application assignments from the original group (with the old name), they will lose them.
- With RTS, any new user who is added to the Workday Provisioning group (with the new name), causes the group (with the new name) to be written to Okta, however this new user will not be assigned to an application or removed from one, since the group (with the new name) in Okta has never had an application associated.
- If an incremental import runs, the results are the same as the RTS scenarios above. The group (with the old name) is not removed, however users who have been updated since last import are moved from the group (with the old name) to group (with the new name), resulting in application un-assignment or de-provisioning.
- If a full import runs, the group (with the old name) is removed, causing everyone in it to be un-assigned or de-provisioned from any associated apps accordingly. The group (with the new name) will be imported, and associated users will all be added to the group (with the new name) and no apps associated.
If you have to rename a group in Workday, create a new group instead.
Currently Workday Group name changes can result in unwanted behavior downstream in Okta. To work around this issue the best course of action is to create a new group with the desired name in Workday, and assign all of the users to it. Wait for an import and/or RTS job to create the new group in Okta.
Once the newly created group is brought into Okta, set it up exactly the same as the group you wished to rename. When all user memberships, group rules, and/or application assignments are the same between the new group with the desired name and the old group, you can remove the original group from Workday and update Okta by running a full import to remove the old group from Okta.
Since all users, rules, and application assignments have been duplicated to the new group, no one should lose access to any applications or assignments.
Map Attributes from Workday to an Okta User Profile
As shown in the Universal Directory (UD) Profile Editor, the base profile that Okta imports from Workday consists of 20 attributes. Some of the attribute mappings from the Workday user to the Okta user exist by default, but others need to be created manually. The table below contains the recommended mappings for typical use cases.
When Workday is configured to write to AD (and UD is enabled), the Okta admin must manually map some attributes between the Workday app user profile and the Okta user profile and the Okta user profile and the AD user profile. This allows attributes to flow from Workday to Okta and then to AD.
Map attributes to an AD user profile
Workday as a Source typically involves creating AD users. Some of the attribute mappings from Okta user to AD user exist by default, but others need to be created manually. The table below contains the recommended mappings for typical use cases.
|hasWorkdayUser() ? (findWorkdayUser().managerUserName + "@" + target_app.namingContext) : null||managerUpn|
|hasWorkdayUser() ? findWorkdayUser().employeeID : user.employeeNumber||employeeID|
|hasWorkdayUser() ? findWorkdayUser().supervisoryOrg : user.department||department|
|hasWorkdayUser() ? findWorkdayUser().businessTitle : user.title||title|
hasWorkdayUser() ? findWorkdayUser().businessUnit : user.costCenter
hasWorkdayUser() ? findWorkdayUser().location : null
hasWorkdayUser() ? findWorkdayUser().employeeID : user.employeeNumber
UD supports the use of custom expressions in profile mappings to transform attributes. As shown in the table above, custom expressions are used to populate the SAM Account Name and Manager (UPN).
The Manager (UPN) attribute is important for linking managers in AD. This is the full custom expression for Manager (UPN):hasWorkdayUser()?(findWorkdayUser().managerUserName + "@" + target_app.namingContext):null
The custom expression triggers this action: If the Workday profile exists for this Okta user, then find the managerUserName attribute of the Workday profile that was imported into Okta and append @[AD domain] to populate the Manager (UPN) attribute.
Okta uses the Manager (UPN) attribute to find the Active Directory user in AD that is this Okta user’s manager, and links the two AD users together. This custom expression can be modified to construct the Manager (UPN) attribute differently to suit special AD environments.
Two other situations can result in additional custom expressions appearing in the Provision to AD profile mappings. The first is when UD is turned on for a pre-existing Workday as a Source deployment. The second is when the Workday integration is added to Okta first, before AD is added. In both cases, the Workday attributes of Business Title, Location, Supervisory Organization, Business Unit, and Employee ID are mapped directly to their corresponding AD attributes directly via custom expression.
Workday custom attributes
Custom attributes can be imported by utilizing the Field Overrides functionality, described below.
Functionality to import attributes via a separate custom report endpoint has been deprecated. Existing custom report configurations will work, but new app instances will not have these configuration options.
Workday field overrides
Field Overrides are an alternate way to pull custom attribute information from Workday that replaces the existing custom report facility.
Custom attributes are currently imported via a separate custom report endpoint as described in Custom attributes imported with a custom report, above. This adds to the complexity of imports since the connector has to deal with two separate endpoints and merge data from both in order to have a complete profile for a user. Custom reports are also discouraged by Workday, especially for large amounts of data. In response to the limitations of custom reports, Workday has introduced support into their primary API to fetch these custom attributes via Field Overrides.
Using Field Overrides simplifies the import process and improves performance.
In order to use Field Overrides, Workday administrators must create a new Field Override Integration System within Workday, add the desired custom attributes to it, and configure Okta to use this Integration System when fetching worker data. These steps are described below:
Create a Field Override Integration
- Log in to your Workday account as an adminstrator, search for Integration System in the search bar, then click Create Integration System.
- Enter the following:
- System Name: Enter a name for your System Integration.
- Comment: Optionally add a comment.
- Template: Select worker from the New using template drop-down menu.
- Press Enter.
- From the list of results, select Core Connector: Worker, then click OK:
- You are redirected to a page for your freshly created Integration System.
- Scroll down to the Custom Integration Services section, and click the + (plus) sign.
- Click Create.
- Select Create Integration Field Override Service from the list of services.
- Enter a Name for the Field Override Service, and select Worker as the Business Object:
- Add more fields to your Field Override Service by clicking the + (plus) sign. Property types are based on the property name, so if you want to have properties of different types, refer to Field Override Property Types for more information about the property types and naming conventions. Then click OK.
- Now you have created your Integration Service is created, you need to configure the field mappings. Go to Actions > Integration System > Configure Integration Field Overrides.
- Select your Integration Service from the list on the left, and configure the mappings for your fields. Type and search for a desired field. Make sure that property types are matching.
- After you have mapped all the properties, click OK, then click Done:
- Search for your Integration System in Workday, then go to Actions > Integration IDs > View IDs.
- Copy and save the value of Integration_System_ID, you will need it to setup/update provisioning settings.
Field override property types
As opposed to using a Custom Report, with Field Override, there is no way to get the attribute type from Integration System setup. This means that all custom properties are treated as strings. If you want to have a custom property be treated as another type by Okta (that is, boolean or number), you need to take an extra step and add the prefix to a property name (Step 9). This prefix will be detected by Okta and transformed to a property type and removed afterward (meaning that it won't show up in Okta's Profile Editor).
To make Okta honor types from Field Override, you will need to name the property with property type and property name divided with colon: <property_type>:<property_name>. For example: string:homePhoneNumber
Supported types are:
The table shows how the property names are transformed.
|Workday Field Override Name||Okta Property Type||Okta Transformed Property Name||Comment|
|string:my_awesome_string_property||string||my_awesome_string_property||Okta will import this property as string and will create a custom property in the Profile Editor with the name my_awesome_string_property and type string|
|boolean:boolean_property||boolean||boolean_property||Okta will import this property as boolean, and will create a custom property in the Profile Editor with the name boolean_property and type boolean|
|string_by_default||string||string_by_default||Okta will import this property as string since there's no type specified, which means it's a string by default. Okta will create a custom property in Profile Editor with the name string_by_default and type string|
|not_a_type:property_name||string||not_a_type:property_name||Okta will import this property as string since the type doesn't match any known type, which means it's a string by default. Okta will create a custom property in the Profile Editor with the name not_a_type:property_name and type string. The property prefix won't be stripped out because it's not a known type|
|integer:integer_property||integer||integer_property||Okta will import this property as integer and will create a custom property in the Profile Editor with the name integer_property and type integer|
|decimal:decimal_property||decimal||decimal_property||Okta will import this property as decimal and will create a custom property in the Profile Editor with the name decimal_property and type decimal|
|number:number_property||number||number_property||Okta will import this property as number and will create a custom property in the Profile Editor with the name number_property and type number|
Configure Workday to use field overrides in Okta
- In Okta, select Applications, search for and select your Workday app instance, then click Provisioning > Integration. You will see the new configuration property: Integration System Id.
- Click Edit and paste the ID of your Integration System you got from step 15 above, then click Save.
- Go to the Profile Editor and select your Workday application to check if the new properties from your Integration System are showing up in the list of attributes.
Custom attributes imported with a custom report
This functionality has been deprecated. Existing custom report configurations will work, but new app instances will not have these configuration options.
A custom Workday report must be created that contains a list of attributes. Okta imports these attributes, and UD maps them to the user profile and to downstream app user profiles.
Create a custom report in Workday
Signing in to Workday
- Search for create custom report, then select the resulting task.
- Complete the following fields:
- Create a report name in the Report Name field.
- Choose Advanced as the Report Type, this displays in the Web Service Enable checkbox.
- Check the Web Service Enable checkbox.
- Click OK.
- Add desired attributes to the custom report.
- If you wish to change the imported attribute’s name, modify the Column Heading Override XML Alias column.
Add the Workday ID attribute to the custom report:
Change the Column Heading Override XML Alias to Workday_ID.
Without Workday_ID, Okta will not successfully import custom attributes.
- XSD (under Simple XML heading)
- JSON (under JSON heading)
- Search for Edit Custom Report.
- Find your custom report.
- Select the Share Tab > Share with specific authorized groups and users.
- Select your integration user.
Optimize the Import Time of Custom Report
The combination of large numbers of users with large numbers of custom attributes, especially calculated fields, can result in long import times into Okta, up to several hours. It can also result in a long lag upon saving the provisioning settings, as Okta imports the custom report to validate that it is formatted correctly.
To get an idea about approximately how long it will take for the import to run without setting up the full integration in Okta, you can hit your Workday Custom Report JSON url by opening the report link in a web browser or via a tool such as Postman. You will be prompted to enter your workday admin credentials to make this work.
In the rare case that the import takes more than 2 hours to run, the Okta service will timeout the open connection. In this case, contact Okta Support and request that the connection timeout period be extended to greater than 2 hours.
Use Paginated Custom Reports (recommended)
In rare situations, setting up a paginated custom report may be helpful. Pagination means that Okta makes a per-user call to pull the custom report for a given user, instead of making a single call for all users.
If it is not possible to extend the 2-hour connection timeout limit to accommodate an import that takes longer than 2 hours, pagination makes a separate per-user call. However, the overall import time will increase significantly.
A paginated custom report can reduce the lag time after saving the provisioning settings because the validation only needs to check the custom report for one user. However, this is only useful if the settings aren't frequently changed as it increases import time.
Okta recommends using non-paginated reports in most use cases.
Create a Paginated Workday Custom Report
Not applicable if the org has less than 5000 users.
Imports from Workday with custom reports can time out with over 5000 users. The solution is to create a paginated custom report, which allows Okta to import chunks of Worker data without timing out. To use this option, follow these steps:
- Under the Filter tab, set up your filter:
- Under the Prompts tab, specify the prompt default values:
- Find the Workday ID of the Integration user (recommended) or the admin who is the owner of the report. If the report owner other than the Integration user, it must be shared with the Integration user.
- View the generated URLs by clicking Actions > Web Service > View URLs.
- In the Employee_ID_Prompt field, enter the Workday ID found in step 3.
- Obtain the newly paginated URLs by right-clicking on the link and selecting Copy URL:
- XSD (under the Simple XML heading)
- JSON (under the JSON heading)
- Generate the reports as before, adding the new URLs.
- In Okta, navigate to the Workday app, then select the Provisioning tab.
- Paste the URL from step 6a (above) into the Custom Report Simple XML XSD URL field (optional). Okta uses the XSD URL to get the custom report’s schema.
- Paste the URL from step 6b (above) into the Custom Report JSON URL field (optional). Okta uses the JSON URL to get the custom report’s data.
Do not deprovision or remove an active admin. If this happens, you'll need to regenerate the URLs by entering a new admin's Workday ID.
Okta can now import any attribute from Workday via the custom report web services endpoint. Final steps include extending the Workday app user profile, the Okta app user profile, and optionally the AD user profile with the new attributes, and mapping attributes between profiles and applying transformations, if required.
See Manage profiles
- Okta does not display Arabic characters imported from Workday correctly.
- Removing a custom attribute in Workday, then importing into Okta, does not erase the custom attribute value that was previously imported.
- If you receive the following error message during profile updates (phone device values) to Workday:
Then your Workday tenant is configured with custom Phone_Device_Type_Id values. You need to reset them to use the Workday-configured factory default values as follows:
Name Value MOBILE Mobile FAX Fax TELEPHONE Telephone PAGER Pager
Contractor to Full-Time Employee Conversion
- In order to be able to use Workday Contractor to Full-Time Employee conversion support, you must modify your Workday tenant setup to configure Universal ID for workers first. Once configured, Universal ID only applies to newly created workers of the tenant. In order to back port it to existing workers you must manually update these Workday profiles using Workday's API. Without a Universal ID, Okta will be unable to detect that a contractor has been converted to full-time. This may lead to duplicate workers in some cases.
- Mapping Universal ID from Workday to Okta is optional and is not required for this feature to work.
What is Universal ID?
On the Workday side, Contractor and Full-Time workers are two separate entities with two separate Workday IDs. Universal ID configuration allows you to link these together by setting the same secondary ID for both (Universal ID).
Why is Universal ID needed:
If your Workday Provisioning integration is configured with pre-hire interval, but Universal ID is not configured, Okta will pull in the Contractor worker, and while fetching pre-hires the future Full-Time user (pre-hire) will also be pulled in. As a result, Okta will create a duplicate entry in the Import tab. This happens because those two workers in Workday have different Workday IDs, and Okta can't detect they are the same user.
How does it work:
When Universal ID is configured in Workday, as part of the Contractor to Full-Time conversion feature, Okta detects if there are any workers coming in as pre-hires that have the same Universal ID as the currently active and existing workers. If there are such pre-hires, we filter them out while the currently existing workers with the same Universal ID are present.
When the Contractor worker is deactivated and the import from Workday is running, a Full-Time user will be the one we select, as the Contractor is no longer an option.
Upon conversion, the Okta user is deactivated and then reactivated. This is expected behavior, from Okta’s perspective, the Contractor worker is terminated and new Full-Time worker is hired.
This was implemented to support cases when a Contractor worker is terminated, but the hire date of the Full-Time user is not the same day.
For example: A Contractor was converted to Full-Time, but they wanted to take a week off before the start date as Full-Time worker. The Full-Time worker will not be imported until their actual start date.
For the conversion to work automatically, you need to enable the minimum set of configuration options on ProvisioningTo Okta tab, as follows:
User Creation & Matching:
Auto-confirm exact matches
Auto-confirm new users
Profile & Lifecycle Sourcing:
Reactivate suspended Okta users (optional, depends on your setup)
Reactivate deactivated Okta user
There might be a gap between Contractor user deactivation and Full-Time user reactivation. This is usually caused by the timezone difference between Workday’s termination/hire dates for user and the time zone that Workday tenant is operating. Currently, Okta supports only Time Zone-Aware terminations, but doesn’t consider the time zone when importing new hires.
To learn how to configure Universal ID for your Workday tenant (note that you need a Workday Community account to access these articles) see:
During imports (Scheduled, RTS, and Incremental), Okta performs a query to determine if any workers have been terminated in the last 24 hours or will be terminated within the next 24 hours. Workers that fall into this category will have the following rules applied to determine:
Immediate Deactivation Reasons: If the termination reason of the worker matches one of the configured immediate termination reasons within Okta, the worker is deactivated immediately.
- Time Zone Aware Deactivation: If the termination reasons are not matched, then the termination/last day worked date of the worker are compared to the current time. Okta relies on the timezone provided by Workday within the termination date when determining if the deactivation time has come to pass. Typically Workday returns the termination date as midnight PST. If the current time is after that date, then the worker is deactivated.
Workers with a future termination date and a matching immediate termination reason will be terminated one day early. For example, if termination Date is 2022/10/22 and current Date is 2022/10/21, and the Immediate Termination reason matches; the user will be terminated as part of the import on 2022/10/21 - one day prior to their termination date.
Workers still only terminate at midnight UTC unless Time Zone Aware Deactivation is enabled.
- See Time Zone Aware Deactivation for workaround.
Immediate Deactivation Reasons
By default, Okta waits until the end of the day to take action on a terminated Worker in Workday. Such actions might include un-assigning them from the Workday app or deactivating them. However, if the termination reasons for the Worker match those specified in Immediate Termination Reasons and the termination date is set to the current date, Okta will take action immediately after receiving the event from Workday.
Configure Immediate Deactivation Reasons
In Okta, select the Provisioning tab for the Workday app.
Enter some Immediate Termination Reasons with the required termination subcategory, as described in Workday.
You can also use Regex expressions to specify deactivation reasons.
Use the pipe (|) OR operator to list multiple deactivation reasons. The following regex defines multiple possible immediate deactivation reasons. Here all deactivated workers with any of the following termination reasons will be immediately unassigned from the Workday app and deactivated in Okta:Terminate_Employee_Voluntary_DissatisfiedPay| Terminate_Employee_Involuntary_Harassment| Terminate_EmployeeImmediateTerm_ImmediateTerm| Terminate_Employee_Voluntary_Commute
Use ^.*<TerminationReason>$ to match termination reasons that end with the specified expression. For example, adding the following to the above expression additionally matches any reasons that end with DissatisfiedPay:^.*DissatisfiedPay$
Use ^<TerminationReason>.* to match termination reasons that start with the specified expression. For example, adding the following additionally matches any reasons that begin with Terminate_Employee_Voluntary:^Terminate_Employee_Voluntary.*
Furthermore, you can use combinations of both, for example:^.*DissatisfiedPay$|^.*Involuntary_Harassment$| ^.*ImmediateTerm$|^Terminate_Employee_Voluntary.*
Be careful when creating these expressions and make sure they are strictly applied to the right workers and not anyone else.
There can be no default value for this text box.
Termination Reasons are selected in Workday under Reason and Secondary Reasons in Workday:
Termination_Subcategory_ID(s) that identify each termination reason can be found by searching for the following in Workday: Integration IDs, then selecting the Business Object: Terminationsubcategory:
The chart below illustrates various outcomes based upon termination variables:
Pre-hire interval set?
Immediate termination reason matches?
Use last day of work?
Worker will become deactivated after their termination date has come to pass
Worker will become deactivated after their last day of work has come to pass
Worker will become deactivated 1 day prior to their termination date coming to pass
Worker will become deactivated 1 day prior to their termination date coming to pass
Worker will become deactivated after their termination date has come to pass
Worker will become deactivated after their last day of work has come to pass
Worker will become deactivated after their termination date has come to pass
Worker will become deactivated after their last day of work has come to pass
Time Zone Aware Deactivation
The Workday Integration now supports Time Zone-Aware Deactivations where a worker's termination is processed based on the time zone of the worker's Location in Workday.
This feature is available for all Workday applications and can be enabled by checking Timezone aware terminations on the Provisioning tab.
Limitation: Time Zone Aware Reactivation is not currently supported.
In order for the Time Zone-Aware Deactivations feature to work successfully, you need to give additional required permissions to the integration System User or System Group listed below then activate those permissions, as described below:
Domain Security Policy Permissions.
- Follow steps a-e (part of step 7) of Grant permission to an Integration System User for the following domains:
- "Worker Data:Manage locations"
- Use Manage: Location if Worker Data:Manage locations isn't available.
Okta detects the location of the worker and processes their scheduled termination (based on either Termination Date or Last Day of Work) based on the associated time zone of that location. This worker will then be deactivated on the next scheduled import after midnight in the time zone of that worker.
If the worker has a preferred time zone in the Workday set, aside from their location, then that time zone takes precedence over their detected location's timezone. Order of precedence of determining time zone is as follows:
- Preferred time zone of the worker
- Time zone of the worker’s location
- Pacific Standard Time (PST)
For example, Cathy is based in Sydney, Australia, and that location in Workday has a time zone of GMT+10.
Cathy is scheduled to be terminated on July 4th. If the Time Zone Deactivation feature is not enabled, Cathy's termination would be processed on the next import after midnight UTC as all deactivations are fixed on the UTC time zone (GMT+0). With the Time Zone Deactivation feature enabled, Cathy will be deactivated in Okta on the next import after midnight in Sydney time (GMT+10). Effectively, Cathy will be deactivated 10 hours prior to when she would have been deactivated in the past.