Oracle Integration Cloud (OIC) Capabilities

TL;DR

• Bottom line: OIC is Oracle's cloud-native iPaaS that bundles application integration, process automation, Visual Builder, and 80+ prebuilt adapters into a single service -- Gen 3 (Kubernetes-native) is the current generation with Projects, parallel flow, RBAC, and AI agent capabilities. [src1]
• Key limit: Billing is per message pack (5K msgs/hr standard, 20K msgs/hr BYOL), billed every hour whether messages flow or not. Standard max 12 packs, BYOL max 3 packs, both cap at 60K msgs/hr. [src4, src5]
• Watch out for: Enterprise edition is required for on-premise adapters (E-Business Suite, JD Edwards, Siebel, SAP) and Process Automation -- Standard edition cannot connect to on-premise systems. [src4]
• Best for: Organizations already on Oracle Cloud SaaS (ERP, HCM, SCM, CX) needing native event-driven and scheduled integrations with prebuilt recipes and a visual designer. [src1]
• Authentication: Gen 3 uses OAuth 2.0 exclusively for all APIs -- basic auth (username/password) is no longer supported. Connectivity agent authentication also changed from basic auth to OAuth. [src7]

System Profile

Oracle Integration Cloud (OIC) is Oracle's fully managed integration platform as a service (iPaaS) running on Oracle Cloud Infrastructure (OCI). It consolidates four capabilities into one service: application integration (orchestration + adapters), process automation (human workflows + forms), Visual Builder (low-code web/mobile apps), and integration analytics. OIC Gen 3, the current generation released in 2024, runs on a Kubernetes-native architecture that provides per-flow scalability and improved performance over Gen 2. [src1]

This card covers the OIC platform itself -- its capabilities, editions, adapters, pricing model, and integration patterns. For specific Oracle ERP Cloud REST API endpoints and rate limits, see the Oracle ERP Cloud REST API card. For FBDI file-based imports, see the Oracle ERP Cloud FBDI Import card.

API Surfaces & Capabilities

OIC is not a single API -- it is an orchestration platform that connects systems through prebuilt adapters, visual flows, and multiple integration patterns. The "API surfaces" here are OIC's integration pattern types and the adapter categories it supports. [src1]

Adapter Categories

OIC provides 80+ prebuilt adapters across these categories: [src1, src6]

Rate Limits & Quotas

Per-Message Pack Limits

[src4, src5]

Concurrency Limits

[src1, src6]

Gen 3 Project Limits

[src3]

Message Counting Rules

• Trigger messages <= 50 KB count as 1 message. [src4]
• Trigger messages > 50 KB count as ceil(size / 50 KB) messages. [src4]
• Internal OIC-to-OIC calls (one integration calling another within the same instance) are NOT counted as billable messages. [src4]
• Response messages from external endpoints follow the same 50 KB sizing rules. [src4]
• Scheduled orchestrations that poll and process N records count the trigger as 1 message, not N. [src4]

Authentication

[src1, src7]

Authentication Gotchas

• Gen 3 broke all basic auth integrations: If migrating from Gen 2, every integration that used username/password must be re-configured for OAuth. The connectivity agent also changed its authentication method. [src7]
• IDCS vs OCI IAM confusion: Gen 3 can use either IDCS or OCI IAM for identity management. The integration URLs and token endpoints differ. Check which identity provider your tenancy uses before configuring. [src1]
• Service account tokens for connectivity agent: The on-premise connectivity agent in Gen 3 authenticates differently from Gen 2. Plan for agent re-installation, not just reconfiguration, during migration. [src7]

Constraints

