Anda di halaman 1dari 71

HCM Data Loader Users Guide

Oracle Fusion Human Capital Management 11g Release 10 (11.1.10)


ORACLE WHITE PAPER

FEBRUARY 2016

Table of Contents
Introduction

HCM Data Loader Data Flow

Who Can Load Data Using HCM Data Loader?

Supported Key Types

Object References

Key Resolution Sequence

Oracle Fusion Business-Object Structure


Terminology

6
6

Zip File Structure

Dat File Structure

File Line Instruction Tags

File Discriminators

Line Structure

Line Ordering

Metadata Line Validation

10

Data Line Validation

10

Preparing the Source Data

10

Reviewing and Cleansing the Source Data

10

Defining Referenced Oracle Fusion HCM Objects

10

Reviewing Lists of Values (LOVs)

11

Preparing the Oracle Fusion Human Capital Management Environment

12

Specifying the HCM Data Loader Scope

12

Defining Your Source Owner

14

Reviewing Enterprise Settings

14

Objects in Multiple Languages

14

Review HCM Data Loader Configuration Parameters

15

Supported Business Objects

15

Reviewing Business Objects

15

Supplied Business-Object Documentation

16

Generating and Modifying Template Files

17

HCM DATA LOADER USERS GUIDE

Extracting Data into the HCM Data Loader File Format

19

Developing an Extract for Each Business Object

19

Retaining Current Values

20

Setting Not Null Attribute Values to Null

20

Lookup Validated Attributes

20

Number Attributes

20

Date and Time Attributes

20

CLOB and BLOB Attributes

20

Supplying Key Values

21

Date Effective and MCPD Components

24

Reserved Characters

29

Flexfields

29

Source-System References

33

Maintaining Existing Date-Effective Data

34

Date-Effective Maintenance Modes

35

Retaining Existing Date-Effective Records

35

Replace Future Dated Records

39

Updating the First Effective Start Date or Last Effective End Date

39

Translation Data

41

Translation-File Discriminators

42

Updating Translation Data

42

Deleting Data from Oracle Fusion

42

Importing and Loading Data

43

Using the HCM Data Loader Interface for File Submission


Monitoring Progress
Import and Load Data User Interface
Extracting Data

43
47
47
55

Status and Errors

55

Compensation Changes

55

Required Post Processes

55

Maintaining Stage Table Data

56

HCM DATA LOADER USERS GUIDE

Deleting a Single Data Set

56

Deleting Multiple Data Sets

57

Best Practices

59

File Shape

59

Data Migration

59

Ongoing Interfaces

59

Additional Help
HCM Data Loader Data Set Status Diagnostic
Glossary

HCM DATA LOADER USERS GUIDE

60
60
64

Table of Figures
Figure 1: User Key: Create Department - The User Key is the Organization Name .................................................. 3
Figure 2: Example of an HCM Data Loader Zip File ................................................................................................. 7
Figure 3: Example of the BlobFiles Folder Content .................................................................................................. 7
Figure 4: METADATA and Data Line Structure ........................................................................................................ 9
Figure 5: SET Line Structure .................................................................................................................................... 9
Figure 6: COMMENT Line Structure ......................................................................................................................... 9
Figure 7: Manage Lookups (Navigator - Setup and Maintenance) .......................................................................... 12
Figure 8: Initiate Data Load (Navigator - Data Exchange - Initiate Data Load)........................................................ 16
Figure 9: Initiate Data Load Page (Navigator - Data Exchange - Initiate Data Load) ............................................. 18
Figure 10: Generate HCM Data Loader Templates Submission Page ................................................................... 18
Figure 11: Review Template Files (Navigator - Data Exchange - Initiate Data Load - Processes) .......................... 19
Figure 12: Loading Attachments - Supplying References to Attachment Files ........................................................ 21
Figure 13: BloblFiles Folder to Deliver Attachment Files for Documents of Record ................................................ 21
Figure 14: Supplying a Source Key for the Local Record ....................................................................................... 22
Figure 15: Supplying a Source Key for a Foreign Object ........................................................................................ 22
Figure 16: Supplying the User Key for the Local Record ........................................................................................ 23
Figure 17: Supplying the User Key for a Foreign Object ......................................................................................... 23
Figure 18: Supplying the Oracle Fusion Surrogate ID for the Local Record ............................................................ 23
Figure 19: Supplying the Oracle Fusion Surrogate ID for a Foreign Object ............................................................ 24
Figure 20: Supplying the Oracle Fusion GUID for the Local Record ....................................................................... 24
Figure 21: Supplying the Oracle Fusion GUID for a Foreign Object ....................................................................... 24
Figure 22: Overwriting Reserved Characters with the SET Command ................................................................... 29
Figure 23: Descriptive Flexfield Code Format ......................................................................................................... 30
Figure 24: Descriptive Flexfield Attribute Name Format .......................................................................................... 30
Figure 25: Descriptive Flexfield METADATA Example ........................................................................................... 31
Figure 26: Extensible Flexfield METADATA Example............................................................................................. 31
Figure 27: Defining DFF Attributes in METADATA ................................................................................................. 32
Figure 28: Supplying Descriptive Flexfield Data ..................................................................................................... 32
Figure 29: Supplying Descriptive Flexfield Data for Multiple Flexfield Codes .......................................................... 32
Figure 30: Defining EFF Attributes in METADATA ................................................................................................. 33
Figure 31: Supplying Descriptive Flexfield Data ..................................................................................................... 33
Figure 32: Specifying a Source System Reference Table Name ............................................................................ 34
Figure 33: Setting the Update Mode for Future-Dated Records .............................................................................. 35
Figure 34: SET Command to Retain Existing Date-Effective Records .................................................................... 35
Figure 35: SET Command to Replace Future-Dated Changes ............................................................................... 39
Figure 36: Import and Load Data - Import Local File............................................................................................... 44
Figure 37: Select local file ...................................................................................................................................... 44
Figure 38: Submit Import and Load HCM Data File ................................................................................................ 44
Figure 39: Import and Load Data - Import File ........................................................................................................ 46
Figure 40: Available WebCenter Content Files ....................................................................................................... 46
Figure 41: Submit Load for an Individual Business Object ...................................................................................... 47
Figure 42: Submit the Load Business Object ESS job ............................................................................................ 47
Figure 43: Import and Load Data Progress Icons ................................................................................................... 48
Figure 44: Import and Load Data Counts ................................................................................................................ 48
Figure 45: Error Management File Structure........................................................................................................... 49
Figure 46: Error Management Physical Row .......................................................................................................... 49
Figure 47: Error Management Attribute Values ....................................................................................................... 50
Figure 48: Error Management Source System References .................................................................................... 50
Figure 49: Correcting Attribute Values .................................................................................................................... 51
Figure 50: Correcting the Date Value for an Attribute ............................................................................................. 52
Figure 51: Corrected Objects Count ....................................................................................................................... 52
Figure 52: Corrected Records and Attributes.......................................................................................................... 53
Figure 53: Stopping a Data Set .............................................................................................................................. 53
Figure 54: Stopping a Business Object ................................................................................................................... 54
Figure 55: Confirming Stop ..................................................................................................................................... 54
Figure 56: Deleting an Individual Data Set ............................................................................................................. 57
Figure 57: Delete Stage Table Data ....................................................................................................................... 58
Figure 58: Schedule Delete HCM Data Loader Stage Table Data .......................................................................... 58
Figure 59: Diagnostic Dashboard (Settings and Actions - Troubleshooting - Run Diagnostic Tests) ...................... 61
Figure 60: Searching for the HCM Data Loader Data-Set Status Diagnostic Test .................................................. 62

HCM DATA LOADER USERS GUIDE

Figure 61: Selecting the HCM Data Loader Data-Set Status Diagnostic Test ......................................................... 62
Figure 62: Supply or Edit Input Parameters ............................................................................................................ 62
Figure 63: Enter the Parameter Values .................................................................................................................. 63
Figure 64: Submitting the HCM Data Loader Data-Set Summary ........................................................................... 63
Figure 65: Reviewing the HCM Data Loader Data-Set Summary Test Run Status ................................................. 63

HCM DATA LOADER USERS GUIDE

Introduction
HCM Data Loader is a powerful tool for bulk-loading data from any source to Oracle Fusion Human
Capital Management (Oracle Fusion HCM).
HCM Data Loader:

Supports important business objects belonging to key Oracle Fusion HCM products, including
Oracle Fusion Global Human Resources, Compensation, Absence Management, Performance
Management, Profile Management, Global Payroll, Talent and Workforce Management.

Is available in cloud, on-premises, and on-demand environments.

Supports one-time data migration, maintenance of Oracle Fusion HCM data via upload, and
coexistence scenarios, where core HR data exists outside Oracle Fusion.

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.

Supports multithreaded processing, which enables you to upload complete system extracts without
severe performance impacts. HCM Data Loader manages references among objects that are
processed on separate threads.

Includes a delimited-file reader that can identify file contents from metadata included in the file that
you upload. This feature enables you to perform partial or incremental loads, thereby minimizing
the related processing.

Supports user keys for all objects. Knowledge of Oracle Fusion internal IDs is not required.

Enables bulk update of objects, regardless of whether they were created using HCM Data Loader.

Loads all data files from the Oracle WebCenter Content server, which provides a single point of
entry to Oracle Fusion HCM.

Can be initiated using a web service call, which enables you to automate data upload.

Is function-rich. For example, you can upload:


o

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 can specify the character set of the data
file by naming any Java supported character set on the File Character Set configuration
parameter.

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.

1 | ENTER TITLE OF DOCUMENT HERE

HCM Data Loader Data Flow


This figure summarizes the process of loading data using HCM Data Loader.

1.

You place a zip file containing your data on the WebCenter Content server.

2.

You submit a request to HCM Data Loader to import and load the zip file of data. 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, grouping
those distinct file lines into Oracle Fusion HCM business objects.

4.

It calls the relevant logical object interface method (delivered in product services) to load objects to the
Oracle Fusion application tables.

5.

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

6.

Having reviewed import and load errors in the HCM Data Loader interface or via the Data Set Summary
extract, you correct them in your source data. You load a new zip file containing the corrected data to the
WebCenter Content server.

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

2 | HCM DATA LOADER USERS GUIDE

Who Can Load Data Using HCM Data Loader?


To load data using HCM Data Loader, you must have the Human Capital Management Integration Specialist job
role.

Supported Key Types


A common problem when integrating data from one system to another is how to identify a record uniquely both when
creating it in a new system and for continuing updates.
HCM Data Loader resolves this by supporting four different key types for all types of object reference:

User Key

Oracle Fusion Surrogate ID

Source Keys

Oracle Fusion GUID (Globally Unique Identifier)

User Key
HCM business objects are published with one or more attributes defined as a user, or natural, key. The user key is
always visible on the user interface and can be used to identify a business object occurrence uniquely. For example,
the user key for organization is the organization name.

Figure 1: User Key: Create Department - The User Key is the Organization Name

This key solution is suitable for both the initial creation and later update of a logical object.
User keys are part of the business object definition and are always mandatory when creating a logical object,
regardless of how you create it.

You must take care when using user keys to reference a logical object to update. The user key value can change
over time and some user key attributes are translatable. In addition, not all records support update if only user
keys are supplied. You are recommended to use source keys wherever possible.

3 | HCM DATA LOADER USERS GUIDE

User Keys for Child Objects


When a business object is bound by another, the user key will also need to include the user key for its parent. For
example, jobs are always part of a set, so JobCode alone would not uniquely identify a job; the SetCode must be
part of the user key for Job. Job grades are for a specific job, so the user key for a job grade would include the user
key for the parent job too; for example GradeCode, JobCode, or SetCode.

The user key is recommended when referencing or maintaining an Oracle Fusion HCM record that was not created
with a source key or where the source key value is unknown.

Oracle Fusion Surrogate ID


The Oracle Fusion surrogate ID is the Oracle Fusion internal system identifier, generated by Oracle Fusion on the
initial creation of the component data in the database. As it is not generated until the data is committed to the
database, this value is not available to uniquely identify a record for creation. Oracle Fusion Cloud customers are
unlikely to have access to the Oracle Fusion surrogate ID, so its use is primarily by on-premise customers.

Source Keys
Integration-enabled business objects can be referenced by the internal ID from your source system. This key
solution is suitable for the initial creation and subsequent update of a business object occurrence. This solution
requires two values to be supplied, the SourceSystemOwner and SourceSystemId. The SourceSystemOwner
specifies the system where the data originated. The SourceSystemId specifies the ID from that source system and
must be unique for the business object component and SourceSystemOwner value.
If you do not have a genuine source system ID to reference your record uniquely, then you can generate or derive
one. For example, you could derive a source system ID for a Person Address using the person number
concatenated with the address type. If you are supplying date-effective history for a record, then the source system
IDs must be supplied for every date-effective record in the file. The values would be identical for each line of the
date-effective history.
If you supply a SourceSystemOwner, then multiple source systems can provide data for the same business objects.
For example, you have Person data on both US and UK databases and these are to be combined into one Oracle
Fusion system. If you provide the SourceSystemOwner, then the SourceSystemID does not need to be unique
across both source systems. It needs to be unique only in its originating database.
Source keys are supported only for integration-enabled business objects. Source keys are not held against the
created record, but in an Integration Key Map table.
You can supply a source key only to uniquely identify new and existing records using HCM Data Loader.
If you do not provide a source key when creating a new object it will be defaulted for you. The SourceSystemOwner
will have a value of FUSION and the SourceSystemId will use the surrogate ID value. You cannot change the
source key once a record has been created.
The SourceSystemOwner value is validated against the HRC_SOURCE_SYSTEM_OWNER lookup. You must add
your source system name to this lookup prior to loading data using source system references

4 | HCM DATA LOADER USERS GUIDE

The source key is the recommended key type to use for all implementations. If you supply a source key when you
create your data in Oracle Fusion, then you can continue to reference your Oracle Fusion data using source system
identifiers when maintaining or referencing that data.
Oracle Fusion GUID
When an integration-enabled business object is created in Oracle Fusion, an Oracle Fusion GUID (globally unique
identifier) is generated. As the GUID is generated on creation of a business object, it is suitable only for identifying
business objects that already exist. It is not available for the initial creation of a business object occurrence. The
GUID is not held against the created record, but in an Integration Key Map table. The GUID is useful for reporting
changes from downstream systems, such as a third-party payroll provider. You extract the changes for the thirdparty payroll, providing the GUID as the unique reference to the worker. If you need to report the changes back to
Oracle Fusion HCM, you can provide the GUID to identify the records to update.

Object References
In HCM Data Loader the four key types can be used to identify:

The row being changed.

The parent of the row being changed. The parent could be supplied in the same file of data to be loaded, or it
may already exist in Oracle Fusion.

Any objects referenced by the row being changed.

