How to load data into Oracle Fusion HCM with HDL (HCM Data Loader)

Every Oracle Fusion HCM project loads data in bulk at some point: workers from the old system during migration, salary changes after an appraisal cycle, new email addresses after a rebrand. In Fusion HCM the tool for this is HCM Data Loader, almost always shortened to HDL. It is also one of the most common topics in Fusion HCM technical interviews.

This guide explains how an HDL file is built, how to load one, and how to read the errors when it fails, which it will the first few times.

HDL, HSDL and FBDI: which is which?

Fusion has more than one bulk-loading route, and people mix them up.

• HDL (HCM Data Loader) loads HCM data such as workers, assignments, salaries and absences from pipe-delimited .dat files that you zip and upload. It is the standard route for HCM.
• HSDL (HCM Spreadsheet Data Loader) lets a business user load the same objects from a spreadsheet. It uses HDL underneath, so the same business objects and rules apply.
• FBDI (File-Based Data Import) is the bulk route for Financials, Procurement and Supply Chain, with CSV files and interface tables. We covered it in loading data into Fusion with FBDI from OIC. It is not used for HCM objects.

If the data is about people and their jobs, the answer is HDL.

What an HDL file looks like

An HDL file is plain text, named after the business object it loads, such as Worker.dat. Values are separated by the pipe character |. Two kinds of line do most of the work:

• A METADATA line names a component of the object and lists the attributes that the following lines will supply, in order.
• A MERGE line supplies one record's values in that same order. MERGE creates the record if it does not exist and updates it if it does.

Here is the shape, using the email component of a worker:

METADATA|PersonEmail|SourceSystemOwner|SourceSystemId|PersonId(SourceSystemId)|DateFrom|EmailType|EmailAddress
MERGE|PersonEmail|LEGACY|EMAIL_1001|PER_1001|2026/10/01|W1|asha.k@example.com
MERGE|PersonEmail|LEGACY|EMAIL_1002|PER_1002|2026/10/01|W1|rohan.m@example.com

A few things to notice:

• The second value on every line repeats the component name, so HDL knows which METADATA line it belongs to. One Worker.dat can hold several components, such as names, emails and assignments, each with its own METADATA line.
• Dates are written as YYYY/MM/DD by default.
• W1 is the email type code for a work email.
• PersonId(SourceSystemId) points at the parent person by that person's own source key. This is how a child record finds its parent without knowing Oracle's internal ID.

Lines starting with COMMENT are ignored, which is handy for notes in a file you will reuse. The file is then zipped, and the zip is what you upload.

Keys: how HDL knows which record you mean

Every MERGE has to identify its record, and this is the part that takes longest to understand. HDL accepts several kinds of key:

• Source keys: a pair of SourceSystemOwner and SourceSystemId that you choose, such as LEGACY and PER_1001. This is what most projects use, because the IDs from the old system can be used directly and stay stable across loads.
• User keys: values people already recognise, such as a person number.
• Oracle's own IDs: the surrogate ID or GUID that Fusion generated. These work, but you have to look them up first.

Pick one style per project and keep to it. The usual advice is source keys, because a second load of the same file then updates the records from the first load instead of creating duplicates.

A source system owner such as LEGACY is not free text. It must be defined as a value of the HRC_SOURCE_SYSTEM_OWNER lookup first, in Setup and Maintenance under the common lookups task. A load that uses an owner nobody defined fails on every line.

Finding the right attributes

Do not guess attribute names. Fusion documents every business object it can load, inside the application:

1. Go to My Client Groups > Data Exchange.
2. Open View Business Objects.
3. Search for the object, for example Worker, and open it.

You will see the object's components as a hierarchy (for Worker: names, emails, addresses, work relationships, assignments and more) and, for each component, its attributes, which of them are required, and which keys it supports. The attribute names here are exactly what goes on your METADATA line.

Start a practice file with only the required attributes and add more once that loads cleanly.

Loading the file

On the same Data Exchange page:

1. Open Import and Load Data.
2. Click Import File, choose your zip and submit it.
3. HDL runs in two stages. Import reads the file, checks the format and moves the lines into staging tables. Load validates each record against the application's rules and creates or updates the real records.
4. Refresh the page to follow progress. Each submitted file appears as a data set, with counts of objects imported, loaded and in error.

A data set can partly succeed: 98 workers load and 2 fail. The ones that loaded stay loaded.

Reading and fixing errors

Click the data set and drill into the business object to see each failed record with its message. Errors fall into two groups, and they point to different fixes:

• Import errors mean the file itself is wrong: an unknown attribute name, a line with more or fewer values than its METADATA line, a wrong date format, or a component name that does not match. Fix the file.
• Load errors mean the file is readable but the data breaks a rule: a parent person that does not exist, a value that is not in a lookup, a date before the record's start date, or a missing required attribute. Fix the data, or load the missing parent first.

After a fix, load the corrected file again. With source keys and MERGE, records that already loaded are simply updated, so you do not have to strip them out first.

A useful habit when practising: change one thing at a time. Load a single record, read the result, then grow the file. Debugging 200 failed lines at once teaches very little.

Who can run HDL

Data Exchange is not open to every Fusion user. It is normally given through the Human Capital Management Integration Specialist role, or a custom role built from it. If your login cannot see the Data Exchange tasks, a user with Security Console access can assign the role. Our post on Security Console access explains what that access involves on a practice instance.

What to practise next

Once a simple email load works, the same steps take you a long way:

• Load a small set of new workers with names, work relationships and assignments, then check them in Person Management.
• Change their assignments with a later effective date and see how HDL handles date-effective history.
• Load the same file twice and confirm that the second load updates rather than duplicates.
• Pull the loaded data back out with an OTBI analysis or a BI Publisher report to reconcile what went in.

All of this needs a Fusion instance where you can open Data Exchange and look at what you loaded. Our Fusion plans come in refresh and non-refresh versions, with or without Security Console.

See the Oracle Fusion plans →