---
# === IDENTITY ===
id: business/erp-integration/oracle-fbdi-deep-dive/2026
canonical_question: "How does Oracle FBDI work - file format, UCM upload, job scheduling, error handling, 40+ templates?"
aliases:
  - "Oracle File-Based Data Import process and templates"
  - "Oracle ERP Cloud FBDI UCM upload and ESS job scheduling"
  - "Oracle Fusion FBDI CSV format, error logs, and interface tables"
  - "Oracle FBDI importBulkData ErpIntegrationService automation"
entity_type: erp_integration
domain: business > erp-integration > oracle-fbdi-deep-dive
region: global
jurisdiction: global
temporal_scope: 2024-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Oracle Fusion Cloud ERP"
    vendor: "Oracle"
    version: "Release 25D / 26A"
    edition: "Enterprise"
    deployment: "cloud"
    api_surface: "SOAP (ErpIntegrationService), REST, File-based (FBDI)"

# === VERIFICATION ===
last_verified: 2026-03-09
confidence: 0.88
version: 1.0
first_published: 2026-03-09

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: volatile
  last_breaking_change: "26A (January 2026)"
  next_review: 2026-09-05
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "FBDI is NOT real-time: it is a batch-only, asynchronous import mechanism with ESS job processing delays"
  - "Maximum recommended CSV file size: 250 MB per ZIP upload; split larger loads into multiple files"
  - "UCM upload requires Base64 encoding of the ZIP file when using ErpIntegrationService SOAP/REST API"
  - "Each FBDI template maps to a specific interface table and ESS job -- using the wrong template/job combination silently fails"
  - "XLSM templates require macros enabled; the 'Generate CSV File' macro produces the ZIP with correct filenames"
  - "Interface table data is purged after the import ESS job completes -- extract error data before purge"
  - "Concurrent FBDI imports to the same interface table can cause locking; serialize imports for the same module"
  - "UCM account path must exactly match the expected destination (e.g., fin/generalLedger/import for GL journals)"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User needs real-time Oracle ERP Cloud integration"
    use_instead: "business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026"
  - condition: "User needs Oracle ERP Cloud SOAP API capabilities"
    use_instead: "Search knowledgelib.io for Oracle ERP Cloud SOAP API — no dedicated unit yet"
  - condition: "User needs SAP data migration (DMF/LSMW)"
    use_instead: "Search knowledgelib.io for SAP data migration (DMF/LSMW) - no dedicated unit yet"

# === AGENT HINTS ===
inputs_needed:
  - key: integration_pattern
    question: "What integration pattern do you need?"
    type: choice
    options:
      - "real-time sync (individual records, <1s latency)"
      - "batch/bulk (scheduled, high volume)"
      - "event-driven (webhook, CDC, platform events)"
      - "file-based (CSV/XML import/export)"
  - key: data_volume
    question: "What's your daily data volume?"
    type: choice
    options:
      - "< 1,000 records/day"
      - "1,000-100,000 records/day"
      - "> 100,000 records/day"
  - key: direction
    question: "What's the data flow direction?"
    type: choice
    options:
      - "inbound (writing to this ERP)"
      - "outbound (reading from this ERP)"
      - "bidirectional sync"

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/business/erp-integration/oracle-fbdi-deep-dive/2026"
suggested_citation: "Source: knowledgelib.io -- AI Knowledge Library (verified 2026-03-09)"

# === RELATED UNITS ===
related_kos:
  depends_on: []
  related_to:
    - id: "business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026"
      label: "Oracle ERP Cloud (Fusion) REST API capabilities — 499-record pagination, expand vs fields, CRUD"
  solves: []

# === SOURCES ===
sources:
  - id: src1
    title: "File-Based Data Import (FBDI) for Financials"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/financials/25d/oefbf/financials-file-based-data-imports.html
    type: official_docs
    published: 2025-10-01
    reliability: authoritative
  - id: src2
    title: "Generate a File-Based Data Import (FBDI) File"
    author: Oracle
    url: https://docs.oracle.com/en/solutions/import-data-for-enterprise-resource-planning/generate-file-based-data-import-fbdi-file.html
    type: official_docs
    published: 2025-06-01
    reliability: authoritative
  - id: src3
    title: "FBDI in Oracle ERP Cloud: An In-Depth Analysis"
    author: Ignisys IT
    url: https://blogs.ignisysit.com/file-based-data-import-fbdi-in-oracle-erp-cloud-an-in-depth-analysis/
    type: technical_blog
    published: 2025-03-01
    reliability: moderate_high
  - id: src4
    title: "Journal Import using File-Based Data Import (FBDI)"
    author: RishOraDev
    url: https://blog.rishoradev.com/2024/03/24/journal-import-using-file-based-data-import-fbdi/
    type: technical_blog
    published: 2024-03-24
    reliability: moderate_high
  - id: src5
    title: "SOAP Web Services for Financials -- ErpIntegrationService"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/financials/25a/oeswf/erpintegrationservice-d16509e420.html
    type: official_docs
    published: 2025-02-01
    reliability: authoritative
  - id: src6
    title: "Data Import Options and Guidelines for Fusion Applications Suite"
    author: Oracle A-Team
    url: https://www.ateam-oracle.com/data-import-options-and-guidelines-for-fusion-applications-suite
    type: technical_blog
    published: 2024-06-01
    reliability: high
  - id: src7
    title: "File-Based Data Import (FBDI) for Procurement"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/procurement/26a/oefbp/index.html
    type: official_docs
    published: 2026-01-01
    reliability: authoritative
