HDL vs HSDL in Oracle HCM Cloud

 

✅ HSDL vs HDL in Oracle HCM Cloud – What’s the Difference? (Complete Guide)

If you work on Oracle HCM Cloud, you’ve definitely heard about HDL and HSDL. Many people get confused because both tools are used for loading and updating HCM data — but they are designed for different purposes.

In this blog, you will understand:

• What is HDL and where it is used

• What is HSDL and why it is business-friendly

• Key differences between HSDL vs HDL

• Which tool is best for conversions, integrations, and ongoing maintenance

• Best practices and recommendations

---

📌 What is HDL (HCM Data Loader)?

HDL (HCM Data Loader) is Oracle’s powerful bulk data loading tool used mainly for:

✅ Initial data migration
✅ Large volume transactions
✅ Complex object hierarchy loads
✅ Background processing

Key Features of HDL

• File-based loader using .dat files

• Requires object-level technical understanding

• Supports full object structures like:

  • Work Relationships

  • Work Terms

  • Assignments

  • Person Details

  • Payroll, Absence, Benefits (depends on object)

• Best suited for implementation and mass updates

💡 Ideal for:
Conversions, integrations, and large-scale changes.

---

📌 What is HSDL (HCM Spreadsheet Data Loader)?

HSDL (HCM Spreadsheet Data Loader) is a spreadsheet-based tool built on top of HDL. It is designed for business-friendly data entry.

Key Features of HSDL

• Uses Excel templates

• Validates data before submission

• User-friendly interface

• Faster for small to medium data loads

• No need to manually write .dat files

• Suitable for functional users

• Limited compared to full HDL capability

💡 Ideal for:
Quick updates, ongoing maintenance, and functional team usage.

---

🔥 HDL vs HSDL – Key Differences (Comparison Table)

Feature	HDL	HSDL
Format	.dat files	Excel templates
Skill Required	Technical + object knowledge	Functional / business friendly
Best For	Conversions + integrations	Quick operational updates
Data Volume	High volume supported	Small to medium volume
Complex Hierarchy	Fully supported	Limited
Validations	Mostly during load	Pre-validation in Excel
Processing	Background	Submission through spreadsheet
Error Handling	HDL logs + stage tables	Spreadsheet validation + errors
Usage	Implementation team	Business users + HR operations

---

✅ When to Use HDL?

Use HDL when you need:

• Initial employee conversion

• Mass updates (10K+ records)

• Complex object loads (Worker + Assignment + Manager + Payroll objects)

• Integrations (scheduled automated file loads)

• Data migration for go-live

📌 Example HDL Use Cases:

• Worker conversion using Worker.dat

• Loading seniority hours

• Loading absence entries in bulk

• Loading organization, jobs, grades, locations

• Payroll-related objects

---

✅ When to Use HSDL?

Use HSDL when you need:

• Quick business updates

• Ongoing maintenance

• Smaller loads

• User-friendly templates

• HR team managed loads

📌 Example HSDL Use Cases:

• Updating phone numbers

• Updating addresses

• Updating manager (small volume)

• Updating cost center assignment

• Updating personal details

---

⭐ My Recommendation (Best Practice)

✅ Use HDL for:

• Implementations

• Integrations

• Mass loads

• Conversions

• Complex hierarchy loads

✅ Use HSDL for:

• Quick business-driven updates

• Day-to-day operational loads

• HR/functional team maintenance

📌 Both tools are essential in Oracle HCM Cloud.
Choosing the right one improves productivity and reduces errors.

✅ Flow Chart : 

HDL vs HSDL

---

🧠 Real Project Tip (Very Important)

During conversions, teams often load Worker data in multiple batches.

In that scenario:

• HDL is always the best option

• You can control performance by disabling auto-trigger processes

• You can run post conversion ESS jobs once at the end

(Example: Refresh Manager Hierarchy, Update Person Search Keywords)

