---
# === IDENTITY ===
id: business/erp-integration/oracle-erp-cloud-fbdi-import/2026
canonical_question: "What are Oracle ERP Cloud FBDI import capabilities - 100K record limit, 250MB file size, ESS scheduling?"
aliases:
  - "Oracle FBDI file-based data import CSV template process"
  - "Oracle ERP Cloud 250MB file size limit 100K records per CSV"
  - "FBDI UCM upload ESS job scheduling import process"
  - "Oracle Fusion FBDI GL AP AR FA import templates"
entity_type: erp_integration
domain: business > erp-integration > oracle-erp-cloud-fbdi-import
region: global
jurisdiction: global
temporal_scope: 2025-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Oracle ERP Cloud (Fusion Cloud Applications)"
    vendor: "Oracle"
    version: "Release 26A (January 2026)"
    edition: "All editions (FBDI is a core platform capability)"
    deployment: cloud
    api_surface: "File-Based (FBDI via SOAP/REST ErpIntegrationService)"

# === VERIFICATION ===
last_verified: 2026-03-01
confidence: 0.91
version: 1.0
first_published: 2026-03-01

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: volatile
  last_breaking_change: "26A — updated FBDI XLSM templates with new macro structure; verify templates each quarterly release"
  next_review: 2026-08-28
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "Max file size: 250 MB per ZIP archive uploaded to UCM"
  - "Practical record limit: ~100,000 records per CSV file for optimal performance; Oracle recommends 10,000 records per batch for error triage"
  - "Max parallel batches: 10 simultaneous FBDI import jobs"
  - "Max files per job: 20 CSV files per ZIP archive (recommended limit for 2M total records)"
  - "FBDI templates change between quarterly releases — always re-download templates before each update cycle"
  - "Two-phase import: Load Interface File for Import (ESS) loads to interface tables; a second module-specific ESS job imports to application tables"
  - "Interface table records from failed imports must be manually purged before reprocessing the same batch"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User needs real-time individual record CRUD operations"
    use_instead: "business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026"
  - condition: "User needs Oracle-to-Oracle data extraction (outbound)"
    use_instead: "business/erp-integration/oracle-bicc-data-extraction/2026"
  - condition: "User needs authentication flow details for Oracle ERP Cloud"
    use_instead: "business/erp-integration/oracle-erp-cloud-authentication/2026"
  - condition: "User needs Oracle Integration Cloud (OIC) adapter patterns"
    use_instead: "business/erp-integration/oracle-integration-cloud-capabilities/2026"

# === 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-erp-cloud-fbdi-import/2026"
suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-03-01)"

# === RELATED UNITS ===
related_kos:
  depends_on:
    - id: "business/erp-integration/oracle-erp-cloud-authentication/2026"
      label: "Oracle ERP Cloud authentication — required for ErpIntegrationService access"
  related_to:
    - id: "business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026"
      label: "Oracle ERP Cloud REST API — alternative for real-time individual record operations"
    - id: "business/erp-integration/oracle-integration-cloud-capabilities/2026"
      label: "Oracle Integration Cloud — orchestrates FBDI imports via ERP Cloud Adapter"
  solves: []
  alternative_to:
    - id: "business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026"
      label: "REST API — alternative for small-volume real-time operations"
  often_confused_with:
    - id: "business/erp-integration/oracle-bicc-data-extraction/2026"
      label: "BICC is outbound extraction; FBDI is inbound import — opposite directions"

