2Introduction to HCM Data Loader

This chapter contains the following:

Overview of HCM Data Loader

HCM Data Loader is a powerful tool for bulk-loading and maintaining data. The data can be from any source. You can use HCM Data Loader for data migration, ongoing maintenance of HCM data, and coexistence scenarios, where core HR data is uploaded regularly. This topic introduces the main features and advantages of HCM Data Loader.

Business-Object Support

You can load business objects for most Oracle Fusion Human Capital Management (HCM) products. These products include Oracle Fusion Absence Management, Compensation, Global Human Resources, Global Payroll, Performance Management, Profile Management, Talent Review and Succession Management, and Workforce Management. You can also update business objects using HCM Data Loader, regardless of how they were created.

Ease of Use

HCM Data Loader has a comprehensive user interface for loading data, monitoring progress, and reviewing any errors. It provides real-time information for all stages of its processing. HCM Data Loader's user interface also includes detailed information about the component hierarchies and attributes of supported business objects.

You can load data from either delimited data (.dat) files or spreadsheets. You can load most supported business objects using either method. You can generate business-object templates to use as the basis of your own .dat files. For a selected business-object component, the template includes every attribute, including those for configured flexfields. When using spreadsheets, you define spreadsheet templates to suit business needs and generate spreadsheets from those templates.

Performance

HCM Data Loader supports multithreaded processing, which enables you to upload complete data extracts without severe performance impacts. References among objects that are processed on separate threads are managed automatically. You can set HCM Data Loader configuration parameters to optimize processing for your environment.

You can also perform partial or incremental loads to update existing objects, thereby minimizing the related processing.

Supported Key Types

HCM Data Loader supports all of the following key types for most business objects:

  • Oracle Fusion GUID

  • Oracle Fusion surrogate ID

  • Source key

  • User key

As user keys and source keys are supported, knowledge of Oracle Fusion internal IDs isn't required.

Business-Object Features

HCM Data Loader supports most business-object features and requirements. For example, you can upload:

  • Current and historical records for date-effective objects. You determine the amount of history to load.

  • End-dated, terminated, or inactive records.

  • Translated attributes in multiple languages. You specify the character set of the data file on the File Character Set configuration parameter for HCM Data Loader.

  • Descriptive flexfields and extensible flexfields.

  • Hierarchical tree data, such as organization and department trees.

  • Attachments and pictures.

  • Data from multiple sources. You can include source-system references in uploaded data.

Automation

You can initiate HCM Data Loader using a web-service call, which enables you to automate data upload.

You can implement Oracle HCM Cloud in either full or coexistence mode. In a coexistence implementation, you use Oracle Fusion Talent Management or Oracle Fusion Compensation, but continue to use your existing HR applications. For both full and coexistence implementations, you implement Oracle HCM Cloud by performing the tasks that appear in your implementation project or for selected functional areas. This topic describes how HCM Data Loader supports these implementation types.

Full Implementations

If you're performing a full implementation of Oracle HCM Cloud, then you can use HCM Data Loader to bulk-load any existing HCM data at appropriate stages in the implementation. Typically, you load each type of data once only for this type of implementation. Following successful upload, you manage your data in Oracle HCM Cloud.

Coexistence Implementations

In a coexistence implementation, you use Oracle Fusion Talent Management or Oracle Fusion Compensation, but maintain your existing HR applications. For this type of implementation, you:

  • Move talent data permanently to Oracle HCM Cloud, which becomes the application of record for talent data.

  • Upload other types of data, such as person records, periodically to Oracle HCM Cloud. The source system remains the application of record for this data.

To implement an HCM coexistence scenario, for any source system, you can use HCM Data Loader for data upload. Follow the general instructions provided for HCM Data Loader. Oracle doesn't supply tools to extract data from your source systems. Work with your implementation partner or develop your own process for extracting the source data.

HCM Data Loader provides a Compensation Changes extract. You can extract assignment, bonus, and salary changes for a specified compensation run if you're using Oracle Fusion Compensation in a coexistence scenario.

