Workday

Okta can import users and groups from Workday through its standard API. Three types of imports are supported:

Full imports

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

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. Okta users are created from imported Workday users, and imported Workday groups can be used to assign apps. Workday no longer manages users after they've been imported into Okta. Updates made to the user in Workday don't affect the associated Okta user.

Workday-driven IT provisioning

Okta integrates with Workday to drive IT provisioning. When a Workday user is imported into Okta, Workday continues to manage them. 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. Therefore, the instructions for configuring Workday-driven IT provisioning are also relevant to import from Workday scenarios.

With Workday-driven IT provisioning, Okta supports the following worker lifecycle events:

  • New hire

    • 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)
  • Updates

    • A Workday user's attribute is changed in Workday
    • Okta imports the attribute change
    • Okta updates the attribute in downstream apps (AD included)
  • Termination

    • A Worker is terminated in Workday
    • Okta imports the status change
    • Okta deactivates the Okta user and accounts in downstream apps (AD included)
  • Rehire

    • A terminated Worker is rehired in Workday
    • The deactivated Okta user needs to be manually reactivated in Okta
    • Okta imports and links the rehired Worker with the reactivated Okta user

Prerequisites

Before you configure provisioning in Okta, ensure that these requirements are met:

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.

  1. To create a Security Group, enter create security group in the search box.
  2. Click Create Security Group in the search results.
  3. Select Integration System Security Group (Unconstrained) from the Type of Tenanted Security Group dropdown.
  4. Enter a name for the group.
  5. 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.
  6. 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)
  7. Set the correct integrated permissions for each business domain:
    1. Enter Domain Security Configuration in the search box.
    2. Click the resulting report.
    3. Enter the business domain name in the search field, and then click OK.
    4. Select DomainEdit Security Policy Permissions from the dropdown menu beside the domain name.
    5. 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.
    6. Verify with Workday to make sure all the required permissions are configured for the security group

  8. Workday might alert you to activate the security policy changes. If you don't activate the changes, the integration user account aren't granted the necessary permissions.
  9. Activate the changes:
    1. Search for Activate Pending Security Policy Changes.
    2. Click the resulting task.
    3. Enter a comment (required), and then click OK.
    4. Verify the changes that need to be activated.

Procedures

Configure Workday provisioning

To set up the API integration, go to the OktaProvisioning 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.
  • 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:
    1. Search for public web services.
    2. Under Reports, select Public Web Services.
    3. From the Public Web Services list, select a service, open its dropdown menu and select Web ServiceView WSDL. which displays the full WSDL in a separate window.
    4. Search the WSDL page for soapbind:address to see the web services endpoint corresponding to the web service that you chose.
    5. 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 to match the Termination_Subcategory_ID for each termination reason, as identified in the Workday Integration IDs. This entry 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:

Scheduled Imports

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. The number of workers in Workday can slow the import, so don't schedule them 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 where it creates 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 isn't 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 two days in the future is reflected in Okta immediately after the next import if the Pre-Start Interval value is set to three.
  • The Pre-Start Interval is ignored for termination date and attribute values imported through 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 on the Custom Report attributes for group assignment in Okta.
  • You must have Profile Sourcing enabled to use the Pre-Start Interval option.
  • Set the interval to the time you need for onboarding.
  • The interval defines when a user is eligible to be imported ahead of their actual start date. It doesn't define when to import the user.

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 DirectoryGroups. These groups can be used like any other Okta group: for app assignments and multi­factor authentication (MFA) policy assignments. 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

Before a Workday admin can manage Provisioning Groups, ensure that they have the correct privileges. If you search for provisioning groups and don't see options to create, delete, or edit Provisioning Groups, then the admin doesn't have the required privileges.

To add Provisioning Group access, follow these steps:

  1. Enter domain security in the Search bar and select Domain Security Policies for Functional Area.
  2. Enter System, and then click OK.
  3. In the left pane, scroll down and expand the Security Administration folder. Then click Provisioning Group Administration.
  4. Next to Provisioning Group Administration in the right pane, click the ellipsis to reveal a dropdown and select Domain Security Policy.
    • If the second item is Enable, the policy is currently disabled. To enable it, click Enable and confirm your selection.
    • If the second item is Disable, the policy is currently enabled. Move to the next step.
  5. 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 dropdown menu next to Domain Security Policy, and then select Domain Security PolicyEdit 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 with Provisioning Groups