---

# 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. [src1, src3]
- **Key limit**: FBDI is batch-only and asynchronous -- there is no real-time capability. Recommended maximum file size is 250 MB per ZIP; split larger loads across multiple files. [src2, src6]
- **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 with no import errors. [src4]
- **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. [src3]
- **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. [src5]

## 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 that are most commonly used in integrations. It does NOT cover ADFdi (ADF Desktop Integrator) spreadsheet uploads, which use a different upload mechanism, or Oracle Data Management Framework (for HCM bulk loads).

| Property | Value |
|---|---|
| **Vendor** | Oracle |
| **System** | Oracle Fusion Cloud ERP, Release 25D / 26A |
| **API Surface** | File-based (FBDI), SOAP (ErpIntegrationService), REST (ERP Integration API) |
| **Current Release** | 26A (January 2026); quarterly update cycle |
| **Editions Covered** | Enterprise (all Oracle Fusion Cloud ERP editions include FBDI) |
| **Deployment** | Cloud (Oracle-managed SaaS) |
| **API Docs URL** | [FBDI for Financials (25D)](https://docs.oracle.com/en/cloud/saas/financials/25d/oefbf/financials-file-based-data-imports.html) |
| **Status** | GA (Generally Available -- core platform feature since initial release) |

## API Surfaces & Capabilities

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

| API Surface | Protocol | Best For | Max Records/Request | Rate Limit | Real-time? | Bulk? |
|---|---|---|---|---|---|---|
| FBDI (File-Based Data Import) | File upload (CSV in ZIP) | Data migration, batch loads, periodic interfaces | Hundreds of thousands per file | No per-request limit; constrained by ESS concurrency | No | Yes |
| ErpIntegrationService (SOAP) | HTTPS/XML | Automating FBDI uploads programmatically | Same as FBDI (wraps file upload + ESS job) | ESS job queue limits | No | Yes |
| ERP Integration REST API | HTTPS/JSON | Automating FBDI uploads from OIC or middleware | Same as FBDI | ESS job queue limits | No | Yes |
| Oracle REST API (CRUD) | HTTPS/JSON | Individual record operations, real-time | 500 records per payload | Throttled per tenant | Yes | No |
| Oracle SOAP API | HTTPS/XML | Legacy integrations, metadata operations | Varies by service | Throttled per tenant | Yes | No |
| Business Events (outbound) | REST callback | Event-driven notifications from ERP | N/A (push-based) | Event queue limits | Yes | N/A |

## Rate Limits & Quotas

### Per-Request Limits

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| Max recommended ZIP file size | 250 MB | FBDI upload to UCM | Split larger data sets into multiple files [src6] |
| Max CSV rows per file | No hard limit | FBDI CSV files | Practical limit ~500K rows before ESS processing time becomes excessive [src6] |
| Base64 payload size (API) | ~333 MB (250 MB * 4/3) | ErpIntegrationService importBulkData | Base64 encoding increases payload by ~33% [src5] |
| Max concurrent ESS jobs | Tenant-dependent (typically 8-16) | Enterprise Scheduler Service | Shared across all scheduled processes, not just FBDI [src6] |
| UCM file retention | Configurable (default 30 days) | UCM content server | Uploaded files auto-purge; download error logs before purge |

### Rolling / Daily Limits

| Limit Type | Value | Window | Edition Differences |
|---|---|---|---|
| ESS job queue depth | Tenant-dependent | Rolling | Higher-tier tenants get more concurrent slots |
| FBDI imports per module | No explicit daily limit | N/A | Constrained by ESS concurrency and processing time |
| API calls (REST/SOAP) | Throttled per tenant | Per minute | Oracle uses fair-use throttling; no published hard number |
| UCM storage | Included in subscription | N/A | Auto-purge configurable |

## Authentication

| Flow | Use When | Token Lifetime | Refresh? | Notes |
|---|---|---|---|---|
| Oracle ERP Cloud UI (SSO) | Manual FBDI uploads via browser | Session-based (configurable) | N/A | Navigate to Tools > File Import and Export |
| Basic Auth (SOAP) | ErpIntegrationService API calls | Per request | No | Username/password; not recommended for production [src5] |
| OAuth 2.0 (JWT) | Automated FBDI via OIC or middleware | Access token: configurable | Yes | Recommended for server-to-server integration [src5] |
| OAuth 2.0 (Client Credentials) | System-to-system FBDI automation | Access token: configurable | Yes | Requires Oracle IDCS or OCI IAM configuration |
| SAML 2.0 | Federated SSO for UI-based uploads | Session-based | N/A | For organizations using identity federation |

### Authentication Gotchas

- ErpIntegrationService requires an integration user with specific roles: `Integration Specialist`, `Financial Integration Specialist`, or module-specific import roles. A generic admin user may not have the correct ESS job submission privileges. [src5]
- OAuth tokens issued by Oracle IDCS must include the correct scope for ERP API access. Missing scopes cause HTTP 403 errors that don't indicate the token is valid but under-scoped.
- Basic Auth is officially supported for SOAP services but Oracle recommends migration to OAuth 2.0 for all new integrations. Basic Auth does not support MFA enforcement.

## Constraints
<!-- Agents: read this section before recommending any integration approach from this unit.
     These are hard constraints that must not be violated. -->

- **Batch-only**: FBDI has zero real-time capability. Minimum latency from file upload to data availability in transaction tables is typically 2-15 minutes depending on ESS queue depth and data volume. [src3]
- **Template-locked format**: Each FBDI import requires the exact XLSM template for that module and data type. You cannot create custom templates or modify column structures. The template defines the interface table mapping. [src1]
- **UCM path dependency**: The UCM account/destination path is hardcoded per template (e.g., `fin/generalLedger/import`, `fin/payables/import`). Uploading to the wrong path means the ESS job cannot locate the file. [src4]
- **Interface table purge**: Oracle purges interface table data after the import ESS job completes (success or failure). You must extract error records from the interface tables or download ESS job logs before purge occurs. [src4]
- **Macro dependency**: XLSM templates require Excel macros to generate the correctly formatted CSV ZIP. LibreOffice and Google Sheets cannot reliably execute these macros. [src1]
- **No partial commit**: If an FBDI import job fails mid-way, there is no partial commit for most templates. The entire batch either succeeds or fails (module-dependent -- some modules like GL Journal Import do support partial success). [src4]
- **Sequential by module**: Running concurrent FBDI imports for the same module (e.g., two simultaneous Journal Import jobs) causes interface table locking and unpredictable failures. Serialize imports per module. [src6]

## 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)
|   |   +-- FBDI is overkill for small volumes
|   +-- 100-500,000 records
|   |   +-- FBDI is the sweet spot
|   |   +-- Single file upload, single ESS job
|   +-- > 500,000 records
|       +-- Split into multiple FBDI files (each <= 250 MB)
|       +-- Submit sequentially to avoid ESS queue saturation
+-- Is this a one-time migration or recurring?
|   +-- One-time migration
|   |   +-- Manual FBDI: download template, populate, upload via UI
|   |   +-- No automation needed
|   +-- Recurring (daily/weekly)
|       +-- Automate with ErpIntegrationService (SOAP) or ERP Integration REST API
|       +-- Use Oracle Integration Cloud (OIC) for managed orchestration
|       +-- Use middleware (MuleSoft, Boomi, Workato) with ERP Cloud adapter
+-- Which module?
|   +-- General Ledger --> Journal Import template (fin/generalLedger/import)
|   +-- Accounts Payable --> Payables Standard Invoice Import (fin/payables/import)
|   +-- Accounts Receivable --> AutoInvoice Import (fin/receivables/import)
|   +-- Procurement --> Supplier Import, PO Import (prc/supplier/import, prc/PurchaseOrder/import)
|   +-- Fixed Assets --> Mass Additions Import (fin/assets/import)
|   +-- Cash Management --> Bank Statement Import (fin/cashManagement/import)
|   +-- SCM --> Item Import, Inventory Transactions (scm/item/import)
|   +-- Project Management --> Project Import templates (prj/ProjectManagement/import)
+-- Error tolerance?
    +-- Zero-loss required --> Validate data pre-upload + check ESS logs + resubmit failures
    +-- Best-effort --> Upload, check summary counts, investigate only significant failures
```

## Quick Reference

### Most Common FBDI Templates by Module

| Module | Template Name | UCM Account Path | Interface Table | ESS Job Name |
|---|---|---|---|---|
| General Ledger | Journal Import | fin/generalLedger/import | GL_INTERFACE | Import Journals |
| Accounts Payable | Payables Standard Invoice Import | fin/payables/import | AP_INVOICES_INTERFACE, AP_INVOICE_LINES_INTERFACE | Import Payables Invoices |
| Accounts Receivable | AutoInvoice Import | fin/receivables/import | RA_INTERFACE_LINES_ALL | AutoInvoice Import |
| Fixed Assets | Fixed Asset Mass Additions Import | fin/assets/import | FA_MASS_ADDITIONS | Post Mass Additions |
| Cash Management | Bank Statement Import | fin/cashManagement/import | CE_STATEMENT_HEADERS_INT, CE_STATEMENT_LINES_INT | Load and Import Bank Statements |
| Procurement | Supplier Import | prc/supplier/import | POZ_SUPPLIERS_INT, POZ_SUPPLIER_SITES_INT | Import Suppliers |
| Procurement | Purchase Order Import | prc/PurchaseOrder/import | PO_HEADERS_INTERFACE, PO_LINES_INTERFACE | Import Purchase Orders |
| Budgetary Control | Budget Import | fin/budgetaryControl/import | GL_BUDGET_INTERFACE | Load Budgets |
| SCM | Item Import | scm/item/import | EGP_SYSTEM_ITEMS_INTERFACE | Import Items |
| SCM | Inventory Transactions | scm/inventory/import | MTL_TRANSACTIONS_INTERFACE | Process Inventory Transactions |
| Project Management | Project Import | prj/ProjectManagement/import | PJF_PROJECTS_INTERFACE | Import Projects |
| Intercompany | Intercompany Transaction Import | fin/intercompany/import | FUN_INTERFACE_HEADERS, FUN_INTERFACE_LINES | Import Intercompany Transactions |

[src1, src7]

### FBDI File Structure

| Component | Format | Description |
|---|---|---|
| XLSM Template | Excel with macros | Pre-built by Oracle; contains Instructions tab + data entry tab(s) matching interface table columns |
| CSV File(s) | Comma-separated values | Generated by the XLSM macro; one CSV per interface table (header + lines for multi-table templates) |
| ZIP Archive | ZIP compression | Contains one or more CSV files; this is what gets uploaded to UCM |
| Properties File (API only) | Key-value pairs | Contains JobName and ParameterList for ErpIntegrationService automation |

## 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. Each module has its own set of templates. [src1]

```
# Navigate in Oracle ERP Cloud UI:
# Navigator > Tools > File Import and Export
# OR download from Oracle docs:
# https://docs.oracle.com/en/cloud/saas/financials/25d/oefbf/

# Example: Download Journal Import template
# File: JournalImport.xlsm
# Contains tabs: Instructions and CSV Generation, GL_INTERFACE
```

**Verify**: Open the XLSM file in Excel --> confirm the "Instructions and CSV Generation" tab exists with a "Generate CSV File" button and the data entry tab matches your target interface table.

### 2. Populate the template with source data

Fill in the data entry tab(s) with your source data. Mandatory columns vary by template. For Journal Import, required fields include Ledger, Accounting Date, Category, Source, Currency, and line-level account/amount fields. [src4]

```
# Journal Import (GL_INTERFACE) mandatory columns:
# STATUS                = "NEW" (always "NEW" for new entries)
# LEDGER_ID             = Numeric ledger ID (from Manage Primary Ledgers)
# ACCOUNTING_DATE       = Date in YYYY/MM/DD format
# USER_JE_SOURCE_NAME   = Journal source (from Manage Journal Sources)
# USER_JE_CATEGORY_NAME = Journal category (from Manage Journal Categories)
# CURRENCY_CODE         = ISO currency code (e.g., USD, EUR)
# ENTERED_DR or ENTERED_CR = Debit or Credit amount
# SEGMENT1..SEGMENTn    = Account code combination segments

# Example row:
# NEW,1001,2026/03/01,Balance Transfer,Manual,USD,2026/03/01,A,01,000,1212,0000,000,99.00,,
```

**Verify**: Row count matches your source data. Debit and credit totals balance (for journal entries). No special characters in fields that could break CSV parsing.

### 3. Generate the CSV ZIP file

Click the "Generate CSV File" button on the Instructions tab. This macro creates a ZIP archive containing one or more CSV files with the exact filenames expected by the ESS import job. [src1]

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

# The ZIP will contain files like:
#   GlInterface.csv         (for single-table templates)
#   or
#   ApInvoicesInterface.csv  (header)
#   ApInvoiceLinesInterface.csv (lines)
```

**Verify**: Unzip the file and confirm CSV files exist with expected filenames. Open a CSV and verify column order matches the interface table definition.

### 4. Upload the ZIP file to UCM

Upload the ZIP file to Oracle UCM via the File Import and Export tool, specifying the correct account/destination path. [src4]

```
# Manual upload via Oracle ERP Cloud UI:
# 1. Navigator > Tools > File Import and Export
# 2. Click "Upload" (+ icon)
# 3. Select your ZIP file
# 4. Set Account: select the correct UCM account path
#    - GL Journals:  fin/generalLedger/import
#    - AP Invoices:  fin/payables/import
#    - AR Invoices:  fin/receivables/import
#    - Suppliers:    prc/supplier/import
#    - POs:          prc/PurchaseOrder/import
# 5. Click "Save and Close"
```

**Verify**: File appears in the File Import and Export list with "Uploaded" status. Document ID is generated (note this for ESS job reference).

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

Submit the "Load Interface File for Import" scheduled process to load data from the CSV into the interface tables. [src4]

```
# Navigate: Tools > Scheduled Processes > Schedule New Process
# Search for: "Load Interface File for Import"
# Parameters:
#   Import Process:    Select the matching import process
#                      (e.g., "Import Journals" for GL)
#   Data File:         Select your uploaded ZIP file from UCM
# Click "Submit"

# This ESS job:
# 1. Reads the ZIP from UCM
# 2. Parses CSV files
# 3. Loads data into interface tables (e.g., GL_INTERFACE)
# 4. Returns a Process ID for tracking
```

**Verify**: ESS job status shows "Succeeded". Check the job log for record counts: "N records loaded into interface table".

### 6. Run the module-specific import ESS job

After the interface tables are loaded, run the import job that moves data from interface tables to transaction tables. [src4]

```
# Navigate: Tools > Scheduled Processes > Schedule New Process
# For GL Journals: search "Import Journals"
# For AP Invoices: search "Import Payables Invoices"
# For Suppliers:   search "Import Suppliers"
#
# Parameters vary by module:
#   GL Import Journals:
#     Ledger:          Your ledger name
#     Source:          Journal source name
#     Group ID:        (optional) filter to specific batch
#   AP Import Payables Invoices:
#     Business Unit:   Your business unit
#     Source:          Invoice source
#
# Click "Submit"
```

**Verify**: ESS job status shows "Succeeded" or "Warning" (warnings indicate partial success). Check output log for imported/rejected record counts. Navigate to the module UI to confirm records exist.

### 7. Review errors and reprocess failures

Download ESS job log and output files to identify rejected records. Correct the data and resubmit only the failed records. [src3]

```
# In Scheduled Processes:
# 1. Find your completed import job
# 2. Click on the process ID to view details
# 3. Download "Log" file -- contains processing details
# 4. Download "Output" file -- contains error records with reasons
#
# Common error log locations:
#   GL Journals:  ESS output + query GL_INTERFACE where STATUS = 'E'
#   AP Invoices:  ESS output + AP_INTERFACE_REJECTIONS table
#   Suppliers:    ESS output + POZ_SUPPLIERS_INT where STATUS = 'ERROR'
#
# For interface table queries (run before purge):
# SELECT * FROM GL_INTERFACE WHERE STATUS = 'E' AND GROUP_ID = :your_group_id
```

**Verify**: Error count is zero or all errors are understood and corrected. Resubmit corrected records using a new FBDI file.

## Code Examples

### Python: Automate FBDI upload via ErpIntegrationService REST API

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

import requests
import base64
import json

# Configuration
ERP_BASE_URL = "https://your-instance.fa.us6.oraclecloud.com"
USERNAME = "integration_user"
PASSWORD = "integration_password"  # Use OAuth in production

# Step 1: Base64-encode the ZIP file
with open("JournalImport.zip", "rb") as f:
    file_content = base64.b64encode(f.read()).decode("utf-8")

# Step 2: Call importBulkData via ERP Integration REST API
# Endpoint: POST /fscmRestApi/resources/latest/erpintegrations
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",  # LedgerId,AccountingDate,Source,etc.
    "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  # Large files take time to upload
)

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