---

🔗 Internal Links 

• Oracle HDL Worker Data Load (Complete Guide) → (worker HDL link)

• HDL Seniority Date Adjustments Examples → (seniority date post link)

• HDL Seniority Hours Template + Examples → (seniority hours post link)

• HDL Absence Entry Template → (Absence entry post link)

• Post Conversion ESS Jobs After HDL (Best Practices) → (ESS jobs post link)

---

❓ FAQ – HSDL vs HDL in Oracle HCM Cloud

Q1. Is HSDL different from HDL?

HSDL is built on top of HDL. It uses Excel templates and converts the data into HDL format internally.

Q2. Which is better for conversion – HDL or HSDL?

HDL is better for conversions because it supports large volume and complex object hierarchy loads.

Q3. Can HSDL load Worker object like HDL?

HSDL supports many worker-related templates, but HDL gives full control and supports complex dependencies.

Q4. Do we need technical knowledge for HSDL?

Not much. HSDL is designed for functional users and HR operations.

Q5. Why is HDL preferred for integrations?

Because HDL can be automated using file-based loads, scheduled processes, and it supports large datasets.

Q6. Which tool gives better error reporting?

HDL provides detailed logs, stage tables, and error records. HSDL provides template validation and simplified errors.

Q7. Can we use both HDL and HSDL in the same project?

Yes. Most Oracle HCM implementations use HDL for conversion and HSDL for business maintenance.

---

💬 Feedback & Comments

Did you use HDL or HSDL in your project?

Share in the comment section:

• Which object you loaded (Worker, Absence, Payroll, etc.)

• Any error you faced

• Whether you used HDL, HSDL, or both

I reply to all comments with solutions and sample templates. 🙌

Examples of Loading Seniority Hours using Oracle HCM HDL

 

✅ Oracle HCM HDL: Load Seniority Hours (Create / Update / Delete) – Worker.dat Examples

For hourly paid workers, many organizations calculate seniority in hours instead of days. To support accurate seniority calculations in Oracle Fusion HCM, you can load seniority hours using HCM Data Loader (HDL).

In this post, you’ll learn how to create, update, and delete Seniority Hours using HDL with both:

• Source Keys (SourceSystemOwner + SourceSystemId)

• User Keys (AssignmentNumber + FromDate)

---

⭐ What are Seniority Hours in Oracle HCM?

Seniority Hours represent the number of hours worked that contribute to a worker’s length of service calculation.

This is mainly used for:

• Hourly paid workers

• Union or bargaining unit employees

• Time & Labor based seniority

• Payroll-driven seniority hours

---

📌 Sources of Seniority Hours Data

You can obtain seniority hours from:

• Oracle Time and Labor (OTL)

• Oracle Global Payroll

• A third-party time system

• External payroll system

---

✅ Important Prerequisites (Must Read)

Before loading seniority hours:

1) Assignment must exist

The assignment must already exist in Oracle HCM.

2) Assignment must be active

The assignment must be active as of the FromDate of the seniority hours.

3) Worker must be hourly paid

The worker must be paid hourly for the entire period you are loading hours.

---

🔍 How to Verify Loaded Seniority Hours

After loading, you can verify data from:

Option 1: UI Page

✅ Manage Seniority Dates page (worker level)

Option 2: Database Query

For multiple workers:
✅ Query table: PER_SENIORITY_HOURS

---

🧾 HDL Object Used

Seniority Hours are loaded using the HDL component:

✅ SeniorityHour (Worker.dat)

---

📂 File Name

📌 File Name:
Worker.dat

---

🔥 Examples of Loading Seniority Hours (HDL)

---

1) Create Seniority Hours Using Source Keys

METADATA|SeniorityHour|AssignmentId(SourceSystemId)|ToDate|FromDate|Hours
|SourceSystemOwner|SourceSystemId
MERGE|SeniorityHour|1031101972|2001/01/01|2000/01/01|500|VISION|UT00214

