1. Create and maintain data with HCM Data Loader
  2. Get started with HCM Data Loader files

Get started with HCM Data Loader files

HCM Data Loader (HDL) files provide a flexible way to create and maintain application data in bulk. Understanding how HDL files are structured and how their instructions are interpreted provides the foundation for building files that correctly identify and process business-object data.

About this playbook

Use this playbook to create HCM Data Loader files that:

  • Create new application data;
  • Update existing records;
  • Add child records to existing business objects;
  • Reference parent and foreign objects correctly;
  • Delete individual records or complete logical objects;
  • Provide reconciliation information for monitoring and reporting.

This playbook also explains the core HDL file concepts needed to perform those tasks, including file structure, METADATA and data-line instructions, source and user keys, source-system owners, parent and foreign references, partial updates, null values, reconciliation values, and ordinary record deletion. You don't need separate playbooks for these concepts.

HDL uses flexible, pipe-delimited .dat files. Include only the business-object components and attributes required for the task, rather than supplying a complete representation of every object.

Before creating a file, use HDL-01 — Understand HCM Data Loader business objects to identify the correct file name, component discriminators, attributes, supported actions, and available keys.

Understand the basic HDL file structure

An HDL load consists of one or more .dat files compressed into a .zip file.

Each .dat file represents a single business-object hierarchy. For example:

  • Worker.dat
  • Job.dat
  • Grade.dat
  • ElementEntry.dat

All components belonging to that hierarchy are supplied in the same .dat file. A Job.dat file can therefore contain Job, Job Valid Grade, Job Evaluation, and other Job child components.

A ZIP file can contain one or more business-object .dat files.

You can package related business objects together when that simplifies dependency processing. HDL imports the files and loads business objects in dependency order so referenced data can be available before the data that references it.

Use one business object per ZIP when testing a new file shape, so that import or load issues are easier to isolate.

During large data migrations, use one business object per ZIP when loading a very large file for that object. This keeps the data set focused and simplifies monitoring, error handling, and recovery.

For smaller or logically related loads, multiple business-object files can be included in the same ZIP where appropriate.

File construction rules

Follow these construction rules when creating and packaging HDL data files to ensure that the files can be recognized and processed correctly.

  • Use the exact business-object file name identified in View Business Objects.
  • Business-object file names are case-sensitive.
  • Save files using UTF-8.
  • Don't place .dat files inside folders in the ZIP.
  • The default field delimiter is the pipe character (|).

Understand the HDL file instructions

HDL uses line instructions to define the structure of the data and specify how records are processed. The instruction you use determines whether a line defines metadata, creates or updates data, deletes data, changes processing behavior, or provides a comment.

Instruction Purpose
METADATA Defines the component and attributes supplied by subsequent data lines
MERGE Creates a record or updates an existing record
DELETE Removes an existing record
SET Changes default processing for the file
COMMENT Adds a comment

METADATA, MERGE, and DELETE lines also include a file discriminator, which identifies the component in the business-object hierarchy.