Oracle FBDI Deep Dive -- File Format, UCM Upload, Job Scheduling, Error Handling & Templates

TL;DR

• Bottom line: Oracle FBDI (File-Based Data Import) is the primary bulk/batch data import mechanism for Oracle Fusion Cloud ERP -- you populate an XLSM template, generate a ZIP of CSVs, upload to UCM, then run ESS jobs to load interface tables and trigger the module-specific import process.
• Key limit: FBDI is batch-only and asynchronous -- no real-time capability. Recommended maximum file size is 250 MB per ZIP; split larger loads across multiple files.
• Watch out for: The UCM account path must exactly match the expected destination for each module (e.g., fin/generalLedger/import for journals). Using the wrong path causes silent failures.
• Best for: Data migration, periodic batch loads (journals, invoices, suppliers, inventory transactions), and any high-volume inbound data scenario where real-time is not required.
• Authentication: Manual uploads use Oracle ERP Cloud UI (SSO). Automated uploads use ErpIntegrationService SOAP/REST API with OAuth 2.0 or Basic Auth + Base64-encoded ZIP payload.

System Profile

Oracle FBDI is a built-in bulk data import framework within Oracle Fusion Cloud ERP (formerly Oracle Cloud Applications). It spans all major modules -- Financials, Procurement, Supply Chain Management, Project Management, and HCM. FBDI uses pre-built Excel (XLSM) templates that contain macros to generate properly formatted CSV files, which are then packaged into ZIP archives and uploaded to Oracle Universal Content Management (UCM) for processing by Enterprise Scheduler Service (ESS) jobs. This card covers FBDI across all Oracle Fusion Cloud ERP modules, focusing on the Financials and Procurement templates. It does NOT cover ADFdi (ADF Desktop Integrator) or Oracle Data Management Framework (HCM bulk loads).

API Surfaces & Capabilities

Oracle Fusion Cloud ERP provides three primary inbound data integration surfaces. FBDI is the file-based bulk option.

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Authentication

Authentication Gotchas

• ErpIntegrationService requires an integration user with specific roles: Integration Specialist, Financial Integration Specialist, or module-specific import roles. [src5]
• OAuth tokens issued by Oracle IDCS must include the correct scope for ERP API access. Missing scopes cause HTTP 403 errors.
• Basic Auth is officially supported for SOAP services but Oracle recommends migration to OAuth 2.0 for all new integrations.

Constraints

• Batch-only: FBDI has zero real-time capability. Minimum latency from file upload to data availability is 2-15 minutes.
• Template-locked format: Each FBDI import requires the exact XLSM template for that module. You cannot create custom templates or modify column structures.
• UCM path dependency: The UCM account/destination path is hardcoded per template. Uploading to the wrong path means the ESS job cannot locate the file.
• Interface table purge: Oracle purges interface table data after the import ESS job completes. Extract error records before purge.
• Macro dependency: XLSM templates require Excel macros. LibreOffice and Google Sheets cannot reliably execute these macros.
• No partial commit: Most FBDI imports are all-or-nothing. The entire batch succeeds or fails (some modules support partial success).
• Sequential by module: Concurrent FBDI imports for the same module cause interface table locking and unpredictable failures.

Integration Pattern Decision Tree

START -- User needs to bulk-import data into Oracle Fusion Cloud ERP
+-- Is this real-time (<1s)?
|   +-- YES --> STOP. FBDI is batch-only. Use Oracle REST API or SOAP API instead.
|   +-- NO --> Continue
+-- What's the data volume?
|   +-- < 100 records --> Consider REST API (simpler, no file handling)
|   +-- 100-500,000 records --> FBDI sweet spot (single file, single ESS job)
|   +-- > 500,000 records --> Split into multiple FBDI files (<= 250 MB each)
+-- One-time or recurring?
|   +-- One-time migration --> Manual FBDI (template + UI upload)
|   +-- Recurring --> Automate with ErpIntegrationService or OIC
+-- Which module?
|   +-- GL --> Journal Import (fin/generalLedger/import)
|   +-- AP --> Invoice Import (fin/payables/import)
|   +-- AR --> AutoInvoice (fin/receivables/import)
|   +-- Procurement --> Supplier/PO Import
|   +-- Assets --> Mass Additions (fin/assets/import)
|   +-- SCM --> Item/Inventory Import
+-- Error tolerance?
    +-- Zero-loss --> Pre-validate + check ESS logs + resubmit failures
    +-- Best-effort --> Upload, check summary counts only