📌 Notes:

• SourceSystemOwner + SourceSystemId uniquely identify the record

• This is best for integrations from external systems

---

2) Create Seniority Hours Using User Keys

The user keys for SeniorityHour are:

✅ AssignmentNumber + FromDate

METADATA|SeniorityHour|AssignmentNumber|ToDate|FromDate|Hours
MERGE|SeniorityHour|E00214|2001/01/01|2000/01/01|500

---

✏️ Updating Seniority Hours

---

3) Update Seniority Hours Using Source Keys

METADATA|SeniorityHour|AssignmentId(SourceSystemId)|ToDate|FromDate|Hours
|SourceSystemOwner|SourceSystemId
MERGE|SeniorityHour|1031101972|2001/01/01|2000/01/01|600|VISION|UT00214

📌 The update happens because the same SourceSystemOwner + SourceSystemId exists.

---

4) Update Seniority Hours Using User Keys

METADATA|SeniorityHour|AssignmentNumber|ToDate|FromDate|Hours
MERGE|SeniorityHour|E00214|2001/01/01|2000/01/01|600

📌 Oracle identifies the record using:

• AssignmentNumber

• FromDate

---

🗑️ Deleting Seniority Hours

---

5) Delete Seniority Hours Using Source Keys

METADATA|SeniorityHour|AssignmentId(SourceSystemId)|SourceSystemOwner|SourceSystemId
DELETE|SeniorityHour|1031101972|VISION|UT00214

---

6) Delete Seniority Hours Using User Keys

METADATA|SeniorityHour|AssignmentNumber|ToDate|FromDate|Hours
DELETE|SeniorityHour|E00214|2001/01/01|2000/01/01|500

---

✏️ Updating Seniority Hours

✅ Example 1: Load Seniority Hours for Multiple Periods (Same Assignment)

Use this when you want to load hours month-wise / week-wise.

METADATA|SeniorityHour|AssignmentNumber|FromDate|ToDate|Hours
MERGE|SeniorityHour|E00214|2024/01/01|2024/01/31|168
MERGE|SeniorityHour|E00214|2024/02/01|2024/02/29|160
MERGE|SeniorityHour|E00214|2024/03/01|2024/03/31|176

🔐 How to Lock and Unlock User Accounts Using HDL in Oracle Fusion HCM (Step-by-Step Guide)

 Step-by-Step Instructions for Administrators

Locking and unlocking user accounts is a common requirement for Oracle Fusion HCM administrators. Whether an employee has left the organization, access must be temporarily restricted, or security compliance requires action, Oracle HCM provides a simple way to lock/unlock accounts using HCM Data Loader (HDL).

In this blog, you’ll learn how to lock and unlock user accounts using HDL, along with the required HDL file format, steps to load it, and the process required to apply changes.

---

✅ Prerequisites

Before you begin, make sure you have:

• Access to perform HDL operations

• Valid Person Numbers for users you want to lock/unlock

• Access to run required ESS process (Send Pending LDAP Requests)

• Admin privileges to verify the user status

---

🔒 Locking a User Account Using HDL

To lock a user account in Oracle Fusion HCM, you need to set the Suspended flag = Y in the User HDL file.

---

Step 1: Prepare the HDL File (User.dat)

Use the following format:

METADATA|User|PersonNumber|Suspended
MERGE|User|<Enter Person Number>|Y

Example:

METADATA|User|PersonNumber|Suspended
MERGE|User|E12345|Y

---

Step 2: Save and Compress the File

1. Save the file as: User.dat

2. Compress it into a ZIP file:

   • Example ZIP name: LockUser.zip

---

Step 3: Upload the HDL File

Navigate to:

My Client Groups → Data Exchange → HCM Data Loader → Import and Load

Then:

1. Click Import File

2. Upload the ZIP file

3. Submit the load

---

