Oracle HCM Integration with Okta

This article explains how to connect Oracle’s HCM system to Okta as a HR Master, using Okta’s Anything as a Source API’s with Okta Workflows.

Overview

Anything-as-a-Source (XaaS) allows you to integrate any source of truth with Okta, and realize the benefits of HR-driven provisioning from any source of truth. XaaS gives customers the flexibility to define the terms of synchronisation between Okta and the source of truth.

See my previous article on Anything-as-a-Source here: Okta Workflows How-To: Anything as a Source with Pagination. This provides an introduction to the Anything-as-a-Source functionality and a step-by-step guide on how to configure the functionality within Okta. My previous article also includes a sample workflow that demonstrates how users can be synchronized from the source (Azure AD domain) to Okta via the XaaS API. The workflow sample also includes the ability to handle a large number of users with pagination of the Microsoft Graph API.

Now we are going to have a look at how we can integrate Oracle HCM with Okta via the XaaS API’s and Okta Workflows.

I have made some alteration to my previous workflow sample to account for the way the Oracle API worked. Additionally, the size of the HCM user repository that I was testing with (40k of users), uncovered some issues to do with handling large result sets. I have made some adjustments to process each batch of users in a more manageable way.

Anything-as-a-Source Constraints

There are some constraints to keep in mind when configuring and running my workflow sample. The constraints applied to the Anything-as-a-Source bulk-upload operation are:

1. You can load up to 200 KB of data in a single bulk-load (/bulk-upsert or /bulk-delete) request for an Identity Source Session. This equates to 200 user profiles. To load more user profiles, you can make multiple bulk-load requests to the same session.
2. The maximum number of bulk-load requests for a session is 50. If you exhaust the maximum number of bulk-load requests and you still need to load more user profiles, then create another Identity Source Session object for the additional user profiles.
3. Once you trigger an Import Session, you can not start a new session in less than 5 minutes. This is to allow completion of the import.

My sample workflow takes all the above into account.

For additional details, see Anything as a Source Okta documentation here: Build an Anything-as-a-Source custom client integration | Okta Developer

Oracle HCM Okta Workflow Example

You can download my Oracle HCM Workflow sample here: Oracle HCM XaaS Workflows

Let me explain the parts of the workflow example that are specific to Oracle HCM. Note that I’m not going to explain the whole workflow. For more detail, see my previous posts. Additionally I have included a number of comments in the flows that will help to describe what the parts of the flow are doing.

Configuration Values

The workflow reads and uses the static values stored in table Configuration. The benefit of defining the values in a table and reading them in at runtime is that they can easily be changed without modifying each flow. These configuration values are explained in the table below:

Name	Description
time_zone	Local Timezone as per Time Zones This is used to adjust the date and time into your local time zone.
hcm_url	HCM Instance URL. This is used to query your HCM instance.
batch_size	The total number of imports within a single transaction Id. Max 50. This defines how many batch imports are run before the transaction is completed and a new transaction starts. It may be more efficient to use smaller batch sizes. This provides the ability to define the size you want.
deactivated_days	How many days in the past should we check for user deactivations. This value depends on how often you run your flow. The value should only be a few days at most.
created_days	How many days in the past should we check for user records, based on the date the user was created. This is just used for testing. It limits the query to retrieve users that were created a certain number of days in the past. I found for a large user base, you initially may not want to include all users in the create and update query. Start with a “few” days in the past, which will only retrieve a handful of users.
page_size	The page size of each bulk upload into Okta. Max 200. This defines the number of users included in each batch upload. It may be more efficient to use an amount less than 200. This provides the ability to define the size you want.

The workflow sample also has a second table called State Table. As per its name, it holds some state information that is used dynamically at runtime. Here is a description of the values:

Name	Description
batch_running	Either true or false. When the workflow starts, this value is set to true and when complete it will be set to false. If a workflow batch is currently running, then a new flow can not start as this could cause an error, so this flag prevents that. Note that if the workflow generates an error, then this value may be left as true. You will need to manually set it back to false before running the flow again.
batch_request_no	The current count of the batch requests. This is used to manage the batch requests between each completion of the transaction.

Flow – [helper 3.0] Get Page of Results

This flow is one of the key flows and is used to retrieve a page of users. It is called by both user Create/Update and user Deactivate flows. Here is the main part of the flow where the HCM query is formatted:

If the operation equals “create”, then the query will be the following:

Note that the retrieval of all the user ‘create’ records also includes user updates.

If the operation does not equals “create” (user deactivation), then the query will be the following:

Once the query has been formatted and executed, the flow will call helper flow [helper 3.1] Process Page of Results.

Once the page of results has been processed, and if there are no more records to retrieve, then the import session will be triggered. See the screen shot below:

In the above screen shot, note the Wait For 5 minutes. You can’t create a new Identity Source Session in less than five minutes after triggering an active session associated with the same identity source. The 5 minute wait prevents that from happening. While the flow is still running, a new flow instance can not be started due to the flag in the state table. For further information on the Identity Source Session process, see the documentation here: identity Source Session Process

