Oracle Fusion HCM Tutorial Blog

Monday, 5 January 2026

Error during Balance Adjustment HDL load

Error Message1 : You Must submit an entry value for input value amount.

Solution: Input Value amount is blank.

Error Message2 : A Previous Process that was run for this payroll relationship couldn't be complete or marked to be run again.

Solution: Please check whether any process or flow has errored out for the person in Person Results.

Thursday, 1 January 2026

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

Navigate to Setup & Maintenance
Search for Manage Common Lookups
Open lookup type HRC_SOURCE_SYSTEM_OWNER
Remove FUSION from the custom lookup code
Update the same value in the Worker.dat (or relevant HDL file)
Zip and reload the file via
My Client Groups → Data Exchange → Import and Load Data
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

Go to Setup & Maintenance
Navigate to Legal Structures
Open Manage Legal Reporting Unit Registrations
Assign a unique Registration Number
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

Refresh the Worker HDL object
Download the latest Worker template
Update the file with:
- PEI EFF
- EFF_CATEGORY_CODE
- FLEX attributes
Follow Oracle documentation for Extensible Flexfields
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

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

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:

Identify the life event associated with the coverage
Void or back out the life event
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.

Wednesday, 1 October 2025

HDL Template for Benefit Participant Enrollment (Oracle Fusion HCM)

Introduction

Oracle Fusion HCM allows Benefit enrollments to be loaded in bulk using HCM Data Loader (HDL). This is especially useful during New Hire loads, Open Enrollment, Life Events, or mass corrections.

In this blog, we will walk through a complete end-to-end process to load Benefit Participant Enrollment using the ParticipantEnrollment.dat file, along with a related CompensationObject section.

When to Use ParticipantEnrollment.dat

You should use ParticipantEnrollment.dat when you need to:

Enroll an employee into a Benefits Program
Assign Plans, Options, and Coverage
Process enrollments triggered by Life Events (New Hire, Marriage, etc.)
Perform initial benefit enrollment for new hires

Prerequisites

Before loading the file, ensure the following:

Employee already exists in the system (Person record created)
Date of Birth (DOB) is populated for the employee - Required for age-based eligibility, dependent validation, and certain benefit plans.
Payroll is assigned to the employee - Payroll effective date aligns with hire/enrollment date
Salary is assigned - Salary record is active as of the benefit enrollment date (Required for benefit plans that calculate rates, premiums, or coverage based on salary)
Benefits Program, Plan, and Options are already configured
Life Event (e.g., New Hire) exists and is active
Dates align with the employee’s hire date and benefit eligibility
HDL access is available

File Name


ParticipantEnrollment.dat

HDL File Structure Overview

This file consists of two main sections:

ParticipantEnrollment – Defines the employee and life event
CompensationObject – Assigns benefit program, plan, option, and coverage

Both sections are mandatory for successful enrollment.

Section 1: ParticipantEnrollment

Purpose

This section identifies who is being enrolled and why (Life Event).

Metadata Definition


METADATA|ParticipantEnrollment|PersonNumber|ParticipantLastName|
ParticipantFirstName|BenefitRelationship|LifeEvent|
LifeEventOccuredDate|EffectiveDate

Sample Data


MERGE|ParticipantEnrollment|7628|XXTEST|Adam|DFLT|New Hire|
2026/01/12|2026/01/12

🔹 Tip: LifeEventOccuredDate and EffectiveDate should normally match the hire date for New Hire enrollments.

Section 2: CompensationObject

Purpose

This section assigns the Benefit Program, Plan, Option, and Coverage.

Metadata Definition


METADATA|CompensationObject|Program|OriginalEnrollmentDate|
PersonNumber|LineNumber|Plan|Option|Coverage|Rate

Sample Data


MERGE|CompensationObject|Choice Program (Core)|2026/01/12|7628|1|
Medical PPO|Participant Only|1000|

Field Explanation

🔹 Tip: Program, Plan, and Option values must exactly match the configuration in Fusion.

Complete Sample ParticipantEnrollment.dat File


METADATA|ParticipantEnrollment|PersonNumber|ParticipantLastName|
ParticipantFirstName|BenefitRelationship|LifeEvent|
LifeEventOccuredDate|EffectiveDate
MERGE|ParticipantEnrollment|7628|XXTEST|Adam|DFLT|New Hire|
2026/01/12|2026/01/12

METADATA|CompensationObject|Program|OriginalEnrollmentDate|PersonNumber
|LineNumber|Plan|Option|Coverage|Rate
MERGE|CompensationObject|Choice Program (Core)|2026/01/12|7628|1|
Medical PPO|Participant Plus One|1000|

HDL Load Steps

Navigate to Data Exchange → HCM Data Loader
Upload ParticipantEnrollment.dat
Submit the Load
Monitor the process:
- Load File
- Import and Load
- Completion status should be Succeeded

Validation After Load

After successful load:

Navigate to Benefit Administration
Search for the employee
Verify:
- Program enrollment
- Plan and option selection
- Coverage details
- Effective dates

Common Errors & Troubleshooting

Common Errors Participant Load

Key Takeaways

ParticipantEnrollment.dat is essential for benefit enrollments via HDL
Both ParticipantEnrollment and CompensationObject sections are required
Dates, names, and configurations must match Fusion setup exactly
Always validate enrollment post-load

Conclusion

HDL provides a powerful and efficient way to manage bulk Benefit enrollments in Oracle Fusion HCM. With a correctly structured ParticipantEnrollment.dat file, you can seamlessly enroll employees into benefit programs triggered by life events such as New Hire.

This end-to-end template can be reused and extended for other plans and options as needed.

If you want, I can also help with:

Open Enrollment HDL
Multiple plans in one file
Retro or correction enrollments
Error-handling scenarios

How to sort data in rtf template

Sort the data in Data model is the recommended approach.

But if you want to sort the data in rtf template then you have to use below xml tag code.

<?sort:fieldname?><?fieldname?>

this will sort the data in ascending order be default as it is not mentioned.

if user want to sort the data in descending order then use below code

<?sort:fieldname;'descending'?><?fieldname?>

Prenotification Status of Personal Payment Method in Oracle HCM

Prenote Status is not stored directly in table, you can find the corresponding details in pay_bank_account_prenotes table.

Prenote status you have to use below logic.

CASE
WHEN pay_bank_account_prenotes.PRENOTE_DATE=TO_DATE('31/12/4712','DD/MM/YYYY') THEN 'ORA_R'
WHEN pay_bank_account_prenotes.PRENOTE_DATE=TO_DATE('01/01/0001','DD/MM/YYYY') THEN 'ORA_SK'
WHEN NVL((pay_bank_account_prenotes.PRENOTE_DATE),TO_DATE('31/12/4712','DD/MM/YYYY'))=TO_DATE('31/12/4712','DD/MM/YYYY') THEN 'ORA_N_S'
WHEN TRUNC(pay_bank_account_prenotes.PRENOTE_DATE+NVL(OrganizationPaymentMethodDEO.VALIDATION_DAYS,0)) <= TRUNC(SYSDATE) THEN 'ORA_C'
ELSE 'ORA_S'
END AS PRENOTE_STATUS