How Data Is Loaded Using HCM Data Loader

This topic outlines the process of loading data in bulk from .dat files using HCM Data Loader. The data can be from any source.

This figure provides a high-level summary of the process.

This figure shows the flow from the user to the
Oracle WebCenter Content server, and from there to HCM Data Loader.
It shows that errors detected in the import stage are reported to
the user, who can correct them and upload another file. Objects that
get through the import stage successfully are loaded to the application
tables. Errors detected in the load stage are also reported to the
user, who can correct them and upload another file.

The steps of this process are:

  1. You place a .zip file containing your .dat files on the Oracle WebCenter Content server.

  2. You submit a request to HCM Data Loader to import and load the .zip file. For this step, you can use either the HCM Data Loader interface or the HcmCommonDataLoader web service.

  3. HCM Data Loader decompresses the .zip file and imports individual data lines to its stage tables. In the stage tables, related data lines are grouped to form business objects.

    Any errors that occur during the import phase are reported on the HCM Data Loader interface.

  4. HCM Data Loader calls the relevant logical object interface method (delivered in product services) to load valid objects to the application tables.

    Any errors that occur during the load phase are reported in the HCM Data Loader interface.

  5. You review any errors from the import and load phases. You can perform this step either on the HCM Data Loader interface or using the HCM Data Loader Data Set Summary extract.

  6. You correct errors from the import and load phases in your source data.

  7. You load a new .zip file containing the corrected data to the WebCenter Content server.

You repeat this process from step 2 until all of the data is successfully loaded.

Tip: You can also correct load errors interactively on the HCM Data Loader interface and resubmit any corrected data from there.

How You Enable Access to HCM Data Loader

You can perform the following tasks in the Data Exchange work area using the predefined job roles Human Resource Specialist and Human Capital Management Integration Specialist:

  • Recent File Loads

  • View Business Objects

  • Import and Load Data

  • Delete Stage Table Data

This topic explains how to give other roles access to these tasks. You must have the IT Security Manager job role or privileges.

Access to the Recent Files Load Task

On the Recent File Loads task, you can review recently submitted file-based data sets and monitor the status of the staging tables. To enable this access, you edit the custom roles to add the following Function Security Privileges:

Function Security Privilege Name Function Security Privilege Code

Load Data Using HCM Data Loader

HRC_IMPORT_AND_LOAD_HCM_DATA

In addition, if the Manage Data Exchange Work Area (HRC_MANAGE_DATA_EXCHANGE_PRIV) function security privilege isn't already granted to the role, then you must grant it.

Access to the View Business Objects Task

On the View Business Objects task, you can review the supported business objects, their hierarchical shape and details of their supported attributes. To enable this access, you edit the custom roles to add the following Function Security Privileges:

Function Security Privilege Name Function Security Privilege Code

Review HCM Data Loader Business Objects

HRC_REVIEW_HDL_BUSINESS_OBJECTS

Generate HCM Data Loader Templates

HRC_GENERATE_HDL_TEMPLATES

In addition, if the Manage Data Exchange Work Area (HRC_MANAGE_DATA_EXCHANGE_PRIV) function security privilege isn't already granted to the role, then you must grant it.

Access to the Import and Load Data Task

On the Import and Load Data task, you can submit files to import into the HCM Data Loader staging tables and load into the Oracle HCM Cloud. You can review progress, monitor record counts, and messages raised. Additionally you can review the values of the attributes supplied in a file. To enable this access, you edit the custom roles to add the following Function Security Privileges:

Function Security Privilege Name Function Security Privilege Code

Import and Load HCM Data

HRC_IMPORT_AND_LOAD_HCM_DATA

Transfer HCM file from UCM and import into stage

HRC_TRANSFER_HCM_FILE_AND_IMPORT

Load HCM Data

HRC_LOAD_HCM_DATA

Review Attribute Values of HCM Business Objects in Stage Tables

