Oracle HCM Data Loader automation is easier to review when the conversation follows the actual stages: prepare a file, upload it, start processing, and inspect the outcome. Fusion Toolkit’s 3.2.0 preview lets you ask AI Administrator to prepare a synthetic job-family file locally, then review upload and processing as separate changes. A completed process still needs a check of the resulting HCM records.
Synthetic illustration: The prompts, profile, dates, and job-family identifiers below are examples, not a recorded session or a successful load. No employee data is used.
Run it directly from the CLI
You can prepare the file, plan its upload and processing, and monitor the returned request directly in a terminal without an AI agent. Use the matching Fusion Toolkit 3.2.0 preview, a valid licence, and the existing hcm-test profile with the required HDL privileges. Open Bash or WSL in the installed fusion-toolkit-ai-administrator folder, with fusion-toolkit on your PATH. The ai-admin commands below execute the Toolkit workflow directly without starting a model session. Confirm the returned environment and origin before proceeding.
Prepare and inspect the synthetic archive locally
Choose a new output directory and the intended effective date:
fusion-toolkit --version
fusion-toolkit ai-admin docs status
fusion-toolkit --output json ai-admin hdl prepare \
--output-directory ./hdl-job-family-test \
--effective-date 2026-10-01
python3 -m json.tool hdl-job-family-test/manifest.json
unzip -p hdl-job-family-test/SyntheticJobFamily.zip JobFamily.dat
Preparation creates SyntheticJobFamily.zip, manifest.json, and upload-request.json locally and makes no Oracle request. Inspect the record and archive checksum. The fixture uses the fixed FTK_SYNTHETIC owner and FTK_SYNTHETIC_FAMILY keys; another directory does not change those keys. Confirm the owner is valid and those keys are reserved in your test environment before loading.
Plan the upload, then approve it interactively
Use the generated request file. Its relative archive path is resolved beside that file. Add Oracle’s action media type to the upload request before planning:
python3 - <<'PY'
import json
from pathlib import Path
path = Path('hdl-job-family-test/upload-request.json')
request = json.loads(path.read_text())
request['headers'] = {
'Content-Type': 'application/vnd.oracle.adf.action+json'
}
path.write_text(json.dumps(request, indent=2) + '\n')
PY
fusion-toolkit --profile hcm-test --output human \
ai-admin api plan \
--request hdl-job-family-test/upload-request.json
Review the full upload plan, including the destination, archive hash, impact, documentation, expiry, and lack of independent built-in upload verification. Planning does not upload. After review, replace the placeholder below with the actual upload plan_id, run apply in an interactive terminal, and enter its exact confirmation phrase only if approved:
fusion-toolkit --profile hcm-test --output human \
ai-admin api apply --plan REPLACE_WITH_UPLOAD_PLAN_ID
Preserve the real content identifier returned by this upload. Do not guess it or automatically submit the same file again after an uncertain response.
Prepare a separate import-and-load plan
Replace REPLACE_WITH_RETURNED_CONTENT_ID in this JSON with the actual content identifier before running the plan command:
cat > hdl-job-family-test/process-request.json <<'JSON'
{
"schema_version": "3.0",
"operation_id": "hcm.hdl.create",
"headers": {
"Content-Type": "application/vnd.oracle.adf.action+json"
},
"body": {
"contentId": "REPLACE_WITH_RETURNED_CONTENT_ID",
"dataSetName": "FTK Synthetic Job Family",
"fileAction": "IMPORT_AND_LOAD",
"fileEncryption": "NONE"
}
}
JSON
fusion-toolkit --profile hcm-test --output human \
ai-admin api plan \
--request hdl-job-family-test/process-request.json
IMPORT_AND_LOAD explicitly requests both stages. NONE matches this unencrypted synthetic fixture; use the appropriate encryption for your own data, as explained in Oracle’s HDL REST tutorial. Review the complete new plan, actual content identifier, source keys, effective date, and processing impact. Upload approval does not approve loading. Only after that separate review, use the new processing plan_id:
fusion-toolkit --profile hcm-test --output human \
ai-admin api apply --plan REPLACE_WITH_PROCESSING_PLAN_ID
Confirm this plan interactively and retain the actual returned RequestId. Both plans expire after ten minutes and are consumed once; changed or expired plans need fresh review. Submission acceptance does not establish that the job family was loaded.
Monitor and diagnose the existing request
Replace the RequestId placeholder with the real processing request identifier. The same parameter file is used for monitoring and diagnostics:
cat > hdl-job-family-test/monitor-parameters.json <<'JSON'
{
"RequestId": "REPLACE_WITH_RETURNED_REQUEST_ID"
}
JSON
fusion-toolkit --profile hcm-test --output json \
ai-admin api execute --recipe hdl-monitor \
--parameters hdl-job-family-test/monitor-parameters.json \
> hdl-job-family-test/monitor-result.json
Check the exit status and saved JSON. Polling permits up to 30 attempts within a 60-second deadline; timeout does not stop Oracle processing. After successful polling the recipe reads business-object results and messages, each bounded to 100 items. If polling fails or times out, read those diagnostics separately against the same RequestId:
fusion-toolkit --profile hcm-test --output json \
ai-admin api execute --recipe hdl-diagnostics \
--parameters hdl-job-family-test/monitor-parameters.json \
> hdl-job-family-test/diagnostics-result.json
python3 -m json.tool hdl-job-family-test/diagnostics-result.json
Inspect every step under data.steps for status, counts, messages, and incomplete reads before considering recovery. Finally, verify the job-family code, name, effective date, and record count through an authorized HCM read or the application. Keep that business verification separate from processing status.
The following AI Administrator walkthrough performs these same stages conversationally.
Start in the installed AI Administrator workspace
Start a compatible agent, such as Codex, Claude Code, or Gemini CLI, inside the installed AI Administrator workspace so it reads the bundled instructions. Use the matching 3.2.0 preview Toolkit, a valid licence, and an existing configured non-production Oracle profile. Here, that profile is hcm-test.
Before remote work, have the assistant identify the profile’s declared environment, site address, and Oracle account. The account needs the appropriate permissions for upload, processing, status, messages, and business-object results. Credentials remain in the configured profile.
The assistant should find the documented workflow for each stage and check documentation freshness. If it relies on cached documentation while offline, it should disclose its retrieval date. Different permissions may apply at different stages; an upload privilege does not guarantee visibility of load errors or resulting records.
Prepare the synthetic file locally
Begin with:
Prepare the synthetic job-family HDL file locally in a new hdl-demo folder, effective from 2026-10-01. Show me the file details and checksums. Do not contact Oracle or upload anything.
The preparation should create SyntheticJobFamily.zip containing JobFamily.dat, together with a file record and upload instructions that the assistant manages. This step makes no Oracle requests. It refuses to overwrite its existing output files, so use a fresh folder for another preparation.
Oracle’s HDL file tutorial explains the file structure and ZIP packaging. A generated archive is preparation; it is not validation against your environment’s business rules.
Ask the assistant to explain the record:
Show the job-family code, name, source keys, and effective date in the prepared file. Explain what I need to check before using it in hcm-test.
The fixture uses source owner FTK_SYNTHETIC and source identifier FTK_SYNTHETIC_FAMILY. The job-family code is also FTK_SYNTHETIC_FAMILY, and the name is Synthetic Job Family. The illustrated date appears in the HDL record as 2026/10/01.
Confirm that the source owner is valid in your test environment and that these identifiers are reserved for this test. Preparing a different folder does not create different business keys. Loading the same keys can update an existing record, so resolve any collision before planning processing.
Plan the upload, then review its approval
Next, ask:
Prepare an upload plan for the reviewed SyntheticJobFamily.zip in hcm-test. Show the complete plan and wait for my approval. Do not start import or loading.
AI Administrator should bind the exact local archive and its checksum to the upload operation. It handles the request format and file encoding. Oracle describes this stage as uploading a file to the HDL import account on WebCenter Content. Uploading does not establish that a job family has been loaded.
Before asking for approval, the assistant must display the complete current upload plan. Check the environment, site address, Oracle account, exact action and destination, full current state with secrets hidden or a clear statement that it cannot be inspected, archive and checksum, impact, recovery guidance, documentation source, release and checksum, verification limits, and plan reference, fingerprint, and expiry.
The upload contract has no independent built-in verification. That limitation should be visible before approval. Preserve the actual response evidence, including the content identifier if one is returned.
Only after reviewing the displayed plan, an approval could be:
I approve the displayed upload plan for the reviewed SyntheticJobFamily.zip in hcm-test.
The assistant should apply that exact plan once. Plans expire after ten minutes. A changed file or expired plan requires a newly displayed plan and fresh approval. If the result is uncertain, investigate it before another upload. Do not invent a content identifier or continue without reliable evidence of the file to process.
Plan import and loading using the returned content identifier
After the upload response supplies the real content identifier, continue:
Using the content identifier returned by that upload, prepare a separate plan to import and load the synthetic job family in hcm-test. Name the data set FTK Synthetic Job Family and use the unencrypted fixture. Do not start processing yet.
The assistant should use the actual identifier from this upload, without guessing its value or where it appears in the response. The plan should explicitly request import and loading. Oracle’s Submit HCM Data Loader reference distinguishes this from import only.
Creating this data set starts the chosen processing sequence. Review the complete current processing plan with the same checks as the upload plan, plus the actual content identifier, data-set name, processing action, and encryption choice. Processing submission also lacks independent built-in verification; monitoring follows separately. Consider the effect of the source keys and effective date on any existing record.
The earlier upload approval cannot authorize this new action, whose content identifier was unknown before upload. Only after the complete processing plan is displayed and reviewed, an approval could be:
I approve the displayed plan to import and load that uploaded synthetic job-family file in hcm-test.
The assistant should apply this plan once and capture the returned request identifier. Acceptance is not completed processing or business verification. If a later load or rollback is needed, it requires another plan and approval. Rollback depends on support for the business object; it is not a universal undo.
Monitor the existing request and investigate errors
Use the returned request identifier:
Monitor the request from that processing step. Explain its status, business-object counts, and messages, and tell me if monitoring ends before processing finishes.
The preview monitor uses bounded status checks: up to 30 attempts within a 60-second deadline. A monitoring timeout does not mean Oracle stopped processing. Error, failed, and completed-with-errors states must not be presented as successful completion.
After successful polling, the workflow reads business-object results and messages, each limited to 100 items. If polling fails or expires, those later reads do not run automatically. Follow up with:
Investigate the same request’s current status, business-object results, and error messages. Explain completed work, failures, and anything still unknown before suggesting recovery.
The assistant should use diagnostic reads against that existing request. Oracle documents the data-set status and data-set messages. Inaccessible or truncated results must remain explicit limitations. Diagnose uncertain processing before considering resubmission. The same distinction appears in ESS job monitoring and recovery.
Verify the resulting HCM record
Finish with:
Check whether the intended job family exists with the reviewed code, name, and effective date. Report processing status and record verification separately.
Use an appropriately authorized read where available, or check the HCM application with the responsible administrator. Confirm the intended record count and investigate unexpected existing versions. If the assistant cannot inspect the record, it should say that business verification remains outstanding.
Keep the archive, approvals, returned identifiers, processing evidence, and record check together. Use the Fusion Toolkit documentation to prepare your own staged test workflow.