Step 4: Run Required Process (Very Important)

After HDL loads successfully, you must run:

✅ Send Pending LDAP Requests

This process applies the account changes to the LDAP directory.

---

Step 5: Verify User is Locked

Go to:

Setup and Maintenance → Create Implementation User

Search using the person number / username and confirm the account is locked.

---

🔓 Unlocking a User Account Using HDL

To unlock a user account, set the Suspended flag = N.

---

Step 1: Prepare the HDL File (User.dat)

METADATA|User|PersonNumber|Suspended
MERGE|User|<Enter Person Number>|N

Example:

METADATA|User|PersonNumber|Suspended
MERGE|User|E12345|N

---

Step 2: Save and Compress the File

1. Save as User.dat

2. Zip it:

   • Example ZIP name: UnlockUser.zip

---

Step 3: Upload the HDL File

Navigate to:

My Client Groups → Data Exchange → HCM Data Loader → Import and Load

1. Click Import File

2. Upload ZIP file

3. Submit

---

Step 4: Run Required Process (Very Important)

After HDL loads successfully, you must run:

✅ Send Pending LDAP Requests

This process applies the account changes to the LDAP directory.

---

Step 5: Verify User is Unlocked

Go to:

Setup and Maintenance → Create Implementation User

Confirm the user is now active/unlocked.

---

⭐ Best Practices and Recommendations

• Always double-check the Person Number before locking/unlocking

• Keep an audit log of user account changes

• Notify users when their account is unlocked (unless security policy says otherwise)

• Regularly review locked accounts to avoid unnecessary access restrictions

• Run Send Pending LDAP Requests after every HDL user suspension change

---

⚠️ Common Issues and Troubleshooting

Issue 1: HDL loads successfully but user is still active

✅ Solution:
Run Send Pending LDAP Requests process.

---

Issue 2: Person number not found

✅ Solution:
Confirm the person exists and has a user account created.

---

Issue 3: Changes not reflecting immediately

✅ Solution:
LDAP sync may take time. Wait 5–10 minutes after process completion.

---

📌 FAQ

1. Can we lock a user account in Oracle Fusion HCM using HDL?

Yes. You can lock a user account using HDL by setting the field Suspended = Y in User.dat.

---

2. What HDL object is used to lock/unlock users?

The HDL object used is:

User

---

3. What does the Suspended flag mean in HDL?

• Y = user is locked/suspended

• N = user is active/unlocked

---

4. Do we need to run any process after loading HDL?

Yes. You must run:

✅ Send Pending LDAP Requests

---

5. Where can we verify if a user is locked/unlocked?

You can verify in:

Setup and Maintenance → Create Implementation User

---

6. Can we lock multiple users in one HDL file?

Yes. Add multiple MERGE lines:

METADATA|User|PersonNumber|Suspended
MERGE|User|E1001|Y
MERGE|User|E1002|Y
MERGE|User|E1003|Y

---

7. Is locking a user same as terminating an employee?

No. Locking only disables login access. Termination affects employment and HR records.

---

✅ Conclusion

Locking and unlocking user accounts using HDL is one of the fastest and cleanest methods available for Oracle Fusion HCM administrators. By updating the Suspended flag and running Send Pending LDAP Requests, you can manage user access securely and efficiently.

 

HDL Template for Dependent Enrollment in Oracle Fusion HCM (DependentEnrollment.dat)

(Using DependentEnrollment.dat)

Introduction

In Oracle Fusion HCM, Dependent Enrollment is a critical step in Benefits processing when employees opt for Spouse, Child, or Family coverage. Dependents must be correctly created, linked, and enrolled for benefits eligibility and premium calculation.

Oracle provides HCM Data Loader (HDL) to bulk load dependent enrollments efficiently using the DependentEnrollment.dat file.

This blog explains a complete end-to-end process for loading Dependent Benefit Enrollments with a working HDL template, prerequisites, common issues, and validation steps.

