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.

Not Able to End Date Person Contact Relationship Using HDL in Oracle Fusion HCM

Not Able to End Date Person Contact Relationship Using HDL in Oracle Fusion HCM

Overview

While working with HCM Data Loader (HDL) in Oracle Fusion HCM, you may encounter a scenario where you try to end date a Person Contact Relationship using HDL—but the load fails or does not behave as expected.

This blog explains why end dating a Person Contact Relationship is not possible using HDL, and what the supported workaround is.

---

Problem Description

You are attempting to end date an existing Person Contact Relationship (such as Emergency Contact, Spouse, or Dependent) using HDL.

Despite providing correct effective dates in the HDL file, the relationship does not get end dated, or the load results in an error.

---

Why This Happens

Oracle Fusion HCM does not support end dating Person Contact Relationships through HDL.

This is a product limitation, not a data issue or configuration problem. The HDL framework currently allows you to:

• Create Person Contact Relationships

• Delete Person Contact Relationships

But it does not allow updating or end dating existing contact relationships.

---

Resolution / Supported Approach

✅ Delete the Person Contact Relationship Using HDL

Since end dating is not supported, the only available option is to delete the Person Contact Relationship using HDL.

When the contact relationship is no longer required:

• Identify the relationship record

• Use a DELETE operation in the HDL file

• Load the file using standard HDL steps

This approach fully removes the relationship from the system.

---

Important Notes

• HDL cannot update or end date Person Contact Relationships

• This limitation applies across all environments (DEV, TEST, PROD)

• Functional UI may still allow updates depending on the relationship type

• Always validate business impact before deleting relationships

---

Best Practices

• Confirm with functional teams before deleting contact relationships

• Maintain backup of original HDL files

• Test DELETE operations in lower environments

• Document deleted relationships for audit purposes

---

Alternative Options

If end dating is required for reporting or compliance:

• Consider managing the relationship manually through the Fusion UI (if supported)

• Evaluate custom reporting logic to handle deleted relationships

• Log the change history externally if required

---

Conclusion

If you are not able to end date a Person Contact Relationship using HDL, it is due to an Oracle-supported limitation. The only supported workaround is to delete the relationship using HDL.

Understanding such limitations helps avoid unnecessary troubleshooting and ensures your data loads remain compliant with Oracle Fusion HCM standards.

💬 Have you faced similar HDL limitations or different contact-related errors? Share your experience in the comments.

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.

  

How to Change Non-Primary Work Relationship to Primary Using Worker.dat (Oracle Fusion HDL)

Introduction

In Oracle Fusion HCM, an employee can have only one Primary Work Relationship at any given time.

During data corrections or integrations, you may encounter a requirement to change an existing non-primary work relationship to primary.

Oracle Fusion allows this update using HCM Data Loader (HDL) by passing specific attributes in the Worker.dat file.

This blog explains:

• When this scenario occurs

• Required HDL attributes

• Sample Worker.dat template

• What happens after upload

HDL Template for Talent Profile

HDL Template for Talent Profile in Oracle Fusion HCM

Load Talent Profile Data Using HCM Loader (HDL)

Oracle Fusion HCM provides the Talent Profile feature to manage employee skills, languages, certifications, competencies, and other professional attributes. To load or migrate talent profile data in bulk, Oracle supports HCM Data Loader (HDL) using the TalentProfile.dat file.

In this blog, we will walk through:

• Talent Profile HDL overview

• Required HDL objects

• Sample HDL template

• Common mistakes and best practices

📹 You can also watch the step-by-step video to load Talent Profile data using HDL from the provided link.

---

📌 What Is Talent Profile in Oracle Fusion HCM?

Talent Profile allows organizations to capture and manage:

• Skills

• Languages

• Certifications

• Education

• Licenses

• Competencies

This data is widely used in Talent Management, Recruiting, Learning, and Succession Planning modules.

---

📂 HDL File Used for Talent Profile

To load Talent Profile data, use the following HDL file:

TalentProfile.dat

This file primarily uses two business objects:

• TalentProfile

• ProfileItem

---

🔹 TalentProfile HDL Object

The TalentProfile object defines the main profile linked to a person.

🔸 Sample Metadata & MERGE

METADATA|TalentProfile|SourceSystemOwner|SourceSystemId|Description|
Summary|ProfileTypeCode|ProfileCode|ProfileStatusCode|ProfileUsageCode
|PersonId

MERGE|TalentProfile|XXTEST|XXTEST_TALENT2|||PERSON|PERSON_TALENT|A|P
|100000609812368

🔑 Key Fields Explained

• ProfileTypeCode → PERSON

• ProfileCode → PERSON_TALENT

• ProfileStatusCode → A (Active)

• ProfileUsageCode → P (Person)

• PersonId → Person ID from Fusion