HRC_REVIEW_ATTRIBUTE_VALUES_OF_HCM_BUS_OBJS_IN_STAGE

In addition, if the Manage Data Exchange Work Area (HRC_MANAGE_DATA_EXCHANGE_PRIV) function security privilege isn't already granted to the role, then you must grant it.

Access to the Import and Load Data Task

On the Import and Load Data task, you can submit files to import, into the HCM Data Loader staging tables and load into the Oracle HCM Cloud. You can review progress, monitor record counts and messages raised. Additionally you can review the values of the attributes supplied in a file. To enable this access, you edit the custom roles to add the following Function Security Privileges:

Function Security Privilege Name Function Security Privilege Code

Import and Load HCM Data

HRC_IMPORT_AND_LOAD_HCM_DATA

Transfer HCM file from UCM and import into stage

HRC_TRANSFER_HCM_FILE_AND_IMPORT

Load HCM Data

HRC_LOAD_HCM_DATA

Review Attribute Values of HCM Business Objects in Stage Tables

HRC_REVIEW_ATTRIBUTE_VALUES_OF_HCM_BUS_OBJS_IN_STAGE

In addition, if the Manage Data Exchange Work Area (HRC_MANAGE_DATA_EXCHANGE_PRIV) function security privilege isn't already granted to the role, then you must grant it.

Access to the Delete Stage Table Data Task

On the Delete Stage Table task, you initiate the deletion of data sets that are no longer required and create schedules for the regular maintenance of the staging tables. To enable this access, you edit the custom roles to add the following Function Security Privilege:

Function Security Privilege Name Function Security Privilege Code

Delete HCM Data Loader Stage Data

HRC_DELETE_HDL_STAGE_DATA

In addition, if the Manage Data Exchange Work Area (HRC_MANAGE_DATA_EXCHANGE_PRIV) function security privilege isn't already granted to the role, then you must grant it.

Note: This privilege also gives access to the Recent File Loads task.

If you want to delete protected data sets before they expire, or maintain schedules to regularly purge protected data sets, you also need the following Function Security Privilege:

Function Security Privilege Name Function Security Privilege Code

Delete HCM Data Loader Protected Data-Sets

HRC_HDL_DEL_PROTECTED_DS

Access to the Configure HCM Data Loader Task

On the Configure HCM Data Loader task, you configure the parameters that control HCM Data Loader and HCM Spreadsheet Data Loader import and load processes. This task is only available in Setup and Maintenance.

To enable access to this task, you edit the custom roles to add the following Function Security Privilege:

Function Security Privilege Name Function Security Privilege Code

Manage Configuration of HCM Data Loader

HRC_MANAGE_CONFIGURATION_HCM_DATA_LOADER

Supported Key Types

When planning to integrate data from one system to another, you must select key types to identify records uniquely. This topic introduces the key types that HCM Data Loader supports.

What Keys Identify

In HCM Data Loader, you use unique keys to identify:

  • The record that you're creating or updating.

  • The parent of the record that you're creating or updating.

    The parent record may either be in the same data file or exist already in Oracle HCM Cloud.

  • Any objects referenced by the record that you're creating or updating.

Supported Key Types

HCM Data Loader supports the following key types, which you can use for all types of object references. When more than one key value exists for an object, key references are resolved in this order:

  1. Oracle Fusion Globally Unique Identifier (GUID)

  2. Source key

  3. Oracle Fusion surrogate ID

  4. User key

If you supply multiple key values, then no cross-validation occurs. For example, if you supply both a GUID and a source key, then the GUID is used and the source key is ignored. If the source key identifies a different record from the GUID, then no error is raised.

Tip: Whenever possible, use source keys for both creating and updating business objects.

Key-Type Features

The following table summarizes the main features of the available key types. The Create and Update columns indicate whether you can use the key type when creating and updating objects.

Key Type Create Update Held on Object Type Generated Automatically

GUID

No

Yes

No

Hexadecimal

Yes

Surrogate ID

No

Yes (see note)

Yes

Numeric

Yes

Source Key

Yes

