Introduction

Use HCM Spreadsheet Data Loader (HSDL) to provide bulk-data loading capabilities to your business users and for your inbound integrations. You can configure spreadsheet templates for your specific use cases and assign access to those templates to just the roles that require them. For example, your recruiting integration could have access to a New Hire spreadsheet, whereas the Promotion spreadsheet would be available to your HR Specialists. Both templates maintain the Worker business object but only for the prescribed use case.

Note:

The advantage of using HSDL for your integrations is that you're restricting the data uploaded to the specific use case supported by the template. You can also enforce data security, if required.

Objectives

In this tutorial, you will:

• Understand how to design and configure HSDL templates.
• Create a working template that can load new hires.

The Worker business object is complex with around 30 objects over 5 levels in the object hierarchy. This tutorial will describe how to create a simple working New Hire template, whilst explaining the common tasks to define a spreadsheet template. You can then apply these steps to any supported business object.

Having understood the basics of template creation, the Next Steps section lists tutorials that will expand your knowledge.

Prerequisites

To complete this tutorial, you will require:

• A Windows machine with the Desktop integration installed, to test your template.
• Access to the Spreadsheet Templates task with a role that's assigned access to create templates for the Worker business object.

Follow tasks 2 and 3 in the Configure Access to Design and Maintain HCM Spreadsheet Data Loader (HSDL) Templates tutorial to create such a role.

Note:

This tutorial assumes you've enabled Redwood. Follow the Release 25C version of this tutorial for the navigation and screenshots if this isn't the case.

Tutorial Tasks

The Spreadsheet Templates Redwood task uses a guided process to create and maintain templates. Tasks in this tutorial are named for the steps in the guided process.

Task 1: Add - Enter template information

In this step you'll create your new template based on the Worker business object hierarchy.

1. Log into the application with a user who has a HSDL template designer role with access to the Worker business object.
2. Navigate to My Client Groups > Data Exchange > Spreadsheet Templates.
3. Click Add to start the guided process.





4. Provide a name, set the business object to Worker, and optionally provide a description.



The template code will be automatically generated based on the template name. You can edit this.

5. Review the Data security. Upload Data As should be set to Session User if you want data security to be applied.

   

   Note:

   Not all business objects support loading data with the session user.

   You need an additional function security privilege to assign access to templates that load data as the elevated user.

6. Click Continue to progress to the Select attributes step.

Task 2: Select attributes

In this task you'll select the attributes you want your spreadsheet user to populate for a new hire.

Tip:

When selecting attributes, focus on the values that users need to enter or maintain in the spreadsheet. You don’t need to manually add every identifier or every object in the hierarchy.

This table summarises the attributes you may want to supply for a simple New Hire. In the following steps you'll add these attributes to your template, along with attributes on these objects that are required for new records:

Object	Attributes
Worker	Date of Birth
Person Name	Last Name First Name Title
Person Legislative Data	Gender Marital Status
Assignment	Person Type Primary Assignment for Work Relationship Department Job Code Position Code Grade Code

Tip:

When you continue to the next step in the guided process flow, the template designer adds any objects needed to preserve the parent-child relationships between the records in the template. You'll then specify which attributes to use to uniquely identify each object, and the template designer will automatically add any identifying attributes, such as Person Number, which aren't already saved to the template.

Worker

The Worker object is the top-level object in the hierarchy and is used to identify an individual employee. It includes the Person Number, Date of Birth and Start Date for the person.

1. Set the Object filter to Worker.





2. Click the Required filter and select For new records.

   

   Tip:

   Remember, attributes that are always required will automatically be added. We need to manually add attributes required for new records because the template designer doesn't know if you're creating new records or updating existing ones.
3. Click the checkbox above the table to select all displayed attributes.





4. Click the link available on the Action Code attribute label. This displays the details of the attribute.

   

   Tip:

   Sometimes attribute names can be unfamiliar, or multiple attributes with similar names can exist. You can use the attribute details panel to review the attribute before selecting it.
5. Clear the Required filter and search for date of birth.
6. Check the Date of Birth attribute.





7. Search for and select the Person Number attribute.

   Note:

   As the Person Number attribute uniquely identifies a worker, the template designer will automatically add this attribute if you don't. Adding it now doesn't prevent the template designer from automatically selecting other required attributes.

Person Name

The Person Name object records your employee's name.

1. Change the Object filter to display the Person Name attributes.