Quick Reference

Most Common FBDI Templates by Module

FBDI File Structure

Step-by-Step Integration Guide

1. Download the correct FBDI template

Navigate to Oracle documentation or My Oracle Support to download the XLSM template for your specific import type. [src1]

# Navigate in Oracle ERP Cloud UI:
# Navigator > Tools > File Import and Export
# OR download from Oracle docs for your release

Verify: Open XLSM in Excel -- confirm "Instructions and CSV Generation" tab with "Generate CSV File" button.

2. Populate the template with source data

Fill in the data entry tab(s) with your source data. Mandatory columns vary by template. [src4]

# Journal Import (GL_INTERFACE) mandatory columns:
# STATUS = "NEW", LEDGER_ID, ACCOUNTING_DATE (YYYY/MM/DD),
# USER_JE_SOURCE_NAME, USER_JE_CATEGORY_NAME, CURRENCY_CODE,
# ENTERED_DR or ENTERED_CR, SEGMENT1..SEGMENTn

Verify: Row count matches source. Debits and credits balance.

3. Generate the CSV ZIP file

Click "Generate CSV File" on the Instructions tab. This macro creates a ZIP with correctly named CSVs. [src1]

# In Excel (macros enabled):
# 1. Go to "Instructions and CSV Generation" tab
# 2. Click "Generate CSV File"
# 3. Save the generated ZIP (e.g., JournalImport.zip)

Verify: Unzip and confirm CSV filenames match expected names.

4. Upload the ZIP file to UCM

Upload via File Import and Export tool with the correct UCM account path. [src4]

# Navigator > Tools > File Import and Export > Upload
# Select correct Account:
#   GL Journals:  fin/generalLedger/import
#   AP Invoices:  fin/payables/import
#   Suppliers:    prc/supplier/import

Verify: File appears with "Uploaded" status. Document ID is generated.

5. Run "Load Interface File for Import" ESS job

Submit the ESS job to load CSV data into interface tables. [src4]

# Tools > Scheduled Processes > Schedule New Process
# Search: "Load Interface File for Import"
# Select Import Process + Data File
# Click "Submit"

Verify: ESS job shows "Succeeded". Check log for record counts.

6. Run the module-specific import ESS job

Move data from interface tables to transaction tables. [src4]

# For GL: search "Import Journals"
# For AP: search "Import Payables Invoices"
# For Suppliers: search "Import Suppliers"
# Set module-specific parameters, then Submit

Verify: ESS job "Succeeded" or "Warning". Check output for imported/rejected counts.

7. Review errors and reprocess failures

Download ESS logs and query interface tables for rejected records. [src3]

# Download Log + Output files from completed ESS job
# Query interface tables BEFORE purge:
# GL: SELECT * FROM GL_INTERFACE WHERE STATUS = 'E'
# AP: SELECT * FROM AP_INTERFACE_REJECTIONS

Verify: Error count is zero or all errors are corrected and resubmitted.

Code Examples

Python: Automate FBDI upload via ERP Integration REST API

# Input:  CSV ZIP file, Oracle ERP Cloud credentials, job parameters
# Output: ESS job request ID for tracking import status

import requests
import base64

ERP_BASE_URL = "https://your-instance.fa.us6.oraclecloud.com"
USERNAME = "integration_user"
PASSWORD = "integration_password"

with open("JournalImport.zip", "rb") as f:
    file_content = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "OperationName": "importBulkData",
    "DocumentContent": file_content,
    "ContentType": "zip",
    "FileName": "JournalImport.zip",
    "JobName": "/oracle/apps/ess/financials/generalLedger/programs/JournalImportLauncher",
    "ParameterList": "1001,2026-03-09,ALL,N,N,N",
    "JobOptions": "ExtractFileType=ALL,InterfaceDetails=2"
}

response = requests.post(
    f"{ERP_BASE_URL}/fscmRestApi/resources/latest/erpintegrations",
    json=payload,
    auth=(USERNAME, PASSWORD),
    headers={"Content-Type": "application/json"},
    timeout=300
)

if response.status_code == 201:
    result = response.json()
    print(f"Import submitted. ESS Request ID: {result.get('ReqstId')}")
