---
# === IDENTITY ===
id: business/erp-integration/oracle-soa-esb-to-oic-migration/2026
canonical_question: "How do you migrate from Oracle SOA/ESB on-prem to OIC - pattern mapping, what doesn't translate?"
aliases:
  - "Oracle SOA Suite to OIC migration guide"
  - "BPEL Mediator OSB to Oracle Integration Cloud migration"
  - "Oracle ESB to OIC pattern mapping and gaps"
  - "What doesn't translate from SOA Suite to OIC"
  - "Oracle on-prem integration to OIC cloud migration"
entity_type: erp_integration
domain: business > erp-integration > oracle-soa-esb-to-oic-migration
region: global
jurisdiction: global
temporal_scope: 2024-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Oracle SOA Suite"
    vendor: "Oracle"
    version: "12c (12.2.1.4)"
    edition: "All editions"
    deployment: "on-premise"
    api_surface: "SOAP, REST, JCA Adapters"
  - name: "Oracle Service Bus (OSB)"
    vendor: "Oracle"
    version: "12c (12.2.1.4)"
    edition: "All editions"
    deployment: "on-premise"
    api_surface: "SOAP, REST, JCA Adapters"
  - name: "Oracle Integration Cloud (OIC)"
    vendor: "Oracle"
    version: "Gen 3 (24.x)"
    edition: "Standard, Enterprise"
    deployment: "cloud"
    api_surface: "REST, SOAP, Adapters"

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

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: volatile
  last_breaking_change: "OIC Gen 3 GA (2024) — Basic Routing pattern removed, project-based organization required"
  next_review: 2026-09-05
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "SOA to OIC is NOT an upgrade — all integrations must be re-developed in OIC"
  - "OIC request/response payload limit: 10 MB for schema-based processing (1 GB for opaque/file-based)"
  - "OIC Gen 3 maximum 100 integrations per project, 50 deployments per project"
  - "Custom Java XPath extension functions are not supported in OIC — must reimplement via OCI Functions or native XSLT"
  - "OIC Basic Routing pattern removed in Gen 3 — must convert to Orchestration pattern"
  - "OCI Process Automation supports REST only — SOAP-triggered process workflows require wrapper interfaces"
  - "Message pack minimum: 1 pack (5K messages/hour non-BYOL, 20K messages/hour BYOL)"
  - "SOA Mediator resequencer has no native OIC equivalent — requires Autonomous DB (ATP) workaround"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "You need OIC Gen 2 to Gen 3 upgrade guidance (already on OIC)"
    use_instead: "business/erp-integration/oracle-integration-cloud-capabilities/2026"
  - condition: "You want to lift-and-shift SOA Suite to OCI Marketplace (keep SOA, not OIC)"
    use_instead: "Search knowledgelib.io for SOA Suite on OCI Marketplace — no dedicated unit yet"
  - condition: "You need Oracle BPM to OCI Process Automation migration"
    use_instead: "Search knowledgelib.io for Oracle BPM to OCI Process Automation — no dedicated unit yet"

# === AGENT HINTS ===
inputs_needed:
  - key: integration_pattern
    question: "What SOA/ESB components are you migrating?"
    type: choice
    options:
      - "BPEL composites (orchestration logic)"
      - "Mediator routing and transformation"
      - "OSB proxy/business services"
      - "B2B/MFT/BAM components"
      - "Full stack (all SOA components)"
  - key: data_volume
    question: "How many integration flows are in scope?"
    type: choice
    options:
      - "< 50 integrations"
      - "50-200 integrations"
      - "> 200 integrations"
  - key: direction
    question: "What's your migration strategy?"
    type: choice
    options:
      - "Big bang re-implementation to OIC"
      - "Phased migration with co-existence"
      - "Lift-and-shift to OCI first, then OIC"

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/business/erp-integration/oracle-soa-esb-to-oic-migration/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-integration-cloud-capabilities/2026"
      label: "Oracle Integration Cloud capabilities and limits — message-pack throughput (5K/20K msgs/hr), 60K cap, concurrency limits, adapters, Gen 3"
    - id: "business/erp-integration/oracle-integration-cloud-capabilities/2026"
      label: "Oracle Integration Cloud (OIC) platform capabilities — Gen 3 architecture and migration, adapter catalog, message-pack pricing, edition and project limits"
  often_confused_with:
    - id: "business/erp-integration/oracle-integration-cloud-capabilities/2026"
      label: "Oracle Integration Cloud capabilities, including a Gen 2 vs Gen 3 comparison table and upgrade constraints (OAuth-only auth, connectivity-agent reinstall, no activity-data migration, Gen 2 EOL posture)"