2. Click the Required filter and select For new records.

   Tip:

   Don't forget to remove any search criteria in the search panel.
3. Select all displayed attributes.
4. Clear the Required filter.
5. Search for and select the First Name attribute.
6. Add any other optional Person Name attributes you want in your template, such as Title.

Person Legislative Data

The Person Legislative Data object captures your employee's marital status and gender.

1. Change the Object filter to Person Legislative Data.
2. Filter the list of attributes to those that are required For new records.



Tip:

There aren't any attributes required for new records on the Person Legislative Data object.
3. Clear the Required filter, search for and add these optional attributes to your template:
• Gender
• Marital Status
4. Review other available Person Legislative Data attributes and add to your template as required.

Assignment

The Assignment object is where you specify your employee's department, location, position, job etc.

1. Add all attributes that are required For new records for the Assignment object.
2. Clear the Required filter.
3. Search for and add other attributes required in your template. Here are a few suggestions:
• Person Type
• Primary Assignment for the Work Relationship
• Department
• Job Code
• Position Code
• Grade Code
4. Click Continue.

Tip:

If you've selected attributes across multiple objects in the hierarchy it may take some time to progress to the next step. The template designer is validating the objects you've selected attributes from and adding any objects needed to ensure each record has a complete hierarchical structure.

Task 3: Choose record identifiers

In this task, you'll review the attributes used to uniquely identify each record included in your template. HSDL supports both user keys and surrogate IDs.

1. Review the list of objects included in the template.

   

   
   

   Tip:

   Although you didn't add attributes from the Work Relationship or Employment Terms object, the template designer understands that records for these objects are required to link the Assignment record to the Worker record.

   

2. Click Edit.

Note:

The template designer automatically configures the template to use user keys as these are attributes your business users are used to seeing in the application.






Tip:

When an object provides multiple user keys the User Key field becomes a choice list, and you can review and select the user key needed for your use case.
3. Change the Attribute Type field to Surrogate Key.



Tip:

You may want to select Surrogate Key for templates used to maintain existing records. Surrogate Key attributes supply a searchable list of values.
4. Notice the change to the attributes used to identify each object in the template.

You're doing this just to observe the behavior and review the attributes that would be included in the template if you used surrogate keys to identify records.





5. Click Cancel. As this template is to upload new records, we'll use User Keys. Surrogate Keys are only available to reference existing records.
6. Click Continue.

   The Configure attributes step shows all attributes saved to your template.



Note:

Attributes used to identify each record and form the parent-child relationship between the records are automatically added to the template. As Worker is a date-effective object Effective Start Date is also automatically added.

Click the Show Hidden Attributes filter and scroll down.

You can now see that attributes on the child objects which map to attributes on the parent object have been automatically added, defaulted and hidden from spreadsheets.

Task 4: Test

You should regularly test your template by generating a spreadsheet and reviewing how it performs, what changes would make it simpler to use and reduce data errors.

Although this task is mentioned only once, you should perform this task repeatedly during the remaining steps.

1. Save any recent changes.
2. Click Generate Spreadsheet in the information banner.

   

   Tip:

   This information banner is available on the remaining steps of the guided process.
3. Open the downloaded xlsx file and click Yes when prompted to log in.
4. Log in with your application username and password. The spreadsheet is generated with each of the selected attributes that are configured to be displayed in the spreadsheet.
5. Click Create Data Set on the Spreadsheet Loader toolbar.



Tip:

If you just want to review column headings, tips, defaults and lists of values, you can do that without creating a data set. You only need a data set to test uploading data using the spreadsheet.
6. Click OK on the dialog page.






A data set is created with a predefined name; you can override this if you want.





7. Double click in any of the cells in the first row under the column headings to initiate the row.



Tip:

Any mandatory cells without a value will be highlighted with a red outline. Any attribute configured with a default constant value will display the default.
8. Double click on cells where the header includes the [..] symbol after the column heading. This opens a searchable list of values.

   

   
   
9. Enter valid data for each of the empty cells in the spreadsheet row.

Tip:

Use the New Person task in the application to identify valid values for your attributes.
10. To test that the spreadsheet loads valid data, click More > Upload on the Spreadsheet Loader toolbar.





11. Click OK on any dialog pages displayed.
12. Click Refresh regularly to refresh the spreadsheet row status.






The Upload Progress will change status until processing completes with a Success or Error status.






If you get an error status, review the error message, and make corrections as required. Click Upload to resubmit the corrected spreadsheet rows in the data set.

