Loading workers and users into Fusion HCM Cloud

Loading users and workers is a fundamental set of tasks for implementing Fusion cloud applications. There are multiple APIs and tools to achieve it, each that addresses either parts of or all of these tasks.  For an integrator, it is important to understand the differences between these APIs/tools and between the objects in HCM cloud that represent users and workers. This blog provides the essentials from integration perspective.

People in HCM cloud – A closer look

As shown in the graphic, there are several representations of people in HCM cloud.  The key representations of people are persons, workers and users.  There are other types that fall into one of these three. Let's take a quick look at each type.

Person

Persons are unique across legal entities, persistent between rehires. One unique person number is assigned for each person. All Workers, non-workers and contacts have a single unique person record. Person record cannot be deleted, even for contacts.  Person record can only be created:

• For a current, past or future work relationship with a legal employer

• A contact relationship with a person meeting above criteria

A person record is never terminated. It continues exist through work relationships of the person

Worker

A worker is a person who has a work relationship with a legal employer within the enterprise.  Workers can be added from HCM application page or, by using HDL or REST API.  Here are some fundamentals about loading workers:

• Worker, Person Legislative Data, Person Name, Work Relationship, Employment Terms, Assignment WorkerType are required elements to load a worker.

  • E-Employee – A person with work relationship and eligible for salary & benefits

  • P-Pending Employee or a contingent worker placement and for whom you create a person record that is effective before the hire or start date. “ReadyToConvert” and "ProjectedStartDate” values to enable automatic conversion. 

  • C-Contingent worker – contingent worker describes a provisional worker who works for an organization on a non-permanent

  • N-Non-worker

• Workers are specific to legal employer. Worker numbers are optional and can be based on global sequence or sequence specific to legal employer. One worker number is assigned per work relationship. If a global sequence is used, the worker number can be retained upon rehiring

Users

Users can log into fusion applications. Users may or may not be  associated with a person at the time of creation. Users can be created automatically upon creating Employees by hiring employee or contingent worker using HCM application page, HDL or REST API.  The "Create User web page" is intended primarily for non-HCM fusion application customers. It creates a basic person record along with user. This is available only If automatic creation of accounts is disabled.

Users can also be created in Security console, through SCIM REST API or by synchronizing with 3rd party identity provider such as Active Directory. These are standalone user accounts that need to be linked to a person without associated user account.  These users can be linked to workers using attributes in Worker.dat file. Note that HDL User.dat file can only be used create users for existing persons or to modify existing users, not for linking existing person and user.

The LDAP Sync job synchronizes new users and user changes with OIM LDAP. This job can be run on one-off basis or scheduled  using “Run User and Roles Synchronization Process” task under setup and maintenance page of fusion cloud application.

Here is a summary of types of objects.

APIs and tools

HCM Data loader (HDL) and HCM REST API can be used to load workers and generate users. Fusion SCIM REST API can be used to create and manage users. A combination of these can also be used to integrate. 

HCM Data Loader (HDL)

HDL is the recommended tool to import historic data, including Workers, into HCM Cloud. HDL supports multiple threads, which enables upload of large volume of data without severe performance impact. HDL provides a comprehensive user interface for initiating data upload, monitoring progress, and reviewing errors, with real-time information provided for both the import and load stages of its processing. It supports current and historic data through date-effective objects and supports user-key references for integration-enabled objects.  HDL integrates WebCenter services provides single, secure storage for uploaded files.  Here are some key points to note while using HDL:

• HDL provides .dat template files for all supported business objects. There is  Data validator tool to verify data files prior to submitting them to HDL. 

• HDL behavior can be modified from “Configure HCM Data Loader” task page to change batch size, number of threads , staging table limits, §File definition characters and scheduling.

• Some behavior can also be controlled through flags in a HDL data file. For example:

  • Audits for HDL can be controlled from file.

SET ENABLE_AUDIT_DATA Y

SET PURGE_AUDIT_DATA Y

• Atom feed are not generated for HDL loads by default.

SET ENABLE_INCREMENTAL_LOAD_EVENTS Y

HCM REST API

The REST API supports a large subset of capabilities of HDL, including loading workers, on a near real-time basis. REST API is preferred for web page and other synchronous integration use cases. It is still  under controlled availability at the time this blog is posted.  There are limits on the number of records retrieved or the number of workers that can be loaded at once via REST API. Refer to REST API documentation for more information.

SCIM REST API

SCIM API is part of Fusion application common features and built to meet the System for Cross-domain Identity Management specification.  Here are some supported functions:

• Get, Create, delete or update users. Enable/Disable users

• Get or update roles and assigned users roles

• Bulk operations via REST

• Get audit history

• Assign users to category

• Does not link persons to users.

SCIM API can be used to build custom extension pages to meet customer requirements manage users those aren't met by the product out-of-box.

References

Access to My Oracle Support is required to view the documents listed here.

• Best Practice For Loading Large User Data Into Fusion Application (Doc ID 2234804.1)

• HCM Data Loader User’s Guide (document ID 1664133.1).

• Data Loading and Data Extraction Best Practices (Doc ID 2043581.1)

• A Data File Validator Tool can be downloaded from My Oracle Support (Doc ID: 2022617.1)

• Fusion REST API: Support for Contingent and Pending Worker (Doc ID 2398822.1)

• Fusion Applications - Security FAQ (Doc ID 1383852.1)

• Getting started Cloud bridge for Active directory

• HCM Steps for Non-HCM customers (Doc ID 1448455.1)

• Controlled Availability to Oracle HCM Cloud REST Services/ATOM Feeds (Doc ID 2060899.1)