# Step 3: Poll for job completion
import time
for attempt in range(60):  # Poll for up to 30 minutes
    status_resp = requests.get(
        f"{ERP_BASE_URL}/fscmRestApi/resources/latest/erpintegrations?finder=ESSJobStatusRF;"
        f"requestId={request_id}",
        auth=(USERNAME, PASSWORD),
        headers={"Accept": "application/json"}
    )
    if status_resp.status_code == 200:
        job_data = status_resp.json()
        items = job_data.get("items", [])
        if items:
            status = items[0].get("RequestStatus")
            print(f"Job status: {status}")
            if status in ("SUCCEEDED", "ERROR", "WARNING"):
                break
    time.sleep(30)
```

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

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

const fs = require('fs');
const https = require('https');
const { DOMParser } = require('xmldom');  // xmldom@0.6.0

const ERP_HOST = 'your-instance.fa.us6.oraclecloud.com';
const USERNAME = 'integration_user';
const PASSWORD = 'integration_password';

// Step 1: Base64-encode the ZIP file
const zipBuffer = fs.readFileSync('JournalImport.zip');
const base64Content = zipBuffer.toString('base64');

// Step 2: Build SOAP envelope for importBulkData
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:Header/>
  <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>`;

// Step 3: Send SOAP request
const auth = Buffer.from(`${USERNAME}:${PASSWORD}`).toString('base64');
const options = {
  hostname: ERP_HOST,
  path: '/fscmService/ErpIntegrationService',
  method: 'POST',
  headers: {
    'Content-Type': 'text/xml;charset=UTF-8',
    'Authorization': `Basic ${auth}`,
    'SOAPAction': 'importBulkData'
  }
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => {
    const doc = new DOMParser().parseFromString(data, 'text/xml');
    const reqId = doc.getElementsByTagName('result')[0]?.textContent;
    console.log(`Import submitted. ESS Request ID: ${reqId}`);
    // reqId = 0 means upload failed (check UCM permissions)
  });
});