# === SOURCES ===
sources:
  - id: src1
    title: "File-Based Data Import (FBDI) for Financials — Oracle Fusion Cloud"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/financials/26a/oefbf/index.html
    type: official_docs
    published: 2026-01-15
    reliability: authoritative
  - id: src2
    title: "ErpIntegrationService SOAP Web Service — Oracle Financials Cloud 25A"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/financials/25a/oeswf/erpintegrationservice-d16509e420.html
    type: official_docs
    published: 2025-01-15
    reliability: authoritative
  - id: src3
    title: "File Size Limits for Import — Oracle Cloud Sales"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/sales/fasqa/file-size-limits-for-import.html
    type: official_docs
    published: 2025-06-01
    reliability: authoritative
  - id: src4
    title: "File-Based Data Import (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: 2024-08-15
    reliability: moderate_high
  - id: src5
    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: 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: "FBDI ImportBulkData using ErpIntegration REST API"
    author: Soalicious
    url: https://soalicious.blogspot.com/2024/06/oic-erp-importbulkdata-using.html
    type: technical_blog
    published: 2024-06-15
    reliability: moderate_high
  - id: src8
    title: "Best Practices And Common Mistakes To Avoid Using FBDI (Doc ID 2677581.1)"
    author: Oracle Support
    url: https://support.oracle.com/knowledge/Oracle%20Cloud/2677581_1.html
    type: official_docs
    published: 2024-01-01
    reliability: authoritative
---

# 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 (e.g., "Import Journals," "Import Payables Invoices") 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]

| Property | Value |
|---|---|
| **Vendor** | Oracle |
| **System** | Oracle Fusion Cloud ERP (Release 26A) |
| **API Surface** | File-Based (FBDI) + ErpIntegrationService (SOAP/REST) |
| **Current Release** | 26A (January 2026) |
| **Editions Covered** | All editions — FBDI is a core platform capability |
| **Deployment** | Cloud |
| **API Docs URL** | [FBDI for Financials](https://docs.oracle.com/en/cloud/saas/financials/26a/oefbf/index.html) |
| **Status** | GA — actively maintained, templates updated quarterly |

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

| Channel | Protocol | Best For | Max Records/Job | File Size Limit | Automated? | Bulk? |
|---|---|---|---|---|---|---|
| **Manual UI Upload** | HTTPS (browser) | Ad-hoc imports, testing | ~100K per CSV | 250 MB ZIP | No | Yes |
| **ErpIntegrationService SOAP** | SOAP/XML | Server-to-server automation | 2M (20 files x 100K) | 250 MB ZIP | Yes | Yes |
| **ErpIntegrationService REST** | REST/JSON | Modern server-to-server | 2M (20 files x 100K) | 250 MB ZIP | Yes | Yes |
| **OIC ERP Cloud Adapter** | Adapter-based | Oracle-to-Oracle, iPaaS orchestration | 2M (20 files x 100K) | 250 MB ZIP | Yes | Yes |
| **External Data Loader Client (EDLC)** | CLI tool | Large-volume migrations, auto-splits | Unlimited (auto-split) | 250 MB per split | Yes | Yes |

## Rate Limits & Quotas

### Per-File / Per-Job Limits

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| **Max ZIP file size** | 250 MB | All channels | Hard limit — UCM rejects larger uploads [src3] |
| **Recommended records per CSV** | ~100,000 | Each CSV within ZIP | Performance degrades above this; Oracle recommends 10K for error triage [src3, src6] |
| **Max CSV files per ZIP** | 20 | Per import job | Oracle recommended limit for 2M total records [src3] |
| **Max total records per job** | ~2,000,000 | Per import job | 20 files x 100K records [src3] |
| **Max parallel import batches** | 10 | Per Oracle instance | Running more than 10 causes ESS queue contention [src3] |

### ESS Job Scheduling Limits

| Limit Type | Value | Notes |
|---|---|---|
| **Concurrent ESS jobs** | Instance-dependent | Shared pool with all scheduled processes — not FBDI-specific [src4] |
| **Job timeout** | Configurable per job | Large imports can run 30+ minutes; monitor via ESS Console [src4] |
| **Callback support** | Yes | ErpIntegrationService supports web service callbacks on completion [src2] |
| **Notification options** | Email, Bell, Both, None | 2-digit code: first digit = channel, second = condition [src2] |

### UCM Upload Limits

| Limit Type | Value | Notes |
|---|---|---|
| **Max upload size (ErpIntegrationService)** | 250 MB | Base64-encoded content in SOAP/REST payload [src2, src3] |
| **Document security group** | FAFusionImportExport | Required for FBDI uploads; Attachment group also works [src2] |
| **Account path (Financials)** | fin$/payables$/import$, fin$/generalLedger$/import$ | Module-specific UCM paths [src7] |

## Authentication

| Flow | Use When | Token Lifetime | Refresh? | Notes |
|---|---|---|---|---|
| **Basic Auth** | Quick automation, testing | Session-based | N/A | Username:password base64-encoded; works for SOAP/REST [src2] |
| **OAuth 2.0 (3-legged)** | OIC, external iPaaS | Access: 1h typical | Yes | Requires Oracle Identity Cloud Service (IDCS) setup [src2] |
| **OAuth 2.0 (JWT assertion)** | Server-to-server, unattended | Configurable | New JWT per request | Recommended for production integrations [src2] |
| **SAML assertion** | Federated identity scenarios | Session-based | N/A | Complex setup; not recommended for FBDI automation [src2] |

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

- 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 (ErpIntegrationService)
|   +-- 100,000 - 2,000,000 --> Split into multiple CSVs (100K each), 1 ZIP, 1 job
|   +-- > 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) + external scheduler
    +-- Oracle-to-Oracle --> OIC with ERP Cloud Adapter "Import Bulk Data" action
    +-- Large migration --> External Data Loader Client (EDLC) with auto-splitting
