Oracle ERP Cloud FBDI Import Capabilities

TL;DR

• Bottom line: FBDI (File-Based Data Import) is Oracle ERP Cloud's primary bulk inbound data mechanism — CSV files packaged in ZIP archives uploaded to UCM, then processed by ESS jobs into interface tables and finally application tables. [src1]
• Key limit: 250 MB max file size per ZIP; ~100,000 records per CSV for optimal performance; max 10 parallel import batches; 20 files per job for up to 2 million total records. [src3]
• Watch out for: FBDI is a two-phase process — "Load Interface File for Import" loads to interface tables, then a separate module-specific ESS job imports to application tables. Skipping phase 2 leaves orphaned interface records. [src5]
• Best for: Batch/bulk inbound data loading — data migrations, periodic integrations, and high-volume transactional imports (journals, invoices, assets, suppliers). [src4]
• Authentication: Basic Auth or OAuth 2.0 against ErpIntegrationService (SOAP/REST) for automated imports; manual UI upload requires standard Fusion login. [src2]

System Profile

Oracle ERP Cloud FBDI is a platform-level capability available across all Oracle Fusion Cloud Applications editions. It provides a standardized file-based import mechanism using Excel/CSV templates that map directly to interface tables. FBDI covers all major Financials modules (GL, AP, AR, FA, CM), Supply Chain Management, HCM, and Project Management. This card focuses on the Financials modules but the FBDI architecture is identical across all pillars. [src1]

FBDI is not a standalone API — it is a file processing pipeline that can be triggered manually via the Scheduled Processes UI, or programmatically via the ErpIntegrationService SOAP/REST web service (importBulkData operation). For automated integrations, Oracle Integration Cloud (OIC) provides a native ERP Cloud Adapter with a dedicated "Import Bulk Data" action. [src2, src7]

API Surfaces & Capabilities

FBDI is not a traditional API but a file-processing pipeline. It can be invoked through multiple channels, each suited to different integration patterns. [src2, src4]

Rate Limits & Quotas

Per-File / Per-Job Limits

ESS Job Scheduling Limits

UCM Upload Limits

Authentication

Authentication Gotchas

• The integration user must have the Integration Specialist role (or equivalent custom role with FND_MANAGE_SCHEDULED_PROCESSES_PRIV) to submit ESS jobs via ErpIntegrationService. [src2]
• Basic Auth is blocked if the instance enforces SSO — use OAuth 2.0 or SAML assertion instead. Many production instances enable SSO, breaking basic auth automations that worked in non-production. [src2]
• The DocumentAccount parameter in importBulkData must match the UCM account path for the target module (e.g., fin$/payables$/import$). Wrong path = file uploads but ESS job fails silently. [src7]

Constraints

• FBDI templates are versioned per Oracle quarterly release (e.g., 25D, 26A). Using a template from a previous release may cause "Load Interface File for Import" to fail with column-mismatch errors. Always re-download templates from Oracle documentation for your current release. [src1, src4]
• The import is a two-phase process: Phase 1 (Load Interface File for Import) loads CSV data into interface tables; Phase 2 (module-specific job like Import Journals) validates and moves data to application tables. Both phases must complete successfully. [src5]
• Failed records in interface tables are not automatically cleaned up. If you resubmit the same batch without purging failed records, you get duplicates or constraint violations. Run the purge process before resubmission. [src6, src8]
• FBDI is inbound-only. For outbound data extraction, use BICC (BI Cloud Connector), BIP reports, or the REST API. [src1]
• ESS job scheduling is shared across all Oracle Fusion processes — a backlog of other scheduled processes (BIP reports, subledger accounting) can delay FBDI import jobs. [src4]
• The jobOptions parameter is mandatory for all programmatic FBDI imports via ErpIntegrationService. Omitting it causes the job to succeed without actually importing data. [src2]

Integration Pattern Decision Tree