req.on('error', (e) => console.error(`SOAP Error: ${e.message}`));
req.write(soapEnvelope);
req.end();
```

### cURL: Manual FBDI upload and status check via REST

```bash
# Input:  Base64-encoded ZIP file, Oracle credentials
# Output: ESS job request ID and status

# Step 1: Upload FBDI file and trigger import
# (Base64-encode your ZIP first: base64 JournalImport.zip > encoded.txt)
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": "'$(cat encoded.txt)'",
    "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"
  }'

# Expected response:
# {"ReqstId": "12345678", ...}

# 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"

# Expected response:
# {"items": [{"ReqstId": "12345678", "RequestStatus": "SUCCEEDED", ...}]}

# Step 3: Download ESS job output (error log)
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": "12345678",
    "FileType": "all"
  }' \
  | python3 -c "import sys,json,base64; d=json.load(sys.stdin); open('output.zip','wb').write(base64.b64decode(d['DocumentContent']))"
```

## Data Mapping

### FBDI CSV Column Mapping for Common Templates

| Template | CSV Column | Interface Table Column | Type | Required | Gotcha |
|---|---|---|---|---|---|
| Journal Import | STATUS | GL_INTERFACE.STATUS | VARCHAR2 | Yes | Must be "NEW" for new entries; "C" for correction [src4] |
| Journal Import | LEDGER_ID | GL_INTERFACE.LEDGER_ID | NUMBER | Yes | Numeric ID, not ledger name; look up in Manage Primary Ledgers |
| Journal Import | ACCOUNTING_DATE | GL_INTERFACE.ACCOUNTING_DATE | DATE | Yes | Format: YYYY/MM/DD; must fall in an open period |
| Journal Import | ENTERED_DR / ENTERED_CR | GL_INTERFACE.ENTERED_DR/CR | NUMBER | Yes | Populate one or the other per line, not both |
| Journal Import | SEGMENT1..SEGMENTn | GL_INTERFACE.SEGMENT1..n | VARCHAR2 | Yes | Must match Chart of Accounts segment values exactly |
| AP Invoice | INVOICE_NUM | AP_INVOICES_INTERFACE.INVOICE_NUM | VARCHAR2 | Yes | Must be unique per supplier within same calendar year |
| AP Invoice | INVOICE_AMOUNT | AP_INVOICES_INTERFACE.INVOICE_AMOUNT | NUMBER | Yes | Header-level total; must equal sum of line amounts |
| AP Invoice | VENDOR_NAME | AP_INVOICES_INTERFACE.VENDOR_NAME | VARCHAR2 | Conditional | Either VENDOR_NAME or VENDOR_ID required |
| Supplier Import | VENDOR_NAME | POZ_SUPPLIERS_INT.VENDOR_NAME | VARCHAR2 | Yes | Supplier name; must be unique in the system |
| Supplier Import | SUPPLIER_NUMBER | POZ_SUPPLIERS_INT.SEGMENT1 | VARCHAR2 | Conditional | Auto-generated if not provided; check numbering config |

### Data Type Gotchas

- Date format in FBDI CSVs must be `YYYY/MM/DD` (with forward slashes), NOT `YYYY-MM-DD`. The macro generates this format correctly, but programmatic CSV generation often uses hyphens, which causes parse failures. [src4]
- Amount fields must use period (`.`) as decimal separator regardless of locale. European comma-decimal formats (e.g., `1.234,56`) will cause import failures. [src3]
- Account code combination segments must exactly match the values configured in the Chart of Accounts. Leading zeros matter -- `001` is different from `1`. [src4]
- GL_INTERFACE.GROUP_ID is optional but highly recommended. Without it, you cannot isolate your import's records from other pending interface records for error investigation. [src4]
- AP Invoice line amounts must sum to the header INVOICE_AMOUNT. A mismatch causes the entire invoice to reject, not just the mismatched lines. [src1]

## Error Handling & Failure Points

### Common Error Codes

| Error / Status | Meaning | Cause | Resolution |
|---|---|---|---|
| ESS Status: ERROR | Import job failed entirely | Invalid file format, wrong UCM path, or ESS job parameter mismatch | Check ESS log file; verify ZIP file structure and UCM account path [src3] |
| ESS Status: WARNING | Partial import success | Some records rejected validation | Download output file; correct rejected records and resubmit [src4] |
| GL_INTERFACE.STATUS = 'E' | Journal line rejected | Invalid account combination, closed period, or unbalanced entry | Query GL_INTERFACE for STATUS='E' and check REFERENCE21-25 for error details [src4] |
| AP_INTERFACE_REJECTIONS | Invoice line rejected | Invalid supplier, missing mandatory fields, or duplicate invoice number | Query AP_INTERFACE_REJECTIONS for rejection reason codes [src1] |
| UCM upload returns 0 | File upload to UCM failed | Incorrect UCM account path, file too large, or permission issue | Verify UCM account path, check integration user's UCM roles [src5] |
| importBulkData returns ReqstId=0 | ErpIntegrationService call failed | UCM upload failure within the service call | Check integration user permissions, verify Base64 encoding is correct [src5] |
| ESS child job: "No data found" | Load Interface File found no CSV data | CSV filenames inside ZIP don't match expected names | Regenerate ZIP using the XLSM macro; do not rename CSV files manually |
| INVALID_ACCOUNTING_PERIOD | Period not open | Accounting date falls in a closed GL period | Open the period or change the accounting date |

### Failure Points in Production

- **Silent UCM path failures**: Uploading a file to the wrong UCM account path (e.g., `fin/payables/import` instead of `fin/generalLedger/import`) does not generate an error at upload time. The file uploads successfully, but the ESS job cannot find it. Fix: `Create a lookup table mapping each FBDI template to its exact UCM path; validate path before upload`. [src4]
- **CSV filename corruption**: Manually renaming CSV files inside the ZIP (or generating CSVs programmatically with wrong filenames) causes "No data found" errors in the Load Interface File job. The filenames must exactly match what the macro generates (e.g., `GlInterface.csv`, not `gl_interface.csv`). Fix: `Always use the XLSM macro to generate CSVs, or reverse-engineer the exact filename from Oracle's template`. [src3]
- **Interface table purge race condition**: The import ESS job purges interface table records after completion. If you need to query error records (STATUS='E'), you must do so before the purge runs. For GL journals, the purge is part of the Import Journals process. Fix: `Download ESS output files immediately after job completion; implement automated log retrieval in your integration flow`. [src4]
- **Base64 encoding issues**: Using the wrong Base64 encoding (URL-safe vs. standard) or including line breaks in the encoded string causes file corruption on UCM. Fix: `Use standard Base64 encoding (RFC 4648) without line breaks; verify the decoded file matches the original ZIP byte-for-byte`. [src5]
- **ESS job queue saturation**: Submitting many FBDI imports simultaneously fills the ESS job queue, delaying all scheduled processes (not just FBDI). Fix: `Implement a queue/throttle in your middleware; submit no more than 2-3 concurrent FBDI jobs per module; monitor ESS queue depth via scheduled process monitoring`. [src6]
- **Character encoding failures**: CSVs containing non-ASCII characters (accented names, CJK characters) must be UTF-8 encoded. The XLSM macro handles this, but programmatic generation may default to ANSI/Latin-1. Fix: `Explicitly set UTF-8 encoding when generating CSVs programmatically; include a BOM marker if required by your Oracle instance configuration`. [src3]

