Oracle Cloud Payroll: Creating US Federal Tax Cards Using HCM Data Loader (HDL)
Introduction
One of the most common activities during the implementation of Oracle Cloud Payroll is creating employee tax cards. Whether you're performing an initial data conversion, onboarding new employees, or migrating from a legacy payroll system, maintaining tax withholding information accurately is essential for correct payroll tax calculations.
Although tax cards can be created individually through the Oracle Cloud user interface, implementation teams often need to load thousands of employee tax elections during a payroll conversion. Oracle Cloud Payroll provides HCM Data Loader (HDL) business objects that allow tax cards to be created efficiently, consistently, and in bulk.
A common misconception is that creating a US Federal Tax Card only requires loading Federal withholding elections. A US Tax Card is composed of multiple HDL business objects that work together to establish the employee's complete payroll taxation configuration.
In this article, we'll explore the complete hierarchy of a US Federal Tax Card, understand the evolution of Oracle's Federal Tax HDL business objects, and walk through a practical HDL example for creating a Federal Tax Card.
Understanding the US Tax Card Hierarchy
A US Tax Card consists of several related HDL business objects that represent different portions of an employee's taxation information.
The overall hierarchy looks like this:
Tax Withholding
│
├── US Taxation
│ │
│ └── US Taxation Base
│
└── Federal Taxes
│
├── FederalTaxesBase
├── FederalTaxes2020
└── FederalTaxes2023
Each component has a specific purpose:
| HDL Object | Purpose |
|---|---|
| TaxWithholding | Creates the parent Tax Withholding card |
| USTaxation | Associates the employee with a Tax Reporting Unit (TRU) |
| USTaxationBase | Stores work location and statutory taxation details |
| FederalTaxes | Creates the Federal Taxes calculation component |
| FederalTaxesBase / FederalTaxes2020 / FederalTaxes2023 | Stores the employee's Federal withholding elections |
Understanding this hierarchy makes it much easier to troubleshoot HDL errors and build reliable conversion files.
Understanding the Federal Tax HDL Objects
One of the most confusing areas for Oracle Payroll consultants is determining which Federal Tax HDL object should be used.
Oracle has introduced multiple versions of the Federal Tax component over time to align with IRS Form W-4 changes.
Today you'll commonly encounter three business objects:
- FederalTaxesBase
- FederalTaxes2020
- FederalTaxes2023
Although they all configure Federal withholding, each represents a different IRS withholding model.
FederalTaxesBase – Pre-2020 IRS W-4
Prior to 2020, employees completed the traditional IRS Form W-4 using withholding allowances.
The primary election options included:
- Filing Status
- Number of Allowances
- Additional Federal Tax Amount
- Federal Tax Exemption
Oracle supports this withholding model using the FederalTaxesBase HDL business object.
Typical attributes include:
- Filing Status
- Allowances
- Additional Tax Amount
- Exempt from Federal Income Tax
- Medicare
- Social Security
- Federal Unemployment
- Federal Income Tax
This object is primarily used when converting employees whose tax elections were established using the pre-2020 IRS W-4.
FederalTaxes2020 – IRS Form W-4 Redesign
Beginning in 2020, the IRS completely redesigned Form W-4.
The most significant change was the elimination of withholding allowances.
Instead of allowances, employees now provide:
- Filing Status
- Multiple Jobs indicator
- Dependents
- Other Income
- Deductions
- Additional Withholding
Oracle introduced the FederalTaxes2020 HDL business object to support this redesigned withholding model.
Unlike the previous version, withholding calculations are based on dollar amounts rather than allowances.
FederalTaxes2023 – Current Federal Tax Model
Oracle later introduced FederalTaxes2023 to support additional legislative updates and enhancements to the Federal withholding model.
The overall structure remains similar to FederalTaxes2020 while supporting newer attributes such as:
- Nonresident Alien Indicator
- Updated Federal withholding calculations
- Additional payroll processing options
For most new Oracle Cloud Payroll implementations today, FederalTaxes2023 is the recommended business object.
Comparing the Federal Tax HDL Objects
| HDL Object | IRS Model | Typical Attributes |
|---|---|---|
| FederalTaxesBase | Pre-2020 W-4 | Filing Status, Allowances, Additional Tax, Exempt |
| FederalTaxes2020 | 2020 W-4 | Multiple Jobs, Dependents, Other Income, Deductions |
| FederalTaxes2023 | Current | Same as 2020 plus Nonresident Alien and newer enhancements |
Which Federal Tax HDL Object Should You Use?
FederalTaxesBase
Use when converting legacy employees whose tax elections were created using the traditional IRS W-4 with withholding allowances.
FederalTaxes2020
Use when employee withholding elections follow the redesigned IRS 2020 W-4.
FederalTaxes2023
Recommended for new Oracle Cloud Payroll implementations using current Oracle releases.
Note: The available HDL business objects depend on your Oracle Cloud Payroll release. Always verify the supported business objects in the Oracle HCM documentation for your environment.
Step 1: Create the Tax Withholding Card
The first step is creating the employee's Tax Withholding card.
METADATA|TaxWithholding|EffectiveStartDate|EffectiveEndDate|LegislativeDataGroupName|DirCardDefinitionName|CardSequence|AssignmentNumber MERGE|TaxWithholding|2025/05/01|4712/12/31|US Legislative Data Group|Tax Withholding|1|E100755
This creates the parent tax card that will contain all Federal and State taxation information.
Step 2: Create US Taxation
Next, associate the employee with the appropriate Tax Reporting Unit.
METADATA|USTaxation|EffectiveStartDate|EffectiveEndDate|LegislativeDataGroupName|CardSequence|
AssignmentNumber|AssociationTaxReportingUnitName|AssociationAssignmentNumber|TaxReportingUnit MERGE|USTaxation|2025/05/01|4712/12/31|US Legislative Data Group|1|E100755|ABC LLC|E100755|ABC LLC
This establishes the taxation relationship between the employee and the Tax Reporting Unit.
Step 3: Load US Taxation Base
The USTaxationBase component stores work location and statutory taxation information.
METADATA|USTaxationBase|EffectiveStartDate|EffectiveEndDate|LegislativeDataGroupName|CardSequence|AssignmentNumber|
AssociationTaxReportingUnitName|AssociationAssignmentNumber|TaxReportingUnit|PrimaryWorkAddress|StateforDisabilityCalculation|StateforUnemploymentCalculation|StatutoryEmployee|StateforFamilyandMedicalLeaveCalculation|StateforLongTermCareCalculation MERGE|USTaxationBase|2025/05/01|4712/12/31|US Legislative Data Group|1|E100755|Abc LLC|E100755|Abc LLC|113 street TN|TN|TN|N||
Typical information maintained includes:
- Primary Work Address
- State Unemployment
- State Disability
- Family Medical Leave
- Long-Term Care
- Statutory Employee indicator
These attributes influence various payroll tax calculations depending on legislative requirements.
Step 4: Create the Federal Taxes Component
Before loading withholding elections, create the Federal Taxes calculation component.
METADATA|FederalTaxes|EffectiveStartDate|EffectiveEndDate|LegislativeDataGroupName|CardSequence|AssignmentNumber MERGE|FederalTaxes|2025/05/01|4712/12/31|US Legislative Data Group|1|E100755
This creates the Federal Taxes section of the employee's tax card.
Step 5: Load Federal Withholding Elections
Finally, load the employee's withholding elections.
For modern Oracle Cloud Payroll implementations, this is typically accomplished using FederalTaxes2023.
METADATA|FederalTaxes2023|EffectiveStartDate|EffectiveEndDate|LegislativeDataGroupName|CardSequence|AssignmentNumber|
FilingStatus|MultipleJobs|QualifyingDependentsAmount|OtherDependentsAmount|TotalDependentsAmount|OtherIncomeAmount|DeductionsAmount|ExtraWithholding|ExemptfromFederalIncomeTaxWithholding|NonresidentAlien|IRSLockinDate|Medicare|FederalUnemployment|SocialSecurity|FederalIncomeTax|EnforceFederalIncomeTaxLookbackRule|TaxEnforcementLevel|RegularAmount|RegularRate|SupplementalAmount|SupplementalRate|CumulativeTaxation MERGE|FederalTaxes2023|2025/05/01|4712/12/31|US Legislative Data Group|1|E100755|4||5|6|11|5|5|||N|||||||PSU|||||
Typical information includes:
- Filing Status
- Multiple Jobs
- Qualifying Dependents
- Other Dependents
- Other Income
- Deductions
- Additional Withholding
- Federal Tax Exemption
- Nonresident Alien indicator
Once loaded, these elections become part of the employee's Federal Tax Card and are used during payroll processing.
Recommended HDL File Split
You can split the HDL load into multiple TaxWithholding.dat files to make the load sequence easier to manage:
- File 1: TaxWithholding
- File 2: USTaxation and USTaxationBase
- File 3: FederalTaxes and FederalTaxes2023
This approach helps validate each parent-child dependency before loading the next section.
Common Business Scenarios
This HDL solution is commonly used for:
- Initial Oracle Payroll implementations
- Payroll data conversions
- Mergers and acquisitions
- Employee onboarding integrations
- Bulk tax election updates
- Payroll system migrations
Benefits of Using HDL
Using HDL to create tax cards provides several advantages:
- Supports large-scale employee conversions
- Eliminates repetitive manual data entry
- Improves data consistency
- Easily repeatable across environments
- Supports version-controlled deployment
- Reduces implementation effort
Best Practices
When loading US Tax Cards:
- Create the Tax Withholding card before child components.
- Use the same CardSequence throughout the hierarchy.
- Verify the employee assignment exists.
- Confirm the Tax Reporting Unit is valid.
- Validate Federal withholding elections before loading.
- Run QuickPay after loading to verify tax calculations.
- Test the complete hierarchy in a lower environment before production deployment.
Common Implementation Pitfalls
Implementation teams frequently encounter issues such as:
- Loading child objects before creating the Tax Withholding card.
- Using inconsistent CardSequence values.
- Invalid Tax Reporting Unit names.
- Incorrect Legislative Data Group.
- Effective dates that do not align across HDL objects.
- Using the wrong Federal Tax HDL object for the employee's W-4 model.
Understanding the dependency between the HDL objects helps avoid many of these issues.
Final Thoughts
Although creating a US Federal Tax Card through HDL may initially appear complex, it becomes much more manageable once you understand the overall hierarchy and the role of each HDL business object.
Rather than thinking of the Federal Tax Card as a single HDL file, think of it as a collection of related components that together define an employee's payroll taxation configuration.
By understanding when to use FederalTaxesBase, FederalTaxes2020, and FederalTaxes2023, implementation teams can build cleaner HDL files, simplify payroll data conversions, and ensure employees' Federal withholding elections are configured accurately.
Important Tip
One of the most common implementation mistakes is attempting to load FederalTaxes2023 directly without first creating the parent TaxWithholding and FederalTaxes components.
Oracle expects the complete tax card hierarchy to exist before child components are loaded. Following a parent-to-child loading sequence not only avoids dependency errors but also results in cleaner, more maintainable HDL files during payroll implementations and future support activities.
