---
# === IDENTITY ===
id: business/erp-integration/oracle-oic-deep-dive/2026
canonical_question: "What are Oracle Integration Cloud (OIC) capabilities - adapters, connections, error handling, pricing model?"
aliases:
  - "Oracle Integration Cloud OIC features and pricing"
  - "OIC Gen 3 adapters and message pack pricing"
  - "Oracle Integration Cloud capabilities and rate limits"
  - "OIC error handling and connectivity agent setup"
entity_type: erp_integration
domain: business > erp-integration > oracle-oic-deep-dive
region: global
jurisdiction: global
temporal_scope: 2024-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Oracle Integration Cloud (OIC)"
    vendor: "Oracle"
    version: "Gen 3 (25.x)"
    edition: "Standard, Enterprise"
    deployment: "cloud"
    api_surface: "REST, SOAP, Adapters, File Server"

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

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: volatile
  last_breaking_change: "Gen 3 migration (2024) — removed Basic Routing, File Transfer integration types; OAuth required for REST APIs"
  next_review: 2026-09-05
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "Standard Edition: no on-premises adapters, no process automation — Enterprise required"
  - "Message pack: 5,000 messages/hour (cloud license) or 20,000 messages/hour (BYOL) — 50KB payload = 1 message unit"
  - "Active integration limit: 800 integrations (raised from 700 in Gen 2)"
  - "Gen 3: only App-Driven and Scheduled integration types — Basic Routing and File Transfer removed"
  - "Connectivity agent requires JDK 17 only (JDK 8 and 11 deprecated in Gen 3)"
  - "Gen 3: basic authentication for Oracle-provided REST APIs no longer supported — must use OAuth"
  - "Parallel action limited to 5 branches maximum per integration flow"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "Need SAP-specific integration patterns"
    use_instead: "business/erp-integration/sap-integration-suite-capabilities/2026"
  - condition: "Need MuleSoft or third-party iPaaS comparison"
    use_instead: "business/erp-integration/ipaas-platform-comparison/2026"
  - condition: "Need Oracle ERP Cloud REST/SOAP API specifics (not OIC)"
    use_instead: "business/erp-integration/oracle-erp-cloud-rest-api-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 target system via OIC)"
      - "outbound (reading from source system via OIC)"
      - "bidirectional sync"

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/business/erp-integration/oracle-oic-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, rate limits"
  alternative_to:
    - id: "business/erp-integration/sap-integration-suite-capabilities/2026"
      label: "SAP Integration Suite (Cloud Integration) capabilities — message counting, adapters, licensing, BTPEA model"
  often_confused_with:
    - 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, rate limits"

# === SOURCES (6 authoritative sources) ===
sources:
  - id: src1
    title: "Oracle Integration 3 — Official Documentation"
    author: Oracle
    url: https://docs.oracle.com/en-us/iaas/application-integration/doc/overview.html
    type: official_docs
    published: 2025-12-01
    reliability: authoritative
  - id: src2
    title: "Differences from Prior Versions of Oracle Integration"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/paas/application-integration/whats-new/differences-prior-versions-oracle-integration.html
    type: vendor_release_notes
    published: 2025-06-01
    reliability: authoritative
  - id: src3
    title: "Oracle Integration Cloud Pricing Explained — OCI vs Classic"
    author: AMIS Technology Blog
    url: https://technology.amis.nl/oracle-cloud/oracle-integration-cloud-pricing-explained-oci-vs-classic/
    type: technical_blog
    published: 2024-09-15
    reliability: moderate_high
  - id: src4
    title: "Oracle Integration Message Packs and Pricing"
    author: Oracle SOA Community
    url: https://blogs.oracle.com/soacommunity/post/oracle-integration-message-packs-and-pricing-by-ankur-jain
    type: community_resource
    published: 2024-06-01
    reliability: moderate_high
  - id: src5
    title: "Advanced Error Handling and Scheduling Best Practices — Oracle Integration Cloud"
    author: Oracle A-Team
    url: https://www.ateam-oracle.com/advanced-error-handling-and-scheduling-best-practices-oracle-integration-cloud
    type: technical_blog
    published: 2024-03-01
    reliability: high
  - id: src6
    title: "Oracle Integration Cloud (OIC) and MCP Protocol"
    author: RedThunder Blog
    url: https://redthunder.blog/2026/01/23/oracle-integration-cloud-oic-and-mcp-protocol-benefits-and-feasibility-in-erp-crm-epm-and-hcm-scenarios/
    type: technical_blog
    published: 2026-01-23
    reliability: moderate_high
