Oracle Integration Cloud (OIC) Deep Dive — Adapters, Connections, Error Handling, and Pricing

TL;DR

• Bottom line: OIC is Oracle's cloud-native iPaaS with 80+ prebuilt adapters, message-pack pricing (5,000 msgs/hr per pack at 50KB each), and native connectivity to all Oracle SaaS products — Gen 3 adds parallel execution, Projects with RBAC, and AI-assisted integration design.
• Key limit: 5,000 messages/hour per message pack (cloud license) or 20,000/hour (BYOL) — a 270KB payload counts as 6 messages, not 1. [src3]
• Watch out for: Standard Edition excludes on-premises adapters and process automation — if you need connectivity agent for on-prem systems, you must have Enterprise Edition.
• Best for: Organizations already on Oracle Cloud (Fusion ERP, HCM, SCM) needing native, low-code integration with prebuilt adapters and Oracle-managed infrastructure.
• Authentication: OAuth 2.0 via OCI IAM (formerly IDCS) for all API access — basic auth deprecated in Gen 3 for Oracle REST APIs. [src2]

System Profile

Oracle Integration Cloud (OIC) is Oracle's fully managed iPaaS (integration Platform as a Service), now in its third generation (Gen 3). It provides application integration, process automation, a visual builder, and an embedded file server. OIC Gen 3 is built on Oracle Cloud Infrastructure (OCI) and uses a microservices architecture with containerized services for independent scaling. Beginning with Gen 3, OIC has been split into two separate products: Oracle Integration 3 (handling integration configuration) and OCI Process Automation (handling workflow and decision modeling). [src1, src2]

This card covers both Standard and Enterprise editions. Standard Edition includes SaaS and technology adapters (REST, SOAP, FTP, database) but excludes on-premises adapters and process automation. Enterprise Edition adds on-premises connectivity via the connectivity agent, B2B features, process automation, and advanced capabilities. This card does NOT cover Oracle SOA Cloud Service or Oracle API Gateway (separate products).

API Surfaces & Capabilities

OIC is not a single API — it is an integration platform that orchestrates flows between systems using adapters. The key "surfaces" are its adapter types and the integration patterns they support. [src1]

Rate Limits & Quotas

Message Pack Limits

OIC billing is based on message packs, not API call counts. Understanding message sizing is critical to cost forecasting. [src3, src4]

Platform Limits

Authentication

OIC Gen 3 uses OCI IAM (successor to IDCS) for identity management. Basic authentication for Oracle-provided REST APIs was removed in Gen 3. [src2]

Authentication Gotchas

• Gen 3 removed basic authentication for Oracle REST APIs — all existing integrations using basic auth must migrate to OAuth before or during Gen 3 upgrade. [src2]
• The connectivity agent auto-renews its OAuth token before expiration — modifying the default 3,600s expiry in IDCS/OCI IAM can cause in-flight request failures. [src1]
• The predefined IDCS scope urn:opc:resource:consumer::all is required to trigger integrations via OAuth — missing this scope is the most common auth configuration error.
• Oracle NetSuite Adapter TBA (Token-Based Authentication) authorization flow is not supported in Gen 3 — use OAuth 2.0 instead. [src2]

Constraints

• Standard Edition cannot connect to on-premises systems — connectivity agent requires Enterprise Edition. [src3]
• Message sizing at 50KB granularity means high-volume integrations with large payloads can consume packs much faster than expected — always calculate effective message count, not just transaction count. [src3, src4]
• Gen 3 removed Basic Routing and File Transfer integration types — only App-Driven Orchestration and Scheduled Orchestration remain. [src2]
• Parallel action is limited to 5 branches — complex fan-out patterns need multiple nested parallel actions or decomposition into child integrations.
• AS2 adapter in Standard Edition is standalone mode only (Gen 2 upgrades) — Enterprise Edition required for full B2B features in Gen 3. [src2]
• Delayed (asynchronous) response support removed for several key adapters (Oracle ERP Cloud, HCM Cloud, Salesforce, ServiceNow). [src2]
• Instance IDs changed from numeric to alphanumeric in Gen 3 — any system parsing OIC instance IDs must update from numeric to string fields. [src2]

Integration Pattern Decision Tree