In the final part of the flow, the configured page size is added to the returned offset. This will be the new offset value for the next user query. The flow will then call itself to retrieve and process the next batch of users. See the screen shot below:

This process will continue until the query returns an indicator that there are no more user records to be returned.

Flow – [helper 3.1] Process Page of Results

As per its name, this flow will process a page of results returned by the Oracle HCM query. Processing includes applying any necessary filters to the data, mapping the data to the Okta format and running a batch import.

The first thing this flow does is filter the users in regard to the Termination Date on the user profile. If performing a create / update, then we do not want any users that have been terminated. These users need to be screened out of the result set.

Note: This could be rectified by including Termination Date in the query, so these users are not returned. This would be a better solution but at the time, I could not get this to work.

Additionally, if we are performing a user deactivation, then we don’t want any users with a Termination Date set in the future.

See the screen shot below:

Flow – [helper 3.1.4] Bulk User Import

This flow controls the importing of the users and is called for each batch upload. Once the user list has been filtered and mapped to the Okta format, the flow uses the user list in a Okta Bulk User Import card as per the screen shot below:

The remainder of this flow is the management of the import session. Once the number of bulk uploads has reached the maximum configured, then the flow will trigger the import session. Once the import session is triggered, the flow will wait 5 minutes and a new session can not be created until 5 minutes has elapsed. After 5 minutes, a new import session is created and passed back to the calling flow.

See the screen shot below:

End to End Enablement

This section details how to get the Oracle HCM Workflows sample up and running. These are the steps that we will be following:

1. Configure a Custom Identity Source app in Okta via the Administration console. This Custom Identity Source app is an additional component that is provided as part of the XaaS release.
2. Import the supplied workflow example and configure the flows to retrieve users from your Oracle HCM instance and bulk-upload the users into your Okta tenant via the Anything-as-a-Source API’s.

Requirements

The Anything as a Source features need to be enabled in your Okta tenant. Once this new feature is enabled, your Okta tenant will have:

1. Access to the new Custom Identity Source app
2. Within Workflows, the Okta connector will include the additional operations to call the XaaS API
3. The Okta Administration console will include an Import Monitoring page

You can download my Oracle HCM Workflow sample here: Oracle HCM XaaS Workflows.

Step 1 – Configure Custom Identity Source App

In this step, we are going to add the Custom Identity Source app to Okta and configure the mapping from the incoming user profile to the Okta profile.

See the official Okta documentation on the Custom Identity Source application here: Use Anything-as-a-Source.

Add Application

In your Okta Administration console, go to Applications > Applications and then click on Browse App Catalog. Then search for Custom Identity Source.

Add the following application to your Okta tenant:

Configure Application

Once you have added the app to your Okta tenant, give the app a meaningful name. In my example, I have named it Oracle HCM.

Next, go to the Provisioning tab and select the Integration option on the left menu. Click Edit and check the box for Enable API Integration. In this example, we will not be importing Groups, so you can un-check the box for Import Groups. Then click Save. See the screenshot below:

Next, under the Provisioning tab, select the To Okta option on the left menu. In the section titled User Creation & Matching, click Edit and check the boxes for the following settings:

1. Auto-confirm exact matches
2. Auto-confirm new users
3. Auto-activate new users

Then click Save. If these settings are not enabled, the administrator will have to manually confirm and activate the imports. See the screenshot below:

In the section titled Profile & Lifecycle Sourcing, click Edit and check the box for Allow Custom Identity Source to source Okta users. You can also optionally check the boxes for Reactivate suspended Okta users and Reactivate deactivated Okta users. Then click Save. See the screenshot below:

Update Identity Source Profile

The default profile for the Custom Identity Source Application contains the following attributes; Username, First Name, Last Name, Email, Second Email and Mobile Phone. To support the profile coming from Oracle HCM, we need to add some additional custom attributes to the profile.

In your Okta Administration console, go to Directory > Profile Editor and select the profile for the Custom Identity Source Application added in the previous section. Then add the following custom attributes:

Display Name	Variable Name	Data Type	Attribute Type
Title	title	string	Custom
Middle Name	middleName	string	Custom
Display Name	displayName	string	Custom
City	city	string	Custom
State	state	string	Custom
Country Code	countryCode	string	Custom
Zip Code	zipCode	string	Custom
Person Number	personNumber	string	Custom
Date Of Birth	dateOfBirth	string	Custom
Legal Entity Id	legalEntityId	string	Custom
Hire Date	hireDate	string	Custom
Termination Date	terminationDate	string	Custom
Gender	gender	string	Custom
Marital Status	maritalStatus	string	Custom
Person Id	personId	string	Custom
Effective Start Date	effectiveStartDate	string	Custom
Citizenship Id	citizenshipId	string	Custom
Citizenship Status	citizenshipStatus	string	Custom
Citizenship Legislation Code	citizenshipLegislationCode	string	Custom
Military Vet Status	militaryVetStatus	string	Custom
Worker Type	workerType	string	Custom
Location Id	locationId	string	Custom
Location Name	locationName	string	Custom
Department Id	departmentId	string	Custom