13. Navigate to the Person Management task to ensure your new hires can be seen.

Tip:

There can be a short delay in seeing your employees in the application.

Task 5: Configure attributes

In this task, you'll learn how to configure default values for your template attributes, hide attributes that you don't want users to update, configure auto-generated person numbers and alter the column headings and tips.

Configuring the attributes will simplify data entry for the user and can restrict what actions the end-user can perform. For example, you can default the Action Code to HIRE and hide this attribute from the spreadsheet. Spreadsheets generated from this template can then only perform the HIRE action.

Default Values

There are three types of defaults you'll configure in this tutorial:

• Constants
• Other Selected Attributes
• Expression

Other types are available, dependent upon the data type of the attribute being defaulted.

Configuring Constant Defaults

Configure these attributes to default their values to a constant value.

1. Click the link on the Action Code attribute column heading.





2. Review the configuration of the attribute and the fields that you can update using the Edit panel.



The default for the attribute is preconfigured as None.

3. Change the Attribute Default to Constant value. A Constant Value field appears.





4. Specify a value of HIRE and click Save.





5. Edit these other attributes to configure a constant value default for them:

Attribute	Object	Constant Value
Name Type	Person Name	GLOBAL
Effective Sequence	Employment Terms	1
Effective Latest Change	Employment Terms	Y
Assignment Status Type	Employment Terms	ACTIVE_PROCESS

Note:

When you specify a default value for a lookup validated attribute you need to specify the lookup code, not the meaning.
6. Review the configured defaults using the Default column in the Configure attributes table.

Configuring Defaults from Other Attribute Values

You can configure attributes to default their values from another attribute already selected in the template.

Tip:

The copy of the attribute value occurs when uploading the spreadsheet data to the staging tables and isn't seen in the template's spreadsheets. When defaulting attribute values from another selected attribute, always hide the defaulted attribute.

1. Edit the Effective Start Date attribute on the Worker object.



Note:

When you create a new hire, the effective start date of the Worker record must be the same as the employee's start date.
2. Specify a Default of Existing selected attribute.





3. Use the searchable list of values on the Attribute Key field to select the Start Date attribute from the Worker object.



Tip:

The list of values uses the attribute key to uniquely identify each attribute in the template. You can find the attribute key for each attribute in the Attribute Key column on the Configure attributes table.



4. Uncheck the Display checkbox to hide the attribute from the spreadsheet.





5. Click Save.

Note:

The template designer automatically defaults user key attributes for parent-child relationships and date-effective fields on child-level objects to the parent's attribute value, so there is no need to do this manually.
6. Edit the Action Code on the Work Relationship, Employment Terms and Assignment objects to default the value from the Action Code on the Worker object and hide the attribute from the spreadsheet.





7. Click Save.



As these attributes have been hidden, they will disappear from the Configure attributes table.

8. Search for "action" and click the Show Hidden Attributes filter to display all occurrences of the Action Code attribute.

   

   
   
9. Edit these attributes to configure the default from an existing selected attribute and uncheck the Display checkbox:

Attribute	Object	Existing Selected Attribute
Start Date	Work Relationship	Worker_StartDate
Legislation Code	Person Legislative Data	PersonName_LegislationCode
Assignment Status Type	Assignment	WorkTerms_AssignmentStatusTypeCode



10. Save your changes.

Configure Defaults using an Expression

You can use groovy expressions to define the default value for an attribute. These can include references to other selected attributes by specifying the Attribute Key that uniquely identifies the attribute in the template.

1. Find the Attribute Key for the Person Number attribute.



Tip:

The attribute key is typically the object name (Worker) followed by the base attribute name (PersonNumber).
2. Edit the Assignment Number attribute on the Employment Terms object.
3. Specify a Default of Use expression and specify a Groovy Expression of "ET" + Worker_PersonNumber.



4. Click Save.
5. Configure an expression default for the Assignment Number attribute on the Assignment object using the expression "E" + Worker_PersonNumber .



6. Save your changes.

Tip:

It's recommended that you don't hide attributes defaulted with constant values or expressions until you've successfully tested them.
7. Consider configuring defaults for other attributes to simplify data entry, such as Legislation Code, Worker Type, Business Unit and Legal Employer. You can either hide these or leave them for the end-user to override if required.

Autogenerated Person Numbers

Only complete this step if you're autogenerating person numbers.