• Enterprise edition required for on-premise adapters: E-Business Suite, JD Edwards, Siebel, and SAP BAPI/IDoc adapters require Enterprise edition. Standard edition cannot connect to any on-premise system. [src4]
• Message packs bill continuously: OIC charges per message pack per hour, regardless of traffic volume. An idle instance with 3 packs costs the same as one processing 15K messages/hour. [src4, src5]
• Gen 3 Project scope isolation: Project assets (connections, lookups, libraries) are NOT shared across projects. Cross-project invocation is not supported. Standalone integrations cannot be imported into projects. [src3]
• Gen 3 Project feature gaps: B2B trading partner mode, event-based integration patterns (Publish Event action), OCI Object Storage actions, and JavaScript library cloning are not yet supported in Gen 3 Projects. [src3]
• Connectivity agent limits: The on-premise connectivity agent supports a fixed number of concurrent connections and has different latency characteristics than cloud-to-cloud integrations. Test throughput before go-live. [src6]
• No Gen 2 activity data migration: Activity stream data (execution history, logs) from Gen 2 is NOT migrated to Gen 3. Historical audit trails are lost. Export via monitoring APIs before migration. [src7]
• Adapter availability varies by region: Not all OIC regions have the same adapter availability. Verify adapter support for your OCI region before provisioning. [src1]

Integration Pattern Decision Tree

START -- User needs to integrate using Oracle Integration Cloud
|-- What integration pattern?
|   |-- Real-time (individual records, <1s latency)
|   |   |-- Source is Oracle SaaS (ERP/HCM/SCM/CX)?
|   |   |   |-- YES --> App-Driven Orchestration with native adapter + business events
|   |   |   +-- NO --> App-Driven Orchestration with REST/SOAP adapter
|   |   +-- Need to react to changes in Oracle Cloud?
|   |       |-- YES --> Event Subscription (Business Events) for ERP/HCM/CX
|   |       +-- NO --> App-Driven Orchestration triggered by REST endpoint
|   |-- Batch/Bulk (scheduled, high volume)
|   |   |-- File-based data (CSV/XML)?
|   |   |   |-- YES --> Scheduled Orchestration + FTP adapter + File adapter
|   |   |   +-- NO --> Scheduled Orchestration + SaaS/DB adapter with pagination
|   |   +-- Need FBDI import to Oracle ERP Cloud?
|   |       |-- YES --> Scheduled Orchestration + ERP Cloud adapter (FBDI pattern)
|   |       +-- NO --> Scheduled Orchestration + target system adapter
|   |-- Event-driven (push notifications)
|   |   |-- Oracle SaaS source?
|   |   |   |-- YES --> Business Events subscription via native adapter
|   |   |   +-- NO --> REST webhook receiver via App-Driven Orchestration
|   |   +-- Multiple consumers need same event?
|   |       |-- YES --> Publish/Subscribe pattern (if supported in your project type)
|   |       +-- NO --> Direct Event Subscription
|   +-- File transfer (move files between systems)
|       +-- Use Scheduled File Transfer (FTP/SFTP) or File adapter
|-- Which edition do you need?
|   |-- On-premise targets (EBS, JDE, Siebel, SAP) --> Enterprise
|   |-- Process Automation (human workflows, forms) --> Enterprise
|   |-- SaaS-to-SaaS and technology only --> Standard
+-- How many message packs?
    |-- Calculate: peak messages per hour / 5,000 (standard) or / 20,000 (BYOL)
    |-- Add headroom: 20-30% buffer for burst traffic
    +-- Remember: billed per hour even when idle

Quick Reference

OIC Editions Comparison

[src4]

Gen 2 vs Gen 3 Comparison

[src1, src2, src7]

Step-by-Step Integration Guide

1. Provision an OIC Instance

Choose your edition (Standard vs Enterprise) based on whether you need on-premise adapters or Process Automation. Select message packs based on expected throughput. [src5]

# OCI CLI: Create OIC Gen 3 instance (Enterprise, 2 message packs)
oci integration integration-instance create \
  --compartment-id $COMPARTMENT_ID \
  --display-name "production-oic" \
  --integration-instance-type "ENTERPRISE" \
  --is-byol false \
  --message-packs 2 \
  --idcs-at $IDCS_ACCESS_TOKEN