else:
    print(f"Error {response.status_code}: {response.text}")

JavaScript/Node.js: Automate FBDI upload via SOAP ErpIntegrationService

// Input:  CSV ZIP file path, Oracle ERP Cloud credentials
// Output: ESS job request ID

const fs = require('fs');
const https = require('https');

const ERP_HOST = 'your-instance.fa.us6.oraclecloud.com';
const base64Content = fs.readFileSync('JournalImport.zip').toString('base64');

const soapEnvelope = `<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:typ="http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/types/">
  <soapenv:Body>
    <typ:importBulkData>
      <typ:document>
        <typ:Content>${base64Content}</typ:Content>
        <typ:FileName>JournalImport.zip</typ:FileName>
        <typ:ContentType>zip</typ:ContentType>
      </typ:document>
      <typ:jobName>/oracle/apps/ess/financials/generalLedger/programs/JournalImportLauncher</typ:jobName>
      <typ:parameterList>1001,2026-03-09,ALL,N,N,N</typ:parameterList>
      <typ:jobOptions>ExtractFileType=ALL,InterfaceDetails=2</typ:jobOptions>
    </typ:importBulkData>
  </soapenv:Body>
</soapenv:Envelope>`;

const auth = Buffer.from('username:password').toString('base64');
const req = https.request({
  hostname: ERP_HOST,
  path: '/fscmService/ErpIntegrationService',
  method: 'POST',
  headers: {
    'Content-Type': 'text/xml;charset=UTF-8',
    'Authorization': `Basic ${auth}`,
    'SOAPAction': 'importBulkData'
  }
}, (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => console.log('Response:', data));
});
req.write(soapEnvelope);
req.end();

cURL: Upload FBDI and check status

# Step 1: Upload FBDI file and trigger import
curl -s -X POST \
  "https://YOUR_INSTANCE.fa.us6.oraclecloud.com/fscmRestApi/resources/latest/erpintegrations" \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{"OperationName":"importBulkData","DocumentContent":"BASE64_CONTENT","ContentType":"zip","FileName":"JournalImport.zip","JobName":"/oracle/apps/ess/financials/generalLedger/programs/JournalImportLauncher","ParameterList":"1001,2026-03-09,ALL,N,N,N","JobOptions":"ExtractFileType=ALL,InterfaceDetails=2"}'

# Step 2: Check ESS job status
curl -s -X GET \
  "https://YOUR_INSTANCE.fa.us6.oraclecloud.com/fscmRestApi/resources/latest/erpintegrations?finder=ESSJobStatusRF;requestId=12345678" \
  -u "username:password" -H "Accept: application/json"

Data Mapping

FBDI CSV Column Mapping for Common Templates

Data Type Gotchas

• Date format must be YYYY/MM/DD (forward slashes), NOT YYYY-MM-DD. [src4]
• Amounts must use period (.) as decimal separator regardless of locale. European comma-decimal formats fail. [src3]
• Account segments must exactly match Chart of Accounts values. Leading zeros matter -- 001 differs from 1. [src4]
• AP Invoice line amounts must sum to header INVOICE_AMOUNT. Mismatch rejects the entire invoice. [src1]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Silent UCM path failures: Wrong UCM path uploads successfully but ESS job can't find the file. Fix: Create a lookup table mapping each template to its exact UCM path. [src4]
• CSV filename corruption: Manually renamed CSVs cause "No data found" errors. Fix: Always use XLSM macro or match exact Oracle filenames. [src3]
• Interface table purge race condition: Error records vanish after import job completes. Fix: Download ESS output files immediately after job completion. [src4]
• Base64 encoding issues: Wrong encoding or line breaks corrupt the file on UCM. Fix: Use standard RFC 4648 Base64 without line breaks. [src5]
• ESS job queue saturation: Many simultaneous FBDI imports block all scheduled processes. Fix: Throttle to 2-3 concurrent FBDI jobs per module. [src6]
• Character encoding failures: Non-ASCII characters require explicit UTF-8 encoding. Fix: Set UTF-8 encoding in programmatic CSV generation. [src3]

Anti-Patterns

Wrong: Uploading raw CSV files without XLSM-generated ZIP

# BAD -- creating ZIP manually with arbitrary CSV filenames
zip manual_upload.zip my_journals.csv
# ESS job says "No data found" -- filename doesn't match Oracle's format