```

## Quick Reference

### FBDI Process Flow (All Modules)

| Step | Action | System | Details |
|---|---|---|---|
| 1 | Download XLSM template | Oracle Docs | Module-specific; re-download each release [src1] |
| 2 | Populate data tab | Excel/ETL | Follow column order exactly; mandatory fields per module [src4] |
| 3 | Generate CSV via macro | Excel | "Generate CSV File" button creates ZIP with CSV(s) + .properties [src5] |
| 4 | Upload ZIP to UCM | UI or API | Manual: Tools > File Import and Export; Automated: importBulkData [src2] |
| 5 | Run "Load Interface File for Import" | ESS | Spawns Transfer File + Load File to Interface child jobs [src5] |
| 6 | Run module-specific import job | ESS | e.g., "Import Journals," "Import Payables Invoices" [src5] |
| 7 | Verify import | ESS Console / UI | Check ESS log for errors; review interface table rejections [src4] |
| 8 | Purge interface tables | ESS | Clean up processed/failed records to prevent reprocessing issues [src8] |

### Module Template Reference

| Module | Template File (XLSM) | Interface Table(s) | ESS Import Job | UCM Account Path |
|---|---|---|---|---|
| **GL Journals** | JournalImportTemplate.xlsm | GL_INTERFACE | Import Journals | fin$/generalLedger$/import$ |
| **AP Invoices** | PayablesStandardInvoiceImportTemplate.xlsm | AP_INVOICES_INTERFACE, AP_INVOICE_LINES_INTERFACE | Import Payables Invoices | fin$/payables$/import$ |
| **AR Transactions** | AutoInvoiceImportTemplate.xlsm | RA_INTERFACE_LINES_ALL | Import AutoInvoice | fin$/receivables$/import$ |
| **FA Assets** | AssetImportTemplate.xlsm | FA_MASS_ADDITIONS | Post Mass Additions | fin$/fixedAssets$/import$ |
| **AP Suppliers** | SupplierImportTemplate.xlsm | AP_SUPPLIERS_INT, AP_SUPPLIER_SITES_INT | Import Suppliers | fin$/payables$/import$ |
| **CM Bank Statements** | BankStatementImportTemplate.xlsm | CE_STATEMENT_HEADERS_INT | Import Bank Statement | fin$/cashManagement$/import$ |

[src1, src5]

## 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 (e.g., GL_INTERFACE for journals). [src1, src5]

```bash
# Example: 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]

```
# GL Journal Import: Required fields per row
# -------------------------------------------------------
# Status              = NEW (always)
# Ledger Name         = e.g., "US Primary Ledger"
# Accounting Date     = YYYY/MM/DD format
# Journal Source      = e.g., "Manual", "Spreadsheet"
# Category            = e.g., "Adjustment", "Accrual"
# Currency Code       = ISO 4217 (e.g., USD, EUR)
# Actual Flag         = A (actual), B (budget), E (encumbrance)
# Entered Debit       = Amount (decimal, no currency symbol)
# Entered Credit      = Amount (decimal, no currency symbol)
# Segment1-SegmentN   = Chart of accounts segment values
#
# Click "Generate CSV File" button on Instructions tab
# Output: JournalImportTemplate.zip containing GlInterface.csv
```

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