---

When to Use DependentEnrollment.dat

Use DependentEnrollment.dat when:

• Enrolling Spouse or Child under an employee’s benefit plan

• Processing Family or Dependent coverage

• Loading dependents during New Hire or Open Enrollment

• Migrating benefit enrollments from a legacy system

• Performing mass updates for dependent benefits

---

Prerequisites

Before loading dependent enrollments, ensure the following data is already available in Fusion HCM:

Employee Prerequisites

• Employee record exists and is active

• PersonNumber is valid

• Employee is already enrolled in a Benefit Program

• Life Event (New Hire / Open Enrollment / Marriage) is processed or available

• Load the Particiapant Enrollment using ParticipantEnrollment.dat. Click  Here for more details. 

Dependent Prerequisites

• Dependent person record exists

• Dependent is linked to employee via Contact.dat

• Dependent Date of Birth (DOB) is populated

• Relationship type (Spouse, Child, etc.) is valid and effective

Benefits Configuration

• Benefit Program, Plan, and Option are configured

• Plan allows dependent coverage

• Eligibility Profiles include dependents

• Coverage values are correctly defined

Date & Security

• Effective Date aligns with life event window

• User has HCM Data Loader and Benefits access

---

File Name

DependentEnrollment.dat

---

HDL File Structure Overview

The file typically includes:

1. DependentEnrollment – Links dependent to the employee’s benefit plan

---

Section: DependentEnrollment

Purpose

This section enrolls a dependent under an employee’s selected benefit plan and option.

---

Metadata Definition

METADATA|DependentEnrollment|PersonNumber|BenefitRelationship|
EffectiveDate|LifeEvent|LifeEventOccuredDate

---

Sample Data

MERGE|DependentEnrollment|7628|DFLT|2026/01/12|New Hire|2026/01/1

---

🔹 Important: Plan and Option must exactly match Fusion setup.

---

Complete Sample DependentEnrollment.dat File

METADATA|DesignateDependent|Plan|Program|Option|DependentPersonNumber|
LineNumber|PersonNumber|DependentLastName|DependentFirstName|
OriginalEnrollmentDate

Sample Data

MERGE|DesignateDependent|Medical PPO|Choice Program (Core)|
Participant Plus One|7629|1|7628|XXTEST|Reena|2026/01/12

---

HDL Load Steps

1. Navigate to Data Exchange → HCM Data Loader

2. Upload DependentEnrollment.dat

3. Submit the process

4. Monitor HDL stages until status shows Succeeded

---

Validation After Load

After the load completes:

1. Navigate to Benefit Administration

2. Search for the employee

3. Verify:

   • Dependent appears under selected plan

   • Coverage reflects dependent inclusion

   • Effective dates are correct

---

Common Errors & Troubleshooting

Dependent HDL Error

---

Best Practices

• Always load Person and ContactRelationship before DependentEnrollment

• Validate dependent DOB and relationship types

• Keep Effective Dates aligned with life events

• Test loads in lower environments before PROD

• Use exact Plan and Option names

Conclusion

Dependent enrollment is a crucial part of Benefits administration in Oracle Fusion HCM. Using DependentEnrollment.dat through HDL ensures accurate, scalable, and efficient processing of dependent benefit enrollments.

By following this end-to-end approach, you can avoid common issues and confidently manage dependent coverage during New Hire, Open Enrollment, and life event scenarios.

The values {attributes} are not valid for the attribute BankAccountId

---

Error While Loading PersonalPaymentMethod Using HCM Data Loader

Introduction

Oracle Fusion HCM HCM Data Loader (HDL) is commonly used to load payroll-related data such as Personal Payment Methods. However, while loading PersonalPaymentMethod.dat, you may encounter validation errors related to bank account resolution.

One of the most common errors is:

HRC-1035539 – The values {attributes} are not valid for the attribute BankAccountId