Yes

No

Alphanumeric

Conditionally (see note)

User Key

Yes

Yes (see note)

Yes

Alphanumeric

No

Note: You can use surrogate IDs when updating objects, but the IDs may not be readily available to Oracle HCM Cloud users. Default source keys are generated only if you don't supply a source key when creating an object. You can't use user keys alone when updating some objects because their values are subject to change.

Keys that aren't held on the object exist in the Integration Key Map table.

Foreign-Object References

Oracle Fusion GUIDs and surrogate IDs are generated only when the associated record is successfully created in Oracle HCM Cloud. Source keys aren't recognized in Oracle HCM Cloud until the associated record exists in Oracle HCM Cloud. Therefore, before you attempt to load data that references foreign objects, you must ensure that those foreign objects exist in Oracle HCM Cloud. For a new implementation, you're recommended to load each business object separately and ensure that it loads successfully before importing the next. If you supply all business objects in the same .zip file, then HCM Data Loader loads them in order of dependency. In this case, a reference to a foreign object fails only if the referenced object failed to load.

Source Keys

A source key is the ID that identifies a business object in its source system. Source keys are supported only for integration-enabled business objects. You can use source keys when creating or updating business objects. You're recommended to use source keys for all implementations but particularly for ongoing integrations, where data is maintained in the source system.

Source-Key Structure

A source key has the two components shown in this table.

Component Description

Source-system owner

Identifies where the data originated.

Source-system ID

ID used in the source system. The ID must be unique for the business-object component and source-system owner.

Having a source-system owner component to the key enables you to upload data from multiple source systems for the same business objects. For example, you may have person data in both US and UK databases to combine in one Oracle HCM Cloud system. The source-system ID doesn't have to be unique across both source systems. It must be unique only for the business-object component and source-system owner.

If you don't have an obvious source-system ID for a record, then you can generate or derive one. For example, you could derive a source-system ID for a person address by concatenating the person number with the address type.

Source keys aren't held against the created record. They exist in the Integration Key Map table.

Source Keys for Date-Effective Business Objects

If you're supplying date-effective history for an object, then you must supply the source system IDs for every date-effective record in the file. The values must be the same for each line of the date-effective history.

Default Source Keys

If you provide no source key when creating an object, then the source key is created automatically. The default source-system owner is FUSION and the default source-system ID is the surrogate ID. You can update the source key later using the Source Key business object. In the Source Key business object, you supply the new source key and a reference to the object that you're updating.

Source-System Owner Values

The source-system owner value is validated against the HRC_SOURCE_SYSTEM_OWNER lookup type. You must add your source-system names to this lookup type before loading data using source-system references. Use the Manage Common Lookups task in the Setup and Maintenance work area to update HRC_SOURCE_SYSTEM_OWNER.

User Keys

Most Oracle HCM Cloud business objects, regardless of whether they're enabled for integration, have one or more attributes that make up a user key. The user key, which is also known as a natural key, is always visible on the user interface.

For example:

  • The user key for an organization is the organization name.

  • The user key for an area of responsibility is the responsibility name plus the person number.

When to Use User Keys

User keys are part of the business object definition. They're always required when you create a logical object, regardless of how you create it.

You can also use user keys when updating logical objects. However, the value of a user key can change, and some user-key attributes are translatable. For this reason, you can't update some business objects if you supply only user keys to reference them. Therefore, whenever possible, you're recommended to use source keys when updating objects.

User keys are recommended when:

  • You're referencing or maintaining an object that wasn't created with a source key.

  • The source-key value is unknown.

User Keys for Child Objects

When a business object is bound by another, the user key must include the user key for its parent. For example:

  • Jobs are always part of a set. Therefore, job code alone doesn't uniquely identify a job. Instead, the set code must be part of the user key for a job.

  • Job grades apply to a specific job. Therefore, the user key for a job grade must include both the user key for the grade and the user key for the parent job. Therefore, the user key for the job grade is made up of the grade code, job code, and set code.