Note: Oracle Fusion GUIDs and Oracle Fusion surrogate IDs are not generated until the record has been
successfully created in Oracle. Source keys are not recognized in Oracle until the record using them has been
successfully created in Oracle. For these reasons, you need to be careful when referencing foreign objects to
ensure the foreign object already exists in Oracle Fusion HCM, prior to attempting to import your data into HCM
Data Loader. For a new Oracle Fusion HCM implementation, the simplest way to achieve that is to load each
business object in a separate zip file and ensure that each zip file has loaded successfully before importing the next.
If you decide to supply all business objects in the same zip file, then HCM Data Loader loads the business objects in
order of potential dependency. In this case, a foreign object reference fails only if the referenced object failed to load
due to an error.

Key Resolution Sequence


Key references are resolved in the following order:

Oracle Fusion GUID

Oracle Fusion surrogate ID

Source key

User key

5 | HCM DATA LOADER USERS GUIDE

Oracle Fusion Business-Object Structure


Many Oracle Fusion HCM business objects comprise a hierarchy of business-object components. At the top of the
hierarchy is the parent component, and beneath it are child (and, sometimes, grandchild) components. Each
business-object component is made up of multiple attributes:

For example, the rating model business-object comprises rating model, rating level, and rating category
components. The rating model component is the parent of the other two components. Each of these components is
made up of attributes such as rating model name, rating model code, rating level code, and so on.
The most complex business object supported by HCM Data Loader is the worker object, where 5 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 level 5. By contrast, the person type object
comprises only the person type component.
When different components for the same business object are delivered together, HCM Data Loader groups them
into logical objects and loads the complete logical object in its entirety. It does not process the individual
components separately. If any part of the logical object fails validation, then the whole logical object is rejected. As
only complete logical objects are loaded, you can be sure of exactly what data has been loaded. For example, the
Accountant job loaded successfully, but the Accounts Clerk job failed.

Terminology
In this Users Guide, the term object or business object always refers to the complete object (the parent component
and all child components). For example, grade and worker are business objects. The terms component or businessobject component refer to individual components of a business object. For example, person name and work
relationship are business-object components. The term 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.

6 | HCM DATA LOADER USERS GUIDE

Zip File Structure


HCM Data Loader accepts compressed zip files that have been uploaded to the WebCenter Content server. These
compressed zip files can be encrypted as a whole, but HCM Data Loader does not support the encryption of files
within the compressed zip file.
The zip file can contain one or more business object specific dat files. Each dat file corresponds to a single business
object, such as location, grade, worker, or salary. Dat files should not be placed within folders in the zip file, and
each dat file must have the name of an HCM Data Loader supported business object.
You supply dat files only for the business objects you are updating.

Figure 2: Example of an HCM Data Loader Zip File

You can define the name of the zip file, which must be in alphanumeric characters (a-z and 0-9). Both upper and
lowercase letters are acceptable.
The only folder names that can be included in the zip file are:

BlobFiles

ClobFiles

You place files to be loaded as attachments or into large objects within these folders. You must ensure that the file
names of these attachments or images are in alphanumeric characters. The data type of the attribute that is used to
load your attachment or large object data determines which folder to use. For example, the File attribute in
Documents of Record (DOR) is used for loading attachment files. It has a data type of BLOB; therefore, files to be
loaded as DOR attachments must be placed in the BlobFiles folder.

Figure 3: Example of the BlobFiles Folder Content

Dat File Structure


HCM Data Loader dat files are business object specific. All components for a business object hierarchy are provided
in the same dat file. For example, job, job valid grade, job evaluation, job extra information, and job legislative extra
information can all be provided in Job.dat.

7 | HCM DATA LOADER USERS GUIDE

This single business object file approach makes it easier to see all the data for a business object and its
components, and aids with the validation of parent references on all child components. It also simplifies the
construction of the zip file as separate directories are not required and there are fewer files to generate.

File Line Instruction Tags


Dat file flexibility is achieved with the use of instruction tags:
Tag

Line Type

Description

METADATA

Definition

Identifies the business-object component and its attributes for which values are included in the
data file.

MERGE

Data

Provides data to be added to Oracle Fusion. You use the MERGE instruction whether creating
or updating objects. Oracle Fusion identifies the appropriate action. The MERGE instruction
accepts complete or partial objects. The data supplied with the MERGE instruction is merged
into the existing Oracle Fusion data.
Note: HCM Data Loader cannot accept multiple MERGE lines for the same record in the same
dat file if that object is not date-effective. For example, you cannot create a Person Ethnicity
record and then correct it from the same file. As the object is not date-effective, you are
attempting to correct the created data, not update it. In such a situation, you can supply only the
current data. Alternatively, you can insert a record in one file and update the record in a second
file.
HCM Data Loader does not process individual file lines but groups related lines. This grouping
works for date-effective records because the file lines are processed in effective start date order.

DELETE

Data

Identifies business-object components to be purged from Oracle Fusion HCM. You cannot
delete individual date-effective records. DELETE supports only the removal of the entire record.
Note: Do not provide a DELETE instruction along with a MERGE instruction for the same
record. HCM Data Loader cannot guarantee the order in which the two instructions will be
processed, so you could either delete and create the record, or update and delete the record.
Caution: Deleted data cannot be recovered. It is recommended that you try to correct your data
rather than delete and recreate it.

SET

Control

Enables override of the default behavior for the file.

COMMENT

Comment

Adds a comment to the data file. The comment has no effect on processing.

File Discriminators
File discriminators are used to uniquely identify the business object component you wish to update. For example,
the available file discriminators for the Job business object are:
Component Name

File Discriminator

Job

Job

Job Valid Grade

JobGrade

Job Evaluation

JobEvaluation

Job Extra Information

JobExtraInfo

Job Legislative Extra Information

JobLegislative

8 | HCM DATA LOADER USERS GUIDE

Line Structure
METADATA, MERGE and DELETE line structure
The shape of each METADATA and data line will be primarily derived by the shape of the view object supporting the
business object component. METADATA, MERGE, and DELETE data lines must have the following structure:
<INSTRUCTION>|<DISCRIMINATOR>|<ATTRIBUTE 1>|<ATTRIBUTE 2>|. . .|<ATTRIBUTE N>
Figure 4: METADATA and Data Line Structure

For example:

METADATA|Job|SetCode|JobCode|JobFamilyName|JobName|EffectiveStartDate|EffectiveE
ndDate

SET line structure


SET lines have the following structure:

SET <PARAMETER> <VALUE>


Figure 5: SET Line Structure

For example:
SET FILE_DELIMITER ,

COMMENT line structure


COMMENT lines have the following structure:

COMMENT <comment>
Figure 6: COMMENT Line Structure

Line Ordering
METADATA lines define which attributes are supplied in the file for a business object component. Therefore, the
definition of a component must appear before any data for that component. You can include multiple METADATA
lines in the same business object file. However, each METADATA line must be for a different discriminator of the
owning business object hierarchy.
SET lines can override how the file is read by default; therefore, they must be supplied before any METADATA lines.
There are no other restrictions for line ordering in the file.
The order of the data lines in the file does not impact the order in which they are processed.

You should not supply DELETE and MERGE lines for the same logical object. There is no guarantee that the object
will first be deleted and then created, or updated and then deleted. Similarly, you must not provide multiple MERGE
lines for the same object. Provide only the latest data, unless the component supports date-effectivity, in which case
you can provide date-effective history for a logical object.

9 | HCM DATA LOADER USERS GUIDE

Metadata Line Validation


Each METADATA line must:

Reference a valid discriminator for the object specified by the dat file name.

Reference a unique discriminator for the object. You cannot supply multiple METADATA lines for the same
discriminator.

List only valid attributes for that discriminator. Attribute names are case sensitive.

Specify the attributes for at least one of the supported key mechanisms to uniquely reference the component
defined by the discriminator.

Data Line Validation


Each data line must:

Be preceded by the METADATA line for the same discriminator.

Contain the same number of attributes as the relevant METADATA line and in the same order.

Not include values for attributes that do not appear in the METADATA line.

Contain a unique reference for itself, using any one of the supported key types.
Each data line for a child component must include a unique reference to its parent. For example,
GradeRateValue must include a unique reference to its GradeRate: .

You can provide MERGE and DELETE instructions in the same file, but not for the same record. For example,
when loading jobs, you cannot provide MERGE and DELETE instructions for the same job.

Preparing the Source Data


This section identifies some tasks to perform before you begin mapping your data to the Oracle Fusion HCM object
model.

Reviewing and Cleansing the Source Data


Identify the business objects that you are planning to upload to Oracle Fusion HCM and their source systems.
Review this source data, and verify that it is both accurate and current. If it is not, then correct any problems before
you attempt to extract it. For example:

Ensure that a manager is identified for every worker and that the information is accurate.

For jobs and positions, ensure that correct job codes and titles exist in the source systems.

For worker history, establish the accuracy of any historical data. Understand whether all historical data must be
uploaded or just key events, such as hire, promotion, and termination.

Preparing the source data in this way will minimize the problems that can occur when you upload data to Oracle
Fusion HCM. It will also make it less likely that you copy any inaccuracies to the new environment.

Defining Referenced Oracle Fusion HCM Objects


Business objects that originate in your source environment may reference a small number of business objects that
cannot be loaded using HCM Data Loader. Some of these objects are predefined. Others need to be defined or
updated in the target Oracle Fusion HCM environment before you load data that references them.
You may have performed this step during implementation of Oracle Fusion HCM.

10 | HCM DATA LOADER USERS GUIDE

The following table identifies the main objects of this type and the Oracle Fusion HCM tasks that you use to review
or create them.
Business Object

Oracle Fusion HCM Task

Schedule

Manage Work Schedules

Official Language Code

Manage Languages

Currency Code

Manage Currencies

Business Unit

Manage Business Unit

Legal Entity

Manage Legal Entity

Content Type

Manage Profile Content Types

Profile Type

Manage Profile Types

Assignment Status Type

Manage Assignment Status

Element Type

Manage Elements

Application Reference Data Set

Manage Reference Data Sets

When referring to these objects in the objects that you are loading, you use their user keys. (Alternatively, you can
use their surrogate IDs, if available.)
HCM Data Loader provides business-object documentation for all supported objects. This documentation specifies
the user key that you can use to reference other objects. For example, the position component includes a reference
to the business unit object, which is not integration enabled. The position documentation identifies the business unit
name as its user key. Therefore, when loading a position component you can refer to the associated business unit
using the business unit name. (For more information about keys, see page 3.)

Reviewing Lists of Values (LOVs)


The permitted values of many object attributes are defined in Oracle Fusion HCM in LOVs. Some LOVs are
predefined and cannot be updated in any way. Others contain some values but you can also add your own. And in
some cases, you can edit or remove predefined values.
In Oracle Fusion HCM, LOVs are defined as lookups. You are recommended to review the predefined lookups and
make any updates before you attempt to load data that uses them. You may have completed this process during
implementation of Oracle Fusion HCM.
Relevant lookups are identified in the business-object documentation for HCM Data Loader supported objects.
To manage lookups, search for relevant tasks by entering Manage % Lookups in the Setup and Maintenance work
area. All available lookups tasks are listed. For example, to manage person lookups, select the Manage Person
Lookups task. On the Manage Person Lookups page, select a lookup to edit:

11 | HCM DATA LOADER USERS GUIDE

Figure 7: Manage Lookups (Navigator - Setup and Maintenance)

Ensuring that lookups contain appropriate values will reduce validation errors when you load data.

Preparing the Oracle Fusion Human Capital Management Environment


Specifying the HCM Data Loader Scope
HCM Data Loader cannot be used in parallel with HCM File-Based Loader or HCM Spreadsheet Data Loader for
maintaining the same business objects. The HCM Data Loader Scope parameter on the Configure HCM Data
Loader page controls whether HCM Data Loader is used for all bulk data loading or just for those objects that are
not supported by HCM File-Based Loader. The HCM Data Loader Scope parameter has two settings:
Settings

Description

Limited

Only business objects not supported by HCM File-Based Loader can be loaded using HCM Data
Loader.

Full

HCM Data Loader is used for bulk loading data into all supported business objects. HCM File Based
Loader and HCM Spreadsheet Data Loader are disabled.

For upgrading customers, the default value of this parameter is Limited. If you attempt to load data for a business
object that is not supported in the Limited mode, then your whole data set will fail to process.
For new customers in Release 10, the default value of this parameter is Full and it cannot be changed to Limited.
Upgrading customers who do not intend to use HCM File-Based Loader or HCM Spreadsheet Data Loader must set
this parameter to Full to ensure complete business object support when using HCM Data Loader.
To update the HCM Data Loader Scope parameter:
1.

Open the Configure HCM Data Loader page (Setup and Maintenance - Configure HCM Data Loader).

2.

For the HCM Data Loader Scope parameter, select Full.

12 | HCM DATA LOADER USERS GUIDE

Important: The HCM Data Loader Scope parameter cannot be set back to Limited once it has been set to Full.
Once this parameter is set to Full, HCM File-Based Loader and HCM Spreadsheet Data Loader no longer function.
Restricted Objects
The HCM Data Loader registered objects that cannot be loaded using HCM Data Loader when the HCM Data
Loader Scope parameter is set to Limited are:
Global HR

Action Reasons

Grade Translation

Organization

Action Reasons Translation

Grade Step Translation

Organization Translation

Actions

Grade Ladder

Position

Actions Translation

Grade Ladder Translation

Position Translation

Location

Step Rate Translation

Department Tree

Location Translation

Grade Rate

Department Tree Node

Job Family

Grade Rate Translation

Person Contact

Job Family Translation

Job

Person Contact Relationship

Grade

Job Translation

Worker

Global Payroll

Element Entry

Compensation

Salary Basis

Salary

Absences

Person Absence Entry

Person Entitlement Detail

Talent

Education Establishment

Rating Category Translation

Content Item Rating Description Translation

Education Establishment Translation

Rating Level Translation

Content Items Relationship

Rating Model

Content Item

Talent Profile

Rating Model Translation

Content Item Translation

Talent Profile Translation

Restricted Business Object Spreadsheets


You cannot upload the following business object spreadsheets available from the HCM Spreadsheet Data Loader
task in the Data Exchange work area when the HCM Data Loader Scope parameter is set to Full. However, you
can still use specialized data loaders such as Payroll Batch Loader, Compensation and Benefits Data Loaders,
Talent Data Loaders, and Core HR Data Loaders.
Global HR

Create Location

Create HR Job Family

Create Worker

Create Grade Ladder (Grades)

Create HR Job

Create Work Relationship and Assignment

Create Grade Ladder (Grades with


Steps)

Create Department

Update Person

Create Position

Update Assignment

Create Market Data: Survey

Create Market Data: Job Family

Create Market Data: Career Level

Create Market Data: Jobs

Create Market Data: Career Stream

Create Market Data: Other Level

Create Absence Record

Create Absence Certifications

Create Absence Types