## Anti-Patterns

### Wrong: Uploading raw CSV files without the XLSM-generated ZIP structure

```bash
# BAD -- creating a ZIP manually with arbitrary CSV filenames
zip manual_upload.zip my_journals.csv
# Upload to UCM... ESS job says "No data found"
# because the CSV filename doesn't match Oracle's expected format
```

### Correct: Use the XLSM template macro to generate the ZIP

```bash
# GOOD -- use the official XLSM template
# 1. Open JournalImport.xlsm in Excel (macros enabled)
# 2. Paste data into GL_INTERFACE tab
# 3. Click "Generate CSV File" on Instructions tab
# 4. Upload the generated ZIP (contains GlInterface.csv with correct name)

# For programmatic generation, match Oracle's exact filenames:
# GL Journals:    GlInterface.csv
# AP Invoices:    ApInvoicesInterface.csv + ApInvoiceLinesInterface.csv
# Suppliers:      PozSuppliersInt.csv + PozSupplierSitesInt.csv + PozSupplierContactsInt.csv
```

### Wrong: Running concurrent FBDI imports for the same module

```python
# BAD -- submitting 5 journal import jobs simultaneously
import threading
files = ["batch1.zip", "batch2.zip", "batch3.zip", "batch4.zip", "batch5.zip"]
for f in files:
    threading.Thread(target=submit_fbdi, args=(f, "JournalImport")).start()
# Result: interface table locking, unpredictable failures, data corruption
```