Oracle Fusion GUIDs and Surrogate IDs

Oracle Fusion Globally Unique Identifiers (GUIDs) and surrogate IDs are two of the four types of keys that HCM Data Loader supports. This topic describes when you can use GUIDs and surrogate IDs to identify business objects uniquely.

Oracle Fusion GUIDs

When you create an integration-enabled business object in Oracle HCM Cloud, a GUID is generated for the object automatically. As the GUID is generated when you create the business object, it's suitable only for identifying business objects that already exist. You can't supply a GUID when creating a business object. The GUID, a hexadecimal value, isn't held on the created object but exists in the Integration Key Map table.

GUIDs are useful when you share changes with down-stream applications, such as third-party payroll providers. You extract the changes for the third-party payroll and provide the GUID as the unique key to the worker. When reporting any updates back to Oracle HCM Cloud, you can use GUIDs to identify the records to update.

Oracle Fusion Surrogate IDs

The surrogate ID, a numeric value, is the internal system identifier that's generated when you create a business object. All objects, including those that aren't integration-enabled, have surrogate IDs. The surrogate ID is held on the object. The ID is also used in the Integration Key Map table to provide a mapping for GUID and source-key values. As the surrogate ID isn't generated until the object is created, you can't use this value when creating objects. Access to surrogate IDs may also be limited. On-premises customers are more likely to have access to surrogate IDs than Oracle HCM Cloud customers.

Business-Object Structure

Each Oracle HCM Cloud business object is a hierarchy of business-object components. At the top of the hierarchy is the parent component, and beneath it may be child and grandchild components. Each business-object component has multiple attributes.

This figure shows a generic business-object structure.

This figure shows a typical Oracle HCM Cloud business
object structure. It shows that the parent component has its own attributes
and also inherits multiple child components. Each child component
has its own attributes.

For example, the Rating Model business object includes Rating Model, Rating Level, and Rating Category components. The Rating Model component is the parent of the other two components. Each component has attributes such as RatingName, RatingModelCode, RatingLevelCode, and so on.

The most complex business object supported by HCM Data Loader is the Worker object, where five levels exist in the object hierarchy. These range from the Worker component at the top to Assignment Work Measure, Assignment Manager, Assignment Grade Steps, and Assignment Extra Information at the bottom. By contrast, the Person Type object has only the Person Type component.

Terminology

This table defines the terms used by HCM Data Loader to refer to business objects.

Term Meaning

Object or business object

Refers to the complete object, which is the parent component and all child components. For example, Grade and Worker are business objects.

Component or business-object component

Refers to components of a business object. For example, Person Name and Work Relationship are components of the Worker object.

Logical object

Refers to a group of related components that form one occurrence of a business object. For example, the grade IC1 is a logical object.

Loading Logical Objects

When you deliver multiple components for the same business object together, HCM Data Loader groups them and loads the complete logical object. It doesn't process the components separately. If any component of the logical object fails validation, then the whole logical object is rejected. As HCM Data Loader loads only complete logical objects, you can be sure of exactly which data has been loaded. For example, when loading jobs, you know which jobs loaded successfully and which jobs failed to load.

Integration-Enabled Objects

HCM Data Loader can load any integration-enabled business object. An integration-enabled business object supports these four key types:

  • Oracle Fusion GUID

  • Oracle Fusion surrogate ID

  • Source key

  • User key

An integration-enabled object has an entry in the Integration Key Map table, where its GUIDs and source keys exist.

HCM Data Loader can also load a few objects, such as Department Tree, that aren't integration enabled. Typically, Oracle HCM Cloud doesn't own such objects and they support neither source keys nor GUIDs.

Tip: You can review business-object details on the View Business Objects page. The Integration Keys Supported field on the Component Details tab for a selected component indicates whether the component is integration enabled.

FAQs for Introduction to HCM Data Loader

Why can't I access HCM Data Loader?

You may not have the correct permissions. You must have the Human Capital Management Integration Specialist job role or privileges to access HCM Data Loader.