This blog explains why this error occurs, the root causes, and multiple solutions to fix it using real project scenarios.

Cause Analysis

Cause 1: Missing BankAccountType

Consider a scenario where two bank accounts exist for the same person:

• Bank Account 1 → No BankAccountType

• Bank Account 2 → Has BankAccountType

In this case:

• If you refer to Bank Account 1, HDL can resolve it without BankAccountType

• If you refer to Bank Account 2, BankAccountType becomes mandatory

❗ If the existing ExternalBankAccount has a value for BankAccountType, it must be provided in PersonalPaymentMethod.dat.

---

Cause 2: Invalid Bank Account Attribute Combination

The system is unable to identify a valid BankAccountId because the values provided for:

• BankName

• BankCountryCode

• BankAccountNumber

• BankAccountType

• BankBranchName

• BankBranchNumber

do not match any existing External Bank Account in Oracle Fusion.

---

Solution 1: Provide BankAccountType When Required

If the External Bank Account already has a BankAccountType, then it must be passed in PersonalPaymentMethod.dat.

Best Practice

✔ Always provide BankAccountType when multiple bank accounts exist
✔ Ensure the value exactly matches what exists in Fusion

This ensures unique resolution of ExternalBankAccount.

---

Solution 2: Validate Bank Account Details in Fusion

Ensure that the following attributes in PersonalPaymentMethod.dat match an existing bank account:

• Bank Name

• Bank Country Code

• Bank Account Number

• Bank Account Type

• Bank Branch Name

• Bank Branch Number

If any of these values are incorrect, Fusion will fail to resolve the BankAccountId.

---

Query to Validate Bank Account Data

Use the below SQL query to verify whether the bank account exists and matches the provided details:

SELECT
    ppr.payroll_relationship_id payrollrelationshipid,
    ppr.person_id personid,
    h.party_id partyid,
    eba.bank_account_id bankaccountid,
    eba.bank_account_num bankaccountnumber,
    eba.bank_id bankid,
    eba.bank_name bankname,
    eba.bank_number banknumber,
    eba.branch_number branchnumber,
    eba.branch_id branchid,
    eba.bank_branch_name branchname,
    eba.eft_swift_code eftswiftcode,
    eba.bank_home_country homecountry,
    eba.bank_account_type bankaccounttype
FROM
    pay_bank_accounts eba,
    iby_account_owners ebao,
    hz_parties h,
    pay_pay_relationships_dn ppr,
    per_persons p,
    hz_orig_sys_references hosp
WHERE
    eba.bank_account_id = ebao.ext_bank_account_id
    AND ebao.account_owner_party_id = h.party_id
    AND hosp.owner_table_id = h.party_id
    AND hosp.orig_system_reference = TO_CHAR(ppr.person_id)
    AND hosp.owner_table_name = 'HZ_PARTIES'
    AND hosp.orig_system = 'FUSION_HCM'
    AND ppr.person_id = p.person_id
    AND h.status = 'A'
    AND eba.bank_account_num = <enter bank account num>
    AND eba.bank_name = <enter Bank Name>
    AND eba.bank_branch_name = <bank branch name>;

🔎 Replace data with values from your PersonalPaymentMethod.dat file.

---

Final Root Causes Summary

Cause 1

• BankAccountType not provided even though it exists in the system

Cause 2

• No matching BankAccountId exists for the provided bank details

Conclusion

The error occurs when Oracle Fusion HCM cannot uniquely identify the External Bank Account for a Personal Payment Method. By ensuring accurate bank details and providing BankAccountType when required, this issue can be resolved effectively.

This approach is widely used in payroll implementations and data migration projects.

Common Errors During Worker HDL Load in Oracle Fusion HCM (With Solutions)

 

Common Errors During Worker HDL Load in Oracle Fusion HCM (With Solutions)

Loading worker data using HDL (HCM Data Loader) in Oracle Fusion HCM is powerful—but even small configuration or data issues can cause errors that block the load process.