1. Edit the Person Number attribute on the Worker object.
2. Check the Autogenerate checkbox.



Note:

Although the person number will be generated when the worker is successfully uploaded, the user of the spreadsheet will still have to supply a value to uniquely distinguish each worker in the spreadsheet. The value supplied will be replaced by the autogenerated value.
3. Click Save.
4. Edit the Assignment Number attribute on the Employment Terms object and check the Autogenerate checkbox.





5. Uncheck the Display checkbox to hide the Assignment Number from spreadsheets generated from this template.

Tip:

Don't remove the Assignment Number default configured in the previous task. This will populate these attributes with a value based on the Person Number.
6. Edit the Assignment Number on the Assignment object to autogenerate its value and hide it from spreadsheets.
7. Save your changes.

Hide Columns

Once your constant and expression defaults are successfully tested, hide defaulted attributes that you don't want the user to change.

1. Edit the attribute to hide from generated spreadsheets.
2. Uncheck the Display checkbox.





3. Click Save.
4. Repeat this for other defaulted attributes you don't want the user to change, such as Action Code, Effective Sequence, Effective Latest Change, and Assignment Status Type.

Tip:

You can easily identify attributes configured with defaults by reviewing the Default column on the Configure attributes table.

Required Attributes

In this step, you'll edit the attributes you want to highlight as required in the spreadsheet.

1. Edit the First Name attribute and check the Required checkbox.





2. Click Save.
3. Repeat for any other attributes that aren't required by default that you want your user to supply.

Column Headings and Tips

Change the column headings and tips to use terminology that your business user will understand. For example, if you are autogenerating your person numbers you may want to rename the Person Number column heading and tip.

1. Edit the Person Number attribute.
2. Change the Column Heading to Row Identifier so users aren't confused when the person is created with a different person number.
3. Change the Column Tip to A number to uniquely identify the row in the spreadsheet.



Tip:

The tip is displayed when you hover over the column heading in the spreadsheet.
4. Click Save.

Reorder Columns

The order in which your columns are displayed in the table determines the order in which those columns are seen in the spreadsheet.

1. Select an attribute you want to move, avoiding clicking the link on the Column Heading. Drag and drop the attribute row to its new location.



Tip:

You need to remove any filters and save your changes before attempting to reorder columns.

Best Practice

Consider the following:

• Clearly specify the type of value to supply.

  If the attribute expects a code, then include 'Code' in the column heading. For example, 'Country Code', instead of 'Country'. To further clarify, you can define a default value of the most common value, so users know the format to supply data in.

• Configure a list of values where possible.
• Consider the order of your columns.

  If you've defined a dependent list of values, ensure the value your list is dependent upon is entered before the attribute with the referring list of values.

Task 6: Override parameters

You can override the default spreadsheet data loading behavior by overriding the parameter default values. In this section, you'll ensure data loading ceases if over 10% of the spreadsheet rows are in error, and you'll enable load events for incremental updates.

1. Navigate to the Override parameters step, either by clicking the step in the guided process bar, or by clicking the Continue button on the Configure attributes step.





2. Click Add Parameters. The Template Parameters drawer opens.





3. Select the Maximum Percentage of Load Errors parameter and click Add.





4. Click the Edit action and update the Value to 10.
5. Add the Enable Load Events for Incremental Updates parameter and update its value to Yes.





6. Click Continue.

Task 7: Add instructions

Optionally, add instructions to your spreadsheets to give your users guidance on how to use the spreadsheets generated from this template.

1. Click Add.





2. Specify a heading and your instruction.





3. Click Add.

   Tip:

   If you have multiple instructions, change the order in which they are displayed by dragging the instruction row up or down the table.
4. Click Continue.

Task 8: Configure access

There are two types of role access to configure for HSDL templates before activating them:

• Data Set Operations

  For business users to be able to use this template their roles must be assigned data set access to the template and the template must be activated.

• Template Maintenance

  Once activated you no longer automatically have access to maintain the template. You should configure which role has the authority to maintain the template once active.

Data set operations

Configure the roles that can generate spreadsheets from this template and the data set access they have.

Note:

The Data security section indicates which type of user uploads the spreadsheet data. If this is set to Elevated user, you may be restricted from assigning data set operations to any roles. The Assign Roles to Template field will confirm if you can.

1. Click Add under the Data set operations heading.





2. Search for and select the role to assign template access to, such as Human Resource Specialist.





3. Click Add.

By default, the role will be assigned access to create, save, and upload data sets.