# === SOURCES ===
sources:
  - id: src1
    title: "Guidelines when moving Integration Workloads from SOA to Oracle Integration"
    author: Oracle A-Team
    url: https://www.ateam-oracle.com/post/guidelines-when-moving-integration-workloads-from-soa-to-oracle-integration
    type: technical_blog
    published: 2023-06-15
    reliability: authoritative
  - id: src2
    title: "Architecting for Scale: OIC Gen 3 Patterns for Oracle ERP"
    author: Vasim Imani
    url: https://vasimimani.medium.com/architecting-for-scale-oic-gen-3-patterns-for-oracle-erp-aa1a8178b020
    type: technical_blog
    published: 2026-01-15
    reliability: moderate_high
  - id: src3
    title: "SOA Suite to OIC - how easy is it?"
    author: Niall Commiskey
    url: https://paascommunity.com/2021/07/31/soa-suite-to-oic-how-easy-is-it-by-niall-commiskey/
    type: community_resource
    published: 2021-07-31
    reliability: moderate_high
  - id: src4
    title: "Oracle Integration Cloud Gen3 Projects: Features, Limitations, and Advantages"
    author: Apps Associates
    url: https://appsassociates.com/blog/oracle-integration-cloud-gen3-projects-features-limitations-and-advantages/
    type: technical_blog
    published: 2024-02-01
    reliability: moderate_high
  - id: src5
    title: "Seamless Transition from Oracle SOA and OSB to Oracle Integration Cloud (OIC)"
    author: Redfaire International
    url: https://www.redfaire.com/resources/seamless-transition-from-oracle-soa-and-osb-to-oracle-integration-cloud-oic
    type: technical_blog
    published: 2024-09-01
    reliability: moderate_high
  - id: src6
    title: "Oracle Integration Instance Edition, Message Pricing, and License Types"
    author: K21 Academy
    url: https://k21academy.com/oracle-integration-cloud-service/oracle-integration-cloud-oic-instance-edition-message-pricing-and-license-types/
    type: community_resource
    published: 2024-06-01
    reliability: moderate
  - id: src7
    title: "Phase 1: Migrate Process Applications to OCI Process Automation"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/paas/application-integration/oracle-integration-oci/phase-1-migrate-process-applications-oci-process-automation.html
    type: official_docs
    published: 2024-01-01
    reliability: authoritative
---

# Oracle SOA/ESB to OIC Migration: Pattern Mapping and Translation Gaps

## TL;DR