START — User needs to integrate systems using Oracle Integration Cloud (OIC)
|-- What edition do you have?
|   |-- Standard Edition
|   |   |-- All systems are cloud-based (SaaS)?
|   |   |   |-- YES -> Proceed with adapter selection
|   |   |   +-- NO (on-premises) -> STOP: upgrade to Enterprise Edition
|   |-- Enterprise Edition -> Proceed
|
|-- What's the integration pattern?
|   |-- Real-time (event-triggered, <1s response)
|   |   |-- Oracle SaaS to Oracle SaaS?
|   |   |   |-- YES -> App-Driven Orchestration with Oracle SaaS adapter
|   |   |   +-- NO -> App-Driven Orchestration with REST/SOAP trigger
|   |   +-- Need human approval step?
|   |       |-- YES -> OCI Process Automation (Enterprise)
|   |       +-- NO -> Standard App-Driven Orchestration
|   |
|   |-- Batch/Scheduled (periodic, high volume)
|   |   |-- Data volume < 5,000 records/hour?
|   |   |   |-- YES -> Single scheduled integration (1 message pack)
|   |   |   +-- NO -> Scheduled + file-based staging via File Server
|   |
|   |-- Event-driven (Business Events, webhooks)
|   |   |-- Source is Oracle SaaS?
|   |   |   |-- YES -> Oracle SaaS adapter with Business Event subscription
|   |   |   +-- NO -> REST adapter webhook trigger or Kafka adapter
|   |   +-- Need guaranteed delivery?
|   |       |-- YES -> Parking lot pattern with ATP database
|   |       +-- NO -> Fire-and-forget with error notification
|   |
|   +-- File-based (FBDI, large file transfer)
|       +-- File Server (SFTP) + Scheduled integration + Stage File
|
+-- Error tolerance?
    |-- Zero-loss -> Parking lot pattern + ATP DB + resubmit flow
    +-- Best-effort -> Scope-based fault handling + email notification

Quick Reference

Adapter Categories

Pricing Quick Reference

Step-by-Step Integration Guide

1. Provision an OIC instance

Select Standard or Enterprise edition based on adapter and process automation requirements. Choose the OCI region closest to your primary data sources. [src1]

# Using OCI CLI to create an OIC instance
oci integration integration-instance create \
  --compartment-id <compartment-ocid> \
  --display-name "production-oic" \
  --integration-instance-type "ENTERPRISE" \
  --is-byol false \
  --message-packs 1 \
  --shape "PRODUCTION"

Verify: OCI Console > Integration > Instances > Check status = Active

2. Configure OAuth for integration invocation

Create a confidential application in OCI IAM (IDCS) with the urn:opc:resource:consumer::all scope to enable OAuth-based integration triggering. [src1]

# Test OAuth token acquisition
curl -X POST \
  "https://idcs-<tenant>.identity.oraclecloud.com/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all" \
  -u "<client-id>:<client-secret>"

Verify: Response contains access_token with expected expiry (default 3600s)

3. Create an integration flow

Use the Design > Integrations UI. Select App-Driven Orchestration for real-time or Scheduled Orchestration for batch. Configure trigger and invoke connections. [src1]

# Integration flow structure
Trigger: REST Adapter (receives POST /orders)
  -> Map: Transform request to ERP format
  -> Invoke: Oracle ERP Cloud Adapter (create Sales Order)
  -> Map: Transform response
  -> Return: Order confirmation with ERP reference

Verify: Activate integration > Test with sample payload via tracking page

4. Deploy connectivity agent (Enterprise Edition)

Install the connectivity agent on a host with network access to on-premises systems. Requires JDK 17 (mandatory in Gen 3). The agent establishes an outbound connection to OIC — no inbound firewall rules needed. [src1, src2]

# Requires JDK 17 (JDK 8/11 deprecated in Gen 3)
java -version  # Must show 17.x

# Install and configure agent
java -jar oic_connectivity_agent.jar
# Agent auto-registers with OIC via OAuth token
# Do NOT modify the default token expiry (3600s)

Verify: OIC Console > Settings > Agents > Agent status = Running

5. Implement error handling with Scope and fault handler

Wrap all invoke activities in a Scope action. Add a fault handler for structured error processing. Use the parking lot pattern for guaranteed delivery. [src5]

# Error handling pattern
Scope: "Process Order"
  -> Invoke: Oracle ERP Cloud Adapter
  -> [On Success] -> Map response -> Return
  -> [Fault Handler]
     -> Log error details
     -> Invoke: ATP Database (insert to parking_lot table)
     -> Notification: Send error email
     -> Re-throw or swallow based on error type

Verify: Tracking page > Errors tab > Verify fault handler execution