In this blog, we’ll cover 10 common Worker HDL load errors, explain why they occur, and provide clear, step-by-step solutions to resolve them quickly.

---

1️⃣ Error: You Must a Primary Value

🔍 Cause

The system requires a primary work term for the worker, but it is missing.

✅ Solution

Add the PrimaryWorkTermsFlag attribute in the WorkTerms metadata and set it to Y.

Tip:
Each worker must have exactly one primary work term.

---

2️⃣ Error: Person can have only 1 active Primary WorkRelationship

🔍 Cause

The worker already has an active primary work relationship, and a new one is being created.

✅ Solution

Update the termination date of the previously terminated work relationship to ensure only one active primary work relationship exists.

---

3️⃣ Error: SourceSystemOwner is unknown

🔍 Cause

The SourceSystemOwner value in the HDL file does not match the lookup configuration.

✅ Solution

1. Navigate to Setup & Maintenance

2. Search for Manage Common Lookups

3. Open lookup type HRC_SOURCE_SYSTEM_OWNER

4. Remove FUSION from the custom lookup code

5. Update the same value in the Worker.dat (or relevant HDL file)

6. Zip and reload the file via
   My Client Groups → Data Exchange → Import and Load Data

7. Refresh and verify successful completion

---

4️⃣ Error:

JBO-FND:::FND_FLEX_SEG_VAL_NOT_IN_LIST: xxx is not in the list

🔍 Cause

The Site Code linked to the Position is invalid or expired.

✅ Solution

• Remove the end date for the Site Code
  OR

• Extend the end date for the Site Code

After correction, reload the Worker HDL file.

---

5️⃣ Error: You must enter a valid value for the GradeId field

🔍 Cause

An invalid or missing grade is passed for a position-based assignment.

✅ Solution (Choose one):

• Provide the correct GradeId or GradeCode

• Pass #NULL (with PER_ENFORCE_VALID_GRADE = Y)

• Set PER_ENFORCE_VALID_GRADE = N to skip grade validation

📌 After loading, run the ESS job:
Synchronize Person Assignment from Position

This syncs grade, job, and other position attributes.

---

6️⃣ Error: The values xxxx aren't valid for the attribute LegislationCode

🔍 Cause

The Legal Entity registration setup is incomplete or duplicated.

✅ Solution

1. Go to Setup & Maintenance

2. Navigate to Legal Structures

3. Open Manage Legal Reporting Unit Registrations

4. Assign a unique Registration Number

5. Save and reload the Worker HDL file

---

7️⃣ Error:

METADATA line for the {BO_NAME} business object is invalid
(While loading Person Extra Information)

🔍 Cause

Outdated Worker HDL template or missing EFF attributes.

✅ Solution

1. Refresh the Worker HDL object

2. Download the latest Worker template

3. Update the file with:

   • PEI EFF

   • EFF_CATEGORY_CODE

   • FLEX attributes

4. Follow Oracle documentation for Extensible Flexfields

5. Zip and reload via Import and Load Data

---

8️⃣ Error:

You cannot update this record because the SourceSystemId and SourceSystemOwner are invalid
(Assignment Supervisor)

🔍 Cause

Mismatch between source keys and Fusion surrogate keys.

✅ Solution (Best Options):

• Remove SourceSystemId/Owner and use Fusion surrogate or user keys

• Ensure parent and child objects use the same key type

• For integrations:

  • Update mappings using HRC_INTEGRATION_KEY_MAP

  • Load mappings via SourceKeys.dat

  • Reload AssignmentSupervisor data

---

9️⃣ Error:

You must provide only one parent record Worker and it must start on the earliest effective start date

🔍 Cause

Incorrect Worker effective dates or duplicate Worker records.

✅ Solution

• Ensure StartDate = EffectiveStartDate