Once complete, click the Mappings button to bring up the profile mappings from the Custom Identity Source App profile to the Okta profile. Ensure all the default and custom attributes are mapped from source to destination. The mapping for the first three attributes is displayed in the screenshot below:

Note: You will also need to add some of these attributes to the Okta profile before you complete the mapping.

Step 2 – Add Required Scopes to App

The additional XaaS operations that have been added to the workflow Okta connector, require some additional scopes. In your Okta Administration console, go to Applications > Applications and select the application titled Okta Workflows OAuth. Open the Okta API Scopes tab and grant consent for the following two scopes:

1. okta.identitySources.manage
2. okta.identitySources.read

In order for the Okta Connector to be able to access these additional scopes, it needs to be re-authorized. Open your workflow console and select Connections at the top of the page. Within your exiting connections, select the Okta connector. Click on the reauthorize icon on the right, and enter in your Domain, Client ID and Client Secret from the Okta Workflows OAuth app.

Step 3 – Configure the Sample Workflow

Import Sample Flows

After you have downloaded the sample flows, go to the workflows console and under Flows, create a new folder for the sample flows. Then click on the three dots at the end of the folder name and select import and select the downloaded sample. The sample contains the following flows:

1. [helper 1.0] Initialize Workflow – Loads configuration values
2. [helper 2.0] Generate New Import Session – Clears all previous import sessions and generates a new one
3. [helper 2.1] Delete Target Import Session – Deletes a import session based on passed session id
4. [helper 3.0] Get Page of Results – Gets a page of Oracle HCM Users
5. [helper 3.1.3] Profile Map to Okta Format – This flow maps the incoming Oracle HCM profile to the Okta profile
6. [helper 3.1.4] Bulk User Import – Manages the triggering of the bulk user import into Okta
7. [helper 3.1] Process Page of Results – Processes a batch of users in the form of an object list
8. [helper] 3.1.1 Filter Active Users – This flow will return a value of True if the user has not been terminated.
9. [helper] 3.1.2 Filter Deactive Users – This flow will return a value of True if the user has been terminated.
10. [helper] 3.1.3.1 Get Location Data – Call HCM to get the location data for the respective user
11. [main 1.0] Scheduled Import Active Users – This flow synchronizes new users and user profile updates with Okta via Anything as a Source API Operations
12. [main 1.0] Scheduled Import Deactivate Users – This flow synchronizes deactivated users with Okta via Anything as a Source API Operations
    

Create Connector

Next, go to the Connections page in the workflow console and select New Connection. Then select the API Connector. Create a new connection of Auth Type of None as per the image below:

Note: The instance of Oracle HCM that I tested against did not require any authentication. Its likely that you will need to add the required authentication at thism point. This can be done at the time the connector is created or it can be done at runtime.

As well as the API Connector, you will also need the Okta Connector. If you have not create an Okta Connector to the underlying Okta tenant, then complete that step at this point.

Update Flows

Now that we have create the connectors, we need to update the flows to use your local instance of the connector.

Open the following flows and update the API Connector cards to use your local API Connector:

1. helper 3.0] Get Page of Results
2. [helper] 3.1.3.1 Get Location Data

Open the following flows and update the Okta Connector cards to use your local Okta Connector:

1. [helper 2.0] Generate New Import Session
2. [helper 2.1] Delete Target Import Session
3. helper 3.0] Get Page of Results
4. [helper 3.1.4] Bulk User Import

Once you have finished updating all the cards to use your connectors, you can now activate each flow.

Import Table Data

Select the Tables tab and open the Configuration table. Then select Import on the top right of the screen and select the supplied data file configuration.csv. Once the data is imported, you should have six records. The two records that need updating are hcm_url and time_zone. The other values can be updated based on your testing of the flows.

Next, open table State Table and select Import on the top right of the screen and select the supplied data file stateTable.csv. Once the data is imported, you should have two records. Neither of these records requires updating.

Step 4 – Run the Sample Workflow

Once configured, we can now run the workflow. We are going to test the following:

1. Import a sub-set of users in the Oracle HCM instance into Okta. The amount of users will be controlled by the value set for created_days in the Configuration table. This is the number of days in the past that the workflow will look for users. For example, if set to a value of 50, the workflow will look for users that have been created in Oracle HCM up to 50 days in the past. Any users with a creation date older than that will be ignored. This control is just designed for testing so you can get the workflow working correctly before importing all of your users.
2. Update a subset of users in Oracle HCM. This will demonstrate how Anything as a Source can perform a delta and only update those users that have a profile change.
3. Deactivate a subset of users. Users deactivate in Oracle HCM will be deactivated in Okta.

Import Users

Now open the Workflow console and then open flow [main 1.0] Scheduled Import Active Users and click the Test button.

Once the flow executes and the import completes, go to Reports > Import Monitoring in the Okta Administration console. The import log should indicate how many new users were added to your Okta tenant.