Create Absence Reasons

Create Absence Plans

Create Absence Categories

Create Educational Establishments

Create Talent Profile Content Type

Create Template Definition

Create Talent Profile Content Item

Create Talent Profile Rating Model

Create Template Section

Create Talent Profile

Create Section Definition

Create Template Period

Create Grade
Compensation

Create Market Data: Job Function


Absences

Talent

13 | HCM DATA LOADER USERS GUIDE

Defining Your Source Owner


If you plan to use source-system IDs, then you must add your source-system owner values to the
HRC_SOURCE_SYSTEM_OWNER lookup before you load data.
To edit this lookup:
1.

In the Setup and Maintenance work area, search for the Manage Common Lookups task.

2.

In the Search Results section, click Go to Task for the Manage Common Lookups task.

3.

On the Manage Common Lookups page, search for the lookup type value
HRC_SOURCE_SYSTEM_OWNER.

4.

In the Search Results, select the lookup type to display its lookup codes.

5.

In the Lookup Codes section of the page, click New (

) to add a lookup-code row. Complete the fields

in the row. Ensure that the new code is enabled and that the start and end dates are valid for the data that
you are loading.
6.

Repeat Step 5 for additional source-system owner values.

7.

Click Save and Close.

Reviewing Enterprise Settings


When you load worker records, by default:

A user-account request is created automatically for each worker. (The request is sent to Oracle Identity
Management when you run the Send Pending LDAP Requests process, as described on page 55.) User
names are in the format specified by Oracle Identity Management.

Roles are provisioned automatically to workers, as specified by current role-provisioning rules.

Workers are notified automatically of their sign-in details.

You are recommended to review the enterprise settings that control user provisioning and make any updates before
you load worker records. For example, you may want to prevent the automatic creation of user-account requests
during initial data loads to the stage environment.
To review the enterprise user-provisioning settings:
1.

Open the Manage Enterprise HCM Information page (Navigator - Setup and Maintenance - Manage
Enterprise HCM Information).

2.

In the section User and Role Provisioning Information, review current settings and make any updates.

3.

Click Submit.

Any changes that you make to the User and Role Provisioning settings apply to the enterprise, regardless of how
person records are created.

Objects in Multiple Languages


If you are using an on-premise version of Oracle Fusion HCM, then to enable support for multiple languages you
install the appropriate language packs during setup. For example, if you want to store translatable values in both
Spanish and German, then you must install the language pack for those languages during enterprise setup. (For
more information about this, see the Oracle Fusion Applications Installation Guide.) For cloud implementations,
requested language packs may be installed before the environment is delivered. Alternatively, you can request
language packs by raising a service request (SR).

14 | HCM DATA LOADER USERS GUIDE

Review HCM Data Loader Configuration Parameters


The HCM Data Loader configuration parameters control the HCM Data Loader import and load processes. The
default settings of the parameters suit most requirements and do not need to be changed. You can review the
delivered settings by performing the task Configure HCM Data Loader (Navigator - Setup and Maintenance Configure HCM Data Loader).
The configuration parameters are:
Parameter

Default

Description

Delete Source File

Yes

Delete the source file from the WebCenter Content server when processed.

File Action

Import and
Load

Default file-processing action.

File Character Set

UTF-8

Character set for business object and attachment files. You can update this to any
Java supported character set.

File Encryption

None

Default file encryption.

Import Cache Clear Limit

2400

Number of file lines to be processed before the cache is cleared.

Import Commit size

100

Number of file lines to import between each commit.

Maximum Percentage of Import Errors

100

Percentage of file lines in error that can occur in a business object before the
import process stops for the object.

Maximum Percentage of Load Errors

100

Percentage of business-object instances in error that can occur for a business


object before the load process stops.

Data Error Stack Trace Occurrences


by Thread

Maximum number of data error message occurrences on a processing thread for


which stack trace is recorded.

Complex Error Stack Trace


Occurrences by Thread

Maximum number of complex error message occurrences on a processing thread


for which stack trace is recorded.

Load Cache Clear Limit

500

Number of business-object instances to be loaded from the stage tables before


the cache is cleared.

Maximum Concurrent Threads for


Load

Maximum number of threads to run concurrently when loading data from the stage
tables to the application tables.

Load Group size

100

Number of business objects processed as a single unit of work by a single thread.

Supported Business Objects


Reviewing Business Objects
The Initiate Data Load page provides a list of HCM Data Loader registered business objects. These are displayed in
the order in which it is recommended that you load them, if performing data migration.

15 | HCM DATA LOADER USERS GUIDE

Figure 8: Initiate Data Load (Navigator - Data Exchange - Initiate Data Load)

From this page you can generate business object templates that provide METADATA lines for all components of the
business object hierarchy. These are useful for identifying the attribute name to use for loading data. See the
Generating and Modifying Template Files section on page 17 for more information.
However, to load a business object successfully to Oracle Fusion HCM, you need to understand its Oracle Fusion
structure, supported key systems, data formats, valid values, and required values.

Supplied Business-Object Documentation


HCM Data Loader provides a spreadsheet containing all the required information for each supported business
object. These are available from the MOS document, HCM Data Loader: Business Object Documentation (Doc ID
2020600.1).
Each spreadsheet is named for its top-level business object. For example, the file Location.xls includes the
information that you need about the location business object.
For complex business objects, the spreadsheet includes one tab for each component of the object. For example, the
Location.xls spreadsheet includes Location and Location Other Address tabs. Objects that support extensible
flexfields (EFFs) also include one tab for each EFF.
General information about a component appears at the top of its tab. This information includes:

The name of the Oracle Fusion HCM product that owns the object.

The name of the data file that you load (for example, Location.dat).

The components identifier (referred to as its discriminator). For example, LocationOtherAddress.

The date type for the components, such as Simple Date, Effective Date, Multiple Changes Per Day (MCPD), or
not dated.

The level at which the component appears in its object hierarchy.

For child and grandchild components, the parent discriminator is also identified.
Following the general information about the component, these details appear for each attribute of the component:

16 | HCM DATA LOADER USERS GUIDE

Value

Description

Attribute Name

The attribute name as it appears in the data file that you load for the component.

Key Type

For attributes that are key values or can be used as key values, identifies the key type. For example, user key, GUID or
Foreign Surrogate ID.

Alternate User
Key for Surrogate
IDs

Identifies the attributes that you can use in place of surrogate IDs. For example, the LocationId is the surrogate ID
attribute for Location. To refer to the location from another business object, you can use the LocationCode and
SetCode user keys in place of the surrogate ID. The alternate user key for an attribute comprises all values that appear
in this column.

Integration Object
Name

For attributes that refer to other business objects, this column provides the name of the referenced object type. If that
object is not integration enabled, then the column contains the text not integration enabled. Integration enabled objects
can be referenced using Integration keys. Objects that are not integration enabled can only be referenced by user key
or Oracle Fusion surrogate ID.

Data Type

The data type of the attribute. For example, Number or String.

Length

The maximum attribute length.

Scale

For Number values, the number of decimal places.

Primary Key

Indicates whether the attribute is a component of the primary key. For example, for the location business object,
LocationId, EffectiveStartDate, and EffectiveEndDate are primary key values.

Mandatory

Indicates whether the attribute is required. You must include required attributes when you create or update objects.

Lookup Name

For attributes that are lists of values, provides the name of the Lookup. To see valid values for an attribute, review the
Lookup as described on page 11.

Description

Provides additional information about the attribute.

For each integration-enabled component, the following attributes appear at the end of the attribute list for each
object component:

Oracle Fusion GUID for the component. This value is generated in Oracle Fusion and is described on page 5.

Source Key attributes SystemOwnerId and SourceSystemId values. For more information, see page 4.

For all business object components, the following information attributes appear at the end of the attribute list:

Source-system reference information (the table name, and up to 10 reference values). For more information,
see section Source-System References on page 33.

The spreadsheet for each supported business object also includes an Overview tab which summarizes the hierarchy
of components for the business object.

Generating and Modifying Template Files


HCM Data Loader provides a template file for each supported business object hierarchy.
The template contains:

A COMMENT line, which identifies the business object, its version, and the file creation date.

A METADATA line for each component of the business object hierarchy that you can load for the business
object. The METADATA line includes every attribute of the component, including environment specific
configured flexfield attributes.

You can generate business object template files and use them as the basis of your own data files.
To generate business object template files, navigate to the Data Exchange work area and select the Initiate Data
Load task.

17 | HCM DATA LOADER USERS GUIDE

Figure 9: Initiate Data Load Page (Navigator - Data Exchange - Initiate Data Load)

The Initiate Data Load page lists all HCM Data Loader supported business objects. You can generate a template for
a single business object or multiple business objects.
Generating a Single Business Object Template
Select the business object and click the Generate Template button on the table toolbar. This action opens the
Generate HCM Data Loader Template File submission page. Click Submit to initiate the process that identifies the
business object shape and generates the template file. You can download the newly created template file by
clicking the download icon (

) in the File column for the business object.

Generating Multiple Business Object Templates


Click the Generate Templates button in the top right of the Initiate Data Loader page. This action opens the
Generate HCM Data Loader Templates submission page.

Figure 10: Generate HCM Data Loader Templates Submission Page

If you set the Module field to All, then templates for every supported business object will be generated.
Alternatively, select a specific module to generate business object templates for.

18 | HCM DATA LOADER USERS GUIDE

To access template files individually from the Business Objects table, click on the file download icon (

) in the File

column for the business object. Alternatively, you can download a single zip file for all the business object templates
you generated in a single process. To view all the processes submitted to generate template files, click the
Processes tab. Click the file download icon (

) for your process.

Figure 11: Review Template Files (Navigator - Data Exchange - Initiate Data Load - Processes)

Modifying METADATA Lines


Do not simply copy the METADATA lines from the template file and use them in your own data files. The template
files are to help you identify the names of all available attributes, including environment-specific attributes such as
flexfield segments. Your own data files should include only the METADATA lines for the components you want to
load and the attribute names for the values you want to supply.
HCM Data Loader validates every attribute name on every METADATA line. It also determines any potential
dependencies on other business objects in the same zip file by reviewing the attributes supplied in METADATA. For
example, if the Job.dat file contains the ValidGrade METADATA line with the GradeId attribute, HCM Data Loader
assumes that the Job.dat has a potential dependency on Grades.

You can improve the speed and efficiency of the import and load processes by declaring only the attributes that you
are supplying data for.

Extracting Data into the HCM Data Loader File Format


This section describes how HCM Data Loader expects your data to be formatted in order for it to be successfully
imported into the HCM Data Loader stage tables.

Developing an Extract for Each Business Object


You need to define mappings between your source data and the Oracle Fusion business-object model by comparing
source attributes with attributes in Oracle Fusion HCM objects. For information on Oracle Fusion HCM objects, refer
to the supplied business-object spreadsheets. You must also define the transformation logic and build extraction

19 | HCM DATA LOADER USERS GUIDE

routines. You can use tools that are native to the source system, such as PL/SQL in Oracle E-Business Suite or
SQR in Oracle PeopleSoft. Alternatively, you can use an ETL (Extract, Transform, and Load) tool, such as Oracle
Data Integrator (ODI) or PowerCenter Informatica.

Retaining Current Values


When you are updating existing Oracle Fusion data, you need to supply only the attributes that have changed, along
with a unique identifier to identify the record being updated. Any attribute values not supplied will not be updated.
However, for date-effective records all attribute values you do supply will be updated for the date-range specified.
For more information, see the section Maintaining Existing Date-Effective Data on page 34.

Setting Not Null Attribute Values to Null


If you want to set an attribute value explicitly to null, you cannot just leave the attribute value blank. Instead, you
must supply the #NULL token.

Lookup Validated Attributes


For attributes that are defined in Oracle Fusion HCM as lookups, you can specify either the lookup code or its
meaning. For example, the gender attribute of the person object can be specified using:

M (the code value) or Male (the code meaning)

F (the code value) or Female (the code meaning)

This is true for non-flexfield attributes only. For more information on lookup meaning values for lookup validated
flexfield segments, see page 33.

Number Attributes
For numbers, only the decimal separator is supported. Do not include currency symbols, scientific notation, or
thousands separators.
To set an existing numeric value to null, specify the tag #NULL as the attribute value.

Date and Time Attributes


The expected formats for date and time values are:
Date

YYYY/MM/DD

Time

YYYY/MM/DD HH24:MI:SS
For example, 2013/11/05 18:35:00

To set an existing date or time value to null, specify the tag #NULL as the attribute value.

CLOB and BLOB Attributes


The method for providing data for Character Large OBjects (CLOB) and Binary Large OBjects (BLOB) differs from
that for all other attributes. Instead of supplying the data directly, you supply the data in a separate file and reference
the filename in the CLOB or BLOB attribute.
This approach is used because data for these data types tends to be very large. Additionally, content to be loaded
directly (rather than by attachment) may need to include new line characters, making it complex to include in the
business object dat file.

20 | HCM DATA LOADER USERS GUIDE

The business object documentation specifies the data type of all attributes. To load data into a CLOB attribute, you
supply that data in a separate file and place that file in a folder named ClobFiles in the same zip file as the business
object dat file. Similarly, to load data or upload an attachment to a BLOB attribute, you supply the data or file to
attach in a folder named BlobFiles in the same zip file.
Files in the ClobFiles and BlobFiles folders can have any name and most extensions are supported.
In the business object dat file you specify the file name for the CLOB or BLOB attribute. For example:

METADATA|DocumentAttachment|DocumentType|File|PersonNumber|..
MERGE|DocumentAttachment|Drivers License|file01.txt|23901|..
MERGE|DocumentAttachment|Drivers License|file02.txt|64235|..
Figure 12: Loading Attachments - Supplying References to Attachment Files

For DocumentAttachment the File attribute has a BLOB data type. Referenced files should be placed in the
BlobFiles folder:

Figure 13: BloblFiles Folder to Deliver Attachment Files for Documents of Record

Supplying Key Values


Creating a New Record
When supplying a unique reference for a new record, only the user key and source key are supported. Both the
Oracle Fusion Surrogate ID and Oracle Fusion GUID are system generated when the record is committed to the
database.

Note: If the source key is not specified on the initial creation of a record it cannot be used later to update that record.
Updating Existing Records
HCM Data Loader does not differentiate between create and update. All records to be loaded into Oracle Fusion
are simply tagged as MERGE requests. For integration-enabled objects, all four key types can be used to reference
an existing object for update or delete. For non-integration-enabled objects, only user key and Oracle Fusion
Surrogate IDs can be used.

21 | HCM DATA LOADER USERS GUIDE

Supplying Source Key Values


The source key comprises two attributes, SourceSystemOwner and SourceSystemId. If supplying a source key to
uniquely reference the record being merged, you can also supply source key values for integration-enabled foreignobject references, including the parent record for child component records.

Note: You cannot use source keys for foreign-object references, including parents, if you are not supplying a source
key for the local record.

