Introduction
Handling multipart/form-data in Oracle Integration Cloud (OIC Gen 3) is a common requirement in real-world integrations where files and metadata must be transmitted together. Whether you’re uploading employee documents to HCM, sending attachments to external REST services, or integrating with third-party APIs like Salesforce or ServiceNow, understanding how multipart requests work in OIC is critical.
In practical projects, this is not just a theoretical concept—it directly impacts integrations involving document uploads, invoice attachments, onboarding files, and more. This article explains multipart/form-data in OIC from a consultant’s perspective, focusing on implementation patterns, challenges, and best practices.
What is Multipart/Form-Data in OIC?
Multipart/form-data is an HTTP request format used to send multiple pieces of data in a single request. Typically, it is used when:
- Uploading files along with metadata
- Sending binary content (PDF, images, Excel files)
- Combining JSON/XML payloads with attachments
In Oracle Integration Cloud, multipart handling is primarily done using:
- REST Adapter
- Stage File Action
- Attachments Processing
- Integration Patterns (App Driven / Scheduled / Basic Routing)
A multipart request consists of:
- Boundary (separates parts)
- Headers per part
- Content (file or text data)
Real-World Integration Use Cases
1. Employee Document Upload (HCM Integration)
A common scenario in Oracle Fusion HCM:
- Upload employee documents (PAN, Aadhaar, contracts)
- Metadata includes:
- Employee ID
- Document Type
- Category
Flow: OIC → REST API → HCM Document Records
2. Invoice Attachment Upload (ERP Integration)
In Oracle Fusion ERP:
- Upload scanned invoices to Payables
- Send:
- Invoice details (JSON/XML)
- PDF attachment
Flow: OIC → ERP REST API → AP Invoice Interface
3. Third-Party API File Upload
Example: Integration with external vendor system
- Upload product images or CSV files
- Include authentication headers
- Send file + attributes
Flow: OIC → External REST API (multipart request)
Architecture / Technical Flow
A typical multipart implementation in OIC looks like this:
- Trigger Integration
- REST trigger or scheduled integration
- Read File
- Stage File action (Read/Write)
- Prepare Payload
- Map metadata fields
- Convert file to binary/base64 if required
- Invoke REST Adapter
- Configure multipart/form-data request
- Process Response
- Handle success/failure
Prerequisites
Before implementing multipart/form-data in OIC:
- Access to OIC Gen 3 instance
- REST endpoint supporting multipart
- Sample payload (Postman or API docs)
- File storage (FTP / Stage File / Object Storage)
- Proper authentication (Basic / OAuth)
Step-by-Step Build Process
Step 1 – Create Integration
Navigation: Home → Integrations → Create
- Choose: App Driven Orchestration or Scheduled Integration
- Name:
Upload_Document_Multipart
Step 2 – Configure REST Trigger (Optional)
If external system sends request:
- Add REST trigger
- Accept metadata parameters
- Define request structure (JSON/XML)
Step 3 – Read File Using Stage File
Action: Stage File → Read File
Configuration:
| Field | Value |
|---|---|
| Directory | /incoming |
| File Name | employee_doc.pdf |
| File Type | Opaque |
👉 Important: Use Opaque schema for binary files.
Step 4 – Configure REST Adapter (Invoke)
Drag REST adapter and configure:
a. Endpoint Configuration
- Method: POST
- URL: Target API endpoint
b. Request Format
Select:
- Multipart Form Data
c. Define Parts
You must define each part manually:
| Part Name | Type | Description |
|---|---|---|
| file | File | Binary file |
| metadata | Text | JSON/XML metadata |
Step 5 – Mapping Multipart Payload
In mapper:
File Part
- Map Stage File output (binary)
- Ensure correct element (usually
opaqueElement)
Metadata Part
Example JSON:
Map fields from trigger or static values.
Step 6 – Set Headers
Add required headers:
| Header | Value |
|---|---|
| Content-Type | multipart/form-data |
| Authorization | Bearer Token |
👉 Note: OIC automatically generates boundary.
Step 7 – Save and Activate
- Validate integration
- Activate
Testing the Technical Component
Test Scenario
Upload employee document:
- Employee ID: 1001
- Document: passport.pdf
Expected Behavior
- File successfully uploaded
- Response returns:
- Document ID
- Status: SUCCESS
Validation Checks
- File size matches
- Metadata correctly stored
- API response code = 200/201
Common Errors and Troubleshooting
1. Boundary Issues
Error: Invalid multipart request
Cause: Manual header override
Fix: Let OIC handle boundary automatically.
2. File Not Uploaded Properly
Error: Empty file received
Cause: Incorrect mapping of opaque element
Fix: Map correct binary node from Stage File.
3. Unsupported Media Type (415)
Cause: Incorrect content-type
Fix: Use multipart/form-data in REST adapter configuration.
4. Authentication Failures
Cause: Missing headers
Fix: Configure security in REST connection.
Best Practices
1. Always Use Stage File for Binary Handling
Avoid direct mapping from trigger to REST invoke for files.
2. Use Opaque Schema for Files
This ensures proper binary transmission.
3. Avoid Manual Boundary Configuration
OIC handles it internally—manual changes break requests.
4. Validate with Postman First
Before building in OIC:
- Test API using Postman
- Export sample request
5. Use Logging for Debugging
- Enable tracking
- Log payload (excluding sensitive data)
6. Handle Large Files Carefully
- Use chunking if required
- Check API size limits
7. Reusable Integration Design
Create reusable components for:
- File handling
- Metadata mapping
Real Consultant Insight
In a recent ERP implementation:
- Client needed bulk invoice uploads with attachments
- Initial approach failed due to incorrect multipart mapping
- Solution:
- Used Stage File + proper REST adapter configuration
- Reduced failures by 90%
Another case:
- HCM onboarding documents integration
- Issue: Files corrupted during upload
- Root cause: Incorrect encoding
- Fix: Switched to Opaque schema
Summary
Handling multipart/form-data in Oracle Integration Cloud Gen 3 is essential for modern integrations involving file uploads and combined payloads. While OIC simplifies much of the complexity, real-world implementations require careful attention to:
- File handling (Stage File)
- Payload mapping
- REST adapter configuration
- Testing and debugging
When implemented correctly, multipart integrations enable seamless document exchange across Oracle Fusion HCM, ERP, and third-party systems.
For deeper reference, review official Oracle documentation:
https://docs.oracle.com/en/cloud/saas/index.html
FAQs
1. Can OIC handle large file uploads using multipart?
Yes, but it depends on API limits. For large files, consider chunking or Object Storage integration.
2. Why is my file getting corrupted during upload?
This usually happens due to incorrect schema or encoding. Always use Opaque type in Stage File.
3. Do I need to manually define multipart boundaries in OIC?
No. OIC automatically generates boundaries. Manual configuration can break the request.