---

🔹 ProfileItem HDL Object

The ProfileItem object stores the actual talent details such as languages, skills, certifications, etc.

🔸 Sample Metadata & MERGE (Language Example)

METADATA|ProfileItem|SourceSystemOwner|SourceSystemId|
ProfileId(SourceSystemId)|ContentType|ContentItem|SectionName|
CountryCountryCode|DateFrom|DateTo|RatingModelCode1|RatingModelCode2
|RatingModelCode3|RatingLevelCode1|RatingLevelCode2|RatingLevelCode3

MERGE|ProfileItem|XXTEST|XXTEST_TALENTPROF2|XXTEST_TALENT2|LANGUAGE
|Hindi|PERSON_LANGUAGE||2021/07/26||LANGUAGE|LANGUAGE|LANGUAGE|
HIGH|HIGH|HIGH

🔑 Key Fields Explained

• ProfileId(SourceSystemId) → SourceSystemId from TalentProfile

• ContentType → LANGUAGE

• ContentItem → Hindi

• SectionName → PERSON_LANGUAGE

• RatingModelCode → LANGUAGE

• RatingLevelCode → HIGH

---

🧩 Supported Content Types in ProfileItem

Some commonly used ContentType values:

• LANGUAGE

• SKILL

• CERTIFICATION

• EDUCATION

• LICENSE

Each content type may have different required attributes depending on configuration.

---

⚠ Common Errors & Troubleshooting

Talent Profile Load Common Issues

---

✅ Best Practices

✔ Load TalentProfile first, then ProfileItem
✔ Use consistent SourceSystemOwner
✔ Validate lookups for ContentType and RatingModel
✔ Test loads in lower environments
✔ Use MERGE instead of CREATE for updates

---

❓ Frequently Asked Questions (FAQ)

Q1. Which HDL file is used for Talent Profile?

Use TalentProfile.dat to load Talent Profile and Profile Items.

Q2. Can we load multiple skills or languages?

Yes. Use multiple ProfileItem records linked to the same TalentProfile.

Q3. Can Talent Profile be updated using HDL?

Yes. Use MERGE with the same SourceSystemId.

Q4. Is PersonId mandatory?

Yes. Talent Profile must be linked to a valid person.

---

🔗 Related Articles (Internal Linking)

• 🔗 Load Worker Data Using HCM Loader

• 🔗 Common Errors During Worker HDL Load

• 🔗 HDL Template for Dependent Enrollment

• 🔗 Change Primary Work Relationship Using HDL

---

📈 Conclusion/ Highlights 

HDL provides a reliable and scalable way to load Talent Profile data in Oracle Fusion HCM. By correctly using TalentProfile and ProfileItem objects, you can efficiently migrate or maintain talent information such as skills and languages.

Highlights

If you found this helpful, bookmark this page and explore other HDL templates available on this blog.

HDL Template to Reverse Termination of Worker in Oracle Fusion HCM

HDL Template for Reverse Termination of Worker in Oracle Fusion HCM

Introduction

In Oracle Fusion HCM, there are scenarios where an employee is terminated by mistake or needs to be rehired with original service details intact. Instead of creating a new work relationship, Oracle provides a way to reverse the termination using HCM Data Loader (HDL).

This blog explains how to reverse a worker termination using HDL, prerequisites, sample Worker.dat template, and common mistakes to avoid.

You can see step by step video to reverse termination of worker using this Link

---

What Is Reverse Termination in Oracle Fusion?

Reverse termination restores a previously terminated worker by:

• Re-activating the same work relationship

• Preserving seniority, assignments, and service history

• Avoiding creation of a new employee record

This is commonly used when:

• Termination was loaded incorrectly

• Incorrect termination date was applied

• HR wants to undo a termination action

---

Prerequisites

Before reversing a termination using HDL, ensure:

1. Worker data already exists
   (Refer to sample Worker.dat for loading worker)

2. Worker is already terminated
   (Termination must be completed successfully via UI or HDL)

3. Correct SourceSystemOwner and SourceSystemId are known for:

   • WorkRelationship

   • Person

---

Object Used for Reverse Termination

To reverse termination, you must use the WorkRelationship object in Worker.dat.

---

HDL Template for Reverse Termination of Worker

Sample HDL Template

METADATA|WorkRelationship|SourceSystemOwner|SourceSystemId|
PersonId(SourceSystemId)|PersonNumber|DateStart|WorkerType|
LegalEmployerName|ReverseTerminationFlag


MERGE|WorkRelationship|XXTEST|XXTEST_PDSERVICE2|XXTEST_PER2|
XXTEST2|2018/01/01|E|US1 Legal Entity|Y

---

Steps to Reverse Termination Using HDL

1. Prepare Worker.dat with WorkRelationship object