The SourceSystemOwner attribute is common for all source keys supplied in a record. Therefore, the foreign objects
being referenced by source key must have the same SourceSystemOwner value as the record being merged.

Before source keys can be used, the SourceSystemOwner value must be created in the
HRC_SOURCE_SYSTEM_OWNER lookup. See page 12 for additional details.

Specifying a Source Key for the Local Record


Supply values for both of the source key attributes SourceSystemId and SourceSystemOwner

METADATA|Job|SourceSystemId|SourceSystemOwner|JobCode|JobName|SetCode|Effective
StartDate|EffectiveEndDate
MERGE|Job|12349|EBS-UK|SE|Software Engineer|COMMON|2010/01/01|4712/12/31
Figure 14: Supplying a Source Key for the Local Record

Specifying a Source Key for a Foreign Object


Append the (SourceSystemId) hint to the surrogate ID attribute for the foreign object being referenced. In this
example Job, the Job must have been created using HCM Data Loader with the source key supplied.

METADATA|Assignment|SourceSystemId|SourceSystemOwner|JobId(SourceSystemId)|Effe
ctiveStartDate|EffectiveEndDate
MERGE|Assignment|234234|EBS-UK|12349|2013/01/01|4712/12/31
Figure 15: Supplying a Source Key for a Foreign Object

Source keys can be used only for integration-enabled foreign objects. The business object documentation identifies
which foreign objects are integration enabled.
If you do not specify a source key when a record is created using HCM Data Loader, then the source key will be
defaulted. The SourceSystemOwner will be FUSION and the SourceSystemId will be the Oracle Fusion surrogate
ID. You can still use source keys to reference records with default source keys, but there is no supported solution for
extracting source key information.
Supplying User Key Values
User keys are specific to the business object component being loaded. The business object documentation identifies
the user key attributes available for each business object component and all foreign objects referenced.

22 | HCM DATA LOADER USERS GUIDE

The user key attributes are mandatory when you first create a record and mandatory for updates unless you supply
a different key type to uniquely reference the record being updated.

Caution: Some user keys can change over time, which can make using the user key for historical references
challenging.
If you are loading date-effective history for a business object component where the user key does change, you must
also supply a source key. This approach allows HCM Data Loader to group related date-effective records correctly
to form the object being loaded.

Specifying a User Key for the Local Record


User keys can comprise multiple attributes, all of which must be supplied if no other key type is being used:

METADATA|Job|JobCode|JobName|SetCode|EffectiveStartDate|EffectiveEndDate
MERGE|Job|SE|Software Engineer|COMMON|2010/01/01|4712/12/31
Figure 16: Supplying the User Key for the Local Record

Specifying a User Key for a Foreign Object


In this example the Assignment is uniquely referenced by a source key. However, the Job is referenced by its user
key:

METADATA|Assignment|SourceSystemId|SourceSystemOwner|JobCode|SetCode|EffectiveS
tartDate|EffectiveEndDate
MERGE|Assignment|234234|EBS-UK|SE|COMMON|2013/01/01|4712/12/31
Figure 17: Supplying the User Key for a Foreign Object

Supplying Oracle Fusion Surrogate ID Values


Oracle Fusion Surrogate IDs are specific to the business object component being loaded. The Business Object
documentation identifies the Oracle Fusion Surrogate ID attribute for the business object component and all foreign
objects referenced.

Oracle Fusion Surrogate IDs cannot be assigned when you create data in Oracle Fusion. Oracle Fusion generates
these IDs internally at commit. Therefore, for new records either a source key or a user key must be supplied.

Specifying Oracle Fusion Surrogate ID for the Local Record

METADATA|Job|JobId|JobName|EffectiveStartDate|EffectiveEndDate
MERGE|Job|13413|Software Engineer - Java|2013/01/01|4712/12/31
Figure 18: Supplying the Oracle Fusion Surrogate ID for the Local Record

Specifying Oracle Fusion Surrogate ID for a Foreign Object


In this example the Assignment is uniquely referenced by a source key. However, the Job is referenced by its
Oracle Fusion Surrogate ID:

23 | HCM DATA LOADER USERS GUIDE

METADATA|Assignment|SourceSystemId|SourceSystemOwner|JobId|EffectiveStartDate|E
ffectiveEndDate
MERGE|Assignment|234234|EBS-UK|13413|2013/01/01|4712/12/31
Figure 19: Supplying the Oracle Fusion Surrogate ID for a Foreign Object

Supplying Oracle Fusion GUID Values


The Oracle Fusion GUID is a hexadecimal value assigned by Oracle Fusion when a record is committed to the
database.
Specifying an Oracle Fusion GUID for the Local Record
When you supply an Oracle Fusion GUID value to uniquely reference the record being merged or deleted, the
attribute name is identical for all business object components: GUID.

METADATA|Job|GUID|JobName|EffectiveStartDate|EffectiveEndDate
MERGE|Job|2342UJFHI2323|Software Engineer - Java|2013/01/01|4712/12/31
Figure 20: Supplying the Oracle Fusion GUID for the Local Record

Specifying an Oracle Fusion GUID for a Foreign Object


Append the (GUID) hint to the surrogate ID attribute for the foreign object being referenced. See this example Job:

METADATA|Assignment|SourceSystemId|SourceSystemOwner|JobId(GUID)|EffectiveStart
Date|EffectiveEndDate
MERGE|Assignment|234234|EBS-UK|2342UJHFI2323|2013/01/01|4712/12/31
Figure 21: Supplying the Oracle Fusion GUID for a Foreign Object

Oracle Fusion GUIDs can be used only for integration-enabled foreign objects. The business object documentation
identifies which foreign objects are integration enabled.

Date Effective and MCPD Components


Data-Effective Maintenance Mode
If you provide changes for a date range where date-effective or MCPD records already exist, then HCM Data Loader
provides two modes that determine how existing Oracle Fusion date-effective records are manipulated.
For more details and examples of how these modes will impact your data, see the Maintaining Existing DateEffective Data section on page 34.
Date effective records have common attributes that are normally mandatory when loading data:
EffectiveStartDate

The start date for the attribute values. This value is always mandatory for date-effective components.

EffectiveEndDate

The end date for the attribute values. If this value is left blank, then the end of time is defaulted, meaning
the date effective record will continue on with no end.

EffectiveSequence

When multiple changes per day (MCPD) can be recorded, the EffectiveSequence provides the order in
which the changes occurred.

24 | HCM DATA LOADER USERS GUIDE

EffectiveLatestChange

A Y/N flag. For MCPD records, this attribute indicates which record is the latest for the EffectiveStartDate.

Supplying Date-Effective History


You can choose how much history to load into Oracle Fusion for new objects, but the history you provide must be
complete and valid.
Retaining Existing Values
When you supply date-effective history for a record that is new to Oracle Fusion, Oracle Fusion deems only the first
date-effective record to be a new record and later-dated records to be updates. To retain the values from the
previous date-effective record, you can either leave the attribute values blank or repeat the value that is to continue.
Leaving an attribute value blank does not set the attribute to null in Oracle Fusion.
For example, loading date-effective history for a new object:

METADATA|Job|EffectiveStartDate|EffectiveEndDate|Attribute1|Attribute2|..
MERGE|Job|1950/01/01|2012/03/04|W|X|..
MERGE|Job|2012/06/02|2013/02/03||Y|..
MERGE|Job|2013/02/04|4712/12/31|Z||..

The resulting data in Oracle Fusion:


EffectiveStartDate

EffectiveEndDate

Attribute1

Attribute2

1950/01/01

2012/03/04

2012/06/02

2013/02/03

2013/02/04

Attribute 1 will retain the W value on the second row, as no value was specified. Similarly, Attribute2 will retain the Y
value on the final row.
Setting Not Null Values to Null
To change a not null value to null you must supply the #NULL token.
For example:

METADATA|Job|EffectiveStartDate|EffectiveEndDate|Attribute1|Attribute2|..
MERGE|Job|1950/01/01|2012/03/04|W|X|..
MERGE|Job|2012/06/02|2013/02/03|#NULL|Y|..
MERGE|Job|2013/02/04|4712/12/31|Z|#NULL|..
The resulting data in Oracle Fusion:
EffectiveStartDate

EffectiveEndDate

Attribute1

Attribute2

1950/01/01

2012/03/04

2012/06/02

2013/02/03

(null)

(null)

2013/02/04

25 | HCM DATA LOADER USERS GUIDE

It is advisable to use the #NULL token to ensure a null value in Oracle Fusion. Leaving an attribute with no value will
roll forward any existing value that attribute may have.
Rules for Supplying Date-Effective History
There Must Be No Gaps in the Date-Effective Records
There is no restriction on the order in which date effective records are provided in the dat file, but there must be no
break in the dates.
Example:
This example is not valid as the information between 5-Mar-2012 and 1-Jun-2012 is missing.

METADATA|Job|EffectiveStartDate|EffectiveEndDate|JobCode|..
MERGE|Job|1950/01/01|2012/03/04|ACC1|..
MERGE|Job|2012/06/02|||ACC1|..

The Unique Key Value Must Not Change Over Time


HCM Data Loader groups your distinct file lines into logical objects, a logical object being one occurrence of the
business object, such as a job or a worker. The logical object grouping is performed on the unique key for the
component, so the key value must be the same across the date-effective history. Any of the four keys types can be
used to uniquely identify the records.
Example:
This example is not valid as the SourceSystemId used to uniquely identify Job ACC1 changes with the date-effective
history.

METADATA|Job|SourceSystemId|EffectiveStartDate|EffectiveEndDate|JobCode|..
MERGE|Job|JB394_19500101|1950/01/01|2012/03/04|ACC1|..
MERGE|Job|JB394_20120305|2012/03/05|2012/06/01|ACC1|..
MERGE|Job|JB394_20120602|2012/06/12||ACC1|..

The EffectiveSequence Must Be Sequential for MCPD Records


When you report multiple changes on the same effective start date, the EffectiveSequence value must start at 1 and
increase sequentially. The same EffectiveSequence value cannot be repeated for the same logical object on the
same date, nor can there be any gaps. If there is only one change for an effective start date the EffectiveSequence
will always be 1. You cannot leave the EffectiveSequence blank when providing multiple changes per day. Without
this information there is no guarantee of the order in which records starting on the same EffectiveStartDate will be
processed.
Example:
This example is not valid as each sequence starts at zero and the sequence number 2 is missing.

METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veEndDate|..

26 | HCM DATA LOADER USERS GUIDE

MERGE|Assignment|2724|2010/06/08|0|2012/03/03|..
MERGE|Assignment|2724|2012/03/04|0|2012/03/04|..
MERGE|Assignment|2724|2012/03/04|3|2012/03/04|..
MERGE|Assignment|2724|2012/03/04|4|2012/06/01|..
MERGE|Assignment|2724|2012/06/02|1||..

The EffectiveLatestChange Must Be Y on the Latest MCPD Record


When you report multiple changes on the same effective start date, the latest record must have an
EffectiveLatestChange value of Y. All earlier records must have an N value. This attribute is always mandatory for
MCPD records.
If there is only one change for an effective start date, then the EffectiveLatestChange is always Y.
Example:
This example is not valid as the EffectiveSequence of 3 is the latest change but the EffectiveLatestChange value is
not Y.

METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veLatestChange|EffectiveEndDate|..
MERGE|Assignment|2724|2010/06/08|1|Y|2012/03/03|..
MERGE|Assignment|2724|2012/03/04|1|N|2012/03/04|..
MERGE|Assignment|2724|2012/03/04|2|N|2012/03/04|..
MERGE|Assignment|2724|2012/03/04|3|N|2012/06/01|..
MERGE|Assignment|2724|2012/06/02|1|Y||..

For MCPD Records That Are Not the Latest, the EffectiveEndDate Must Match the EffectiveStartDate.
When you report multiple changes on the same effective start date, all MCPD records that are not the latest change
must have an EffectiveEndDate matching the EffectiveStartDate.
Example:
This example is not valid because the EffectiveEndDate of those records with an EffectiveLatestChange of N have
an EffectiveEndDate that does not match the EffectiveStartDate.

METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veLatestChange|EffectiveEndDate|..
MERGE|Assignment|2724|2010/06/08|1|Y|2012/03/03|..
MERGE|Assignment|2724|2012/03/04|1|N|2012/06/01|..
MERGE|Assignment|2724|2012/03/04|2|N|2012/06/01|..
MERGE|Assignment|2724|2012/03/04|3|Y|2012/06/01|..
MERGE|Assignment|2724|2012/06/02|1|Y||..

An Example of a Valid MCPD History

METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effectiv
eLatestChange|EffectiveEndDate|..
MERGE|Assignment|2724|2010/06/08|1|Y|2012/03/03|..
MERGE|Assignment|2724|2012/03/04|1|N|2012/03/04|..

27 | HCM DATA LOADER USERS GUIDE

MERGE|Assignment|2724|2012/03/04|2|N|2012/03/04|..
MERGE|Assignment|2724|2012/03/04|3|Y|2012/06/01|..
MERGE|Assignment|2724|2012/06/02|1|Y||..
The following rules have been observed:

There are no gaps in the dates.

The unique key is identical for all date-effective records.

The EffectiveSequence starts at 1 for all new effective start dates and is sequential for matching effective start
dates.

The EffectiveLatestChange is always N when the record is not the latest change for an effective start date and
Y when it is.

The EffectiveEndDate matches the EffectiveStartDate when the MCPD record is not the latest change for an
effective start date.

Supplying Incremental Date Effective Changes


When your object already exists in Oracle Fusion you may not know exactly what is recorded. The change you need
to add may be the latest change, or future changes may already exist. For MCPD records, you may not know the
next available sequence number, or you may want to correct existing data. This section describes how to maintain
existing date-effective and MCPD records.
Updating a Date-Effective Record
Simply supply the data that has changed with the effective start date on which the change became effective.

METADATA|Job|SourceSystemId|SourceSystemOwner|EffectiveStartDate|EffectiveEndDat
e|ActiveStatus
MERGE|Assignment|2724|EBS-UK|2015/01/01||I
Note: The EffectiveEndDate value has not been supplied, ensuring that this change will take effect until the end of
time.
Generating a New MCPD Split
For MCPD records, if you do not know the next available sequence number, then you can generate it simply by
leaving the EffectiveSequence attribute blank.

METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effectiv
eLatestChange|EffectiveEndDate|..
MERGE|Assignment|2724|2010/06/08||Y|4712/12/31|..

Correcting an Existing MCPD Split


By supplying an EffectiveSequence value that already exists you will be correcting the existing record, not creating a
new MCPD split. To correct MCPD records, you must supply all MCPD attributes to uniquely identify the MCPD
record to correct.

METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effectiv
eLatestChange|EffectiveEndDate|..
MERGE|Assignment|2724|2010/06/08|3|N|4712/12/31|..