START — User needs to bulk-import data into Oracle ERP Cloud
|
+-- What module?
|   +-- GL (Journals) --> Template: JournalImportTemplate.xlsm
|   |   +-- ESS Phase 1: "Load Interface File for Import"
|   |   +-- ESS Phase 2: "Import Journals"
|   |   +-- Interface table: GL_INTERFACE
|   |
|   +-- AP (Invoices) --> Template: PayablesStandardInvoiceImportTemplate.xlsm
|   |   +-- ESS Phase 1: "Load Interface File for Import"
|   |   +-- ESS Phase 2: "Import Payables Invoices"
|   |   +-- Interface tables: AP_INVOICES_INTERFACE, AP_INVOICE_LINES_INTERFACE
|   |
|   +-- AR (Transactions) --> Template: AutoInvoiceImportTemplate.xlsm
|   |   +-- ESS Phase 1: "Load Interface File for Import"
|   |   +-- ESS Phase 2: "Import AutoInvoice"
|   |   +-- Interface table: RA_INTERFACE_LINES_ALL
|   |
|   +-- FA (Assets) --> Template: AssetImportTemplate.xlsm
|   |   +-- ESS Phase 1: "Load Interface File for Import"
|   |   +-- ESS Phase 2: "Post Mass Additions"
|   |   +-- Interface table: FA_MASS_ADDITIONS
|   |
|   +-- Other --> Download module-specific template from Oracle docs
|
+-- How many records?
|   +-- < 10,000 --> Single CSV, single job, manual or automated
|   +-- 10,000 - 100,000 --> Single CSV, single job, automated
|   +-- 100,000 - 2,000,000 --> Split into multiple CSVs (100K each), 1 ZIP
|   +-- > 2,000,000 --> Multiple jobs (max 2M per job), max 10 parallel
|
+-- Automation method?
    +-- One-time / ad-hoc --> Manual UI upload via Scheduled Processes
    +-- Scheduled recurring --> ErpIntegrationService (SOAP/REST)
    +-- Oracle-to-Oracle --> OIC with ERP Cloud Adapter
    +-- Large migration --> External Data Loader Client (EDLC)

Quick Reference

FBDI Process Flow (All Modules)

Module Template Reference

Step-by-Step Integration Guide

1. Download and prepare the FBDI template

Download the current-release XLSM template from Oracle documentation for your target module. Open in Excel with macros enabled. The template contains an "Instructions and CSV Generation" tab and one or more data tabs. [src1, src5]

# Download GL Journal Import template for Release 26A
# Navigate to: Oracle Help Center > Fusion Cloud Financials > FBDI for Financials
# Download: JournalImportTemplate.xlsm
# Data tab: GL_INTERFACE
# Required columns: Status, Ledger Name, Accounting Date, Journal Source,
#                   Category, Currency Code, Actual Flag, Entered Debit/Credit,
#                   Segment1-SegmentN (chart of accounts segments)

Verify: Open XLSM, check version matches your Oracle release (e.g., "26A" in Instructions tab).

2. Populate data and generate CSV

Fill in the data tab with your records. Run the "Generate CSV File" macro to produce a ZIP archive containing the CSV file(s) and a .properties file. [src5]

# Click "Generate CSV File" button on Instructions tab
# Output: JournalImportTemplate.zip containing GlInterface.csv + .properties

Verify: Unzip the generated archive and confirm CSV column count matches template definition.

3. Upload and submit via ErpIntegrationService REST API (automated)

For automated integrations, use the importBulkData operation on the ErpIntegrationService REST endpoint. [src2, src7]

# REST endpoint: POST /fscmRestApi/resources/11.13.18.05/erpintegrations
curl -X POST \
  "https://<instance>.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations" \
  -H "Content-Type: application/json" \
  -u "integration_user:password" \
  -d '{
    "OperationName": "importBulkData",
    "DocumentContent": "<base64-encoded-ZIP>",
    "ContentType": "zip",
    "FileName": "JournalImportTemplate.zip",
    "DocumentAccount": "fin$/generalLedger$/import$",
    "JobName": "/oracle/apps/ess/financials/generalLedger/programs/,JournalImportLauncher",
    "ParameterList": "<LEDGER_ID>#NULL#NULL#NULL#N",
    "JobOptions": "InterfaceDetails=2"
  }'
# Response: { "ReqstId": 12345678, "RequestStatus": "SUBMITTED" }

Verify: GET ...?finder=ESSJobStatusRF;requestId=12345678 returns "RequestStatus": "SUCCEEDED".

4. Monitor and handle errors

Poll ESS job status and download execution logs for error details. [src2, src4]

# Check job status
curl -s -X GET \
  "https://<instance>/fscmRestApi/resources/11.13.18.05/erpintegrations?finder=ESSJobStatusRF;requestId=12345678" \
  -u "user:pass"

# Download job log files
curl -s -X POST \
  "https://<instance>/fscmRestApi/resources/11.13.18.05/erpintegrations" \
  -H "Content-Type: application/json" \
  -u "user:pass" \
  -d '{"OperationName":"downloadESSJobExecutionDetails","ReqstId":"12345678"}'

Verify: Status is "SUCCEEDED" or "WARNING" (check logs for warning details).

Code Examples

Python: Automated FBDI Import via REST API

# Input:  CSV data file (e.g., GL journals), Oracle ERP Cloud credentials
# Output: ESS job request ID, final job status