Verify: Check instance status in OCI Console > Integration > Instances -- expected: ACTIVE

2. Configure Connections

Create connections for each system you need to integrate. OIC uses a connection-per-system model. [src1]

# REST API: List available adapters to verify your edition supports what you need
curl -X GET "https://<oic-host>/ic/api/integration/v1/adapters" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  -H "Accept: application/json"

Verify: Adapter list includes your target system adapter (e.g., oracle/erp-cloud, salesforce, sap)

3. Create an Integration Flow

Use the OIC Designer (visual, browser-based) to create an integration. Choose the pattern: App-Driven for real-time, Scheduled for batch. [src1]

# REST API: Export an integration for version control
curl -X GET "https://<oic-host>/ic/api/integration/v1/integrations/<integration-id>/archive" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  -o integration_export.iar

Verify: .iar file downloaded successfully (this is OIC's integration archive format)

4. Deploy and Activate

Deploy the integration to make it live. For Scheduled integrations, define the cron schedule. [src1]

# REST API: Activate an integration
curl -X POST "https://<oic-host>/ic/api/integration/v1/integrations/<integration-id>/activate" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "ACTIVATED"}'

Verify: Integration status = ACTIVATED in OIC console > Integrations

5. Monitor Message Consumption

Track your message pack usage to avoid overage and plan scaling. [src4]

# REST API: Check integration monitoring metrics
curl -X GET "https://<oic-host>/ic/api/integration/v1/monitoring/integrations" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  -H "Accept: application/json"

Verify: billableMessageCount in response matches expected volume

Code Examples

Python: Trigger an OIC REST Endpoint (App-Driven Integration)

# Input:  OIC endpoint URL, OAuth credentials, payload
# Output: Integration execution result

import requests

# Step 1: Get OAuth token from IDCS/OCI IAM
token_url = "https://<idcs-host>/oauth2/v1/token"
token_resp = requests.post(token_url, data={
    "grant_type": "client_credentials",
    "scope": "https://<oic-host>:443urn:opc:resource:consumer::all"
}, auth=("CLIENT_ID", "CLIENT_SECRET"))
access_token = token_resp.json()["access_token"]

# Step 2: Call the OIC integration endpoint
oic_url = "https://<oic-host>/ic/api/integration/v1/flows/rest/<INTEGRATION>/<VERSION>/<RESOURCE>"
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}
payload = {
    "customerName": "Acme Corp",
    "orderAmount": 15000.00,
    "currency": "USD"
}

response = requests.post(oic_url, json=payload, headers=headers)
print(f"Status: {response.status_code}")
print(f"Response: {response.json()}")

cURL: Test OIC Connectivity and Export Integration

# Input:  OIC host URL, OAuth bearer token
# Output: Integration list (JSON)

# List all integrations
curl -X GET "https://<oic-host>/ic/api/integration/v1/integrations" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  -H "Accept: application/json" | jq '.items[] | {name: .name, status: .status}'

# Check message pack usage (monitoring)
curl -X GET "https://<oic-host>/ic/api/integration/v1/monitoring/dashboards/MESSAGES" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  -H "Accept: application/json"

Data Mapping

OIC Adapter Data Type Mapping

Data Type Gotchas

• Oracle ERP Cloud business events deliver JSON with string-typed numbers: Always cast numeric fields explicitly in the OIC mapper rather than relying on implicit conversion. [src1]
• Lookup tables in OIC have a 100,000-row limit: For large reference data mappings, use a database adapter lookup instead of OIC's built-in lookup feature. [src6]
• XSLT mapper vs JavaScript mapper: The XSLT mapper is the default and handles most transformations. JavaScript libraries (Gen 3 Projects) are better for complex conditional logic but add to project asset count. [src3]

Error Handling & Failure Points

Common Error Codes

[src1, src6]

Failure Points in Production