28 | HCM DATA LOADER USERS GUIDE

Reserved Characters
By default, these characters are reserved and cannot be included in attribute values:

Delimiter (pipe |)

Escape (slash \)

To include the new line and pipe characters in attribute values, you precede them immediately with the escape
character (slash \). For example:

METADATA|Address|AddressLine1
MERGE|Address|TheSteading\|Kier Allan
This entry enables the pipe character to appear in AddressLine1:
The Steading|Kier Allan
To include the new-line character in a value, you specify \n. For example:

METADATA|Address|AddressLine1
MERGE|Address|TheSteading\nKier Allan
This entry results in the following value for AddressLine1:
The Steading
Kier Allan

The SET File-Line Instruction


You can override the reserved characters for a file by using the SET file-line instruction, which must appear before
any METADATA lines in the file.
The format of the SET command for overriding reserved characters is:

SET FILE_ESCAPE <new_value>


SET FILE_DELIMITER <new_value>
SET FILE_NEW_LINE <new_value>
Figure 22: Overwriting Reserved Characters with the SET Command

The new value can be up to 10 characters. For example, you could set the new-line character to newline and the file
delimiter to comma (,) using the following SET commands:

SET FILE_DELIMITER ,
SET FILE_NEW_LINE newline
In this case, METADATA and MERGE lines could appear as follows:

METADATA,Address,AddressLine1
MERGE,Address,TheSteading\newlineKier Allan

Flexfields
Using HCM Data Loader, you can load both descriptive flexfield and extensible flexfield data.

29 | HCM DATA LOADER USERS GUIDE

After configuring your descriptive and extensible flexfields, open the Initiate Data Load page to generate a template
for your object. The generated template will include in the METADATA lines all the attributes required to successfully
load data into your configured flexfields. For more information about generating business object templates, refer to
page 17.
This section explains the concepts that are common to supplying descriptive and extensible flexfield data, followed
by the specific information required for each flexfield type.
Flexfield Code
If you are supplying flexfield attribute values, in addition to providing the flexfield attribute names, you must also
supply the flexfield code in the METADATA line, in the format:

FLEX:<descriptive flexfield code>


Figure 23: Descriptive Flexfield Code Format

The available flexfield codes will be included in your generated template file.
Both descriptive and extensible flexfields have one or more contexts. This attribute will be used to supply the
context information on your MERGE lines.
Flexfield Attribute Names
Flexfield attribute names are derived from the name you configured for the flexfield segment. However, they must
also be provided with a hint that tells HCM Data Loader which flexfield the attribute belongs to, and which context it
is applicable to:

<flexfield attribute name>(<flexfield code><context code>)


Figure 24: Descriptive Flexfield Attribute Name Format

Some business object components support multiple descriptive flexfields. By supplying both the flexfield code and
context against each flexfield attribute, you can supply all descriptive flexfield attributes together for every supported
flexfield and every configured context. Although extensible flexfields do not support multiple flexfield codes on the
same line, the format of the attribute name is the same for consistency.
Descriptive Flexfield Example
The contract component of the worker business object supports both the PER_CONTRACT_DF and
PER_CONTRACT_LEG_DDF descriptive flexfields.
These flexfields have the following configuration:
DFF

Context

Attribute

Hint

PER_CONTRACT_DF

Global

_CONTRACT_GLB

(PER_CONTRACT_DF=Global Data
Elements)

CONTRACT_DF

_Currency

(PER_CONTRACT_DF=CONTRACT_DF)

CH

_MAIN_CONTRACT

(PER_CONTRACT_LEG_DDF=CH)

CN

_CONST_PROB_DATE

(PER_CONTRACT_LEG_DDF=CN)

CN

_NDA

(PER_CONTRACT_LEG_DDF=CN)

CN

_COMPETITION_CLAUSE

(PER_CONTRACT_LEG_DDF=CN)

PER_CONTRACT_LEG_DDF

30 | HCM DATA LOADER USERS GUIDE

CN

_NOTICE_DURATION_UNIT

(PER_CONTRACT_LEG_DDF=CN)

If you were to generate a Worker.dat template file, the Contract METADATA line would include these attributes:

METADATA|Contract|...|_CONTRACT_GLB(PER_CONTRACT_DF=Global Data Elements)


|_Currency(PER_CONTRACT_DF=CONTRACT_DF)|_MAIN_CONTRACT(PER_CONTRACT_LEG_DDF=CH)
|_CONST_PROB_DATE(PER_CONTRACT_LEG_DDF=CN)|_NDA(PER_CONTRACT_LEG_DDF=CN)|_COMPE
TETION_CLAUSE(PER_CONTRACT_LEG_DDF=CN)|_NOTICE_DURATION_UNIT(PER_CONTRACT_LEG_D
DF=CN)
Figure 25: Descriptive Flexfield METADATA Example

Extensible Flexfield Example


The Job hierarchy provides the JobLegislative extensible flexfield. This flexfield has the following configuration:
EFF

Context

Attribute

Hint

PER_JOBS_LEG_EFF

CA

_EE0G

(PER_JOBS_LEG_EFF=CA)

CA

_NOC_CODE

(PER_JOBS_LEG_EFF=CA)

CH

_POSITION_TYPE

(PER_JOBS_LEG_EFF=CH)

FR

_ECAP_JOB

(PER_JOBS_LEG_EFF=FR)

FR

_INSEE_PCS_EXT_CODE

(PER_JOBS_LEG_EFF=FR)

If you were to generate a Worker.dat template file, the Contract METDATA line would include these attributes:

METADATA|JobLegislative|..|EFF_CATEGORY_CODE|FLEX:PER_JOBS_LEG_EFF|_EEOG(PER_JO
BS_LEG_DFF=CA)|_NOC_CODE(PER_JOBS_LEG_DFF=CA)|_POSITION_TYPE(PER_JOBS_LEG_DFF=C
H)|_ECAP_JOB(PER_JOBS_LEG_DFF=FR)|_INSEE_PCS_EXT_CODE(PER_JOBS_LEG_DFF=FR)
Figure 26: Extensible Flexfield METADATA Example

Supplying Descriptive Flexfield Data


This section describes how to construct METADATA and MERGE lines in a data file to supply descriptive flexfield
data.
You can load data for all attributes of any descriptive flexfield defined for all HCM Data Loader registered objects.

Constructing the Descriptive Flexfield METADATA


Descriptive flexfields extend a business object. Descriptive flexfield attributes can be provided with the core
attributes for the business object component.

31 | HCM DATA LOADER USERS GUIDE

To supply descriptive flexfield data for a business object component, simply include the relevant Flexfield Code and
Descriptive Flexfield attributes in the METADATA line of the business object component. These values are
available from your generated business object template file.

METADATA|Job|FLEX:PER_JOBS_DFF|JobCode|ActiveStatus|FullPartTime|MedicalCheckupR
equired|RegularTemporary|EffectiveStartDate|EffectiveEndDate|Name|SetCode|JobFam
ilyName|_JOB_LEVEL(PER_JOBS_DFF=US)
Figure 27: Defining DFF Attributes in METADATA

The DFF attributes can be defined anywhere on the METADATA line; they do not need to be appended to the end.

Constructing Descriptive Flexfield MERGE Lines


For each supported descriptive flexfield for a business object component, a record can have only one context at a
time. The context for each record must be supplied against the Flexfield Code for the descriptove flexfield.
Example:

METADATA|Job|FLEX:PER_JOBS_DFF|JobCode|ActiveStatus|FullPartTime|MedicalCheckupR
equired|RegularTemporary|EffectiveStartDate|EffectiveEndDate|Name|SetCode|JobFam
ilyName|_JOB_LEVEL(PER_JOBS_DFF=US)
MERGE|Job|US|ACC|A|F|N|R|2000/01/01|4712/12/31|Accountant|COMMON|Finance|1
Figure 28: Supplying Descriptive Flexfield Data

Supplying Descriptive Flexfield MERGE Lines for Multiple Flexfield Codes and Contexts
When multiple descriptive flexfields are supported for the same business object component, the data can be loaded
at the same time:

METADATA|Contract|AssignmentId|ContractId|EffectiveStartDate|EffectiveEndDate|F
LEX:PER_CONTRACT_DF|FLEX:PER_CONTRACT_LEG_DDF|_CONTRACT_GLB(PER_CONTRACT_DF=Glo
bal Data Elements) |_Currency(PER_CONTRACT_DF=CONTRACT_DF)
|_MAIN_CONTRACT(PER_CONTRACT_LEG_DDF=CH)|_CONST_PROB_DATE(PER_CONTRACT_LEG_DDF=
CN)|_NDA(PER_CONTRACT_LEG_DDF=CN)|_COMPETETION_CLAUSE(PER_CONTRACT_LEG_DDF=CN)|
_NOTICE_DURATION_UNIT(PER_CONTRACT_LEG_DDF=CN)
MERGE|Contract|E8732|39987|2013/12/14|2014/03/04|CONTRACT_DF|CN|Contract Glb
value|USD|Contract Data|||
MERGE|Contract|E8732|39987|2014/03/05|4712/12/31|CONTRACT_DF|CH|Contract Glb
value|USD||31/03/2015|NDA Value|Competition Clause Value
Figure 29: Supplying Descriptive Flexfield Data for Multiple Flexfield Codes

Supplying Extensible Flexfield Data


This section describes how to construct METADATA and MERGE lines in a data file to supply extensible flexfield
data.
Category Code
In addition to the Flexfield Code, extensible flexfields also have a Category Code. This code will be provided in your
generated template file with an attribute name of EFF_CATEGORY_CODE.
Constructing the EFF METADATA

32 | HCM DATA LOADER USERS GUIDE

Extensible flexfields are not an extension of a business object component, but a separate component in the
business object hierarchy.
To supply extensible flexfield data, simply include the METADATA line for the EFF component, removing any
attribute names for which you will not be supplying data.