---

# 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. [src3]
- **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 all 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. The card does NOT cover Oracle SOA Cloud Service (a different product for BPEL/Mediator workloads) or Oracle API Gateway (separate API management product). [src3]

| Property | Value |
|---|---|
| **Vendor** | Oracle |
| **System** | Oracle Integration Cloud (OIC) Gen 3 |
| **API Surface** | REST, SOAP, Adapters (80+), File Server, B2B |
| **Current Version** | 25.x (continuous release) |
| **Editions Covered** | Standard, Enterprise |
| **Deployment** | Cloud (OCI) |
| **API Docs URL** | [Oracle Integration 3 Documentation](https://docs.oracle.com/en-us/iaas/application-integration/index.html) |
| **Status** | GA (Gen 3 mandatory; Gen 2 end-of-support) |

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

| Capability | Protocol | Best For | Concurrency | Edition | Real-time? | Bulk? |
|---|---|---|---|---|---|---|
| Application adapters (Oracle SaaS) | REST/SOAP | Oracle Fusion ERP, HCM, SCM, CX | Per message pack | Standard+ | Yes | Via scheduled |
| Technology adapters | REST/SOAP/FTP/JMS/Kafka | Database, file, messaging connectivity | Per message pack | Standard+ | Yes | Yes |
| On-premises adapters | Via connectivity agent | On-prem databases, EBS, JDE, PeopleSoft | Agent-limited | Enterprise only | Yes | Yes |
| B2B adapter | EDI/AS2 | Trading partner document exchange | Per message pack | Enterprise only | Yes | Yes |
| File Server | SFTP | Staged file processing, large payloads | Embedded | Standard+ | No | Yes |
| Process Automation | BPMN 2.0 | Human workflows, approvals, decisions | Separate product | Enterprise only | Yes | No |
| Visual Builder | REST/UI | Low-code application development | Separate metering | Enterprise only | Yes | No |
| RPA | UI automation | Systems without APIs | Robot-based | Enterprise only | No | No |

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

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| Messages per pack per hour (Cloud License) | 5,000 | Standard cloud license | Each 50KB in+out = 1 message |
| Messages per pack per hour (BYOL) | 20,000 | Bring Your Own License | Requires existing Oracle Fusion Middleware license |
| Messages per pack per month (SaaS) | 1,000,000 | Oracle Integration for SaaS | Monthly aggregate, not hourly |
| Max message packs (Cloud License) | 12 | Per instance | 12 x 5,000 = 60,000 msgs/hr max |
| Max message packs (BYOL) | 3 | Per instance | 3 x 20,000 = 60,000 msgs/hr max |
| Grace threshold | 1.3x | Hourly average over 24h | Exceeding 1.3x hourly average triggers billing for additional pack |
| Message size unit | 50 KB | Per message | 270KB payload = 6 messages (rounded up) |
| Minimum charge | 1 message pack/hour | Always | Even with zero usage, 1 pack/hr minimum |

[src3, src4]

### Platform Limits

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| Active integrations | 800 | Per instance | Raised from 700 in Gen 2 |
| Parallel branches | 5 | Per parallel action | New in Gen 3 |
| Connectivity agent instances | Multiple | Enterprise Edition | For on-premises connectivity |
| Scheduled integration minimum interval | 1 minute | Scheduled integrations | Frequency depends on pattern |
| Design-time concurrent users | Not formally limited | Per instance | Performance may degrade with many concurrent editors |

[src1, src2]

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

| Flow | Use When | Token Lifetime | Refresh? | Notes |
|---|---|---|---|---|
| OAuth 2.0 Client Credentials | Server-to-server integration invocation | 3,600s (1 hour) default | Yes | Recommended for automation; uses IDCS/OCI IAM confidential app |
| OAuth 2.0 Authorization Code | User-context operations, Visual Builder | Session-based | Yes | Requires callback URL configuration |
| OAuth 2.0 Resource Owner | Legacy migration only | Session-based | No | Not recommended for new development |
| OCI IAM API Key | OCI API calls (instance management) | Per-request signature | N/A | For managing OIC instances via OCI APIs |
| Connectivity Agent Token | Agent-to-OIC communication | 3,600s auto-renewed | Yes (automatic) | Do not modify default token expiry |

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

- 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. Existing integrations of removed types must be migrated before upgrade. [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) — workaround requires separate invoke connections for success and failure callbacks. [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 below
|   |   |   +-- NO (on-premises systems involved) -> 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 (prebuilt)
|   |   |   +-- NO -> App-Driven Orchestration with REST/SOAP trigger + target adapter
|   |   +-- Need human approval step?
|   |       |-- YES -> OCI Process Automation (separate product, Enterprise)
|   |       +-- NO -> Standard App-Driven Orchestration
|   |
|   |-- Batch/Scheduled (periodic, high volume)
|   |   |-- Data volume < 5,000 records/hour?
|   |   |   |-- YES -> Single scheduled integration (within 1 message pack)
|   |   |   +-- NO -> Scheduled + file-based staging via File Server
|   |   +-- Need file processing (CSV/XML)?
|   |       |-- YES -> Scheduled integration + File Adapter + Stage File action
|   |       +-- NO -> Scheduled integration + adapter direct calls
|   |
|   |-- Event-driven (Oracle Business Events, webhooks)
|   |   |-- Source is Oracle SaaS (ERP/HCM/SCM)?
|   |   |   |-- YES -> Oracle SaaS adapter with Business Event subscription
|   |   |   +-- NO -> REST adapter webhook trigger or Kafka adapter
|   |   +-- Need guaranteed delivery?
|   |       |-- YES -> Implement parking lot pattern with ATP database
|   |       +-- NO -> Fire-and-forget with error notification
|   |
|   +-- File-based (FBDI, large file transfer)
|       +-- Use File Server (embedded SFTP) + Scheduled integration + Stage File
|
|-- On-premises systems involved?
|   |-- YES -> Deploy connectivity agent (Enterprise, JDK 17 required)
|   +-- NO -> Direct cloud-to-cloud adapter connectivity
|
+-- Error tolerance?
    |-- Zero-loss required -> Parking lot pattern + ATP DB + resubmit flow
    +-- Best-effort -> Scope-based fault handling + email notification
```

## Quick Reference

### Adapter Categories

| Category | Examples | Count | Edition |
|---|---|---|---|
| Oracle SaaS | ERP Cloud, HCM Cloud, SCM Cloud, CX Sales, NetSuite | 20+ | Standard+ |
| Database | Oracle DB, MySQL, SQL Server, PostgreSQL | 5+ | Standard+ |
| Technology | REST, SOAP, FTP, File, JMS, Kafka, AS2 | 15+ | Standard+ |
| Third-Party SaaS | Salesforce, ServiceNow, Workday, SAP, Shopify | 20+ | Standard+ |
| On-Premises | E-Business Suite, JD Edwards, PeopleSoft, Siebel | 10+ | Enterprise |
| AI/ML | OCI AI Services, OpenAI, Anthropic LLMs | 3+ | Standard+ |
| Healthcare | FHIR, HL7 | 2 | Standard+ |
| Messaging | Oracle AQ, RabbitMQ, Azure Service Bus | 5+ | Standard+ |

### Pricing Quick Reference

| Edition | Pay-as-You-Go | Annual Commit | BYOL Discount |
|---|---|---|---|
| Standard | ~$808/month per pack | ~$539/month per pack | ~60% off |
| Enterprise | ~$1,617/month per pack | ~$1,078/month per pack | ~60% off |

[src3]

## 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. Configure the instance shape (determines update window). [src1]

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

```bash
# 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 connection (source adapter) and invoke connection (target adapter). [src1]

```
# Integration flow structure (pseudocode)
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, on-prem)

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]

```bash
# Download agent installer from OIC Console > Settings > Agents
# 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 to the Scope for structured error processing. Use the parking lot pattern for guaranteed delivery. [src5]

```
# Error handling pattern (OIC flow structure)
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 and parking lot record

### 6. Configure scheduling for batch integrations

Use Scheduled Orchestration for recurring batch operations. Set frequency (minutes, hours, days) and configure the scheduler to call asynchronous child integrations for parallel processing. [src5]

```
# Scheduling best practice (OIC flow structure)
Scheduler (Parent): Runs every 15 minutes
  -> Query source system for new/changed records
  -> For-Each record batch:
     -> Invoke: Async child integration (one-way, fire-and-forget)
     -> [Child processes records independently]
  -> Scheduler thread freed for next iteration

# Key: Parent calls ONE-WAY async child.
# Child does NOT return response to parent.
# This prevents scheduler thread blocking.
```

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

## Code Examples

### Python: Trigger an OIC integration via REST

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

```bash
# 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 specific integration run status
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

| Feature | Gen 2 | Gen 3 | Notes |
|---|---|---|---|
| Visual mapper | Yes | Enhanced Redwood UI | Drag-and-drop field mapping |
| XSLT functions | Standard set | Expanded built-in set | More string, date, math functions |
| Import mappings | No | Yes | Reuse mappings across integrations |
| Lookups | Domain Value Map (DVM) | Domain Value Map (DVM) | Key/value reference tables |
| Custom functions | XSLT templates | XSLT templates + JavaScript | JavaScript added in Gen 3 |
| Conditional mapping | If-then in XSLT | If-then + Switch | Improved conditional logic |

### 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 when comparing timestamps across sources.
- Large payload mapping (>10MB) can cause memory issues in the mapper — stage large files to File Server and process in chunks rather than mapping inline. [src5]
- Multi-value (repeating) elements require explicit for-each mapping — the visual mapper may auto-create this, but nested repeating groups need manual configuration.

## Error Handling & Failure Points

### Common Error Patterns

| Error | Meaning | Cause | Resolution |
|---|---|---|---|
| ORA-00001 | Unique constraint violation | Duplicate record in target | Implement idempotency check before insert; use upsert pattern |
| CASDK-0004 | Connection timeout | Target system unreachable or slow | Increase timeout in connection properties; check connectivity agent health |
| IC-INVOKE-0015 | Rate/throttle limit exceeded | Too many messages in window | Implement backoff; reduce scheduled frequency; add message pack |
| IC-SCHEDULE-0001 | Scheduled integration overlap | Previous run not finished when next starts | Increase interval or convert to async child pattern |
| OIC-AUTH-0001 | Authentication failure | Expired token or misconfigured OAuth | Verify IDCS/OCI IAM confidential app; check scope configuration |
| CASDK-0007 | Payload too large | Response exceeds adapter limits | Paginate or stage to File Server; reduce batch size |

[src1, src5]

### 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; monitor message consumption in OCI Console`. [src3, src4]
- **Connectivity agent token expiry**: Modifying the default 3,600s token expiry in IDCS causes in-flight requests to fail when the agent cannot auto-renew. Fix: `Never modify the default OAuth token expiry for the connectivity agent application in IDCS/OCI IAM`. [src1]
- **Scheduler thread starvation**: Synchronous child invocations block the parent scheduler thread, preventing it from processing remaining batch items. Fix: `Always call child integrations as one-way asynchronous (async) — the child should not return a response to the parent`. [src5]
- **Gen 3 migration breakage**: Integrations using Basic Routing or File Transfer types fail after Gen 3 upgrade since these types were removed. Fix: `Migrate all Basic Routing integrations to App-Driven Orchestration and File Transfer integrations to Scheduled Orchestration before upgrade`. [src2]
- **Delayed response removal**: Adapters that relied on async response (ERP Cloud, HCM Cloud, Salesforce, ServiceNow) lose that capability in Gen 3. Fix: `Create separate invoke connections — one for success callbacks, one for failure callbacks in fault handler`. [src2]
- **REST endpoint identifier encoding change**: Gen 2 encoded pipe characters (%7C) in integration identifiers; Gen 3 uses literal pipe (|). Fix: `Update any external system that constructs OIC REST endpoint URLs to handle literal pipe characters`. [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
     -> Process next record
// Result: scheduler thread blocked, remaining records delayed,
// risk of overlap with next scheduled run
```

### Correct: Asynchronous one-way child invocation

```
// GOOD — scheduler dispatches and moves on
Scheduler (Parent)
  -> For-Each record:
     -> Invoke ASYNC (one-way) child integration
     -> Scheduler thread immediately freed
  -> Parent completes quickly
// Child processes independently, errors go to parking lot
```

### Wrong: Single monolithic integration for complex flows

```
// BAD — one massive integration handles everything
Integration: "Full Order Process"
  -> Validate order
  -> Check inventory (ERP)
  -> Create customer (CRM)
  -> Create sales order (ERP)
  -> Create shipment (WMS)
  -> Send notification (email)
// Result: any failure restarts entire flow,
// debugging is difficult, resubmission reprocesses everything
```

### Correct: Decompose into idempotent microflows

```
// GOOD — each step is a separate, idempotent integration
Integration 1: "Validate Order" -> publishes event
Integration 2: "Check Inventory" -> subscribes, publishes result
Integration 3: "Create Customer" -> idempotent upsert
Integration 4: "Create Sales Order" -> checks for existing
Integration 5: "Create Shipment" -> independent
// Result: individual retry, easier debugging,
// parking lot per step, no cascading failures
```

### Wrong: Ignoring message sizing in capacity planning

```
// BAD — counting transactions, not messages
Requirement: 10,000 orders/hour
Plan: 1 message pack (5,000 msgs/hr) x 2 = 2 packs
// Reality: average order payload = 150KB
// Effective messages per order = ceiling(150/50) = 3
// Actual need: 10,000 x 3 = 30,000 msgs/hr = 6 packs
```

### Correct: Calculate effective message count from payload size

```
// GOOD — factor in payload sizing
Requirement: 10,000 orders/hour
Average payload: 150KB
Messages per transaction: ceiling(150KB / 50KB) = 3
Effective messages/hr: 10,000 x 3 = 30,000
Message packs needed: ceiling(30,000 / 5,000) = 6 packs
// Also account for 1.3x grace threshold for burst headroom
```

## Common Pitfalls

- **Edition mismatch**: Purchasing Standard Edition then discovering on-premises connectivity requires Enterprise Edition. Fix: `Audit all source/target systems before purchasing — any on-premises system requires Enterprise Edition with connectivity agent`. [src3]
- **Message pack under-sizing**: Planning based on transaction count, not payload-adjusted message count. Fix: `Always calculate effective messages: ceiling(payload_KB / 50) x transaction_count. Include response payloads, not just requests`. [src3, src4]
- **Gen 3 upgrade unpreparedness**: Not migrating Basic Routing and File Transfer integrations before Oracle-managed Gen 3 upgrade. Fix: `Inventory all integrations by type; convert Basic Routing to App-Driven and File Transfer to Scheduled before upgrade window`. [src2]
- **Connectivity agent JDK version**: Running connectivity agent on JDK 8 or 11 (deprecated in Gen 3) causes startup failures. Fix: `Install JDK 17 on all connectivity agent hosts before Gen 3 upgrade`. [src2]
- **Hardcoded REST identifiers**: External systems constructing OIC integration URLs break after Gen 3 due to pipe encoding change (%7C vs |). Fix: `URL-decode or handle both formats in external callers; test all external integrations post-upgrade`. [src2]
- **Scheduler overlap**: Scheduled integrations that run longer than their interval cause overlapping executions. Fix: `Use async child pattern so parent completes quickly; alternatively, increase interval or add locking via ATP flag table`. [src5]
- **IDCS token modification**: Changing the default OAuth token expiry (3600s) for the connectivity agent IDCS application. Fix: `Leave the default value unchanged — the agent handles token renewal automatically`. [src1]

## Diagnostic Commands

```bash
# 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 (last 24 hours)
curl -s -X GET \
  "https://<oic-host>/ic/api/integration/v1/monitoring/instances?status=FAILED&timewindow=24h" \
  -H "Authorization: Bearer <token>" | jq '.items[] | {id, integrationName, startTime, errorMsg}'

# 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 (via OCI Monitoring)
oci monitoring metric-data summarize-metrics-data \
  --compartment-id <compartment-ocid> \
  --namespace oracle_oci_integration \
  --query-text 'MessageCount[1h].sum()' \
  --start-time <start-iso> --end-time <end-iso>
```

## Version History & Compatibility

| Version | Release | Status | Key Changes | Migration Notes |
|---|---|---|---|---|
| Gen 3 (25.x) | 2024-2025 | Current | Redwood UI, Projects, parallel execution, RBAC, Rapid Adapter Builder, AI/MCP support | Mandatory upgrade from Gen 2; Oracle-managed, <10 min downtime |
| Gen 3 (24.x) | 2024 | Current | Initial Gen 3 release, microservices architecture, OCI-native | Removed Basic Routing, File Transfer; OAuth required |
| Gen 2 | 2019-2024 | EOL | Full feature set, 700 active integrations, Basic Routing supported | Upgrade path to Gen 3 is automatic |
| Classic (ICS) | 2016-2019 | EOL | Original iPaaS offering | Must upgrade to Gen 2 first, then Gen 3 |

[src1, src2]

### Deprecation Policy

Oracle Integration follows a continuous release model with updates approximately every 2-4 weeks. Gen 2 to Gen 3 upgrades are mandatory and Oracle-managed — customers cannot remain on Gen 2. Features removed in Gen 3 (Basic Routing, File Transfer, delayed response) have documented workarounds but will not be restored. API versioning is release-based, not numbered — always test after each update window. [src2]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Integrating Oracle SaaS products (ERP, HCM, SCM, CX) | Need API gateway with advanced rate limiting and developer portal | Oracle API Gateway or Apigee |
| Need low-code, visual integration designer for Oracle ecosystem | Complex transformation logic requiring custom Java/Python code | MuleSoft Anypoint or custom middleware |
| Want Oracle-managed iPaaS with prebuilt SaaS adapters | Primarily non-Oracle systems with no Oracle SaaS | Boomi, Workato, or MuleSoft |
| Batch file processing with embedded SFTP file server | Real-time streaming at sub-second latency (>100K events/sec) | Apache Kafka, Oracle Streaming, or Confluent |
| Oracle-to-Oracle integration with business events | Multi-cloud orchestration across AWS, Azure, GCP services | Workato or custom event-driven architecture |
| Need B2B/EDI trading partner connectivity (Enterprise) | Simple point-to-point API proxy with no transformation | Oracle API Gateway or direct REST calls |

## Cross-System Comparison

| Capability | Oracle OIC | MuleSoft Anypoint | Boomi | Workato |
|---|---|---|---|---|
| Pricing model | Message packs (5K msgs/hr/pack) | vCore-based | Connection + flow-based | Recipe + connection-based |
| Prebuilt adapters | 80+ | 400+ | 200+ | 1,000+ |
| Oracle SaaS depth | Native (deepest integration) | Good (certified adapters) | Good | Good |
| On-premises support | Connectivity agent (Enterprise) | Mule runtime (on-prem) | Atom (on-prem) | On-prem agent |
| Low-code designer | Visual flow designer | Anypoint Studio + Flow Designer | Visual, drag-and-drop | Recipe builder |
| Process automation | OCI Process Automation (separate) | Not included | Flow Services | Workflow bots |
| B2B/EDI | Built-in (Enterprise) | B2B add-on | B2B/EDI add-on | Limited |
| AI integration | OCI AI, OpenAI, Anthropic, MCP support | AI Chain | GPT connector | AI by Workato |
| API management | Separate (Oracle API Gateway) | Built-in (API Manager) | API Management add-on | API platform |
| File handling | Embedded SFTP file server | File connector | Disk connector | File connector |

## 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 — Oracle will upgrade your instance with <10 min downtime. 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 and release notes for breaking changes.
- Process Automation is now a separate product from Oracle Integration 3 — pricing and provisioning are independent. Do not assume OIC Enterprise includes unlimited process automation.
- All pricing figures are approximate and region-dependent. Oracle pricing varies by contract type (pay-as-you-go, annual commit, ULA). Always request a formal quote for production planning. [src3]

## Related Units

- [Oracle ERP Cloud API Capabilities](/business/erp-integration/oracle-erp-cloud-api-capabilities/2026)
- [Oracle ERP Data Sync Playbook](/business/erp-integration/oracle-erp-data-sync-playbook/2026)
- [SAP Integration Suite Deep Dive](/business/erp-integration/sap-integration-suite-deep-dive/2026)