import requests
import base64
import time

def fbdi_import(instance_url, username, password, zip_path,
                document_account, job_name, parameter_list,
                job_options="InterfaceDetails=2"):
    """Upload FBDI ZIP and submit import via ErpIntegrationService REST."""
    with open(zip_path, "rb") as f:
        doc_content = base64.b64encode(f.read()).decode("utf-8")

    endpoint = f"{instance_url}/fscmRestApi/resources/11.13.18.05/erpintegrations"
    payload = {
        "OperationName": "importBulkData",
        "DocumentContent": doc_content,
        "ContentType": "zip",
        "FileName": zip_path.split("/")[-1],
        "DocumentAccount": document_account,
        "JobName": job_name,
        "ParameterList": parameter_list,
        "JobOptions": job_options
    }
    resp = requests.post(endpoint, json=payload, auth=(username, password))
    resp.raise_for_status()
    request_id = resp.json().get("ReqstId")

    # Poll for completion (max 30 min, 30s intervals)
    for attempt in range(60):
        time.sleep(30)
        status_resp = requests.get(
            f"{endpoint}?finder=ESSJobStatusRF;requestId={request_id}",
            auth=(username, password))
        items = status_resp.json().get("items", [])
        if items:
            status = items[0].get("RequestStatus", "UNKNOWN")
            if status in ("SUCCEEDED", "ERROR", "WARNING"):
                return {"request_id": request_id, "status": status}
    return {"request_id": request_id, "status": "TIMEOUT"}

cURL: Quick FBDI status check

# Input:  ESS job request ID from importBulkData
# Output: Job status (SUBMITTED, RUNNING, SUCCEEDED, ERROR, WARNING)

curl -s -X GET \
  "https://<instance>/fscmRestApi/resources/11.13.18.05/erpintegrations?finder=ESSJobStatusRF;requestId=12345678" \
  -u "integration_user:password" | python3 -m json.tool

Data Mapping

GL Journal Import — Key Fields

Data Type Gotchas

• Oracle FBDI date format is YYYY/MM/DD with forward slashes, not hyphens. Using YYYY-MM-DD causes silent data type conversion errors on some modules. [src5]
• Numeric fields must not contain currency symbols, thousand separators, or trailing spaces. "1,234.56" should be "1234.56". [src4]
• Fields containing commas or double quotes must be CSV-escaped (wrap in double quotes, escape internal quotes with double-double-quotes). The XLSM macro handles this automatically, but manual CSV generation often misses it. [src4]
• Multi-segment accounting flexfield values must match the exact segment separator configured in Oracle (typically "-" but may be "." in some implementations). [src5]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Template version drift: FBDI XLSM templates change every quarterly release. Using a 25D template on a 26A instance can cause silent column mapping errors. Fix: Re-download templates after every quarterly update and verify column mapping in a test import. [src1, src4]
• Phase 2 not triggered: "Load Interface File for Import" succeeds but the module-specific import job is never submitted. Fix: Always chain both ESS jobs; use callbacks or status polling to trigger Phase 2 after Phase 1 completes. [src5]
• Interface table pollution: Failed import records accumulate across multiple attempts. Fix: Run the module-specific purge process before every import attempt after a failure. [src8]
• Encoding issues: CSV files with BOM characters or non-UTF-8 encoding cause failures or garbled data. Fix: Save CSV as UTF-8 without BOM; validate encoding before upload. [src4]
• Parallel batch collision: Running more than 10 parallel FBDI jobs overwhelms the ESS scheduler. Fix: Limit to 10 parallel batches; implement job queue with sequential submission. [src3]
• DocumentAccount path mismatch: Wrong UCM path causes file to upload but ESS job cannot find it. Fix: Use exact paths per module — fin$/generalLedger$/import$ for GL, fin$/payables$/import$ for AP. [src7]

Anti-Patterns

Wrong: Uploading all records in a single massive CSV

# BAD — 500,000 records in one CSV file
# Performance degrades exponentially above 100K records
# Error triage is nearly impossible
# ESS job may time out or consume excessive memory

Correct: Split into batches of 10,000-100,000 records

# GOOD — split into manageable batches
# 500K records -> 5 CSV files of 100K each -> 1 ZIP -> 1 job
# Use Group ID to enable selective reprocessing of failed batches

Wrong: Skipping Phase 2 (module-specific import job)

# BAD — submitting "Load Interface File for Import" and assuming done
# Data only reaches interface tables after Phase 1
# Application tables remain unchanged until Phase 2 runs

Correct: Always chain Phase 1 and Phase 2