### 3. Upload to UCM and submit ESS job (manual)

For manual imports, navigate to Scheduled Processes in Oracle ERP Cloud, search for "Load Interface File for Import," and submit with the appropriate parameters. [src5]

```
# Manual UI process:
# 1. Navigator > Tools > Scheduled Processes
# 2. Click "Schedule New Process"
# 3. Search: "Load Interface File for Import"
# 4. Parameters:
#    - Import Process: Select module (e.g., "Import Journals")
#    - Data File: Upload your ZIP file
# 5. Submit
# 6. Monitor: Check ESS job status (Transfer File > Load File to Interface)
# 7. After "Load Interface" completes, submit the import job:
#    - For GL: "Import Journals" (set Group ID if used)
#    - For AP: "Import Payables Invoices" (set Source parameter)
```

**Verify**: ESS Console shows "Succeeded" for both child jobs (Transfer File, Load File to Interface).

### 4. Upload and submit via ErpIntegrationService REST API (automated)

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

```bash
# REST endpoint: POST /fscmRestApi/resources/11.13.18.05/erpintegrations
# Content-Type: application/json
# Authorization: Basic <base64(username:password)>

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-content>",
    "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 includes ReqstId for tracking
# { "ReqstId": 12345678, "RequestStatus": "SUBMITTED", ... }
```

**Verify**: `GET /fscmRestApi/resources/11.13.18.05/erpintegrations?finder=ESSJobStatusRF;requestId=12345678` returns `"RequestStatus": "SUCCEEDED"`.

### 5. Upload and submit via ErpIntegrationService SOAP (automated)

For SOAP-based automation, use the `importBulkData` operation on the ErpIntegrationService WSDL. [src2]

```xml
<!-- SOAP Request to importBulkData -->
<!-- WSDL: https://<instance>/fscmService/ErpIntegrationService?WSDL -->

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:typ="http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/types/"
  xmlns:erp="http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/">
  <soapenv:Body>
    <typ:importBulkData>
      <typ:document>
        <erp:Content>BASE64_ENCODED_ZIP_CONTENT</erp:Content>
        <erp:FileName>JournalImportTemplate.zip</erp:FileName>
        <erp:ContentType>zip</erp:ContentType>
        <erp:DocumentTitle>GL Journal Import</erp:DocumentTitle>
        <erp:DocumentAuthor>INTEGRATION_USER</erp:DocumentAuthor>
        <erp:DocumentSecurityGroup>FAFusionImportExport</erp:DocumentSecurityGroup>
        <erp:DocumentAccount>fin$/generalLedger$/import$</erp:DocumentAccount>
      </typ:document>
      <typ:jobDetails>
        <erp:JobPackageName>/oracle/apps/ess/financials/generalLedger/programs/</erp:JobPackageName>
        <erp:JobDefName>JournalImportLauncher</erp:JobDefName>
        <erp:ParameterList>LEDGER_ID,#NULL,#NULL,#NULL,N</erp:ParameterList>
      </typ:jobDetails>
      <typ:notificationCode>#NULL</typ:notificationCode>
      <typ:callbackURL>#NULL</typ:callbackURL>
      <typ:jobOptions>InterfaceDetails=2</typ:jobOptions>
    </typ:importBulkData>
  </soapenv:Body>
</soapenv:Envelope>

<!-- Response returns requestId (long) for ESS job tracking -->
```

**Verify**: Call `getESSJobStatus` with the returned requestId; expect status "SUCCEEDED".

### 6. Implement error handling and retry logic

Check ESS job status, download execution logs, and handle failures. [src2, src4]

```bash
# Check ESS job status
curl -X GET \
  "https://<instance>.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations?finder=ESSJobStatusRF;requestId=12345678" \
  -u "integration_user:password"

# Download ESS job execution details (log + output)
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": "downloadESSJobExecutionDetails",
    "ReqstId": "12345678"
  }'
# Response: DocumentContent (base64-encoded ZIP with log files)

# Common status values:
# SUBMITTED  -> Job queued
# RUNNING    -> Job executing
# SUCCEEDED  -> Job completed successfully
# ERROR      -> Job failed (check logs)
# WARNING    -> Job completed with warnings (partial success)
```

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