6. Configure scheduling for batch integrations

Use Scheduled Orchestration for recurring batch operations. Set frequency and configure the scheduler to call asynchronous child integrations. [src5]

# Scheduling best practice
Scheduler (Parent): Runs every 15 minutes
  -> Query source system for new/changed records
  -> For-Each record batch:
     -> Invoke: Async child integration (one-way)
  -> Scheduler thread freed for next iteration
# Key: Parent calls ONE-WAY async child

Verify: Monitoring > Integrations > Check scheduled runs and child execution counts

Code Examples

Python: Trigger an OIC integration via REST

# Input:  OIC REST endpoint URL, OAuth credentials
# Output: Integration execution response

import requests

# Step 1: Get OAuth token from OCI IAM
token_url = "https://idcs-<tenant>.identity.oraclecloud.com/oauth2/v1/token"
token_resp = requests.post(
    token_url,
    data={
        "grant_type": "client_credentials",
        "scope": "urn:opc:resource:consumer::all"
    },
    auth=("<client-id>", "<client-secret>")
)
access_token = token_resp.json()["access_token"]

# Step 2: Invoke the integration
oic_url = "https://<oic-host>/ic/api/integration/v1/flows/rest/ORDER_SYNC/1.0/orders"
response = requests.post(
    oic_url,
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    },
    json={"orderNumber": "ORD-001", "amount": 1500.00}
)
print(response.status_code, response.json())

cURL: Check OIC instance health and message usage

# Input:  OIC host, OAuth token
# Output: Instance status and message consumption

# Check integration monitoring
curl -X GET \
  "https://<oic-host>/ic/api/integration/v1/monitoring/integrations" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"

# Check failed integration instances (last 24 hours)
curl -X GET \
  "https://<oic-host>/ic/api/integration/v1/monitoring/instances?status=FAILED&limit=10" \
  -H "Authorization: Bearer <access-token>"

Data Mapping

OIC Mapping Capabilities

Data Type Gotchas

• OIC uses XSLT 1.0 for transformations — date functions are limited compared to XSLT 2.0; complex date parsing requires custom templates or pre-processing. [src1]
• Oracle ERP Cloud business events deliver timestamps in UTC, but OIC scheduled integrations run in the instance timezone — always convert explicitly.
• Large payload mapping (>10MB) can cause memory issues — stage large files to File Server and process in chunks. [src5]
• Multi-value (repeating) elements require explicit for-each mapping — nested repeating groups need manual configuration.

Error Handling & Failure Points

Common Error Patterns

Failure Points in Production

• Message pack exhaustion: Large payloads silently consume multiple message units (270KB = 6 messages). Fix: Calculate effective messages as ceiling(payload_size_KB / 50) before capacity planning. [src3, src4]
• Connectivity agent token expiry: Modifying the default 3,600s token expiry causes in-flight request failures. Fix: Never modify the default OAuth token expiry for the connectivity agent. [src1]
• Scheduler thread starvation: Synchronous child invocations block the parent scheduler thread. Fix: Always call child integrations as one-way asynchronous. [src5]
• Gen 3 migration breakage: Integrations using Basic Routing or File Transfer types fail after Gen 3 upgrade. Fix: Migrate to App-Driven or Scheduled Orchestration before upgrade. [src2]
• Delayed response removal: ERP Cloud, HCM Cloud, Salesforce, ServiceNow adapters lose async response capability. Fix: Create separate invoke connections for success and failure callbacks. [src2]
• REST endpoint identifier encoding change: Gen 2 encoded pipe (%7C); Gen 3 uses literal pipe (|). Fix: Update external systems that construct OIC REST endpoint URLs. [src2]

Anti-Patterns

Wrong: Synchronous child invocation from scheduler

// BAD — blocks scheduler thread for each record
Scheduler (Parent)
  -> For-Each record:
     -> Invoke SYNCHRONOUS child integration
     -> Wait for child response
// Result: scheduler thread blocked, overlap risk

Correct: Asynchronous one-way child invocation

// GOOD — scheduler dispatches and moves on
Scheduler (Parent)
  -> For-Each record:
     -> Invoke ASYNC (one-way) child integration
  -> Parent completes quickly
// Child processes independently

Wrong: Single monolithic integration for complex flows

// BAD — one massive integration handles everything
Integration: "Full Order Process"
  -> Validate -> Check inventory -> Create customer
  -> Create order -> Ship -> Notify
// Any failure restarts entire flow