### Correct: Serialize FBDI imports per module, parallelize across modules

```python
# GOOD -- sequential within module, parallel across modules
import threading

def import_sequential(files, module):
    for f in files:
        submit_fbdi(f, module)
        wait_for_completion()  # Wait for ESS job to finish before next

# Different modules can run in parallel safely
threading.Thread(target=import_sequential, args=(gl_files, "JournalImport")).start()
threading.Thread(target=import_sequential, args=(ap_files, "InvoiceImport")).start()
# GL and AP imports use different interface tables -- no locking conflict
```

### Wrong: Not validating data before FBDI upload

```python
# BAD -- blindly uploading source data without validation
data = extract_from_source()
generate_csv(data)
upload_to_ucm()
run_import()
# Result: 30% rejection rate, hours of debugging, re-processing
```

### Correct: Pre-validate against Oracle's business rules before upload

```python
# GOOD -- validate before generating CSV
errors = []
for row in data:
    if not is_valid_account_combination(row['segments']):
        errors.append(f"Row {row['line']}: invalid account {row['segments']}")
    if not is_period_open(row['accounting_date']):
        errors.append(f"Row {row['line']}: period closed for {row['accounting_date']}")
    if row['entered_dr'] and row['entered_cr']:
        errors.append(f"Row {row['line']}: cannot have both DR and CR on same line")

if errors:
    print(f"Pre-validation failed: {len(errors)} errors")
    for e in errors[:10]:
        print(f"  {e}")
else:
    generate_csv(data)
    upload_to_ucm()
    run_import()
```