## Code Examples

### Python: Automated FBDI Import via REST API

```python
# 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
import zipfile
import io

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

    # Base64-encode the ZIP file
    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"

    # Submit importBulkData
    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")
    print(f"Submitted ESS job: {request_id}")

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

    return {"request_id": request_id, "status": "TIMEOUT"}


# Usage — GL Journal Import
result = fbdi_import(
    instance_url="https://myinstance.fa.us2.oraclecloud.com",
    username="INTEGRATION_USER",
    password="password",
    zip_path="/data/JournalImportTemplate.zip",
    document_account="fin$/generalLedger$/import$",
    job_name="/oracle/apps/ess/financials/generalLedger/programs/,JournalImportLauncher",
    parameter_list="300000001234567,#NULL,#NULL,#NULL,N"
)
print(f"Final: {result}")
```

### JavaScript/Node.js: Automated FBDI Import

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

const fs = require("fs");
const axios = require("axios"); // axios@1.7+

async function fbdiImport({ instanceUrl, username, password,
  zipPath, documentAccount, jobName, parameterList,
  jobOptions = "InterfaceDetails=2" }) {

  const zipContent = fs.readFileSync(zipPath).toString("base64");
  const endpoint = `${instanceUrl}/fscmRestApi/resources/11.13.18.05/erpintegrations`;
  const auth = { username, password };

  // Submit importBulkData
  const { data } = await axios.post(endpoint, {
    OperationName: "importBulkData",
    DocumentContent: zipContent,
    ContentType: "zip",
    FileName: zipPath.split("/").pop(),
    DocumentAccount: documentAccount,
    JobName: jobName,
    ParameterList: parameterList,
    JobOptions: jobOptions
  }, { auth });

  const requestId = data.ReqstId;
  console.log(`Submitted ESS job: ${requestId}`);

  // Poll for completion
  for (let i = 0; i < 60; i++) {
    await new Promise(r => setTimeout(r, 30000));
    const statusResp = await axios.get(
      `${endpoint}?finder=ESSJobStatusRF;requestId=${requestId}`,
      { auth }
    );
    const items = statusResp.data.items || [];
    if (items.length) {
      const status = items[0].RequestStatus;
      console.log(`  Poll ${i + 1}: ${status}`);
      if (["SUCCEEDED", "ERROR", "WARNING"].includes(status)) {
        return { requestId, status };
      }
    }
  }
  return { requestId, status: "TIMEOUT" };
}

// Usage — AP Invoice Import
fbdiImport({
  instanceUrl: "https://myinstance.fa.us2.oraclecloud.com",
  username: "INTEGRATION_USER",
  password: "password",
  zipPath: "./PayablesInvoiceImport.zip",
  documentAccount: "fin$/payables$/import$",
  jobName: "/oracle/apps/ess/financials/payables/invoices/transactions/,APXIIMPT",
  parameterList: "300000001234567,#NULL,#NULL,#NULL,#NULL,#NULL"
}).then(console.log);
```

### cURL: Quick FBDI status check

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

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

# Expected response shape:
# {
#   "items": [{
#     "ReqstId": 12345678,
#     "RequestStatus": "SUCCEEDED",
#     "OperationName": "importBulkData",
#     ...
#   }],
#   "count": 1
# }
```

## Data Mapping

### GL Journal Import — Key Fields

