Build HCM Data Loader files

Building an HDL file involves defining the data to supply, specifying the required processing instruction, and uniquely identifying each record. Use the appropriate attributes and keys so that HDL can determine whether to create, update, or identify existing application data.

Define the attributes with METADATA

Every component that you supply in a file requires a METADATA line.

For example:

The values mean:

• METADATA — the instruction;
• JobFamily — the file discriminator;
• the remaining values — the component attributes and the order in which data will be supplied.

A corresponding data line must provide values in that same order:

You can define only one METADATA layout for each component within a file. Include only the attributes required for the scenario.

Use the METADATA Attribute values shown in View Business Objects rather than display labels.

Use MERGE for both creates and updates

HDL has one instruction for creating or updating application records:

You don't specify CREATE or UPDATE.

HDL identifies the record using the keys supplied on the line and then determines whether it must create a new record or update an existing one.

For example:

If the identified Job doesn't exist and the Job component supports Create, HDL creates it.

If it already exists and the component supports Update, HDL updates it.

This is distinct from the Supported Actions information described in Understand HCM Data Loader business objects. Supported Actions tells you whether the component permits Create, Update, and Delete. MERGE is the file instruction used for both Create and Update.

For updates supply only what changed

Keep update files focused on the values that need to change. For an existing record, provide:

• Attributes to identify the record
• Supply the attributes whose values you want to update

Attributes omitted from the file retain their existing values. Avoid including unchanged attributes unnecessarily.

Use NULL to Remove an Existing Value

A blank field doesn't explicitly set an existing attribute to null.

To clear an existing value, supply:

Don't confuse:

• attribute omitted from METADATA — leave the current value unchanged;
• blank value — doesn't mean “clear this value”;
• #NULL — explicitly set the attribute to null.

Choose how to identify each record

Every MERGE or DELETE record must be identified uniquely. Choose a supported key type based on whether you're creating a record, updating an existing record, and how the record is identified by the source or application.

HDL supports four key types:

Key type	Create	Update	Typical use
Source key	Yes	Yes	Recommended for integrations and migrations
User key	Yes	Usually	Business-visible natural key
GUID	No	Yes	Existing integration-enabled records
Surrogate ID	No	Yes	Existing records where internal ID is available

When you supply more than one supported key, HDL resolves them in this order:

• GUID
• source key
• surrogate ID
• user key

HDL doesn't cross-validate multiple supplied keys. If a GUID identifies one record and a supplied source key identifies another, the GUID wins and HDL doesn't raise an inconsistency error merely because the keys disagree.

For that reason, avoid supplying competing key types unless there's a specific need.

Prefer source keys for integrations

Source keys provide a stable way to identify records created or maintained by an external source system. Each source key combines the owner of the source data with an identifier that's unique within that source.

A source key consists of:

• SourceSystemOwner
• SourceSystemId

For example:

Oracle recommends source keys where possible, particularly for integrations where another system remains the system of record. Source keys are stable even when user-facing key values change.

Before using your own SourceSystemOwner value, add it to the HRC_SOURCE_SYSTEM_OWNER lookup.

User keys may still be required on create

Even when a source key identifies the record, some user-key attributes are still functionally required when creating the application record.

If you supply both source and user keys, the source key is the identifier HDL uses for matching.

Understand default source keys

If you create a record without supplying a source key, HDL generates a default source key:

• SourceSystemOwner = FUSION
• SourceSystemId = the generated surrogate ID

You can later use or replace this source key.

For planned integrations, however, don't rely on default source keys when you already have a stable source-system identifier. Supplying your own source key from the beginning normally makes later maintenance and cross-object references easier.

Update a source key when necessary

Don't change source-key values simply by changing SourceSystemOwner or SourceSystemId on the normal business-object MERGE line.

To replace an existing source key, use the Source Key business object and a SourceKey.dat file.

For example:

You can update both default source keys and source keys that you originally supplied for integration-enabled objects.

Use user keys when they're the appropriate identifier

A user key is made up of one or more business-visible values.

For example, Job may be identified by:

• Job Code; and
• Set Code.

All attributes that form the selected user key must be supplied when that key is being used to identify the record.

Be careful when user key values can change

Some user keys contain values such as names or codes that customers can change.

That makes them less suitable as long-term integration identifiers. Some objects can't reliably be updated using only a changed user key.

Where possible, use a source key for ongoing maintenance, particularly when:

• user-key values can change;
• values can be translated;
• historical data is involved;
• another system remains the system of record.