Okta can automate the creation, update, and deactivation of users from Workday to Active Directory (AD). Okta drives provisioning through 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 with provisioning groups:

  1. Sign in to Okta.
  2. Find the desired Workday provisioning group under DirectoryGroups.
  3. Click the group.
  4. Click Manage Directories.
  5. Select the AD domains to associate with the Workday provisioning group.
  6. Select the AD OU within which you wish to provision accounts.
  7. Click Done.
  8. 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.

Considerations

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 picks up the Workday group name change, and writes the new name into Okta as a new and separate group within Okta.
  • With RTS, when any user who's a member of the group is updated, they're removed from the original group in Okta and added to the newly created Okta group. If that user got application assignments from the original group (with the old name), they will lose them.
  • Any new user who is added to the Workday Provisioning group (with the new name), causes the group to be written to Okta. However, this new user won't be assigned to an application or removed from one, because 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 preceding RTS scenarios. The group (with the old name) isn't removed, but users who have been updated since the last import are moved from the group (with the old name) to group (with the new name). This results in application unassignment or deprovisioning.
  • If a full import runs, the group (with the old name) is removed, causing everyone in it to be unassigned or deprovisioned from any associated apps accordingly. The group (with the new name) is imported, and associated users are added to it. No applications are associated.

If you have to rename a group in Workday, create a new group instead.

Workday Group name changes can result in unwanted behavior downstream in Okta. To work around this issue, create a group with the desired name in Workday and assign users to it. Wait for an import or an RTS job to create the new group in Okta.

After the newly created group is brought into Okta, set it up the same as the group that you wanted to rename. When the user memberships, group rules, and application assignments are the same for both groups, you can remove the old group (with the original name) from Workday and update Okta by running a full import.

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

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.

Workday

Okta

appuser.accountType userType
appuser.businessTitle title
appuser.businessUnit department
appuser.city city
appuser.countryCode countryCode
appuser.email email
appuser.employeeID employeeNumber
appuser.firstName firstName
appuser.lastName lastName
appuser.location locale
appuser.managerId managerId
appuser.managerUserName manager
appuser.mobilePhone mobilePhone
appuser.postalCode zipCode
appuser.secondEmail secondEmail
appuser.state state
appuser.streetAddress streetAddress
appuser.supervisoryOrg organization
appuser.workPhone primaryPhone

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 following table contains the recommended mappings for typical use cases.

Okta

Active Directory

user.email email
user.firstName firstName
user.lastName lastName
hasWorkdayUser() ? (findWorkdayUser().managerUserName + "@" + target_app.namingContext) : null managerUpn
substringBefore(user.login, "@") samAccountName
user.streetAddress streetAddress
user.middleName middleName
hasWorkdayUser() ? findWorkdayUser().employeeID : user.employeeNumber employeeID
hasWorkdayUser() ? findWorkdayUser().supervisoryOrg : user.department department
user.honorificPrefix honorificPrefix

user.state

state

user.countryCode

countryCode

user.preferredLanguage

preferredLanguage

user.city

city

hasWorkdayUser() ? findWorkdayUser().businessTitle : user.title title
user.zipCode postalCode

user.division

division

user.mobilePhone

mobilePhone

hasWorkdayUser() ? findWorkdayUser().businessUnit : user.costCenter

departmentNumber

hasWorkdayUser() ? findWorkdayUser().location : null

deliveryOffice

user.primaryPhone

telephoneNumber

hasWorkdayUser() ? findWorkdayUser().employeeID : user.employeeNumber

employeeNumber

user.honorificSuffix

honorificSuffix

Custom expressions

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 through custom expressions.

Workday custom attributes

Custom attributes can be imported by using the Field Overrides functionality, which is described in the following section.

Functionality to import attributes through a separate custom report endpoint has been deprecated. Existing custom report configurations aren't affected, but new app instances won't 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 imported using a separate custom report endpoint as described in Custom attributes imported with a custom report. This adds to the complexity of imports because the connector must work with two separate endpoints and merge data from both 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 through Field Overrides.

Using Field Overrides simplifies the import process and improves performance.

Configuration

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.