## Common Pitfalls

- **Wrong date format in programmatic CSVs**: Oracle FBDI expects `YYYY/MM/DD` with forward slashes. Most programming languages default to `YYYY-MM-DD` (ISO 8601). The import silently treats malformed dates as null, causing "missing mandatory field" errors. Fix: `Explicitly format dates as YYYY/MM/DD in your CSV generation code; add a format validation step before upload`. [src4]
- **Forgetting to set STATUS = 'NEW'**: The GL_INTERFACE.STATUS column must be set to "NEW" for every row. Leaving it blank or setting it to any other value causes the Import Journals job to skip those rows with no error message. Fix: `Hardcode STATUS = 'NEW' as the first column in every CSV row`. [src4]
- **Not splitting large files**: Processing 1M+ records in a single FBDI file causes ESS job timeouts and excessive memory consumption. Fix: `Split into files of 50K-100K records each; submit sequentially with 1-2 minute gaps between submissions`. [src6]
- **Ignoring GROUP_ID for GL journals**: Without GROUP_ID, you cannot isolate your import's records in the GL_INTERFACE table. If another integration runs simultaneously, error investigation becomes impossible. Fix: `Always set GROUP_ID to a unique batch identifier; use timestamp + source system prefix`. [src4]
- **Testing with production-volume data on POD refresh**: Refreshed POD environments may have different ESS concurrency limits than production. A load that works in production may fail or queue indefinitely on a test POD. Fix: `Confirm ESS concurrency settings on your test environment before load testing`. [src6]
- **Not downloading error logs before interface table purge**: Oracle purges interface table data after the import ESS job completes. If you query the interface table after the purge, you get zero rows -- even for errors. Fix: `Automate ESS log download as part of your integration flow; call downloadESSJobExecutionDetails immediately after job completion`. [src4]