Correct: Use the XLSM template macro to generate the ZIP

# GOOD -- use official template or match exact filenames:
# GL Journals:  GlInterface.csv
# AP Invoices:  ApInvoicesInterface.csv + ApInvoiceLinesInterface.csv
# Suppliers:    PozSuppliersInt.csv + PozSupplierSitesInt.csv

Wrong: Running concurrent FBDI imports for the same module

# BAD -- submitting 5 journal imports simultaneously
for f in files:
    threading.Thread(target=submit_fbdi, args=(f,)).start()
# Result: interface table locking, data corruption

Correct: Serialize within module, parallelize across modules

# GOOD -- sequential within module, parallel across modules
threading.Thread(target=import_sequential, args=(gl_files, "GL")).start()
threading.Thread(target=import_sequential, args=(ap_files, "AP")).start()
# GL and AP use different interface tables -- no locking

Wrong: Not validating data before upload

# BAD -- blindly uploading without pre-validation
generate_csv(raw_data)
upload_and_import()
# Result: 30% rejection rate, hours of debugging

Correct: Pre-validate against Oracle business rules

# GOOD -- validate accounts, periods, amounts before CSV generation
errors = validate_all_rows(data)
if not errors:
    generate_csv(data)
    upload_and_import()
else:
    report_errors(errors)

Common Pitfalls

• Wrong date format: Oracle expects YYYY/MM/DD (forward slashes). Most languages default to YYYY-MM-DD. Fix: Explicitly format dates with forward slashes. [src4]
• Missing STATUS = 'NEW': GL_INTERFACE.STATUS must be "NEW" for every row. Blank status causes silent skipping. Fix: Hardcode STATUS = 'NEW' as first column. [src4]
• Not splitting large files: 1M+ records in a single file causes ESS timeouts. Fix: Split into 50K-100K record files; submit sequentially. [src6]
• Ignoring GROUP_ID: Without GROUP_ID, you can't isolate your records in GL_INTERFACE. Fix: Always set GROUP_ID to a unique batch identifier. [src4]
• Not downloading logs before purge: Interface tables are purged after import. Fix: Automate ESS log download immediately after job completion. [src4]
• Wrong template version: Templates vary between releases. Fix: Always download the template for your specific release (25D vs 26A). [src1]

Diagnostic Commands

# Check FBDI import ESS job status via REST API
curl -s -X GET \
  "https://YOUR_INSTANCE.fa.us6.oraclecloud.com/fscmRestApi/resources/latest/erpintegrations?finder=ESSJobStatusRF;requestId=YOUR_REQUEST_ID" \
  -u "username:password" -H "Accept: application/json"

# Download ESS job execution details (log + output)
curl -s -X POST \
  "https://YOUR_INSTANCE.fa.us6.oraclecloud.com/fscmRestApi/resources/latest/erpintegrations" \
  -u "username:password" -H "Content-Type: application/json" \
  -d '{"OperationName":"downloadESSJobExecutionDetails","ReqstId":"YOUR_REQUEST_ID","FileType":"all"}'

# Verify ErpIntegrationService WSDL accessibility
curl -s -o /dev/null -w "%{http_code}" \
  "https://YOUR_INSTANCE.fa.us6.oraclecloud.com/fscmService/ErpIntegrationService?WSDL" \
  -u "username:password"
# Expected: 200

# SQL queries for interface table errors (run before purge):
# GL: SELECT * FROM GL_INTERFACE WHERE STATUS = 'E' AND GROUP_ID = :id
# AP: SELECT * FROM AP_INTERFACE_REJECTIONS WHERE PARENT_TABLE = 'AP_INVOICES_INTERFACE'

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• FBDI template column structures vary between releases. Always download the template for your specific version -- using a template from a different release may cause silent failures.
• ErpIntegrationService and ERP Integration REST API are wrappers around the same FBDI process. They do not bypass FBDI limitations.
• ESS job concurrency is shared across ALL scheduled processes, not just FBDI. Heavy loads can block period close and reporting.
• Oracle does not publish official file size limits. The 250 MB recommendation comes from Oracle A-Team best practices.
• Interface table column names and CSV filenames are case-sensitive on some Oracle Cloud infrastructure configurations.
• FBDI is the ONLY supported import mechanism for some data types (e.g., GL budgets). No REST or SOAP alternative exists for these.