To create a Field Override Integration:

  1. Log in to your Workday account as an adminstrator, search for Integration System in the search bar, and then click Create Integration System.
  2. 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.
  3. Press Enter.
  4. From the list of results, select Core Connector: Worker, then click OK:
  5. You're redirected to a page for your freshly created Integration System.
  6. Scroll down to the Custom Integration Services section, and click the + (plus) sign.
  7. Click Create.
  8. Select Create Integration Field Override Service from the list of services.
  9. Enter a Name for the Field Override Service, and select Worker as the Business Object:
  10. 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.
  11. Now you have created your Integration Service is created, you need to configure the field mappings. Go to ActionsIntegration SystemConfigure Integration Field Overrides.
  12. 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.
  13. After you have mapped all the properties, click OK, then click Done:
  14. Search for your Integration System in Workday, then go to ActionsIntegration IDsView IDs.
  15. Copy and save the value of Integration_System_ID. You need this value to set up and update your provisioning settings.

Field override property types

As opposed to using a Custom Report, with Field Override, there's 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). Okta detects this prefix, transforms it to a property type, and then removes the prefix (that is, the prefix doesn't appear in the Okta Profile Editor).

To make Okta honor types from Field Override, you need to name the property with property type and property name separated by colon as follows: <property_type>:<property_name>. For example, string:homePhoneNumber

Supported types are:

  • string
  • boolean
  • integer
  • number
  • decimal

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

  1. In Okta, select Applications, search for and select your Workday app instance, then click ProvisioningIntegration. You will see the new configuration property: Integration System Id.
  2. Click Edit and paste the ID of your Integration System you got from step 15 above, then click Save.
  3. Go to the Profile Editor and select your Workday application.

  4. Click Add Attribute. Check if the new properties from your Integration System appear in the list of attributes. If they're not listed, click Refresh Attribute List and select the attributes that you want to add. Click Save.

  5. Click Mappings in the Profile Editor and map the attributes.

Custom attributes imported with a custom report

This functionality has been deprecated. Existing custom report configurations aren't affected, but this option isn't available for new app instances.

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

  1. Sign in to Workday.
  2. Search for create custom report, then select the resulting task.
  3. 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.
  4. Add desired attributes to the custom report.
  5. If you want 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 won't successfully import custom attributes.

  6. After creating the custom report, click the ellipsis after the report name and go to Web ServiceView Urls.
  7. Get the following URLs by right-clicking the link and selecting Copy URL:
    1. XSD (under Simple XML heading)
    2. JSON (under JSON heading)
  8. Share the custom report with your integration user:
    1. Search for Edit Custom Report.
    2. Find your custom report.
    3. Select the Share TabShare with specific authorized groups and users.
    4. 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's formatted correctly.

You can estimate how long the import might take without setting up the full integration in Okta. To do so, access your Workday Custom Report JSON url by opening the report link in a web browser or using a tool such as Postman. Enter your workday admin credentials when prompted.

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:

  1. Under the Filter tab, set up your filter:
  2. workday7-1.png

  3. Under the Prompts tab, specify the prompt default values:
  4. workday_new_1.png

  5. 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.
  6. View the generated URLs by clicking ActionsWeb ServiceView URLs.
  7. In the Employee_ID_Prompt field, enter the Workday ID found in step 3.
  8. 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.

  9. Obtain the newly paginated URLs by right-clicking on the link and selecting Copy URL:
    1. XSD (under the Simple XML heading)
    2. JSON (under the JSON heading)
  10. Generate the reports as before, adding the new URLs.
  11. In Okta, navigate to the Workday app, then select the Provisioning tab.
  12. 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.
  13. 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.
  14. 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

Known limitations

  • 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:

workday_prov_1.png

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

Features

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.

Universal ID

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 isn't configured, Okta pulls in the Contractor worker and the future Full-Time user (pre-hire). As a result, Okta creates a duplicate entry in the Import tab. This happens because those two workers in Workday have different Workday IDs, and Okta can't detect that 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:

Deactivation

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.

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

  1. In Okta, select the  Provisioning tab for the Workday app.

  2. Enter some Immediate Termination Reasons with the required termination subcategory, as described in Workday.

    You can also use Regex expressions to specify deactivation reasons.

    Regex Examples:

    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.

Notes:

  • 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?

Outcome

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.

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:

  1. Preferred time zone of the worker
  2. Time zone of the worker's location
  3. 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.

Related topics

Incremental imports

Workday Real-Time Sync

Workday Email and Phone writeback

Configure Workday writeback for home and work contacts

Best practices and FAQ