4. Alter the data set access as required.

Data Set Operations

Operation	Description
Create	Data sets can be created.
Save	Data set data can be saved to the staging tables.
Upload	Data sets can be uploaded, and valid rows saved to the application.
Roll Back	Data sets can be rolled back, deleting data that was successfully loaded and not subsequently updated. Roll back is only available for a few business objects.
View All	All existing data sets for the template can be downloaded and reviewed, not just those created by the user.




Tip:

You may have a template that you need a role to be able to create and save data to the staging tables but not have access to upload that data, and a second role that can't create new data sets but can review data sets created by other users and upload them. This can achieve a form of approval.

Template maintenance

Once the template is active you can only maintain it if your role is configured to maintain the template.

These steps describe how to assign template maintenance.

1. Click Add under the Template maintenance heading.





2. Search for the template designer or maintenance role, such as HSDL Template Designer and add the roles that can maintain this template.





3. Click Add.

Task 9: Review and activate

Only active templates are visible in the Run Spreadsheet Data Loader task and are available to REST services. For templates that have a Draft status, complete these steps.

On the Review and activate step you can review the list of columns that will be seen in spreadsheets generated from the template and the order in which they will be displayed. You can also review attributes that are part of the template definition but not displayed in the spreadsheet.

Review

1. Review the list of Spreadsheet Attributes, checking for spelling errors in column headings and tips and confirming that the Validation Type, Required status, Default values, and column order are correct.





2. Click on the Hidden Attributes tab to review the attributes that are part of the template definition but not displayed in spreadsheets.

   

   
   

Validate and Activate

1. Click Validate.

If the template is valid, you'll see a dialog asking if you want to activate the template?






Note:

If the template has warnings or errors, you'll be able to review these on the Validation Messages tab.





2. Click Activate.

   Your template is now available on the Run Spreadsheet Data Loader task for users that have a role configured with data set access to the template and can be used by REST when supplying a csv file for upload.

Test Business User Access

You should now log in as a user with the role assigned access to your template and confirm the template is available in the Run Spreadsheet Data Loader task and that spreadsheets generated from the template work as desired.

Task 10: Exporting and Importing

In this task you'll export your template definition and learn how to import your template into production.

You'll require a HSDL Template Maintenance role on production configured to import templates for the business object your template is based on. Refer to the Configure Access to Design and Maintain HCM Spreadsheet Data Loader (HSDL) Templates tutorial for the steps to create such a role.

Exporting

When your template is fully tested and ready to be moved to production you can export the template definition.

1. Log into the application with your HSDL Template Designer role and navigate to the Spreadsheet Templates task.
2. Search for your template.
3. Click the Actions button and select the Export action.






Your template definition is exported as an XML file and should be available in your Downloads directory.

Importing

1. Navigate to the Spreadsheet Templates task in Data Exchange.
2. Click Import.





3. On the Import Spreadsheet Template panel, specify a name that describes the use case that the spreadsheet template supports, such as New Hires.
4. If the template is legislation specific, specify the Legislative Data Group that it's applicable for.
5. Select the template's XML definition file to import.
6. Provide a description so business users can understand when to use this template.



Tip:

A code will be defaulted based on the name specified but you can override this. It needs to be unique.
7. Click Import.

   You'll be returned to the Spreadsheet Templates page where a page level banner will confirm if the template is successfully imported or if issues were found.



Tip:

If errors were encountered, download the log file for more information.
8. Search for your imported template and click the template name to edit the template.
9. Repeat the steps in Task 8 to configure access and assign template maintenance roles.
10. Follow the template validation and activation steps in Task 9.

    Users with the assigned roles can now access your template in the Run Spreadsheet Data Loader task.

Next Steps

The following tutorials will further expand your HCM Spreadsheet Data Loader knowledge:

• Defining HSDL Templates to Create Multiple Child Records in a Spreadsheet Row
• Including Flexfield Segments in HCM Spreadsheet Data Loader Templates

Related Links

The latest tutorials for HDL and HSDL are published in this topic on Cloud Customer Connect:

• HCM Data Loader Oracle by Example Tutorials

Acknowledgements

• Authors - Ema Johnson (Lead Principal Product Manager, HCM Data Loader & AI)

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

---

Title and Copyright Information

Create a HCM Spreadsheet Data Loader Template to Bulk-Load New Hires

G12936-07

May 2026

Copyright ©2026,

Oracle and/or its affiliates.