Tuesday, 29 September 2026

AI Agent: Spreadsheet Data Loader Advisor for HSDL

AI Agent: Spreadsheet Data Loader Advisor for HSDL – Complete Setup & Runtime Walkthrough Guide

Bulk data entry in Oracle Cloud HCM has traditionally relied on technical HCM Data Loader (HDL) pipelines or desktop-dependent HCM Spreadsheet Data Loader (HSDL) workbooks. In Update 26C, Oracle transforms this experience with the release of the AI Agent: Spreadsheet Data Loader Advisor for HSDL.

Delivered as an autonomous workflow agent running inside AI Agent Studio and surfaced directly on Redwood pages via Guided Journeys, this advisor allows users to upload raw delimited CSV files and execute HSDL batch loads through natural conversation. Below is the complete step-by-step implementation guide covering security permissions, ESS indexing jobs, CSV header matching rules, and the complete runtime demonstration with every step illustrated.

📌 Technical Architecture Profile

Target Release Oracle Fusion Cloud HCM Update 26C
Delivered Agent Name Spreadsheet Data Loader Advisor
Agent Workflow Code ORA_DATALOADER_HSDL_AGENT
Deployment Architecture Guided Journey (Workflow Agent) on Redwood Pages / AI Agent Studio / AI Chat
Supported File Inputs Delimited CSV Files (Cross-platform: macOS, Linux, Windows)
Delivered Privileges Access HCM Spreadsheet Data Loader Advisor & Access HCM Data Loader Advisor

Step 1: Configure Administrator Profile Options

Enabling the AI Agent and Guided Journey infrastructure requires setting four profile options at the Site level. Setting ORA_ASE_SAS_INTEGRATION_ENABLED to Yes is critical, as it activates the Permission Groups button on role configuration screens in Security Console.

Navigation: Setup and Maintenance > Search Tasks: Manage Administrator Profile Values

Profile Option Code Required Value Level Functional Purpose
ORA_ASE_SAS_INTEGRATION_ENABLED Yes Site Enables Smart Agent Services & activates Permission Groups in Security Console
ORA_PER_GUIDED_JOURNEYS_ENABLED Y Site Enables Guided Journeys framework across Fusion HCM
ORA_PER_GUIDED_JOURNEYS_SETUP_REDWOOD_ENABLED Y Site Enables Redwood configuration for Guided Journeys Setup
ORA_HCM_VBCS_PWA_ENABLED Y Site Enables Redwood Visual Builder Progressive Web App framework

Step 2: Security Role Architecture (Duty Role, Job Role & User Assignment)

Access to the HSDL AI Agent is governed through dedicated duty and job roles utilizing Permission Groups. Follow these sub-steps in the Security Console (Tools > Security Console):

A. Create the Custom Duty Role (AL_TEST_AGENT_DUTY_ROLE)

  1. Click Create Role.
  2. Set Role Name to AL_TEST_AGENT_DUTY_ROLE and Role Code to AL_TEST_AGENT_DUTY_ROLE.
  3. Select Role Category as HCM - Duty Roles.
  4. Under Duty role for, select the radio button Permission Groups.
Figure 1: Creating custom duty role with 'Permission Groups' radio checked.
  1. Navigate to Step 5: Role Hierarchy and click the Roles and Permission Groups sub-tab.
  2. Click Add Role, search for, and add the following two permissions:
    • Access HCM Spreadsheet Data Loader Advisor (Code: ORA_DR_HRC_ACCESS_HSDL_LOADER_ADVISOR)
    • Access HCM Data Loader Advisor (Code: ORA_DR_HRC_ACCESS_DATA_LOADER_ADVISOR)
  3. Proceed to the Summary step and click Save and Close.
Figure 2: Adding HSDL and HDL Advisor permission groups under Duty Role Hierarchy.
Figure 3: Summary verification for AL_TEST_AGENT_DUTY_ROLE.

B. Create the Custom Job Role & Assign to User

  1. Click Create Role.
  2. Set Role Name to AL_TEST_DL_AGENT_JOB_ROLE and Role Code to AL_TEST_DL_AGENT_JOB_ROLE.
  3. Select Role Category as HCM - Job Roles and check Enable Permission Groups.
Figure 4: Creating AL_TEST_DL_AGENT_JOB_ROLE with Permission Groups enabled and adding duty role membership.
  1. Under Role Hierarchy > Roles and Permission Groups, search for and add the newly created duty role: AL_TEST_AGENT_DUTY_ROLE.
  2. Save and close the Job Role.
  3. Navigate to Users in Security Console, edit the target user account (e.g., Mitch Blum), and attach AL_TEST_DL_AGENT_JOB_ROLE. Save and close.
Figure 5: Attaching AL_TEST_DL_AGENT_JOB_ROLE to user account in Security Console.

Step 3: Run Document Preparation & Indexing ESS Processes

The HSDL Advisor relies on Retrieval-Augmented Generation (RAG) and document indexing to understand business objects and existing active templates. Navigate to Tools > Scheduled Processes and submit the following three background jobs in sequence:

⚠️ Sequential Execution Requirement: Run each process only after the preceding process has completed with a status of Succeeded. Files cannot be loaded or interpreted by the agent until Process Agent Documents finishes successfully.
  1. Send Pending LDAP Requests: Synchronizes role memberships and permission groups across application security.
  2. Prepare HCM Data Loader AI Agent: Configures agent parameters and sets up initial business object mappings.
  3. Process Agent Documents (ProcessRAGDocuments): Processes and publishes HSDL business object metadata, template structures, and documentation into the agent vector store.