- **Bottom line**: SOA-to-OIC is a full re-implementation, not an upgrade; every composite must be rebuilt using OIC's Application-Driven Orchestration pattern, and roughly 20-30% of SOA patterns have no direct OIC equivalent.
- **Key limit**: OIC caps schema-based payloads at 10 MB (vs. SOA's unlimited in-memory processing) and Gen 3 limits projects to 100 integrations and 50 deployments each.
- **Watch out for**: Custom Java embedding, custom XPath extension functions, Mediator resequencer, complex BPEL correlation sets, and SOA Spring contexts have no native OIC equivalents and require architectural workarounds.
- **Best for**: Organizations moving from Oracle on-prem middleware to cloud-native integration, especially those already on Oracle Fusion Cloud ERP/HCM/SCM.
- **Authentication**: OIC uses OAuth 2.0 for cloud-to-cloud; SOA on-prem typically uses WS-Security, OWSM policies, or SAML -- these must be redesigned for OIC's identity model.

## System Profile

This card covers the migration path from Oracle SOA Suite 12c and Oracle Service Bus (OSB) 12c running on-premises on WebLogic Server to Oracle Integration Cloud (OIC) Gen 3, Oracle's cloud-native iPaaS. The migration is relevant for organizations whose SOA Suite infrastructure faces hardware refresh cycles, WebLogic license renewals, or strategic cloud mandates. This is NOT a lift-and-shift guide -- Oracle provides a separate path for running SOA Suite on OCI Marketplace if you want to keep the SOA runtime. This card specifically covers re-implementation to OIC.

| System | Role | API Surface | Direction |
|---|---|---|---|
| Oracle SOA Suite 12c | Source platform -- BPEL, Mediator, adapters | SOAP, REST, JCA | Outbound (migrating from) |
| Oracle Service Bus 12c | Source platform -- proxy services, routing | SOAP, REST, JCA | Outbound (migrating from) |
| Oracle Integration Cloud Gen 3 | Target platform -- Orchestration, adapters | REST, SOAP, Adapters | Inbound (migrating to) |
| OCI Process Automation | Target for BPM/Human Task workflows | REST only | Inbound (migrating to) |

## API Surfaces & Capabilities

### SOA Suite Component to OIC Pattern Mapping

| SOA Component | OIC Equivalent | Migration Complexity | Gap Level | Notes |
|---|---|---|---|---|
| BPEL Process (sync) | App-Driven Orchestration (sync) | Medium | Low | Rebuild flow logic; most constructs map well |
| BPEL Process (async) | App-Driven Orchestration (async) | Medium-High | Low-Medium | Correlation sets need redesign |
| Mediator routing | Orchestration with switch/filter | Low-Medium | Low | Routing rules translate to OIC switch actions |
| Mediator resequencer | Custom with Autonomous DB (ATP) | High | High | No native OIC equivalent; requires ATP database and Integration Accelerator recipe |
| OSB proxy service | OIC trigger (REST/SOAP adapter) | Medium | Low | Rebuild pipeline stages as orchestration actions |
| OSB business service | OIC invoke (adapter connection) | Low | Low | Direct adapter-to-adapter replacement |
| OSB pipeline with branching | Orchestration with switch/scope | Medium | Low-Medium | Complex XQuery transforms need XSLT rewrite |
| Human Task (BPM) | OCI Process Automation | High | Medium | Web forms must be rebuilt; SOAP triggers need REST wrappers |
| Business Rules (SOA) | OCI Process Automation Decision Models | Medium-High | Medium | Rule dictionaries need redesign as DMN models |
| B2B (EDI/AS2) | OIC B2B with AS2/FTP adapters | High | Medium | Trading partner agreements need reconfiguration |
| MFT (Managed File Transfer) | OIC File Server + FTP adapter | Medium | Low-Medium | Schedule-based transfers remap well; complex routing less so |
| BAM (Business Activity Monitoring) | OIC Monitoring + custom dashboards | High | High | No direct equivalent; use OIC built-in monitoring plus OCI Observability |
| SOA Event Delivery Network (EDN) | OIC publish/subscribe (limited) | High | High | Gen 3 does not support event-based design or publish-event actions in projects |
| Spring Context / Java Embedding | OCI Functions (serverless) | High | High | Must extract Java logic to OCI Functions and invoke via REST |
| Custom XPath Functions | OCI Functions or native XSLT | High | High | No custom XPath extension support in OIC; rewrite or externalize |
| Complex XSLT with custom constructors | Simplified XSLT in OIC Mapper | Medium-High | Medium | OIC Mapper cannot render unsupported XSLT constructors; manual XSLT editing required |

[src1, src3]

## Rate Limits & Quotas

### OIC Message Pack Sizing (Target Platform)

| Metric | Non-BYOL | BYOL | Notes |
|---|---|---|---|
| Messages per hour (1 pack) | 5,000 | 20,000 | Minimum 1 pack required |
| Max packs via UI | 12 | 3 | Can override via OCI CLI |
| Max packs via CLI | Unlimited (custom) | Unlimited (custom) | Contact Oracle for >12 packs |
| Billing model | Per hour (running) | Per hour (running) | Billed whether sending messages or not |

[src6]

### OIC Processing Limits

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| Schema-based payload | 10 MB | All integrations | In-memory processing cap |
| File-based (opaque schema) | 1 GB | Stage File, FTP, REST attachments | Does not load into OIC memory |
| Integrations per project (Gen 3) | 100 | Per project | Create additional projects for larger portfolios |
| Project deployments | 50 | Per project | Active deployed integrations |
| Connections per project | 20 | Per project | Shared connections across integrations |
| Lookups per project | 20 | Per project | Key-value mapping tables |
| JavaScript libraries per project | 20 | Per project | Reusable JS code modules |
| Concurrent scheduled integrations | Varies by pack | Per instance | Depends on message pack count |

[src4, src1]

### SOA Suite Comparison (Source Platform)

| Capability | SOA Suite 12c On-Prem | OIC Gen 3 | Impact |
|---|---|---|---|
| Payload size | Unlimited (memory-bound) | 10 MB schema / 1 GB file | Large XML payloads need chunking |
| Concurrent threads | Server-dependent | Message pack-dependent | Must right-size message packs |
| BPEL dehydration | Database-backed | OIC-managed | Less control over instance persistence |
| Custom Java code | Full JVM access | None (use OCI Functions) | Architectural change required |
| XSLT engine | Full XSLT 2.0 + extensions | XSLT 1.0/2.0 subset in Mapper | Complex transforms may need redesign |
| Scheduling | ESS / cron | OIC scheduler (basic) | Limited scheduling options; use OCI Scheduler for complex |

[src1, src4]

## Authentication

### Authentication Model Changes

| SOA Mechanism | OIC Equivalent | Migration Action | Notes |
|---|---|---|---|
| WS-Security (OWSM policies) | OAuth 2.0 / OIC Security Policies | Redesign auth flow | OWSM policies do not carry over |
| SAML assertions | OAuth 2.0 + IDCS federation | Configure IDCS federation | Token format changes |
| Username/Password (wsse) | Basic Auth / OAuth 2.0 | Reconfigure per connection | Prefer OAuth for production |
| SSL mutual auth (2-way SSL) | OIC certificate upload | Upload certs to OIC trust store | Per-connection configuration |
| Custom token handlers | OCI Functions + OIC REST invoke | Externalize custom auth logic | No custom auth handler support in OIC |

[src1]

### Authentication Gotchas

- OIC connections store credentials per-environment; when promoting from dev to test to prod, connection credentials must be reconfigured in each target environment -- there is no automated credential migration. [src1]
- SOA keystore and OWSM policy configurations are server-level; OIC manages certificates globally (not per-project in Gen 3), which can cause certificate conflicts in multi-team environments. [src4]
- OAuth token refresh in OIC is automatic for prebuilt cloud adapters (ERP, HCM) but must be manually handled for custom REST connections using refresh token flows. [src1]

## Constraints

- **Full re-implementation required**: SOA and OIC have fundamentally different design-time and runtime environments; there is no automated migration tool that converts SOA composites to OIC integrations. [src1]
- **10 MB payload ceiling**: SOA composites processing large XML documents (common in B2B, financial reconciliation) must be redesigned for OIC's 10 MB schema-based limit or refactored to use file-based/streaming approaches. [src1]
- **No custom Java in OIC runtime**: SOA composites using Java embedding, Spring beans, or custom XPath Java functions must externalize that logic to OCI Functions and invoke via REST, adding network latency and deployment complexity. [src1]
- **Gen 3 project boundaries**: Each OIC Gen 3 project is limited to 100 integrations, 50 deployments, and 20 connections; large SOA estates (500+ composites) require partitioning into multiple projects with no cross-project asset sharing. [src4]
- **Basic Routing deprecated**: SOA Mediator-style routing patterns that were built using OIC Gen 2's Basic Routing pattern must be converted to Orchestration; Basic Routing is removed in Gen 3. [src2]
- **SOAP-only process triggers**: OCI Process Automation (the Human Task replacement) supports REST only; any SOA BPEL process triggered via SOAP requires an OIC integration wrapper to present a REST interface. [src7]
- **Message pack billing**: OIC bills per running hour regardless of message volume; organizations must estimate message volumes from SOA runtime metrics to right-size packs and avoid over-provisioning. [src6]

## Integration Pattern Decision Tree

```
START -- Migrating SOA/ESB to OIC
|
+-- Step 1: Inventory SOA components
|   +-- BPEL composites --> Map to OIC App-Driven Orchestration
|   +-- Mediator routing --> Map to OIC Orchestration with switch/filter
|   +-- OSB proxy services --> Map to OIC trigger + orchestration
|   +-- Human Tasks / BPM --> Map to OCI Process Automation
|   +-- B2B (EDI/AS2) --> Map to OIC B2B adapters
|   +-- MFT --> Map to OIC File Server + FTP adapter
|   +-- BAM dashboards --> Map to OIC Monitoring + OCI Observability
|   +-- Custom Java / Spring --> Extract to OCI Functions
|
+-- Step 2: Identify untranslatable patterns
|   +-- Custom XPath functions? --> Rewrite in XSLT or OCI Functions
|   +-- Mediator resequencer? --> Requires ATP database workaround
|   +-- SOA EDN events? --> Redesign as OIC scheduled polling or OCI Events
|   +-- Java embedding? --> Move to OCI Functions (REST invocation)
|   +-- Complex BPEL correlation sets? --> Simplify or use tracking variables
|   +-- BAM real-time dashboards? --> OCI Logging Analytics + custom viz
|
+-- Step 3: Choose migration strategy
|   +-- < 50 integrations, simple patterns?
|   |   --> Big bang re-implementation (3-4 months, 2 devs)
|   +-- 50-200 integrations, mixed complexity?
|   |   --> Phased migration with co-existence (6-12 months)
|   +-- > 200 integrations or complex Java?
|   |   --> Phased with SOA on OCI Marketplace interim (12-18 months)
|   +-- Need SOA features OIC lacks?
|       --> Hybrid: SOA on OCI + OIC for new integrations
|
+-- Step 4: Size OIC message packs
    +-- Analyze SOA runtime metrics (messages/hour, peak periods)
    +-- Factor for growth (1.5x-2x current volumes)
    +-- Account for OIC overhead (each adapter invoke = 1 message)
    +-- Start with estimated packs, monitor, adjust after 30 days
```

## Quick Reference

### SOA Adapter to OIC Adapter Mapping

| SOA/OSB Adapter | OIC Adapter | Gap | Migration Notes |
|---|---|---|---|
| Database Adapter (JCA) | Oracle Database Adapter | Low | SQL operations map directly; stored procedure support available |
| JMS Adapter | JMS Adapter | Low | Connection factory details change; destination names remap |
| FTP Adapter | FTP Adapter | Low | Supports FTP, SFTP, FTPS; file polling patterns translate well |
| File Adapter | Stage File action | Low-Medium | Local file operations become Stage File read/write in OIC |
| AQ Adapter | Oracle AQ Adapter | Low | Advanced Queuing connections require OCI networking setup |
| Oracle Apps Adapter (EBS) | Oracle E-Business Suite Adapter | Medium | API differences between SOA and OIC versions of the adapter |
| SAP Adapter (iDocs) | SAP Adapter (OIC) | Medium | Connection configuration differs; iDoc support maintained |
| MQ Series Adapter | IBM MQ Adapter | Medium | MQ connection via OIC Connectivity Agent (on-prem bridge) |
| REST Adapter | REST Adapter | Low | Configuration-driven; WADL/Swagger import supported |
| SOAP Adapter | SOAP Adapter | Low | WSDL import; WS-Security policies need reconfiguration |
| Oracle ERP Cloud Adapter | Oracle ERP Cloud Adapter | Very Low | Native OIC adapter; best-supported path |
| Custom JCA Adapter | No equivalent | High | Must rewrite as REST service + OCI Functions |
| Coherence Adapter | No equivalent | High | Replace with OCI Cache or Redis via REST |
| UMS (email/SMS) Adapter | Email notification action | Medium | Limited compared to SOA UMS; use OCI Notifications for SMS |

[src1, src3]

## Step-by-Step Integration Guide

### 1. Inventory and classify SOA composites

Catalog every deployed SOA composite, OSB project, and BPM process in your domain. Extract the component types, adapters used, and integration patterns. [src1]

```bash
# Export SOA composite list from WebLogic using WLST
# Input: Running WebLogic domain with SOA infra
# Output: CSV of deployed composites with component details

connect('weblogic', 'password', 't3://soahost:7001')
cd('/SOAFolder/soa-infra')
composites = cmo.getDeployedComposites()
for comp in composites:
    print(comp.getDN() + ',' + comp.getMode() + ',' + str(comp.isDefault()))
disconnect()
```

**Verify**: Review the output CSV; cross-reference with your SOA domain's EM console composite listing.

### 2. Classify each composite by migration complexity

For each composite, identify the SOA component types and match them to OIC equivalents using the pattern mapping table above. Flag composites with untranslatable patterns. [src1, src3]

```
Classification categories:
- GREEN  (direct map): BPEL sync/async, Mediator routing, OSB proxy,
         standard adapters (DB, FTP, JMS, REST, SOAP)
- YELLOW (redesign):   Complex XSLT, Human Tasks, Business Rules,
         BPEL correlation sets, B2B, MFT
- RED    (no equivalent): Custom Java/Spring, custom XPath,
         Mediator resequencer, EDN events, BAM, Coherence, custom JCA
```

**Verify**: The ratio is typically 50-60% green, 20-30% yellow, 10-20% red for a mature SOA estate.

### 3. Set up OIC connectivity to on-prem systems

Install the OIC Connectivity Agent on a server inside your data center network. This agent enables OIC cloud integrations to reach on-premises databases, JMS queues, file systems, and other resources without VPN. [src1]

```bash
# Download and install OIC Connectivity Agent
# Input: OIC instance URL, agent group name
# Output: Running agent connected to OIC

# 1. Download agent installer from OIC console > Agents > Download
# 2. Extract and configure
unzip oic_connectivity_agent.zip -d /opt/oic-agent
cd /opt/oic-agent

# 3. Configure agent properties
cat > InstallerProfile.cfg << 'AGENTCFG'
oic_URL=https://your-oic-instance.integration.ocp.oraclecloud.com
agent_GROUP_IDENTIFIER=ON_PREM_AGENT_GROUP
oic_USER=oic-agent-user@domain.com
oic_PASSWORD=encrypted-password
AGENTCFG

# 4. Run installer
java -jar connectivityagent.jar

# 5. Verify agent status in OIC console > Agents
```

**Verify**: OIC console > Design > Agents shows the agent group with status "Running".

### 4. Rebuild a BPEL composite as OIC Orchestration

Map the BPEL process flow to an OIC App-Driven Orchestration integration. Replace BPEL activities with OIC actions. [src1, src3]

```
BPEL Activity          --> OIC Action
-----------------------------------------------
Receive                --> Trigger (REST or App adapter)
Invoke                 --> Invoke (adapter connection)
Assign (copy rules)    --> Map (XSLT mapper)
Switch/Case            --> Switch action
While                  --> While loop (avoid polling; use callbacks)
Wait                   --> Schedule or Wait action
Throw/Catch            --> Fault handler / Scope with error
Scope                  --> Scope action
Flow (parallel)        --> Not natively supported; use separate integrations
FlowN                  --> Not supported; use parent orchestration with child invocations
Compensate             --> Not natively supported; implement manual compensation logic
Java Embedding         --> Invoke OCI Function via REST adapter
```

**Verify**: Test the rebuilt OIC integration against the same test data used for the original SOA composite; compare outputs field-by-field.

## Data Mapping

### XSLT Migration Reference

| SOA XSLT Feature | OIC Mapper Support | Workaround |
|---|---|---|
| Standard XSLT 1.0 functions | Fully supported | Direct migration |
| XSLT 2.0 functions | Partially supported | Test each function; some need rewrite |
| Custom XPath Java functions | Not supported | Rewrite as OCI Function, call via REST invoke |
| oraext: extension functions | Partially supported | Some Oracle extensions available; test individually |
| dvm: (Domain Value Map) lookups | OIC Lookups | Recreate DVMs as OIC Lookup tables |
| xref: (Cross-reference) functions | Not supported | Implement xref via database lookup + OIC DB adapter |
| Complex multi-file XSLT imports | Single XSLT file in OIC | Merge imported stylesheets into single file |
| XSLT with embedded Java | Not supported | Extract Java to OCI Functions |
| XQuery (OSB) | XSLT only in OIC | Rewrite XQuery transforms as XSLT |
| Custom XSLT constructors | Not renderable in OIC Mapper | Edit XSLT source directly (Mapper cannot visualize) |

[src1]

### Data Type Gotchas

- SOA BPEL uses strongly-typed XML Schema variables; OIC uses the same schemas but requires all schemas to be self-contained (no external schema imports via catalog.xml). [src1]
- OSB XQuery 1.0 functions like fn-bea:inlinedXML() have no XSLT equivalent in OIC; these must be replaced with REST adapter calls or Stage File read operations. [src3]
- SOA Domain Value Maps (DVMs) support versioning and cross-references; OIC Lookups are flat key-value tables with no versioning, so migration requires simplifying DVM structures. [src1]
- SOA cross-reference (xref) tables for ID mapping between systems have no OIC native equivalent; build custom xref logic using an OIC-connected database table. [src1]

## Error Handling & Failure Points

### Common Migration-Related Errors

| Error | Meaning | Cause | Resolution |
|---|---|---|---|
| OIC-PAT-00001 | Integration activation failed | Schema validation error or unsupported XSLT | Fix schema/XSLT imports; ensure single self-contained schema |
| CASDK-0004 | Connection test failed | Connectivity Agent not reachable or misconfigured | Verify agent status, network routes, and firewall rules |
| ORA-00060 (via DB adapter) | Deadlock detected | Concurrent DB operations from multiple integrations | Add retry with jitter; reduce parallel execution |
| OIC-MAPPER-001 | Unsupported XSLT construct | Imported SOA XSLT contains custom constructors | Edit XSLT source code manually; remove unsupported elements |
| INTEGRATION-0007 | Payload too large | Message exceeds 10 MB schema processing limit | Split payload using Stage File + chunking pattern |
| OIC-SCH-001 | Schedule conflict | Multiple scheduled integrations competing for capacity | Stagger schedules; increase message packs if needed |

[src1, src4]

### Failure Points in Production

- **Polling loops hitting OIC timeout**: SOA BPEL processes commonly use While loops to poll for completion (e.g., waiting for ERP import jobs). In OIC, these loops consume thread capacity and can exceed flow timeout limits. Fix: `Replace polling with callback-based patterns using OIC's "Receive Callback" adapter action (especially for FBDI bulk imports)`. [src2]
- **Connectivity Agent single point of failure**: On-prem integrations fail completely when the Connectivity Agent goes down. Fix: `Deploy a high-availability agent group with 2+ agents behind a load balancer; configure agent failover`. [src1]
- **Message pack exhaustion during peak**: SOA handled spikes via WebLogic thread pools; OIC throttles at message pack limits. Fix: `Monitor message consumption via OIC dashboard; configure auto-scaling or purchase burst packs for known peak periods`. [src6]
- **XSLT performance degradation**: Complex SOA XSLTs that performed well on dedicated WebLogic JVMs may be slow in OIC's shared runtime. Fix: `Simplify transforms; move heavy processing to OCI Functions; use Stage File for large document transforms`. [src1]
- **Certificate expiry breaking integrations**: SOA managed certificates in WebLogic keystores with admin visibility; OIC certificates expire silently. Fix: `Track certificate expiry dates externally; set calendar reminders 30 days before expiry; upload renewed certs proactively`. [src1]

## Anti-Patterns

### Wrong: Polling for bulk import completion

```
// BAD -- SOA-style polling loop in OIC wastes thread capacity and risks timeout
While (jobStatus != "COMPLETE") {
    Wait(30 seconds)
    Invoke ERP -> Get Job Status
    // OIC thread blocked for entire duration (could be 30+ minutes)
}
```

### Correct: Use callback pattern for async completion

```
// GOOD -- Submit job, release thread, receive callback when done
1. Invoke ERP -> Submit FBDI Import Job (returns job ID)
2. Integration ends (thread released)
3. Separate integration triggered by ERP callback:
   "Receive Callback Message upon completion of FBDI bulk import job"
   -> Process results
```

[src2]

### Wrong: Migrating all composites to a single OIC project

```
// BAD -- exceeds project limits, no separation of concerns
Project: "SOA_Migration"
  - 350 integrations (exceeds 100 limit)
  - 45 connections (exceeds 20 limit)
  - All teams sharing one project
```

### Correct: Partition by domain with separate projects

```
// GOOD -- respects Gen 3 project limits, enables team autonomy
Project: "Finance_Integrations" (40 integrations, 8 connections)
Project: "HR_Integrations" (30 integrations, 6 connections)
Project: "Supply_Chain" (55 integrations, 12 connections)
Project: "B2B_EDI" (25 integrations, 5 connections)
```

[src4]

### Wrong: Direct Java embedding migration attempt

```java
// BAD -- trying to port SOA Java embedding directly to OIC
// OIC has no Java embedding support
String result = someCustomJavaClass.processData(inputXml);
// This code cannot run in OIC runtime
```

### Correct: Extract Java logic to OCI Functions

```java
// GOOD -- deploy as OCI Function, invoke from OIC via REST
// OCI Function (Java runtime)
public class DataProcessor implements Function {
    public String handleRequest(String input) {
        return processData(input); // Your custom Java logic here
    }
}
// OIC: Invoke via REST adapter -> https://functions.oci.region/invoke
```

[src1]

## Common Pitfalls

- **Underestimating re-implementation effort**: Teams assume SOA-to-OIC is a "migration" and estimate 1:1 effort. Reality: each SOA composite requires a fresh OIC integration design, build, and test cycle. Budget 2-5 days per simple integration, 1-3 weeks per complex one. [src3]
- **Ignoring message pack sizing**: Organizations provision OIC based on CPU equivalence (like SOA on WebLogic), but OIC sizes by messages per hour. Extract SOA runtime metrics (messages/hour, peak throughput) before provisioning. Start with estimated packs and right-size after 30 days of production data. [src6]
- **Not addressing connectivity agent early**: On-prem database, JMS, and file adapters all require the Connectivity Agent. Install and test the agent infrastructure in the first sprint, not when individual integrations need it. [src1]
- **Assuming XSLT portability**: SOA XSLTs with custom Java functions, DVMs, cross-references, or complex imports will fail in OIC. Audit every XSLT file before migration begins; refactor in SOA first if possible. [src1]
- **Overlooking the Gen 2 to Gen 3 gap**: Teams targeting OIC Gen 2 patterns (Basic Routing, non-project-based organization) must account for Gen 3 architectural changes. Plan for Gen 3 from the start to avoid a second migration. [src2, src4]
- **Running parallel licensing too long**: During phased migration, both SOA Suite on-prem licenses and OIC subscriptions are active. Plan the migration timeline to minimize overlap; target 3-6 months of co-existence maximum. [src5]

## Diagnostic Commands

```bash
# Check OIC instance health and message consumption
curl -X GET "https://YOUR_OIC_INSTANCE/ic/api/integration/v1/monitoring/dashboard" \
  -H "Authorization: Bearer $OIC_TOKEN" \
  -H "Accept: application/json"

# List all deployed integrations and their status
curl -X GET "https://YOUR_OIC_INSTANCE/ic/api/integration/v1/integrations?limit=100" \
  -H "Authorization: Bearer $OIC_TOKEN"

# Check Connectivity Agent status
curl -X GET "https://YOUR_OIC_INSTANCE/ic/api/integration/v1/agents" \
  -H "Authorization: Bearer $OIC_TOKEN"

# View integration instance errors (last 24 hours)
curl -X GET "https://YOUR_OIC_INSTANCE/ic/api/integration/v1/monitoring/errors?timeWindow=24h" \
  -H "Authorization: Bearer $OIC_TOKEN"

# Check message pack usage
curl -X GET "https://YOUR_OIC_INSTANCE/ic/api/integration/v1/monitoring/messageCount" \
  -H "Authorization: Bearer $OIC_TOKEN"

# SOA side: export composite list for migration inventory (WLST)
# Run from $MW_HOME/oracle_common/common/bin/wlst.sh
# listDeployedComposites() -> outputs all active composites
```

## Version History & Compatibility

| Version | Release | Status | Breaking Changes | Migration Notes |
|---|---|---|---|---|
| OIC Gen 3 (24.x) | 2024 Q1 | Current | Basic Routing removed; project-based org required | Target platform for all new migrations |
| OIC Gen 2 (23.x) | 2023 | Supported (EOL planned) | None | Migrate to Gen 3 before EOL |
| SOA Suite 12.2.1.4 | 2020 | Extended Support | N/A | Most common source version for migration |
| SOA Suite 12.2.1.3 | 2018 | Extended Support | N/A | Upgrade to 12.2.1.4 first, then migrate |
| SOA Suite 11g | 2009-2014 | Desupported | N/A | Upgrade to 12c first; direct 11g-to-OIC not documented |
| OSB 12.2.1.4 | 2020 | Extended Support | N/A | Migrate alongside SOA Suite |

[src1, src4]

### Deprecation Policy

Oracle SOA Suite 12c is in Extended Support with Premier Support ending. Oracle is actively pushing customers toward OIC as the strategic integration platform, with SOA Suite on OCI Marketplace as an interim step. OIC Gen 2 will reach EOL; all customers should target Gen 3. [src1, src5]

## When to Use / When Not to Use

| Use This Migration Path When | Don't Use When | Use Instead |
|---|---|---|
| Moving to Oracle Fusion Cloud ERP/HCM and need cloud-native integration | SOA composites rely heavily on custom Java/Spring with no cloud equivalent | Lift-and-shift SOA to OCI Marketplace |
| SOA infrastructure faces hardware EOL or WebLogic license renewal | You need SOA EDN event-driven architecture (OIC Gen 3 has no equivalent) | Keep SOA on OCI, build new integrations in OIC (hybrid) |
| Integration portfolio is primarily adapter-to-adapter with standard patterns | You have < 2 years until SOA license renewal (not enough time for full migration) | Renew SOA license, plan migration for next cycle |
| Organization has mandated cloud-first strategy | Integration latency requirements demand in-process Java (sub-millisecond) | Keep SOA on-prem or SOA on OCI |
| Want to reduce operational overhead of WebLogic/SOA administration | You need full XSLT 2.0 with custom extensions and complex multi-file imports | SOA on OCI Marketplace |

## Cross-System Comparison

| Capability | SOA Suite 12c (On-Prem) | OIC Gen 3 (Cloud) | Migration Impact |
|---|---|---|---|
| Deployment model | WebLogic Server cluster | Multi-tenant cloud PaaS | Infrastructure management eliminated |
| Development tool | JDeveloper | Browser-based designer | Developer retraining required (1-2 weeks) |
| Orchestration | BPEL 2.0 (full spec) | App-Driven Orchestration (subset) | Some BPEL constructs not available |
| Routing/Mediation | Mediator + OSB | Orchestration switch/filter | Routing rules must be rebuilt |
| Mapping | XSLT 2.0 + XQuery + custom | XSLT in OIC Mapper (visual + source) | Complex transforms need simplification |
| Custom code | Java embedding, Spring, custom XPath | None (use OCI Functions) | Major architectural change |
| Human workflow | BPM / Human Task | OCI Process Automation | Forms rebuilt; SOAP triggers need wrappers |
| Monitoring | EM Console, BAM | OIC Dashboard, OCI Observability | Different monitoring paradigm |
| Event-driven | EDN (Event Delivery Network) | Limited (no EDN equivalent in Gen 3) | Must redesign to polling or external events |
| File handling | Unlimited in-memory | 10 MB schema / 1 GB file-based | Large payloads need redesign |
| Pricing model | CPU-based perpetual license | Message pack subscription (hourly) | Operating cost model change |
| High availability | WebLogic clustering (admin-managed) | Built-in (Oracle-managed) | Operational simplification |
| Connectivity to on-prem | Direct (same network) | Via Connectivity Agent | Agent infrastructure required |

## Important Caveats

- This migration guidance reflects OIC Gen 3 capabilities as of early 2026; Oracle continuously adds features to OIC, so some current gaps (e.g., limited event support in projects) may be addressed in future releases.
- Message pack pricing varies by region and contract type; the 5K/20K messages-per-hour figures are standard list pricing and may differ under enterprise agreements.
- The 6-month/200-integration benchmark cited from community sources involved relatively simple integrations; complex SOA estates with heavy Java embedding or B2B will take significantly longer.
- SOA Suite Extended Support timelines and OIC Gen 2 EOL dates are subject to Oracle's support lifecycle policies; verify current dates on Oracle's support portal.
- OIC Connectivity Agent performance depends on network latency between on-prem and OCI region; choose the nearest OCI region and ensure low-latency connectivity.

## Related Units

- [Oracle Integration Cloud API Capabilities](/business/erp-integration/oracle-oic-api-capabilities/2026)
- [Oracle ERP Cloud OIC Integration Playbook](/business/erp-integration/oracle-erp-cloud-oic-integration/2026)
- [SOA Suite Lift-and-Shift to OCI Marketplace](/business/erp-integration/oracle-soa-oci-marketplace-migration/2026)