• Idle instance billing surprise: OIC bills per message pack per hour, even when no messages flow. A 3-pack Enterprise instance costs the same running idle on weekends as during peak Monday processing. Fix: Use OCI resource scheduler to stop/start instances during off-hours, or right-size packs. [src4, src5]
• Gen 2 to Gen 3 migration breaks authentication: All basic auth integrations fail immediately after Gen 3 upgrade. The connectivity agent also requires re-installation with OAuth. Fix: Inventory all connections using basic auth before migration; pre-configure OAuth credentials in parallel environment. [src7]
• Project asset limit exhaustion: Hitting 100 integrations or 20 connections per project silently blocks new deployments. Fix: Monitor project usage via OIC console; plan multi-project architecture for large implementations (>50 integrations). [src3]
• Scheduled integration clock drift: Scheduled orchestrations may not fire at exact specified times under heavy load. Fix: Design idempotent integrations that handle duplicate runs; use watermark timestamps instead of "run since last execution" patterns. [src1]
• File Server connection pool exhaustion: 50-connection limit per instance can bottleneck parallel file transfers. Fix: Serialize file operations; implement connection pooling with retry; consider separate FTP endpoints per integration. [src6]

Anti-Patterns

Wrong: Using a separate message pack per integration for isolation

// BAD -- provisioning multiple OIC instances for "isolation"
// Instance 1 (1 pack): Salesforce integrations
// Instance 2 (1 pack): SAP integrations
// Instance 3 (1 pack): HCM integrations
// Result: 3x billing cost, no shared connections, maintenance nightmare

Correct: Use Projects for isolation within a single instance

// GOOD -- single OIC instance with Gen 3 Projects for logical separation
// Project 1: Salesforce integrations (RBAC: Salesforce team)
// Project 2: SAP integrations (RBAC: SAP team)
// Project 3: HCM integrations (RBAC: HR IT team)
// Result: shared message packs, lower cost, centralized monitoring

Wrong: Polling Oracle ERP Cloud for changes on a tight schedule

// BAD -- polling every 5 minutes for new invoices
// Uses up message pack allocation on empty polls
// Scheduled Orchestration: "Get invoices where lastUpdateDate > lastRunTime"
// If 280 runs/day return 0 results, you've burned 280+ messages for nothing

Correct: Use Business Events subscription for change detection

// GOOD -- subscribe to Oracle ERP Cloud business events
// Zero messages consumed when no changes occur
// Event Subscription: "oracle.apps.financials.payables.invoices.invoiceCreated"
// Messages only consumed when actual invoices are created

Wrong: Hardcoding connection details in integration flows

<!-- BAD -- endpoint URL embedded in XSLT or integration logic -->
<assign>
  <copy>
    <from>"https://production-erp.oracle.com/fscmRestApi/resources/v1/invoices"</from>
    <to>$endpoint</to>
  </copy>
</assign>

Correct: Use OIC Connection properties and environment-specific configurations

// GOOD -- use OIC connection abstraction
// Connection "Oracle_ERP_Production" -> endpoint configured in connection, not flow
// Same integration .iar file deploys to dev/test/prod by swapping connections
// Use Lookups or configuration integrations for environment-specific values

Common Pitfalls

• Standard vs Enterprise edition mismatch: Purchasing Standard edition then discovering you need on-premise adapters (E-Business Suite, SAP) is a costly upgrade. Fix: Audit all target systems before provisioning -- if any are on-premise, you need Enterprise. [src4]
• Message pack over-provisioning: Buying 6+ message packs "just in case" when actual throughput is 2K msgs/hr wastes budget. Fix: Start with 1-2 packs, monitor actual consumption for 30 days, then right-size. OIC allows pack count changes without re-provisioning. [src4, src5]
• Not planning for Gen 3 Project limitations: Designing a monolithic integration architecture within a single project hits the 100-integration limit. Fix: Plan a multi-project architecture early. Group by business domain (Finance, HR, Supply Chain) with max 50-70 integrations per project to leave headroom. [src3]
• Ignoring Gen 2 EOL timeline: Gen 2 instances will eventually be deprecated. Fix: Start Gen 3 migration planning now. Export all integration .iar files, document all connections and their auth methods, and test in a Gen 3 sandbox. [src7]
• Treating OIC as a real-time ESB: OIC is an iPaaS optimized for cloud-to-cloud integration, not a high-frequency event bus. Sub-second latency at scale requires dedicated messaging (Kafka, Oracle Streaming). Fix: Use OIC for orchestration and transformation; use Oracle Streaming or Kafka for high-throughput event streaming. [src1]
• Skipping connectivity agent performance testing: The on-premise connectivity agent adds latency (20-100ms per hop). At high volumes, this compounds. Fix: Load-test with production-equivalent data volumes through the connectivity agent before go-live. [src6]