Figure 6: Monitoring Scheduled Processes to verify indexing completion.

Step 4: CSV File Preparation & Header Mapping Rules

The HSDL Advisor does not create new HSDL templates. Instead, it consumes a delimited CSV file, reads the attribute columns in the header row, checks which existing active HSDL template is suitable for that data, and initiates the load.

Header Row Identification Rule

The headers in the CSV file must correspond to attributes defined under the HDL Business Objects page (Data Exchange > View Business Objects) or active HSDL template field names.

  • Row 1 is mandatory headers: Do not include titles, blank rows, or company notes above the first row.
  • Attribute name alignment: Use exact or recognizable attribute labels (e.g., EffectiveStartDate, BusinessUnitName, PositionCode).
  • File Format: Always save as CSV UTF-8 (Comma delimited) (*.csv).

Sample CSV Layout: Position Business Object

Here is the exact CSV format used in the demonstration (Position_load.csv) configured to load Position attributes:

EffectiveStartDate,BusinessUnitName,PositionCode,Name,DepartmentName
01-01-1951,US1 Business Unit,123450,Name_123450,Benefits US

Step 5: Testing & Running the Advisor in AI Agent Studio

Administrators can test and demo the advisor directly in AI Agent Studio before publishing to end users:

1. Locate Workflow in AI Agent Studio

Sign in as an Administrator (e.g., Curtis Feitty), navigate to AI Agent Studio > Workflows, and search for Spreadsheet Data Loader Advisor (Code: ORA_DATALOADER_HSDL_AGENT). Click the Run (Play) icon to launch the chat interface.

Figure 7: Locating and launching the Spreadsheet Data Loader Advisor workflow in AI Agent Studio.

2. Initiate Chat & Upload CSV

In the chat interface, click the prompt: "Help me load data from a CSV file". The agent explains that it will inspect the header row, identify attributes, suggest active HSDL templates, map columns, and initiate the load. Attach and upload Position_load.csv using the paperclip attachment icon.

Figure 8: Initiating conversational data load and uploading Position_load.csv.

3. Automatic Object Identification & Template Approval

The agent inspects the file, outputs "Identified business object : Position", and displays a table of available active templates (Position / Code: ORA_PER_POSITION and Positions_Translations). Click Approve to proceed with the recommended template.

Figure 9: Business object identification and interactive template recommendation table.

4. Job Initiation & Review Confirmation

Upon clicking Approve, the agent transitions through Thinking... and confirms: "Data load was successfully initiated for the file with request ID : 10036474". It provides direct links: "Review Spreadsheet: here" and "Navigate To Recent Spreadsheet Loads" along with the exact data set name.

Figure 10: Successful HSDL load initiation message with Request ID and audit links.

5. Verify in Data Exchange Work Area

Navigate to Data Exchange > Recent Spreadsheet Loads to verify the background load status, imported row counts, and data set details.

Figure 11: Auditing the batch execution under Data Exchange > Recent Spreadsheet Loads.

Step 6: Deploying the Advisor to Redwood Pages via Guided Journey

To expose the advisor directly to users on operational Redwood pages (such as Position Creation or Data Exchange), configure a Guided Journey task and bind it in Visual Builder Studio:

A. Create the Guided Journey

  1. Navigate to My Client Groups > Show More > Journeys Setup > Guided Journey.
  2. Click Create to initialize a new Guided Journey.
  3. Add a task with the following values:
    • Task Name: HCM Spreadsheet Data Loader AI Agent
    • Task Description: Upload csv files and initiate HSDL
    • Task Type: Agent
    • Agent Type: Workflow Agent
    • Workflow Agent: HCM Spreadsheet Data Loader Advisor
  4. Save the Guided Journey and record the generated Guided Journey Code and Task Code.

B. Bind in Visual Builder Studio

  1. Open any target Redwood page (such as the Position creation page).
  2. From the Settings and Actions user menu, select Edit Page in Visual Builder Studio.
  3. Select an existing project or create a new VB Studio workspace project.
  4. Under Page Properties, locate the Set Guided Journey Page property at the Page level and select your Guided Journey.
  5. Use Preview to test the advisor's interactive CSV upload, then Publish the workspace.

What’s Coming Next: Enhancements in 26D

Oracle has already previewed significant functional additions arriving in Update 26D to expand conversational diagnostics and status auditing:

  • Real-Time Load Progress: Conversational tracking of data set execution status, including counts of loaded objects.
  • In-Line Error Diagnostics: Detailed failure breakdowns displaying message type, source process, full error text, and occurrence counts.
  • Natural Language Historical Search: Ask queries like "Show me the largest loads submitted last week" or "Find loads submitted by user Mitch Blum".
  • Structured Summary Tables: Direct tabular responses containing data set names, row counts, creation dates, templates used, and spreadsheet links.

🎯 Key Implementation Takeaways

  • Role Setup with Permission Groups: Select the Permission Groups radio button on the duty role after setting ORA_ASE_SAS_INTEGRATION_ENABLED to Yes.
  • Scheduled Processes Ordering: Always verify that Prepare HCM Data Loader AI Agent and Process Agent Documents have succeeded before attempting CSV loads.
  • Template Discovery: The agent does not create new templates; your CSV headers must match attributes of existing, active HSDL templates in the pod.
  • Cross-Platform Ready: Business users on macOS, Linux, or ChromeOS can now execute HSDL loads directly through browser conversation without installing Windows desktop integration tools.
Oracle Fusion Cloud HCM Update 26C Spreadsheet Data Loader Advisor Setup Guide
Posted by at
Labels: , ,

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)