## Diagnostic Commands

```bash
# 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 files)
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"}'

# List files in UCM for a specific account path
# (Use Oracle BI Publisher or UCM Content Server UI -- no direct REST endpoint for listing)

# Check interface table for errors (run in Oracle SQL via BI Publisher or direct DB query):
# GL Journals:
# SELECT STATUS, REFERENCE1, REFERENCE4, SEGMENT1||'.'||SEGMENT2||'.'||SEGMENT3 AS ACCOUNT
# FROM GL_INTERFACE WHERE STATUS = 'E' AND GROUP_ID = 'YOUR_GROUP_ID';

# AP Invoices:
# SELECT INVOICE_NUM, REJECT_LOOKUP_CODE, DESCRIPTION
# FROM AP_INTERFACE_REJECTIONS WHERE PARENT_TABLE = 'AP_INVOICES_INTERFACE';

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

# Check ESS job queue depth (via BI Publisher scheduled report or Fusion UI):
# Navigator > Tools > Scheduled Processes > Search > Status = "Running" or "Wait"
```

## Version History & Compatibility

| Release | Date | Status | Key Changes | Notes |
|---|---|---|---|---|
| 26A | 2026-01 | Current | New procurement FBDI templates; sustainability activity import | Quarterly update |
| 25D | 2025-10 | Supported | Enhanced error reporting in ESS output logs | -- |
| 25C | 2025-07 | Supported | New bank statement reconciliation FBDI template | -- |
| 25B | 2025-04 | Supported | Performance improvements for large-volume imports | -- |
| 25A | 2025-01 | Supported | ERP Integration REST API enhancements for FBDI | -- |
| 24D | 2024-10 | Supported | Additional SCM FBDI templates | -- |
| 24C | 2024-07 | Supported | Fixed asset lease import template added | -- |

[src1, src7]

### Deprecation Policy

Oracle Fusion Cloud ERP follows a quarterly release cycle (A, B, C, D per year). FBDI templates are backward-compatible within major releases. Oracle adds new templates with each release but rarely removes existing ones. Template column additions are typically additive (new optional columns appended). Breaking changes to FBDI templates are documented in release-specific "What's New" guides and require template re-download. [src1]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Bulk data migration from legacy ERP systems (1K-1M+ records) | Real-time record creation or updates (<1s latency required) | Oracle REST API (CRUD operations) |
| Periodic batch interfaces (daily journal imports, weekly supplier syncs) | Small-volume individual record operations (<100 records) | Oracle REST API or SOAP API |
| Data volumes exceed REST API practical limits (>500 records/payload) | Outbound data extraction from Oracle ERP | BI Publisher reports, OTBI, or Oracle REST API queries |
| Module requires FBDI (no REST/SOAP equivalent for that data type) | Real-time event notifications from Oracle ERP | Oracle Business Events + webhooks |
| One-time setup data loads (Chart of Accounts, opening balances) | Continuous bidirectional sync | Oracle Integration Cloud (OIC) with CDC |
| Budget imports and period-end mass adjustments | Ad-hoc queries or data lookups | Oracle REST API or BI Publisher |

## Important Caveats

- FBDI template column structures vary between Oracle releases. Always download the template for your specific release version (e.g., 25D vs. 26A) -- using a template from a different release may have missing or extra columns that cause silent failures. [src1]
- The ErpIntegrationService (SOAP) and ERP Integration REST API are wrappers around the same FBDI process -- they do not bypass FBDI limitations. The underlying mechanism is always: file upload to UCM + ESS job execution. [src5]
- ESS job concurrency is shared across ALL scheduled processes in your Oracle ERP tenant, not just FBDI. Heavy FBDI loads can block other critical scheduled processes (period close, reporting). Plan FBDI batch windows carefully. [src6]
- Oracle does not publish official FBDI file size limits. The 250 MB recommendation comes from Oracle A-Team best practices and community experience. Your mileage may vary based on tenant configuration and network conditions. [src6]
- Interface table column names and CSV filenames are case-sensitive on some Oracle Cloud infrastructure configurations. Always match the exact case from the XLSM template. [src3]
- FBDI is the ONLY supported import mechanism for some data types (e.g., GL budgets, certain asset transaction types). For these, there is no REST or SOAP alternative. [src1]

## Related Units

- [Oracle ERP Cloud REST API Capabilities](/business/erp-integration/oracle-erp-cloud-rest-api/2026) -- real-time API surface for individual record operations
- [Oracle ERP Cloud SOAP API](/business/erp-integration/oracle-erp-cloud-soap-api/2026) -- includes ErpIntegrationService that wraps FBDI
- [Oracle ADFdi Desktop Integrator](/business/erp-integration/oracle-adf-desktop-integrator/2026) -- spreadsheet-based upload (different mechanism from FBDI)