| CSV Column | Interface Table Column | Type | Required | Gotcha |
|---|---|---|---|---|
| Status | STATUS | String | Yes | Must be "NEW" for new records [src5] |
| Ledger Name | LEDGER_NAME | String | Yes | Must match exactly — case-sensitive [src5] |
| Accounting Date | ACCOUNTING_DATE | Date | Yes | Format: YYYY/MM/DD — not YYYY-MM-DD [src5] |
| Journal Source | USER_JE_SOURCE_NAME | String | Yes | Must exist in Lookup (e.g., "Spreadsheet", "Manual") [src5] |
| Category | USER_JE_CATEGORY_NAME | String | Yes | Must exist in Lookup (e.g., "Adjustment") [src5] |
| Currency Code | CURRENCY_CODE | String | Yes | ISO 4217 — "USD", not "US Dollar" [src5] |
| Entered Debit | ENTERED_DR | Number | Conditional | Either debit or credit per line, not both [src5] |
| Entered Credit | ENTERED_CR | Number | Conditional | Either debit or credit per line, not both [src5] |
| Segment1-SegmentN | SEGMENT1-SEGMENTN | String | Yes | Must match chart of accounts structure [src5] |
| Group ID | GROUP_ID | Number | No | Enables selective batch import — highly recommended [src5] |

### AP Invoice Import — Key Fields

| CSV Column | Interface Table Column | Type | Required | Gotcha |
|---|---|---|---|---|
| Invoice Number | INVOICE_NUM | String | Yes | Must be unique per supplier + business unit [src1] |
| Invoice Date | INVOICE_DATE | Date | Yes | Format: YYYY/MM/DD [src1] |
| Vendor Name | VENDOR_NAME | String | Conditional | Either Vendor Name or Vendor Number, not both [src1] |
| Invoice Amount | INVOICE_AMOUNT | Number | Yes | Must equal sum of line amounts [src1] |
| Line Amount | AMOUNT | Number | Yes (lines) | Per line; no currency symbols [src1] |
| Distribution Account | DIST_CODE_COMBINATION | String | Conditional | Concatenated segment string (e.g., "01-110-7100-0000") [src1] |

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

| Error | Meaning | Cause | Resolution |
|---|---|---|---|
| **FBDI-001: Load File to Interface failed** | CSV structure mismatch | Template version mismatch or wrong column count | Re-download template for current release; verify CSV column count matches [src4] |
| **GL-IMPORT: Unbalanced journal** | Debit/credit imbalance | Total debits do not equal total credits for a journal batch | Verify amounts; check for rounding errors in currency conversion [src5] |
| **AP-IMPORT: Duplicate invoice** | Duplicate detection | Same invoice number + supplier + business unit already exists | Use unique invoice numbers; check existing invoices before import [src1] |
| **ESS-TIMEOUT** | Job exceeded time limit | Too many records in single batch or ESS queue congestion | Split into smaller batches; schedule during off-peak hours [src4] |
| **UCM-UPLOAD: File too large** | 250 MB limit exceeded | ZIP file exceeds UCM upload limit | Split data into multiple ZIP files; submit as separate jobs [src3] |
| **INTERFACE-PURGE: Records exist** | Stale interface records | Previous failed import left records in interface table | Run purge process for the module before resubmitting [src8] |

### 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 where data loads to wrong fields. 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. Data sits in interface tables indefinitely. 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 in interface tables across multiple attempts, causing subsequent imports to process stale records alongside new ones. Fix: `Run the module-specific purge process (e.g., "Purge Interface Tables") before every import attempt after a failure`. [src8]
- **Encoding issues**: CSV files with BOM (Byte Order Mark) characters or non-UTF-8 encoding cause "Load File to Interface" to fail or produce garbled data. Fix: `Save CSV as UTF-8 without BOM; validate encoding before upload`. [src4]
- **Parallel batch collision**: Running more than 10 parallel FBDI import jobs overwhelms the ESS scheduler, causing random job failures or extreme queue delays. Fix: `Limit to 10 parallel batches; implement job queue with sequential submission`. [src3]
- **DocumentAccount path mismatch**: The UCM account path in importBulkData must exactly match the module. Wrong path causes the file to upload successfully to UCM but the ESS job cannot find it. Fix: `Use exact paths — 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 — one bad record affects the entire batch
# 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
# Or: 50 CSV files of 10K each -> 3 ZIPs -> 3 jobs (for better error isolation)
# 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 data is imported
# Data only reaches interface tables after Phase 1
# Application tables remain unchanged until Phase 2 runs
# Users see no journals/invoices despite "successful" load
```

### Correct: Always chain Phase 1 and Phase 2