Diagnostic Commands

# Check OIC instance status and configuration
curl -X GET "https://<oic-host>/ic/api/integration/v1/monitoring/health" \
  -H "Authorization: Bearer $OAUTH_TOKEN"

# List all active integrations and their status
curl -X GET "https://<oic-host>/ic/api/integration/v1/integrations?status=ACTIVATED" \
  -H "Authorization: Bearer $OAUTH_TOKEN" | jq '.items | length'

# Check message pack consumption (current billing period)
curl -X GET "https://<oic-host>/ic/api/integration/v1/monitoring/dashboards/MESSAGES" \
  -H "Authorization: Bearer $OAUTH_TOKEN"

# Monitor failed integration instances (last 24h)
curl -X GET "https://<oic-host>/ic/api/integration/v1/monitoring/integrations?status=FAILED&timeWindow=LAST_24_HOURS" \
  -H "Authorization: Bearer $OAUTH_TOKEN"

# Verify connectivity agent status (for on-premise integrations)
curl -X GET "https://<oic-host>/ic/api/integration/v1/agents" \
  -H "Authorization: Bearer $OAUTH_TOKEN" | jq '.items[] | {name: .name, status: .agentStatus}'

# Export integration for backup/version control
curl -X GET "https://<oic-host>/ic/api/integration/v1/integrations/<INTEGRATION_ID>|<VERSION>/archive" \
  -H "Authorization: Bearer $OAUTH_TOKEN" -o backup.iar

Version History & Compatibility

[src1, src2, src7]

Deprecation Policy

Oracle Integration follows Oracle's standard cloud service lifecycle. Gen 2 instances are in maintenance mode with no new features. Oracle has not announced a hard EOL date for Gen 2 but is actively encouraging migration to Gen 3. All new features (Projects, AI Agents, HITL, new adapters) are Gen 3 exclusive. [src2, src7]

When to Use / When Not to Use

Cross-System Comparison

Important Caveats

• Message pack billing is continuous: Unlike consumption-based pricing (pay per API call), OIC charges for provisioned capacity per hour. An idle 6-pack instance costs ~$3,600/month regardless of usage. Model your actual throughput before sizing. [src4, src5]
• Gen 3 feature parity not complete: Some Gen 2 features (B2B trading partner mode, certain adapter capabilities, event-based Publish Event action in Projects) are not yet available in Gen 3. Verify your specific requirements before migrating. [src3, src7]
• Adapter updates lag behind SaaS releases: When Oracle ERP Cloud releases a new API version, the OIC adapter may take 1-2 quarterly releases to support new endpoints. Plan for manual REST adapter calls for bleeding-edge features. [src1]
• BYOL licensing requires existing Fusion Middleware licenses: The 20K msgs/hr BYOL rate requires proof of existing Oracle middleware license entitlements. This is not simply a cheaper pricing tier. [src4]
• Regional availability matters: Not all OIC features and adapters are available in all OCI regions. Check regional availability before provisioning, especially for new features like AI Agents. [src1]
• OIC pricing and limits are subject to change: Oracle regularly updates pricing and feature availability. Always verify against current Oracle Integration pricing page and release notes before making purchasing decisions. [src5]