Correct: Decompose into idempotent microflows

// GOOD — each step is separate, idempotent
Integration 1: "Validate Order" -> publishes event
Integration 2: "Check Inventory" -> subscribes, publishes
Integration 3: "Create Customer" -> idempotent upsert
// Individual retry, easier debugging

Wrong: Ignoring message sizing in capacity planning

// BAD — counting transactions, not messages
Requirement: 10,000 orders/hour, avg payload 150KB
Plan: 2 message packs (10,000 msgs)
// Reality: ceiling(150/50) = 3 msgs per order
// Actual: 30,000 msgs/hr = 6 packs needed

Correct: Calculate effective message count from payload size

// GOOD — factor in payload sizing
Messages per order = ceiling(150KB / 50KB) = 3
Effective msgs/hr = 10,000 x 3 = 30,000
Packs needed = ceiling(30,000 / 5,000) = 6

Common Pitfalls

• Edition mismatch: Purchasing Standard then discovering on-premises connectivity requires Enterprise. Fix: Audit all source/target systems before purchasing. [src3]
• Message pack under-sizing: Planning based on transaction count, not payload-adjusted message count. Fix: Calculate: ceiling(payload_KB / 50) x transaction_count. [src3, src4]
• Gen 3 upgrade unpreparedness: Not migrating Basic Routing and File Transfer integrations before upgrade. Fix: Inventory all integrations by type; convert before upgrade window. [src2]
• Connectivity agent JDK version: Running on JDK 8 or 11 (deprecated) causes startup failures. Fix: Install JDK 17 on all agent hosts before Gen 3 upgrade. [src2]
• Hardcoded REST identifiers: External systems break after Gen 3 due to pipe encoding change. Fix: URL-decode or handle both %7C and | in external callers. [src2]
• Scheduler overlap: Integrations running longer than their interval cause overlapping executions. Fix: Use async child pattern or increase interval. [src5]
• IDCS token modification: Changing the default OAuth token expiry for the connectivity agent. Fix: Leave default value unchanged — agent handles renewal automatically. [src1]

Diagnostic Commands

# Check OIC instance status via OCI CLI
oci integration integration-instance get \
  --integration-instance-id <instance-ocid> \
  --query 'data.{"Status":status,"Shape":"instance-shape","Message Packs":"message-packs"}'

# List all integrations and their status
curl -s -X GET \
  "https://<oic-host>/ic/api/integration/v1/integrations?limit=100" \
  -H "Authorization: Bearer <token>" | jq '.items[] | {name, status, version}'

# Check failed integration instances
curl -s -X GET \
  "https://<oic-host>/ic/api/integration/v1/monitoring/instances?status=FAILED&limit=10" \
  -H "Authorization: Bearer <token>"

# Check connectivity agent health
curl -s -X GET \
  "https://<oic-host>/ic/api/integration/v1/agents" \
  -H "Authorization: Bearer <token>" | jq '.items[] | {name, status, lastHeartbeat}'

# Monitor message consumption (OCI Monitoring)
oci monitoring metric-data summarize-metrics-data \
  --compartment-id <compartment-ocid> \
  --namespace oracle_oci_integration \
  --query-text 'MessageCount[1h].sum()'

Version History & Compatibility

Deprecation Policy

Oracle Integration follows a continuous release model with updates every 2-4 weeks. Gen 2 to Gen 3 upgrades are mandatory and Oracle-managed. Features removed in Gen 3 have documented workarounds but will not be restored. [src2]

When to Use / When Not to Use

Cross-System Comparison

Important Caveats

• Standard vs Enterprise Edition differences are significant — on-premises connectivity, process automation, and B2B all require Enterprise. Verify requirements before purchasing. [src3]
• Message pack pricing makes OIC cost-sensitive to payload size — a "simple" integration with large payloads can consume 5-10x more message units than transaction count suggests. Always calculate with ceiling(payload_KB / 50). [src3, src4]
• Gen 3 upgrade is mandatory and Oracle-managed — prepare by migrating incompatible integration types and updating JDK to 17 on connectivity agent hosts. [src2]
• OIC release cadence is every 2-4 weeks — features can change without traditional "major version" announcements. Subscribe to Oracle Integration blog for breaking changes.
• Process Automation is now a separate product from Oracle Integration 3 — pricing and provisioning are independent.
• All pricing figures are approximate and region-dependent. Oracle pricing varies by contract type. Always request a formal quote for production planning. [src3]