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.