METADATA|JobLegislative|EFF_CATEGORY_CODE|FLEX:PER_JOBS_LEG_EFF|JobId(SourceSys
temId)|JobCode|SetCode|EffectiveStartDate|EffectiveEndDate|SourceSystemOwner|So
urceSystemId|LegislationCode|_EEO1_CATEGORY(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_FLSA
_STATUS(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_INSEE_PCS_CODE(PER_JOBS_LEG_EFF=FR)|_ECA
P_JOB(PER_JOBS_LEG_EFF=FR)|_LINE_OF_PROGRESSION(PER_JOBS_LEG_EFF=HRX_US_JOBS)
Figure 30: Defining EFF Attributes in METADATA

Constructing the Extensible Flexfield MERGE lines


An extensible flexfield record can have only one context at time. The context for each record must be supplied
against the Flexfield Code for the flexfield.
Example:

METADATA|JobLegislative|EFF_CATEGORY_CODE|FLEX:PER_JOBS_LEG_EFF|JobId(SourceSys
temId)|JobCode|SetCode|EffectiveStartDate|EffectiveEndDate|SourceSystemOwner|So
urceSystemId|LegislationCode|_EEO1_CATEGORY(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_FLSA
_STATUS(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_INSEE_PCS_CODE(PER_JOBS_LEG_EFF=FR)|_ECA
P_JOB(PER_JOBS_LEG_EFF=FR)|_LINE_OF_PROGRESSION(PER_JOBS_LEG_EFF=HRX_US_JOBS)
MERGE|JobLegislative|JOB_LEG|HRX_US_JOBS|OCT18EFF1|OCT18EFF1|COMMON|1990/01/01|
4712/12/31|HRC_SQLLOADER|OCT18EFF1_LEG1|US|TECHNICIAN|EXEMPT||| Testing EFF
MERGE|JobLegislative|JOB_LEG|FR|OCT18EFF1|OCT18EFF1|COMMON|1990/01/01|4712/12/3
1|HRC_SQLLOADER|OCT18EFF1_LEG2|FR|||387b|N|
Figure 31: Supplying Descriptive Flexfield Data

Unlike other components of the business object hierarchy, EFF MERGE lines cannot be supplied in isolation, but,
must be accompanied by a parent record.
Supplying Lookup Validated Flexfield Values
For configured flexfield attributes, the flexfield attribute name must be suffixed with _Display if providing a lookup
meaning value. For example, for a configured gender attribute on a flexfield, supply the lookup code (M or F) in the
gender attribute. To supply the meaning (Male or Female), use the attribute name gender_Display.

METADATA|Job|FLEX:PER_JOBS_DFF|gender_Display(PER_JOBS_DFF=JOBCONTEXT1)|..
MERGE|Job|JOBCONTEXT1|Male|..
MERGE|Job|JOBCONTEXT1|Female|..

Source-System References
You can include source-system references in each data line in a file.
Source-system references are optional. They enable you to record the source-system database table name, column
names, and attribute values. These details are visible in the HCM Data Loader interface. Therefore, if an object fails
to load, you can easily identify the data source.

33 | HCM DATA LOADER USERS GUIDE

Source-system references comprise a name and a value.


Source-System Names
You specify source-system names in the relevant METADATA line.
To specify the source-system table name, you add to the METADATA line:

SourceRefTableName=<table name>
Figure 32: Specifying a Source System Reference Table Name

You can specify up to 10 source-system column names in the same METADATA line using the SourceRef001 to
SourceRef010 tags.
For example:

METADATA|Job|SourceRefTableName=PER_JOBS|SourceRef001=JOB_ID|SourceRef002=EFFEC
TIVE_START_DATE|SourceRef003=EFFECTIVE_END_DATE
Source-system references can appear anywhere in the METADATA line after the instruction and discriminator tags.
Source-System Values
Supply the source-system values on each data line, ensuring that they appear in the order specified on the
METADATA line.
In data lines you must leave the source-system table name blank. This value appears in the METADATA definition
only.
For example:

METADATA|Job|SourceRefTableName=PER_JOBS|SourceRef001=JOB_ID|SourceRef002=EFFEC
TIVE_START_DATE|SourceRef003=EFFECTIVE_END_DATE
MERGE|Job||135|2010/01/01|4712/12/31
MERGE|Job||136|2010/01/01|4712/12/31

Maintaining Existing Date-Effective Data


Maintaining Oracle Fusion data when existing date-effective records exist for the date range of the update can be a
challenge. This section describes the various options available when existing date-effective records may exist.
When you supply changes for date-effective records, your updates may affect multiple date-effective rows. Care
must be taken if your change predates existing data for your record.
For example:
CURRENT JOB OBJECT

ESD

EED

JobCode

JobName

RegularTemporary

FullPartTime

Active Status

2010/06/08

2012/01/09

ACC1

Accounts Clerk

PART_TIME

2012/01/10

2012/03/03

ACC1

Accounts Clerk

FULL_TIME

2012/03/04

4712/12/31

ACC1

Accounts Administrator T

FULL_TIME

34 | HCM DATA LOADER USERS GUIDE

If you supply an update with an Effective Start Date of 2011/01/01 and no Effective End Date is supplied, a new
date-effective split will be generated on the 1st January 2011 but both the 10th January 2012 and 4th March 2012
records will be impacted. How these records will be updated depends on the date-effective maintenance mode.

Date-Effective Maintenance Modes


HCM Data Loader supports two different update modes that impact how future-dated records are handled:

Retain - Retains all existing date-effective records. This mode is recommended when you are supplying an
incremental update to an existing record.

Replace - Removes existing date-effective splits for the date range specified. This mode is useful during
data migration, when you are uploading the complete data for a record.

Both modes generate a new date-effective split if you specify an effective start or end date that is new. That is, no
date-effective split exists for that date.
Both modes only update the attributes for which you have supplied values. To ensure a null value exists, make use
of the #NULL token. See Setting Not Null Attribute Values to Null on page 20.
The following information provides guidance on the functionality that these modes provide. However, not all
business objects fully support these modes. See the business object specific documentation for more information.
The Replace mode is the HCM Data Loader default behavior.
The mode can be controlled with a SET command:

SET PURGE_FUTURE_CHANGES <value>


Figure 33: Setting the Update Mode for Future-Dated Records

You can specify either Y (Replace) or N (Retain).

Retaining Existing Date-Effective Records


This is the recommended behavior when supplying incremental updates to existing data.
To retain future dated records you must include a SET command to override the default behavior:

SET PURGE_FUTURE_CHANGES N
Figure 34: SET Command to Retain Existing Date-Effective Records

When HCM Data Loader is running in retain mode, you can choose to:

Retain future dated record values without updating them.

Retain future date-effective splits but roll forward the changed values.

Here, a future-dated record is any date-effective record that has an effective start date later than the effective start
date of the update being processed.
Retaining Future Dated Record Values
If you want any future dated changes to be retained untouched, then instead of supplying a date for the Effective
End Date, use the #RETAIN tag. This tag ensures that your change will take effect only from your supplied Effective
Start Date until the next date-effective record. If there are no future-dated records, then your change will continue
until the end-date of the record, usually the end of time.

35 | HCM DATA LOADER USERS GUIDE

Assignment Example
CURRENT ASSIGNMENT OBJECT

ESD

Seq

EED

Action Code

Job

Grade

Location

Normal Hours

2010/06/08

2012/03/03

HIRE

ACC1

IC2

HQ

40

2012/03/04

2012/03/04

PROMOTION

ACC1

IC4

HQ

40

2012/03/04

2012/03/04

TRANSFER

ACC1

IC4

LVP

40

2012/03/04

2012/06/01

JOB_CHANGE

ACC3

IC4

LVP

40

2012/06/02

4712/12/31

JOB_CHANGE

ACC2

IC4

LVP

40

Update the working hours on the 10th Jan 2012 retaining future dated values

SET PURGE_FUTURE_CHANGES N
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veLatestChange|EffectiveEndDate|ActionCode|NormalHours
MERGE|Assignment|2724|2012/01/10||Y|#RETAIN|ASG_CHANGE|37.5
NEW ASSIGNMENT OBJECT

ESD

Seq

EED

Action Code

Job

Grade

Location

Normal Hours

2010/06/08

2012/01/09

HIRE

ACC1

IC2

HQ

40

2012/01/10

2012/03/03

ASG_CHANGE

ACC1

IC2

HQ

37.5

2012/03/04

2012/03/04

PROMOTION

ACC1

IC4

HQ

40

2012/03/04

2012/03/04

TRANSFER

ACC1

IC4

LVP

40

2012/03/04

2012/06/01

JOB_CHANGE

ACC3

IC4

LVP

40

2012/06/02

4712/12/31

JOB_CHANGE

ACC2

IC4

LVP

40

Note: The EffectiveSequence attribute was not supplied with a value in order to ensure that the next MCPD split
was assigned to this change. If you want to start at an existing MCPD split, then specify the EffectiveSequence and
EffectiveLatestChange values for that MCPD record.

ATTENTION: This is the only recommended action for MCPD records, or any record with a mandatory ActionCode.
By attempting to roll forward any changes over future-dated records, you are likely to corrupt the ActionCode for
each future dated record in your specified date range.

If you had not supplied the #RETAIN tag but instead left the EffectiveEndDate unspecified or had a value of
4712/12/31 (to ensure the change was applied until the end of time) you would get a very different result.
Update the working hours on the 10th Jan 2012 overwriting future dated values:

SET PURGE_FUTURE_CHANGES N
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veLatestChange|EffectiveEndDate|ActionCode|NormalHours
MERGE|Assignment|2724|2012/01/10||Y||ASG_CHANGE|37.5

36 | HCM DATA LOADER USERS GUIDE

NEW ASSIGNMENT OBJECT

ESD

Seq

EED

Action Code

Job

Grade

Location

Normal Hours

2010/06/08

2012/01/09

HIRE

ACC1

IC2

HQ

40

2012/01/10

2012/03/03

ASG_CHANGE

ACC1

IC2

HQ

37.5

2012/03/04

2012/03/04

ASG_CHANGE

ACC1

IC4

HQ

37.5

2012/03/04

2012/03/04

ASG_CHANGE

ACC1

IC4

LVP

37.5

2012/03/04

2012/06/01

ASG_CHANGE

ACC3

IC4

LVP

37.5

2012/06/02

4712/12/31

ASG_CHANGE

ACC2

IC4

LVP

37.5

As the Action Code is a mandatory attribute for which you have supplied a value, the supplied value will overwrite
the existing Action Code for all future-dated records.

Note: This action is not reversible. If you supply attribute values that span existing date-effective splits, then they will
all be updated with every attribute value supplied.

Correcting Future Dated Record Values


To roll your changes forward across any future-dated records, you have two options:

Specify the effective end date when the change should stop.

Specify that the change should continue until the end of the object.

Note: This functionality should be used with caution. Many business objects have mandatory attributes. All values
you supply will be rolled forward across all records in the date range that you specify. This outcome could have an
undesired impact on your data. Review the specific business object documentation for more details.

Supplying an Effective End Date


If you know when your change should end, supply that date in the EffectiveEndDate attribute.
CURRENT JOB OBJECT

ESD

EED

JobCode

JobName

RegularTemporary

FullPartTime

Active Status

2010/06/08

2012/01/09

ACC1

Accounts Clerk

PART_TIME

2012/01/10

2012/03/03

ACC1

Accounts Clerk

FULL_TIME

2012/03/04

4712/12/31

ACC1

Accounts Administrator T

FULL_TIME

You can apply a change to RegularTemporary from 4th March 2011 to 4th April 2014 by including these lines in the
Job .dat file:

37 | HCM DATA LOADER USERS GUIDE

SET PURGE_FUTURE_CHANGES N
METADATA|Job|SourceSystemId|EffectiveStartDate|EffectiveEndDate|ReqularTemporar
y
MERGE|Job|45346|2011/03/04|2014/04/04|R
NEW JOB OBJECT

ESD

EED

JobCode

JobName

RegularTemporary

FullPartTime

ActiveStatus

2010/06/08

2011/03/03

ACC1

Accounts Clerk

PART_TIME

2011/03/04

2012/01/09

ACC1

Accounts Clerk

PART_TIME

2012/01/10

2012/03/03

ACC1

Accounts Clerk

FULL_TIME

2012/03/04

2014/04/04

ACC1

Accounts Administrator R

FULL_TIME

2014/04/05

4712/12/31

ACC1

Accounts Administrator T

FULL_TIME

A new date-effective split will be created for both the start and end dates. Only the RegularTemporary attribute was
supplied with a value, so only that attribute is updated for the date-range. Other attributes retain their existing
values.
Correct All Future-Dated Records for the Life of the Object
Most objects do not end but are terminated or become inactive. However, you can stop a few objects, such as
element entries, in time. The #ALL tag provides a safe way of specifying that you want all future dated records to be
corrected with your changes, regardless of the end date of the object.
CURRENT JOB OBJECT

ESD

EED

JobCode

JobName

RegularTemporary

FullPartTime

ActiveStatus

2010/06/08

2012/01/09

ACC1

Accounts Clerk

PART_TIME

2012/01/10

2012/03/03

ACC1

Accounts Clerk

FULL_TIME

2012/03/04

4712/12/31

ACC1

Accounts Administrator T

FULL_TIME

You can apply a change to RegularTemporary from 4-Mar-2011 until the end of the Job by including these lines in
the Job .dat file:

SET PURGE_FUTURE_CHANGES N
METADATA|Job|SourceSystemId|EffectiveStartDate|EffectiveEndDate|ReqularTemporar
y
MERGE|Job|45346|2011/03/04|#ALL|R
NEW JOB OBJECT

ESD

EED

JobCode

JobName

RegularTemporary

FullPartTime

ActiveStatus

2010/06/08

2011/03/03

ACC1

Accounts Clerk

PART_TIME

2011/03/04

2012/01/09

ACC1

Accounts Clerk

PART_TIME

2012/01/10

2012/03/03

ACC1

Accounts Clerk

FULL_TIME

2012/03/04

4712/12/31

ACC1

Accounts Administrator R

FULL_TIME

38 | HCM DATA LOADER USERS GUIDE

Replace Future Dated Records


This mode is recommended only when supplying the complete date-effective history for an object, where existing
data in Oracle Fusion must be replaced with the data supplied in the file.
By default, future-dated changes will be replaced. However, to ensure this behavior supply this SET command:

SET PURGE_FUTURE_CHANGES Y
Figure 35: SET Command to Replace Future-Dated Changes

CURRENT ASSIGNMENT OBJECT

ESD

Seq

EED

Action Code

Job

Grade

Location

Normal Hours

2010/06/08

2012/03/03

HIRE

ACC1

IC2

HQ

40

2012/03/04

2012/03/04

PROMOTION

ACC1

IC4

HQ

40

2012/03/04

2012/03/04

TRANSFER

ACC1

IC4

LVP

40

2012/03/04

2012/06/01

JOB_CHANGE

ACC3

IC4

LVP

40

2012/06/02

4712/12/31

JOB_CHANGE

ACC2

IC4

LVP

40

Update the working hours on the 10th Jan 2012 replacing future dated values:

SET PURGE_FUTURE_CHANGES Y
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veLatestChange|EffectiveEndDate|ActionCode|NormalHours
MERGE|Assignment|2724|2012/01/10||Y||ASG_CHANGE|37.5
NEW ASSIGNMENT OBJECT

ESD

Seq

EED

Action Code

Job

Grade

Location

Normal Hours

2010/06/08

2012/01/09

HIRE

ACC1

IC2

HQ

40

2012/01/10

4712/12/31

ASG_CHANGE

ACC1

IC2

HQ

37.5

A new date-effective split is generated for the new EffectiveStartDate of 10th Jan 2012.
The date-effective records that existed after that date are replaced by this change.
Existing attribute values that predate the change and where new values have not been supplied will continue on the
new record. To explicitly remove existing values, the #NULL token must be supplied.

CAUTION: This action is not reversible.

Updating the First Effective Start Date or Last Effective End Date
To alter the first effective start date or the last effective end date, you must place a Y against either of the following
attributes:

ReplaceFirstEffectiveStartDate

39 | HCM DATA LOADER USERS GUIDE

ReplaceLastEffectiveEndDate

You supply the new date using the EffectiveStartDate and EffectiveEndDate attributes.
This functionality can also be used in conjunction with supplying other updates. For example, you can specify an
earlier effective start date and supply a name change to reconcile across all existing date-effective records.
Examples
The following example shows how to alter the first effective start date of an existing Job:

METADATA|Job|JobId|EffectiveStartDate|EffectiveEndDate|ReplaceFirstEffectiveSta
rtDate
MERGE|Job|23452|1950/01/01|4712/12/31|Y

The following example shows how to end an existing recurring element entry:

METADATA|ElementEntry|ElementEntryId|EffectiveStartDate|EffectiveEndDate|Replac
eLastEffectiveEndDate
MERGE|ElementEntry|4634|2014/01/01|2014/04/05|Y
The following example shows how to alter both dates, with multiple date-effective records:

METADATA|Organization|Name|EffectiveStartDate|EffectiveEndDate|ReplaceFirstEffe
ctiveEndDate
MERGE|Organization|Org_DHQA|1970/01/01|2013/12/31|Y|
MERGE|Organization|Org_DHQA|2001/01/01|2010/12/31||
MERGE|Organization|Org_DHQA|2011/01/01|2015/12/31||Y

Limitations
There are certain situations in which the ability to replace the last effective end date is not supported.
Invalid action
Some objects do not support the last effective end date being anything other than the Oracle Fusion end of time. In
these cases, HCM Data Loader raises an error if the ReplaceLastEffectiveEndDate attribute is included in the
METADATA line.
Similarly, objects such as worker do not support the first effective start date being altered using this mechanism. To
alter a worker's effective start date, you can use the NewStartDate worker attribute.
If you attempt to alter the first effective start date or the last effective end date for an object that does not support it,
you will receive the following error message:
The {BUSINESS OBJECT} METADATA line cannot be processed as the {ATTRIBUTE} attribute is invalid. {DATE
ATTRIBUTE} cannot be modified for this business object.
Tokens
Token

Description

Example

BUSINESS OBJECT

The business object discriminator

Worker

ATTRIBUTE

The name of the replace attribute

ReplaceFirstEffectiveStartDate

40 | HCM DATA LOADER USERS GUIDE

DATE ATTRIBUTE

The name of the effective date attribute that cannot be updated

EffectiveStartDate

for this object

Reconcile Mode
When running in reconcile mode, you can populate the EffectiveEndDate with different values to control what
happens to any future-dated records that may exist. The following values cannot be used in conjunction with altering
the last effective end date:

#RETAIN

#ALL

null

Translation Data
In environments where multiple languages are enabled, you can load translated objects. HCM Data loader supports
any Java supported character set.
Loading translated objects is a two-stage process:
1.

You create the object by loading the base-language version. At this stage, translation records are created
for all enabled languages, but they hold base-language versions of any translatable values. For example, if
US English is your base language, then translation records hold US English versions of translatable
values.

2.

Once the base-language version is created successfully, you load the translated values as corrections to
the base-language object. To perform this step, you use data-file templates that are provided specifically
for translation. One translation data-file template is provided for each business-object component that
includes translatable values.

For example, if you create a record for the Sales Manager job in an environment where US English is the base
language and French, German, and Spanish are enabled, then the object is created as follows:

Language

Source Language Name

US English

US English

Sales Manager

French

US English

Sales Manager

German

US English

Sales Manager

Spanish

US English

Sales Manager

Once this object is successfully created, you can load a single translation data file (JobTranslation.dat) to correct the
French, German, and Spanish translations of the job name. You can load the translations in separate files, one per
language, if you prefer.
You can deliver translation files either in the same zip file as the original object or separately. However, you cannot
deliver them before the object that they apply to exists.

41 | HCM DATA LOADER USERS GUIDE

Translation-File Discriminators
Unique file discriminators are defined for the translation files and are identified in the relevant file. For example, the
file discriminator for the file JobTranslation.dat is JobTranslation.
Effective Dates
When you load translated values for an existing object, you must ensure that the effective dates in the translation
files are the same as those in the base-language version of the object. If you later update the object, then you
update the base-language object before updating the translation object. All components of a translated object must
remain synchronized.
Example: Job.dat

METADATA|Job|SourceSystemOwner|SourceSystemId|EffectiveStartDate|EffectiveEndDa
te|JobCode|Name|ActiveStatus
MERGE|Job|EBS-UK|JB2ACC44|2010/01/01|2014/04/04|ACADM|Accounts Administrator|A
MERGE|JOB|EBS-UK|JB2ACC44|2014/04/05|4712/12/31|ACADM|Accounts Clerk|A
Example: JobTranslation.dat

METADATA|Job|SourceSystemOwner|SourceSystemId|EffectiveStartDate|EffectiveEndDate
|Language|Name
MERGE|Job|EBS-UK|JB2ACC44|2010/01/01|2014/04/04|ES| Administrador de Cuentas
MERGE|JOB|EBS-UK|JB2ACC44|2014/04/05|4712/12/31|ES| Cuentas Clerk

Updating Translation Data


If the object is not date-effective, then you can simply upload the relevant translation file only.
If you are providing an updated translated value for a date-effective object and no date-effective split exists on the
start date of the new translation value, then you must also update the base-language object. This requirement
exists to ensure that the effective dates of the base-language and translation objects remain the same.

Deleting Data from Oracle Fusion


You can delete many objects, regardless of whether they were loaded using HCM Data Loader. To delete an object,
include the DELETE instruction tag in the relevant data file. For example, you could delete a previously loaded Job
Family object by including these lines in the JobFamily.dat file:

METADATA|JobFamily|EffectiveStartDate|EffectiveEndDate|JobFamilyName
DELETE|JobFamily|2012/10/01|4712/12/31|Sales01

Caution: Deleted data cannot be recovered. It is recommended that you try to correct your data rather than delete
and recreate it.

Before deleting an object, ensure that other business objects do not refer to it.
Note that:

42 | HCM DATA LOADER USERS GUIDE

You can delete complete business objects and individual complete business-object components. You cannot
delete individual date-effective records.

When you delete a parent object, its child objects and any translation objects are also deleted. For example, to
delete a grade and its child business objects, you create a DELETE instruction for the Grade discriminator. To
delete only a grade rate value child component, you create a DELETE instruction for the GradeRateValue
discriminator.

You cannot delete worker objects from the production environment, though you can delete some child
components of the worker object. For example, you can delete the person e-mail component of a worker object.

You cannot include DELETE instructions in translation data files.

Deletion means complete removal of the object from Oracle Fusion HCM. A deleted object cannot be
recovered.

To delete a date-effective object referenced by user keys, the EffectiveStartDate and EffectiveEndDate
attributes are mandatory.

To delete a date-effective object using source keys, Oracle Fusion GUID, or Oracle Fusion surrogate ID the
effective start and end dates are not mandatory.

You must not supply a DELETE instruction for an object that has a MERGE instruction in the same file. HCM
Data Loader will not know in which order to process the two instructions.

Importing and Loading Data


This section describes:

How to import and load your data

How to monitor progress and correct any errors

Some processes to run after loading Worker and Hierarchy Tree data

Before attempting to load any data into Oracle Fusion, review the Preparing the Oracle Fusion Human Capital
Management Environment section on page 12.
To process the zip file:
1.

Upload the file to the Oracle WebCenter Content server. Oracle WebCenter Content allocates a unique content
ID to every file.

2.

Initiate the submission of your file with HCM Data Loader.

The Automating HCM Data Loader whitepaper explains how to use the WebCenter Content server web service.
This document is available from the MOS document, HCM Data Loader: User Guide (Doc ID 1664133.1).

Using the HCM Data Loader Interface for File Submission


To import and load your zip file:
1.

Open the Import and Load Data page (Navigator - Data Exchange - Import and Load Data).

2.

Click the dropdown menu on the Import File button and select Import Local File.

43 | HCM DATA LOADER USERS GUIDE

Figure 36: Import and Load Data - Import Local File

3.

In the Select File dialog box, click the Browse button to search and select your file. Alternatively, drag the file
from your local file browser to the Browse button.

Figure 37: Select local file

4.
5.

Click Submit to upload your file to the WebCenter Content server. The file is then secured by the HCM Data
Loader import account and allocated a unique content ID.
On the Schedule Request page, review the parameter values and click Submit. A confirmation message
showing the process ID appears. Note the process ID.

Figure 38: Submit Import and Load HCM Data File

44 | HCM DATA LOADER USERS GUIDE

6.

Click OK to close the message and return to the Import and Load Data page.

File Import Parameters


The following parameters are available when submitting this process:
Parameter

Description

File Name

The name of the file on the Oracle WebCenter Content server to process.

Content ID

WebCenter Content ID for the file on the WebCenter Content server.

File Action

Two options:
Import and load automates the load process for each business object in the zip file.
Import only only imports the business object data into the stage tables. The Load process can be
manually initiated from the user interface.

File Encryption

Encryption type for the file.

Delete Source File

Purge the source file from the WebCenter Content server after processing.

Maximum Percentage of Import


Errors

Percentage of file lines in error that can occur in a business object before the import process stops for the
object.

Maximum Percentage of Load


Errors

Percentage of business-object instances in error that can occur for a business object before the load
process stops.

Maximum Concurrent Threads


for Load

The maximum number of concurrent process threads to use for loading your data set.

Load Group Size

The number of objects to process at a time by each thread. The record counts will only be updated at the
end of processing each group.

Import Only
If you set the File Action parameter to Import only then your business object data will be:

Streamed from your zip file on the WebCenter Content server and decrypted if your file is encrypted

Validated for business object file name and METADATA definitions

Imported into the HCM Data Loader file line stage tables

Validated against attribute data types

Grouped by local key values to form logical records of related date-effective file lines. For example, all dateeffective file lines supplied for a job are grouped into a logical occurrence of a job, such as the job Accountant.

Formed into logical objects by resolving parent references. For example the logical record for a valid grade is
associated with the job it references

For more information on how to supply key values correctly, see the Supplying Key Values section on page 21.
Your valid logical objects will not be loaded into Oracle Fusion if you submit your file in the Import only mode.

Import and Load


If you set the File Action parameter to Import and load, the above import steps will be performed before valid
logical objects are submitted for loading. HCM Data Loader does not load your data directly into Oracle Fusion.
Instead, it passes your valid object data to the business-object-specific services. These services are responsible for
performing validation that is specific to the business object.

45 | HCM DATA LOADER USERS GUIDE

Submitting a WebCenter Content File


If your zip file is already available on the WebCenter Content server, then you can still submit it from the Import and
Load page:
1.

Open the Import and Load Data page (Navigator - Data Exchange - Import and Load Data).

2.

On the Import and Load Data page, click Import File.

Figure 39: Import and Load Data - Import File

3.

In the WebCenter Content Files dialog box, any files that have not been processed are listed. You can filter
the list to reduce it. For example, you can enter the WebCenter Content ID or file creation date. Select the file
that you posted to the WebCenter Content server and click Submit.

Figure 40: Available WebCenter Content Files

4.

On the Schedule page, review the parameters and click Submit.

Initiating Load or Resubmitting Load


Whether you submitted your data set in the Import only mode, or you want to resubmit a failed load process, you
can initiate the load process directly by clicking the Load button on the Business Objects table.

46 | HCM DATA LOADER USERS GUIDE

To initiate load for a specific business object:


1.

Select the business object and click Load. Only business objects with a loaded status of Ready ( ), Error (
), or Stopped ( )have the Load button enabled.

Figure 41: Submit Load for an Individual Business Object

2.

On the submission page, review the parameter values, update if necessary, and click Submit.

Figure 42: Submit the Load Business Object ESS job

Monitoring Progress
Import and Load Data User Interface
On the Import and Load Data page (Navigator - Data Exchange - Import and Load) you can review the status of
your import and load requests. By default, this page displays the status of any requests that you submitted in the last
7 days. You can search for particular data sets (zip files) and business objects.
The Search Results section presents one row for each data set. The Progress section of the search results is as
follows:

47 | HCM DATA LOADER USERS GUIDE

Figure 43: Import and Load Data Progress Icons

This section provides a summary of the import and load processes for each data set. If errors or warnings occur
during either the import or load process, then the relevant icons (warning
and error
) appear. If both stages
complete successfully, then the green check mark (

) appears in both columns.

Other icons that can be seen in the Progress section are In Progress (

), Ready ( ), Locked (

) and Stopped (

).
When warnings and errors occur, messages provide the details. You click the Messages icon to open the Messages
page.
The Imported Physical Rows and Objects sections of the search results provide more detail:

Figure 44: Import and Load Data Counts

The Imported Physical Rows section shows the percentage of rows in the data set imported successfully to the
stage tables. It also shows the total number of rows in the data set, the number of rows imported, and the number
that failed to import.
The Objects section shows the percentage of objects in the data set that loaded successfully to the application
tables. It also shows the total number of objects in the data set, the number of objects that are ready to load, the
number that loaded successfully, the number that failed to load, and the number of objects that have been manually
corrected on the Error Management page. As objects are created during the Import stage, you can see failed objects
during import, before load has started.
Positive numbers in Failed columns are hyperlinks to more information about the failures.
For any data set selected in the Search Results section, the Business Objects tab in the Details section of the Import
and Load page provides information about the progress of each business object. For example, if the data set
includes both grades and locations, then one row appears for grades and one for locations.
The Processes tab in the Details section of the Import and Load page shows the status of the process submitted to
import and load the data set.

Reviewing Physical Row Errors


On the Import and Load Data page, click the number in the Failed column of the Imported Physical Rows section in
the search results. This action opens the File Line Errors page, where you can review import errors for a data set.
(You can also open this page from the Number of Messages column on the Messages page.)
In the File Structure section of the page, expand any folders to see file lines with import errors. For example:

48 | HCM DATA LOADER USERS GUIDE

Figure 45: Error Management File Structure

When you select a line with errors:

The Messages section of the File Line Errors page displays the associated error message.

The Details section of the File Line Errors page displays the contents of the physical row.

The Physical Row tab displays the METADATA and data lines supplied in the file for the record that has
errored:

Figure 46: Error Management Physical Row

Using this information, you can determine how to correct the import errors. You must import and load the corrected
data again, and you must add the corrected data file to a new zip file. Any attempt to process the existing zip file
again will fail.
Examples of physical row errors are:

The instruction or discriminator tags are not recognized.

The number of values supplied in a data line does not match those defined in the METADATA.

A unique reference for the component was not supplied.

The parent on a child component could not be found, either in the file or in Oracle Fusion HCM.

Reviewing Object Errors


On the Import and Load Data page, click the number in the Failed column of the Objects section in the search
results. This action opens the Object Errors page, where you can review object errors for a data set.
In the Data Structure section of the page, expand any folders to see objects with errors. When you select an object
with errors, the Details section of the Object Errors page shows the:

Object attributes and the values that you supplied for those attributes

49 | HCM DATA LOADER USERS GUIDE

Source-system references, if any

Contents of the physical row

For example, attributes:

Figure 47: Error Management Attribute Values

Source System References


The values displayed in the Source System References tab are those supplied in the METADATA and data lines in
your file for the SourceRef attributes. See page 33 for details of how to provide values that are displayed in the user
interface.

Figure 48: Error Management Source System References

The Messages section of the Object Errors page displays error messages for the selected object.
Using this information, you can determine how to correct the errors. You must import and load the corrected data
again, and you must add the corrected data file to a new zip file. Any attempt to process the existing zip file again
will fail.
Examples of object errors:

An alphanumeric value being supplied for a numeric attribute

The foreign object referenced using an integration key is not found in Oracle Fusion HCM

A logical object with validation errors

50 | HCM DATA LOADER USERS GUIDE

Where possible, HCM Data Loader always forms logical objects from the distinct data lines, even if those lines are in
error. In this way, only complete valid objects are loaded into Oracle Fusion HCM.

Correcting Attribute Values for Objects in Error


You can correct individual attribute values for objects that are in error.
1.

Open the Error Management page and drill down in the Data Structure hierarchy to the record you want to
correct.

Figure 49: Correcting Attribute Values

2.

Click Edit on the Attributes tab to provide corrections for individual attributes on the selected record.

3.

Provide your updates. For dates you can use the date picker to update the date value.

51 | HCM DATA LOADER USERS GUIDE

Figure 50: Correcting the Date Value for an Attribute

4.

To save your changes click Save or Save and Close. You can reject your changes and return to the Import
and Load page by clicking Cancel.

You can resubmit Load to process your corrected objects. See the Initiating Load or Resubmitting Load section on
page 46.
Resetting Corrected Attribute Values
You can reset any corrected attribute value to the value supplied in the file by selecting the attribute to reset and
clicking Reset.

Reviewing Corrected Objects


A count of all objects with corrected attribute values is available in both the Data Sets and Business Objects tables
on the Import and Load Data page.

Figure 51: Corrected Objects Count

Clicking on the Corrected Objects count opens the Error Management page, where you can review your corrections.

52 | HCM DATA LOADER USERS GUIDE

Figure 52: Corrected Records and Attributes

Corrected records and attributes are highlighted by the updated value ( ) icon.

Stopping Processing
You can stop a processing data set at any time. The Stop button on the Data Set table and Business Objects table
can be clicked to initiate the request. However, it can take a few minutes for a large data set to stop processing
completely. To retain efficiency in the import and load processing, the check for a request to stop is intermittent.
Stopping a Processing Data Set
1.

Select the data set you want to stop, and Refresh the Data Sets table to ensure that the data set is still
processing. The availability of the Stop button is determined by the Imported and Loaded statuses of the data
set. The button is enabled only if either is In Progress ( ).

2.

Click Stop.

Figure 53: Stopping a Data Set

53 | HCM DATA LOADER USERS GUIDE

Stopping an Individual Business Object


1.

Select the Business Object you want to stop. It is worth refreshing the Business Objects table to ensure that the
Business Object is still processing. The availability of the Stop button is determined by the Imported and
Loaded statuses of the business object: only if either is In Progress ( ) is the button enabled.

2.

Click Stop.

Figure 54: Stopping a Business Object

Confirming the Stop Request


A stopped import process cannot be restarted. You will be asked to confirm that you want to proceed with stopping
the process. Click OK to proceed.

Figure 55: Confirming Stop

Potential Errors
Sometimes it is not valid to request a stop. Perhaps processing has already completed normally, there are no
processes to stop, or a stop has already been requested. For these situations a dialog box will display the reason
why the stop request will not be submitted.

Stopped Business Objects


When a Business Object is stopped, the process where the stop occurred will have a stopped status:

54 | HCM DATA LOADER USERS GUIDE

You cannot restart the Import process for stopped or failed imports. You can restart stopped and failed Load
processes. For more information, see Initiating Load or Resubmitting Load on page 46.

Extracting Data
HCM Data Loader makes use of two outputs from HCM Extracts. As for all predefined HCM Extracts, you are
recommended to make a copy of the predefined extract and tailor it to suit your use case.

Status and Errors


HCM Data Loader is delivered with the HCM Data Loader Data Set Summary report available in HCM Extracts. This
report extracts the Data Set and Business Object status and record counts, along with all messages raised and the
records impacted by each message.
The delivered output is in XML making the extract machine readable. You can, however, create your own BI
Publisher formats based on this extract.

Compensation Changes
HCM Extracts also delivers the Compensation Changes extract. This report extracts the compensation changes
made for a particular compensation run.

Required Post Processes


After a successful data migration or incremental update, some business objects require further processes to be run
to complete data setup in the Oracle Fusion HCM environment. You run these processes as required from the
Scheduled Processes work area.
Business Object

Process

Description

Worker

Synchronize Person Records

When you run the Synchronize Person Records process, changes to person
and assignment details that have occurred since the last data load are
communicated to consuming applications, such as Oracle Fusion Trading
Community Model and Oracle Identity Management, in the Oracle Fusion
environment.

Worker

Update Person Search


Keywords

Several attributes of person, employment, and profile records are used as


person-search keywords. This process copies keyword values from the
originating records to the PER_KEYWORDS table, where they are indexed to
improve search performance. When you run the Update Person Search
Keywords process, the whole PER_KEYWORDS table is refreshed; therefore,
you are recommended to run the process at times of low activity to avoid
performance problems.
Submit this process with the After Batch Load parameter set to Yes.

Worker

Optimize Person Search


Keywords Index

Optimizes the index of the person search keywords table. Recommended to


be run after the Update Person Search Keywords process.

Worker

Refresh Manager Hierarchy

For performance reasons, the complete manager hierarchy for each person is
extracted from live data tables and stored in a separate manager hierarchy

55 | HCM DATA LOADER USERS GUIDE

Business Object

Process

Description
table, known as the denormalized manager hierarchy. It ensures that a
person's manager hierarchy is both easily accessible and up to date. The
Refresh Manager Hierarchy process populates the denormalized manager
hierarchy table with latest information after each data load.

Worker

Send Personal Data for


Multiple Users to LDAP

Updates several person-related changes and updates the corresponding OIM


attributes. An update request is sent to OIM which in turn updates the LDAP.
Run this process only when you want user accounts to be created or updated.

Worker

Autoprovision Roles for All


Users

This process provisions and deprovisions roles based on current roleprovisioning rules.

Name Format

Apply Name Formats to


Person Names

Applies the name formats Display Name, List Name, Full Name, and Order
Name to denormalized person name data when a name format is modified or
added.

Organization Tree Node /


Department Tree Node

Tree Flattening Logic

Tree data flattening that improves query performance against the hierarchical
data, especially for hierarchical queries such as roll-up queries.

Organization Tree Node /


Department Tree Node

Tree Audit

Auditing tree-structure metadata verifies that it conforms to all rules and


ensures data integrity. Running an audit allows you to view audit details and
messages and correct any validation errors that the audit detects.

Maintaining Stage Table Data


When you are loading large volumes of data into Oracle Fusion HCM, the HCM Data Loader staging tables can
rapidly increase in size. It is good practice to regularly delete the stage table data for Data Sets that you have
finished processing.
The frequency of deleting stage table data depends on the volume and frequency of your data loads. During data
migration, you may want to consider deleting every large Data Set as you finish with it.
There are two ways to delete HCM Data Loader stage table data. You can:

Delete an individual data set from the Import and Load Data page

Delete multiple data sets using the Delete Stage Table Data page

Deleting a Single Data Set


To delete a single data set from the HCM Data Loader stage tables:
1.

Open the Import and Load Data page (Navigator - Data Exchange - Import and Load Data).

2.

On the Import and Load Data page, select the Data Set you want to delete and click Delete. You can restrict
which data sets are displayed by altering the search criteria.

56 | HCM DATA LOADER USERS GUIDE

Figure 56: Deleting an Individual Data Set

3.

In the Schedule Request dialog box, select Yes in the Delete Source File parameter if you want the source file
on the WebCenter Content server also to be deleted.
Note: If you submitted this Data Set with the Delete Source File parameter set to Yes, then the source file will
already have been purged and selecting Yes here will have no impact.

4.

Click Submit.

5.

The ID of the process that will perform the delete is displayed. Click OK to close the dialog.

You can review the status of the process by navigating to the Delete Stage Table Data page. This page has a
processes table that displays the results of all processes submitted to delete stage table data.

Deleting Multiple Data Sets


To delete Data Set stage table data for multiple data sets or for data sets that conform to specific conditions:
1.

Open the Delete Stage Table Data page (Navigator - Data Exchange - Delete Stage Table Data).

57 | HCM DATA LOADER USERS GUIDE

Figure 57: Delete Stage Table Data

2.

Use the Search criteria to identify which data sets you want to include in the search. By default, all data sets
created by the current user that have not been updated in over a month are listed.

3.

Identify the correct data sets to purge and click Schedule.

Figure 58: Schedule Delete HCM Data Loader Stage Table Data

4.

If you want to delete the source files for the data sets from the WebCenter Content server, ensure the Delete
Source File parameter is set to Yes.

58 | HCM DATA LOADER USERS GUIDE

5.

Click Submit.

You can review the status of the process by refreshing the Processes table at the bottom of the Delete Stage Table
Data page.

Caution: Deleting stage table data is not reversible. Once you have purged a data set you will no longer be able to
report on it or extract errors that were generated for it.

Best Practices
File Shape
When determining your file shape, the following actions are recommended:

Extract only changed attribute values, along with a unique reference to the record being maintained.

Never include both DELETE and MERGE instructions for the same record in the same file. HCM Data Loader
does not guarantee the order in which the file lines are processed.

HCM Data Loader validates every attribute name supplied in METADATA lines in your file. It will negatively impact
performance to include attributes that you do not intend to supply data for.

Data Migration
When creating business objects during data conversion, it is recommended that you deliver one object type per zip
file. For example, create one zip file for jobs, one for grades, one for workers, and so on. You must ensure that you
load individual zip files in the correct order and correct any errors before loading the next object to avoid datareference errors.
For objects containing date-effective components:

Set the HCM Data Loader date-effective maintenance mode to replace by supplying the SET
PURGE_FUTURE_CHANGES Y command at the top of your file.

Supply #NULL for attributes that should have null values when supplying history.

Understand and adhere to the date-effective rules. See the section Date Effective and MCPD Components
on page 24 for more details.

When loading large volumes of data it is recommended that you regularly purge the stage table data for Data Sets
that you no longer need to reference. For more information, see the section Maintaining Stage Table Data on page
56.

Ongoing Interfaces
When reporting incremental changes for ongoing interfaces:

Extract only the changed attribute values, along with a unique reference to the record being updated.

For date-effective records:


o

Set the HCM Data Loader behavior to retain future-dated records by supplying the SET
PURGE_FUTURE_CHANGES N line at the top of your file.

59 | HCM DATA LOADER USERS GUIDE

Note: If you do not supply this command any existing future-dated records for your updated date
range will be purged.
o

Always supply the effective start date of the change.

Supply the #RETAIN tag for the effective end date if you do not want to correct any future dated
records.

Leave the effective end date null if you want a change to roll on until the end of time.
Note: Every attribute specified will be used to correct each record within the specified date-range,
inclluding attributes such as ActionCode.

Leave the effective sequence blank to ensure a new MCPD split is generated with the correct
sequence for a new multiple changes per day record (MCPD).

Supply all business object files in the same compressed zip file. HCM Data Loader ensures they are processed
in the correct order. Referenced data is loaded before the data that references it.

Additional Help
HCM Data Loader Data Set Status Diagnostic
The HCM Data Loader Data Set Status diagnostic is available from the diagnostic framework and provides
additional technical information that can assist you to identify problems. Use this output when the error message
returned does not supply enough information for you to identify a solution. The output can be sent to Oracle Support
to help Oracle identify and resolve your issue.
Report Output
The HCM Data Loader Data-Set Summary is a user-readable HTML output that provides status information, along
with details of every process submitted to process your data set.
For each business object included in your data set, the business object status and file definition is reported. The
following sections are used to provide technical information about your failed records:

Failed and Unprocessed Objects

Child Rows with No Valid Parent

Failed and Unprocessed Rows

Failed and Unprocessed Lines

The HCM Data Loader Data-Set Summary does not include any sensitive data. It provides internal statuses, error
messages and, where recorded, stack trace.
Parameters
It is advisable to restrict the report output to errors that need further investigation. The following parameters are
available to achieve this:
Where this information can be found

Name

Description

**Content ID

A unique reference to a single Data Set

Data Sets table Content ID

**Process ID

A unique reference to a single Data Set

Data Sets table Process ID

60 | HCM DATA LOADER USERS GUIDE

(Import and Load Data user interface)

Business Object Name

The name of a business object in the Data Set. This is


optional though it is recommended if your do not supply
the other parameter values.

Business Objects table Business Object

Message Text

Partial or complete message text. Only records that


failed with this message will be reported.

Messages page Message Text, or


Error Management page Message Text

User Keys

A comma-delimited list of the user key values. Only


records with these user keys will be reported

Error Management Data Structure for Object


errors

Line Numbers

A comma-delimited list of file line numbers. Only the file


lines with these sequence numbers will be reported.

Error Management Data Structure for Line errors.

Maximum Number of
Messages

The maximum number of messages to report. The


minimum is 1 and the maximum possible is 500.

** Either Content ID or Process ID must be supplied to uniquely identify a Data Set.

Submitting the HCM Data Loader Data-Set Summary


To submit the HCM Data Loader Data-Set Summary you must have access to the Diagnostic Dashboard.

Figure 59: Diagnostic Dashboard (Settings and Actions - Troubleshooting - Run Diagnostic Tests)

1.

On the Diagnostic Dashboard (User Name Settings and Actions Troubleshooting List Run
Diagnostic Tests) search for the HCM Data Loader Data-Set Summary test by entering the name in the Test
Name search field and clicking Search.

61 | HCM DATA LOADER USERS GUIDE

Figure 60: Searching for the HCM Data Loader Data-Set Status Diagnostic Test

2.

Select the test by clicking the checkbox to the left of the test name and click Add to Run.
The HCM Data Loader Data-Set Summary appears in the Choose Tests to Run and Supply Inputs section.

Figure 61: Selecting the HCM Data Loader Data-Set Status Diagnostic Test

3.

To review the parameter values, click the Click to Supply or Edit Input Parameters button.

Figure 62: Supply or Edit Input Parameters

4.

Review the available parameters and provide values to target the output for the data you need to report.

62 | HCM DATA LOADER USERS GUIDE

Figure 63: Enter the Parameter Values

5.

Enter the parameter values and click OK. The parameters window closes.

6.

Enter a name in the Run Name field to name your test run. Alternatively, leave this field blank for the
application to generate a name.

7.

Click Run to submit the HCM Data Loader Data-Set Summary.

Figure 64: Submitting the HCM Data Loader Data-Set Summary

8.

Click OK in the confirmation dialog box displaying the test Run name.

9.

Click the Display Latest Test Run Status Information link to retrieve the run results.

Figure 65: Reviewing the HCM Data Loader Data-Set Summary Test Run Status

10. Expand the test hierarchy to see the HCM Data Loader Data-Set Status output and click the Report icon to
open the report.
The output can be saved and attached to a service request if you need support from Oracle.

63 | HCM DATA LOADER USERS GUIDE

Glossary
Term

Description

attribute

A data field in a business-object component.

business object

A data structure that represents a real-world business artifact, such as worker or job. Comprises one or more
business-object components in a hierarchical structure.

child component

A component of a business object that occurs below the top level of the component hierarchy.

component

A logical grouping of attributes in a business object. A component has a unique ID that enables it to be
maintained independently of the business object to which it belongs.

data set

A zip file containing one or more .dat files to be loaded.

date-effective

Records that store the history of a component. Date-effective components do not have any gaps in their
history. Examples of date-effective components are Job, Contract, Assignment Manager.

discriminator

In an HCM Data Loader .dat file, the value that identifies the business-object component to be loaded.

file-line instruction tag

In an HCM Data Loader .data file, the value that identifies the purpose of a file line. Valid tags are: COMMENT,
DELETE, METADATA, MERGE, and SET.

file template

The data (.dat) file supplied for each integration-enabled business object. It contains a METADATA file line for
each business-object component showing all attributes of the component. File templates are also supplied for
translation-object components.

GUID

Globally Unique Identifier.

integration-enabled object Business object that can be loaded using HCM Data Loader and for which a Logical Object interface method
exists.
logical object

The grouping of related data lines to form one occurrence of the object, such as the Job Sales Consultant.

MCPD

Some date-effective components support reporting Multiple Changes Per Day (MCPD). These allow different
attribute values on the same record to be changed and stored as separate updates, this is achieved by having
an effective sequence for each change on the same effective start date. Examples of MCPD components are
Work Terms and Assignment.

METADATA file line

In an HCM Data Loader .dat file, the file-instruction line that defines, for a business-object component, the
attributes to be loaded and their order.

natural key

Alternative term for user key.

object

See business object.

OIM

Oracle Identity Management.

parent component

A component of a business object that occurs at the top of the component hierarchy.

primary key

A key made up of the attributes that uniquely identify a row.

simple-dated

Components that have a date range during which they are valid, typically date from and date to. These
components can have gaps in the date records, unlike date-effective components. Examples of simple dated
components are Person Address, Person Email.

source-system ID

Source-system owner and ID values for integration-enabled objects.

source-system reference

Source system table name, column name, and attribute values optionally included in a business-object
component to be loaded.

surrogate ID

Oracle Fusion internal system ID for a business-object component.

user key

A key formed of real-world attributes, such as person name or job code.

64 | HCM DATA LOADER USERS GUIDE

Oracle Corporation, World Headquarters

Worldwide Inquiries

500 Oracle Parkway

Phone: +1.650.506.7000

Redwood Shores, CA 94065, USA

Fax: +1.650.506.7200

CONNECT W ITH US

blogs.oracle.com/oracle
facebook.com/oracle
twitter.com/oracle
oracle.com

Copyright 2014, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only, and the
contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other
warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or
fitness for a particular purpose. We specifically disclaim any liability with respect to this document, and no contractual obligations are
formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any
means, electronic or mechanical, for any purpose, without our prior written permission.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and
are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are
trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. 0216
HCM Data Loader Users Guide
February 2016

65 | HCM DATA LOADER USERS GUIDE