# GOOD — chain both phases with status checking
result1 = fbdi_import(...)  # Phase 1: Load Interface File for Import
if result1["status"] == "SUCCEEDED":
    result2 = submit_ess_job(  # Phase 2: Module-specific import
        job_name="ImportJournals",
        parameters={"group_id": batch_group_id}
    )

Wrong: Resubmitting failed batches without purging interface tables

# BAD — import fails, fix CSV, resubmit same batch
# Failed records from attempt 1 still in interface tables
# Result: duplicate processing, constraint violations

Correct: Purge interface tables before resubmission

# GOOD — clean slate before retry
# 1. Run "Purge Interface Tables" ESS job for the module
# 2. Wait for purge to complete
# 3. Resubmit corrected CSV with both Phase 1 and Phase 2

Common Pitfalls

• Using old XLSM templates after quarterly release: Oracle updates FBDI templates every release. Column additions, removals, or reordering break imports silently. Fix: Download fresh templates after every quarterly release; diff column headers against previous version. [src1, src4]
• Ignoring the .properties file: The XLSM macro generates a .properties file alongside the CSV. Missing .properties causes "Load Interface File for Import" to fail. Fix: Always use the macro to generate the ZIP, or manually create the .properties file with correct metadata. [src4]
• Date format mismatch: Oracle FBDI expects YYYY/MM/DD. Many ETL tools output YYYY-MM-DD or MM/DD/YYYY. Fix: Standardize all dates to YYYY/MM/DD before CSV generation. [src5]
• Not using Group ID for GL journals: Without Group ID, "Import Journals" processes ALL records in GL_INTERFACE. Fix: Always set Interface Group Identifier and pass matching Group ID parameter to Import Journals. [src5]
• Running imports during peak business hours: FBDI jobs share the ESS scheduler with all other processes. Fix: Schedule FBDI imports during off-peak hours or coordinate with the ERP admin team. [src4]
• Assuming importBulkData handles both phases: The REST/SOAP operation only handles Phase 1. Fix: Submit Phase 2 via submitESSJobRequest after Phase 1 completes, or use OIC adapter which orchestrates both phases. [src2]

Diagnostic Commands

# Check ESS job status for a specific request ID
curl -s -X GET \
  "https://<instance>/fscmRestApi/resources/11.13.18.05/erpintegrations?finder=ESSJobStatusRF;requestId=<REQUEST_ID>" \
  -u "user:pass" | python3 -m json.tool

# Download ESS job log files (base64-encoded ZIP)
curl -s -X POST \
  "https://<instance>/fscmRestApi/resources/11.13.18.05/erpintegrations" \
  -H "Content-Type: application/json" \
  -u "user:pass" \
  -d '{"OperationName":"downloadESSJobExecutionDetails","ReqstId":"<REQUEST_ID>"}'

# List documents in UCM by file prefix (verify upload)
curl -s -X POST \
  "https://<instance>/fscmRestApi/resources/11.13.18.05/erpintegrations" \
  -H "Content-Type: application/json" \
  -u "user:pass" \
  -d '{"OperationName":"getDocumentIdsForFilePrefix","DocumentPrefix":"JournalImport"}'

# ErpIntegrationService WSDL (19 operations available)
# https://<instance>/fscmService/ErpIntegrationService?WSDL

Version History & Compatibility

Oracle Fusion Cloud Applications follow a quarterly release cadence (A=Jan, B=Apr, C=Jul, D=Oct). FBDI templates are updated each release but Oracle maintains backward compatibility for at least 2 releases. Using templates more than 2 releases old is unsupported and may cause silent data mapping errors. [src1]

When to Use / When Not to Use

Important Caveats

• FBDI template columns and macros change between quarterly Oracle releases (26A, 26B, etc.). Always verify your template matches your current instance release before importing. A mismatched template may load data to wrong columns without raising errors. [src1]
• The 250 MB file size limit is a hard UCM constraint. For large datasets, split across multiple ZIP files and submit as separate import jobs (max 10 parallel). [src3]
• FBDI is inbound-only. There is no FBDI "export" — for outbound data extraction, use BICC, BIP reports, or the REST API query endpoints. [src1]
• Performance varies significantly by module. GL journal imports are typically fastest; AP invoice imports with complex validation rules (matching, tax calculation) are slowest. Budget 5-30 minutes per 100K records depending on module complexity. [src4]
• The jobOptions parameter in ErpIntegrationService is mandatory but poorly documented. Omitting it or using wrong values causes the job to "succeed" without actually processing data. Module-specific values: GL uses InterfaceDetails=2, AP uses InterfaceDetails=1. [src2, src7]