Oracle FBDI Common Failures — File Format, Validation, Reference Data, UCM Permissions

TL;DR

• Bottom line: Oracle FBDI failures fall into 4 categories: file format errors (wrong CSV name/structure), validation failures (bad data values), reference data mismatches (invalid lookups), and UCM permission issues (missing upload roles).
• Key limit: Load Interface File for Import is all-or-nothing — one invalid row rejects the entire batch.
• Watch out for: CSV file name prefix must exactly match FBDI template specification — wrong prefix causes silent rejection with no error.
• Best for: Troubleshooting Oracle FBDI import failures across all ERP modules.
• Authentication: UCM upload requires specific security roles separate from ERP module roles.

System Profile

Oracle FBDI is the primary bulk data loading mechanism for Oracle Fusion Cloud ERP using Excel templates that generate CSV files compressed into ZIP archives and uploaded to UCM.

Rate Limits & Quotas

Common FBDI Failure Categories

Constraints

• Files must be ZIP archives containing CSV — other formats rejected.
• CSV file names must match exact template prefix — wrong prefix = silent rejection.
• All-or-nothing per batch — one bad row rejects entire file.
• 240 byte field limit — multi-byte characters (CJK) limit to ~80 characters.
• Excel macro limit ~100K rows before becoming unresponsive.
• UCM virus scanning can reject files with unclear errors.

Integration Pattern Decision Tree

START — FBDI import failed
├── File upload to UCM
│   ├── "No valid data files found" → Check CSV prefix
│   ├── UCM account missing → Assign UCM role
│   └── Permission denied → Add File Import and Export role
├── Load Interface File (ESS job)
│   ├── Error → Check field lengths, dates, required fields
│   ├── Warning → Partial load, check error report
│   └── Succeeded with 0 rows → CSV prefix mismatch
├── Module import
│   ├── Reference data errors → Verify lookups/segments
│   └── Business rule violations → Check duplicates, periods
└── Post-import issues
    ├── Wrong values → Column order mismatch
    └── Missing records → Check row count

Quick Reference

Step-by-Step Integration Guide

1. Prepare FBDI File

Download template, populate data, generate CSV with correct prefix. [src1]

2. Upload via REST API

Use erpintegrations endpoint for automated uploads. [src2]

payload = {
    "OperationName": "importBulkData",
    "DocumentContent": base64_content,
    "ContentType": "zip",
    "FileName": "JournalImport.zip",
    "JobName": "/oracle/apps/ess/.../JournalImportLauncher"
}
response = requests.post(f"{BASE_URL}/fscmRestApi/resources/11.13.18.05/erpintegrations",
    headers=headers, json=payload)

3. Monitor ESS Job Status

Poll until SUCCEEDED, ERROR, or WARNING. [src2]

Code Examples

Python: Pre-Validate FBDI CSV

# Input:  CSV file, field specifications
# Output: Validation errors per row

def validate_fbdi_csv(csv_path, field_specs):
    errors = []
    with open(csv_path, "r", encoding="utf-8-sig") as f:
        reader = csv.reader(f)
        header = next(reader)
        for row_num, row in enumerate(reader, start=2):
            for col_idx, spec in enumerate(field_specs):
                value = row[col_idx].strip() if col_idx < len(row) else ""
                if spec.get("required") and not value:
                    errors.append(f"Row {row_num}: '{spec['name']}' required")
                if value and spec.get("max_bytes"):
                    if len(value.encode("utf-8")) > spec["max_bytes"]:
                        errors.append(f"Row {row_num}: '{spec['name']}' exceeds limit")
    return errors

cURL: Upload FBDI File

FILE_CONTENT=$(base64 -w0 JournalImport.zip)
curl -X POST "$ORACLE_URL/fscmRestApi/resources/11.13.18.05/erpintegrations" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"OperationName\":\"importBulkData\",\"DocumentContent\":\"$FILE_CONTENT\",\"ContentType\":\"zip\",\"FileName\":\"JournalImport.zip\"}"

Data Mapping

FBDI File Name Prefix Reference

Data Type Gotchas

• Dates must use YYYY/MM/DD with forward slashes — hyphens not accepted. [src1]
• Amounts use period (.) decimal separator regardless of locale. [src3]
• Multi-byte chars: 240 bytes = ~80 CJK characters. [src5]
• Booleans: "Y" or "N" only — "true"/"false"/"1"/"0" not accepted. [src1]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Silent 0-row load: CSV prefix mismatch — job succeeds but loads nothing. Fix: Verify CSV name against Instructions tab. [src2]
• BOM characters: Excel adds BOM that Oracle parser cannot handle. Fix: Save as UTF-8 without BOM. [src6]
• Multi-byte truncation: 240-byte limit truncates CJK text. Fix: Pre-validate byte length. [src5]

Anti-Patterns

Wrong: Generic CSV File Names

// ❌ BAD: JournalImport_March.csv, data_export.csv
// Silent rejection — no error message

Correct: Exact Template Prefix

// ✅ GOOD: GlInterface.csv, ApInvoicesInterface.csv

Wrong: Upload Without Pre-Validation

// ❌ BAD: 100K rows, one bad date → entire batch fails

Correct: Validate Every Row First

# ✅ GOOD: Catch errors before upload
errors = validate_fbdi_csv("data.csv", specs)
if not errors: upload_to_ucm("data.zip")

Common Pitfalls

• Not reading Instructions tab: Contains field specs and CSV prefix. Fix: Read completely before populating. [src1]
• Not re-downloading templates after updates: New columns may be added. Fix: Re-download after quarterly update. [src2]
• Locale-specific formatting: DD/MM/YYYY, comma decimals fail. Fix: YYYY/MM/DD, period decimals. [src3]
• Not verifying row count after success: SUCCEEDED with 0 rows is silent failure. Fix: Compare loaded rows vs expected. [src2]

Diagnostic Commands

# Check ESS job status
curl -X GET "$ORACLE_URL/fscmRestApi/resources/11.13.18.05/erpintegrations?finder=ESSJobStatusRF;requestId=REQUEST_ID" \
  -H "Authorization: Bearer $TOKEN"

# Validate CSV encoding
file your_file.csv
# Expected: "UTF-8 Unicode text" (NOT "with BOM")

# Count rows
wc -l your_file.csv  # Subtract 1 for header

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• FBDI templates are release-specific — always re-download after quarterly updates.
• All-or-nothing behavior means pre-validation is essential, not optional.
• CSV prefix matching may be case-sensitive on some environments.
• UCM permissions are separate from ERP module permissions.
• Error messages are often vague — detailed errors in ESS job output log.