```python
# 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}
    )
    # Monitor Phase 2 separately
```

### Wrong: Resubmitting failed batches without purging interface tables

```
# BAD — import fails, fix CSV, resubmit same batch
# Failed records from attempt 1 are still in interface tables
# Attempt 2 loads new records BUT Phase 2 also picks up old failed records
# Result: duplicate processing attempts, constraint violations, data corruption
```

### 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
# 4. Run both Phase 1 and Phase 2
```

## Common Pitfalls

- **Using old XLSM templates after quarterly release**: Oracle updates FBDI templates every release (25D, 26A, 26B). Column additions, removals, or reordering break imports silently — data lands in wrong fields. Fix: `Download fresh templates from Oracle docs 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. This file contains metadata the import process needs. Manually creating CSV without the .properties file 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. The import may succeed but dates are parsed incorrectly. 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, including records from other sources or failed previous imports. Fix: `Always set Interface Group Identifier in the FBDI file and pass the matching Group ID parameter to Import Journals`. [src5]
- **Running imports during peak business hours**: FBDI jobs share the ESS scheduler with all other processes (BIP reports, subledger accounting, etc.). Large imports during peak hours cause cascading delays. Fix: `Schedule FBDI imports during off-peak hours (nights/weekends) or coordinate with the ERP admin team`. [src4]
- **Assuming importBulkData handles both phases**: The `importBulkData` REST/SOAP operation only handles Phase 1 (Load Interface File for Import). Phase 2 must be submitted separately. Fix: `Submit Phase 2 via submitESSJobRequest after Phase 1 completes, or use OIC adapter which can orchestrate both phases`. [src2]

## Diagnostic Commands

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

# Check all 19 ErpIntegrationService operations
# WSDL: https://<instance>/fscmService/ErpIntegrationService?WSDL
# Key operations: importBulkData, getESSJobStatus, downloadESSJobExecutionDetails,
#                 uploadFileToUcm, submitESSJobRequest, getDocumentIdsForFilePrefix
```

## Version History & Compatibility

| Release | Date | Status | Template Changes | Notes |
|---|---|---|---|---|
| **26A** | 2026-01 | Current | Updated macro structure in XLSM templates | Re-download all templates [src1] |
| **25D** | 2025-10 | Supported | Minor column additions in AP/AR templates | Check AP_INVOICE_LINES_INTERFACE for new optional fields |
| **25C** | 2025-07 | Supported | No breaking template changes | Stable release for FBDI |
| **25B** | 2025-04 | Supported | New FBDI templates for Project Management | No impact on Financials templates |
| **25A** | 2025-01 | Supported | ErpIntegrationService SOAP documentation refresh | [src2] |

### Deprecation Policy

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. However, using templates more than 2 releases old is unsupported and may cause silent data mapping errors. Oracle publishes template changes in the "What's New" section of each release's FBDI documentation. [src1]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Bulk data migration (10K-2M records) | Real-time individual record CRUD | Oracle ERP Cloud REST API |
| Scheduled periodic batch imports (daily/weekly journals, invoices) | Outbound data extraction from Oracle | BICC or BIP Reports |
| Data corrections requiring mass updates via interface tables | Low-latency event-driven integrations | Oracle Business Events + OIC |
| Initial data load during implementation | Fewer than 100 records per transaction | REST API with JSON payload |
| Non-Oracle source systems pushing data to Oracle ERP | Oracle-to-Oracle cloud integrations | OIC pre-built integrations or Application Data Management (ADM) |

## 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 (BI Cloud Connector), 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]

## Related Units

- [Oracle ERP Cloud Authentication](../oracle-erp-cloud-authentication/2026) — prerequisite for ErpIntegrationService access
- [Oracle ERP Cloud REST API Capabilities](../oracle-erp-cloud-rest-api-capabilities/2026) — alternative for real-time individual record operations
- [Oracle BICC Data Extraction](../oracle-bicc-data-extraction/2026) — outbound counterpart to FBDI's inbound import
- [Oracle Integration Cloud Capabilities](../oracle-integration-cloud-capabilities/2026) — orchestrates FBDI imports via native ERP Cloud Adapter