2. Set ReverseTerminationFlag = Y

3. Zip the file

4. Navigate to:

   My Client Groups → Data Exchange → Import and Load Data
   

5. Upload and submit the HDL zip

6. Monitor process status

7. Validate worker record in UI

---

Post Load Validation Checklist

After successful load, verify:

• Worker status is Active

• Assignment is restored

• Termination dates are cleared

• No new work relationship created

---

Common Errors & Troubleshooting

Reverse Termination Common Issues

---

When NOT to Use Reverse Termination

Do not use reverse termination if:

• Employee must be rehired as a new hire

• Legal employer has changed

• Service history must restart

In these cases, perform a new hire action instead.

---

Best Practices

✅ Always confirm termination exists before reversal
✅ Use original WorkRelationship SourceSystemId or User Keys
✅ Validate in lower environments first
✅ Avoid mixing reverse termination with assignment updates

---

Related Articles

• Load Worker Data Using HCM Loader

• HDL Template to Terminate Worker

• Change Non Primary WRL to Primary Work Relationship Using HDL

• Common Worker.dat HDL Errors and Fixes

---

Conclusion

Reverse termination using HDL is a powerful feature when handled correctly. By setting the ReverseTerminationFlag to Y on the WorkRelationship object, you can quickly restore an employee without data loss.

If you frequently work with Oracle Fusion HCM HDL, mastering reverse termination can save hours of manual correction.

HDL Template for Assignment Supervisor

HDL Template for Assignment Supervisor in Oracle Fusion HCM

Overview

In Oracle Fusion HCM, assignment supervisor details (such as Line Manager) can be loaded or updated using HCM Data Loader (HDL). To load an assignment supervisor, Oracle uses the Worker.dat file with the AssignmentSupervisor business object.

You can see step by step video to load assignment supervisor using this Link

This blog explains:

• Prerequisites for loading Assignment Supervisor

• HDL template and sample data

• Key attributes and explanations

• Common errors and troubleshooting

---

Prerequisites

Before loading assignment supervisor data, ensure the following:

1. Worker data must already be loaded

   • Employee, Manager, and their assignments should exist in Fusion.

   • Assignment SourceSystemId must be available.

   • Load Worker data using Worker.dat

2. Assignment and Manager details

   • Both employee and manager must have valid assignments.

   • Manager person and assignment must exist on or before the supervisor effective date.

📌 Note: Assignment Supervisor data is loaded using the Worker.dat file, not a separate HDL file.

---

HDL File Used

Worker.dat

---

Assignment Supervisor HDL Template

METADATA Section

METADATA|AssignmentSupervisor|AssignmentId(SourceSystemId)|SourceSystemOwner
|SourceSystemId|EffectiveStartDate|EffectiveEndDate|
ManagerAssignmentId(SourceSystemId)|ManagerId(SourceSystemId)|
ManagerType|PersonId(SourceSystemId)|PrimaryFlag

Sample MERGE Data

MERGE|AssignmentSupervisor|XXTEST_ASSIGN2|XXTEST|XXTEST_MANAGER1
|2018/01/01|4712/12/31|XXTEST_ASSIGN1|XXTEST_PER1|LINE_MANAGER|
XXTEST_PER2|Y

---

Common Use Cases

• Load Line Manager during employee migration

• Update reporting manager

• Correct supervisor details

• Bulk manager changes using HDL

---

Common Errors & Troubleshooting

Assignment Supervisor Issue

---

Best Practices

• Always validate Assignment and Manager SourceSystemIds

• Use 4712/12/31 as EffectiveEndDate for active supervisors

• Avoid overlapping primary supervisors

• Test with a single record before bulk load

---

Frequently Asked Questions (FAQ)

❓ Which HDL file is used to load Assignment Supervisor?

Assignment Supervisor data is loaded using the Worker.dat file.

❓ Can I update an existing manager using HDL?

Yes, use the same SourceSystemId with updated manager details.

❓ Can I load multiple supervisors?

Yes, but only one primary supervisor is allowed per assignment.

❓ What ManagerType should I use for reporting manager?

Use LINE_MANAGER for standard reporting hierarchy.

❓ Can I end-date a supervisor using HDL?

Yes, update the EffectiveEndDate with the required date.

Oracle Cloud - Load Worker Data - HDL

How to Load Worker Data in Oracle Fusion Using HCM Loader (HDL)

Introduction

Oracle Fusion HCM uses HCM Data Loader (HDL) to import Worker and related objects efficiently.
This blog explains step-by-step how to load Worker data, including Worker, Person, Work Relationship, Assignments, and more, using Worker.dat and HCM Loader.

You will also find:

• Sample HDL templates

• Required components per object

• Loading steps and verification

• Related articles for Oracle Fusion troubleshooting