• Match the earliest date from PER_ALL_PEOPLE_F

• If creating only a new assignment or work relationship:

  • Remove METADATA Worker

  • Remove MERGE Worker records

---

🔟 Error: No Assignment record from 2018-10-27

🔍 Cause

Assignment data is missing from the Worker HDL file for the specified effective date.

✅ Solution

Add the Assignment record in Worker.dat starting from 2018-10-27, then reload the file.

---

✅ Best Practices for Worker HDL Loads

• Always use the latest HDL templates

• Validate effective dates carefully

• Avoid mixing Fusion surrogate keys and source keys

• Run required ESS jobs after position-based updates

• Test loads in DEV or TEST before PROD

---

🔚 Conclusion

Worker HDL errors in Oracle Fusion HCM are common—but most are caused by data inconsistencies, configuration gaps, or outdated templates. Understanding these errors and applying the correct solution can save hours of troubleshooting and ensure smooth data loads.

💬 Have questions or faced a different error?
Drop them in the comments—I’ll help you troubleshoot.

You Can’t Delete a Person Contact Relationship Because the Person Is a Benefit Dependent or Beneficiary

Overview

While managing Person Contact Relationships in Oracle Fusion HCM, you may encounter an error when trying to delete or end date a contact using HDL or the UI.

This issue typically occurs when the contact is linked to Benefits as a dependent or beneficiary. In this blog, we’ll explain the error, why it happens, and the exact steps to resolve it.

---

Error Message

You may see one of the following error messages:

You cannot delete the contact because the person is designated as a benefit dependent or beneficiary, or an attempt was made to process the benefit designation

OR

Error removing a duplicate beneficiary/contact

---

Why This Error Occurs

Oracle Fusion HCM restricts the deletion or end dating of a Person Contact Relationship when the person is:

• Added as a benefit dependent

• Designated as a beneficiary in one or more benefit plans

• Actively covered under a benefits plan

• Associated with a processed or backed-out life event

This validation ensures data integrity for benefits processing and payroll calculations.

---

Resolution Steps

Follow the steps below in sequence to resolve the issue.

---

✅ Step 1: Check if the Contact Is Added as a Beneficiary

• Navigate to the employee’s Benefits section

• Verify whether the dependent/contact is added as a beneficiary

• If yes, remove the beneficiary designation

---

✅ Step 2: Check if the Dependent Is Elected in Any Benefit Plan

• Review all benefit plans where the contact may be elected as:

  • Primary beneficiary

  • Secondary beneficiary

• If the dependent is elected in any plan, remove the election

---

✅ Step 3: Check If the Dependent Is Covered in Any Plan

If the dependent is actively covered:

1. Identify the life event associated with the coverage

2. Void or back out the life event

3. Run the ESS job:

Purge Backed-Out or Voided Life Event Data

This step is mandatory to fully remove benefit-related dependencies.

---

Final Step: Delete or End Date the Person Contact Relationship

Once all benefit dependencies are cleared:

• You can now delete or end date the Person Contact Relationship

• This can be done using:

  • HDL

  • Fusion UI

The system will no longer block the action.

---

Important Notes

• Benefits dependencies always take precedence over contact maintenance

• HDL and UI both follow the same benefit validation rules

• Always confirm with functional/benefits teams before removing dependent data

• Perform these steps in lower environments first

---

Best Practices

• Review benefit dependencies before deleting contacts

• Maintain audit records when removing beneficiaries

• Purge voided life events to avoid residual data issues

• Use consistent effective dates during benefit cleanup

---

Conclusion

If you’re unable to delete or end date a Person Contact Relationship in Oracle Fusion HCM, the most common reason is that the person is linked as a benefit dependent or beneficiary.

By removing beneficiary elections, clearing dependent coverage, and purging backed-out life events, you can successfully delete or end date the contact using HDL or the UI.

💬 Have you faced similar benefit-related HDL issues? Share them in the comments.