How to migrate an Oracle SOA Suite handoff yourself

To migrate an Oracle SOA Suite handoff, export the deployed composite and trace the service contract, approval state, fault behavior, and destination receipt. Start by replacing one bounded step, such as delivering an already approved invoice. Keep the existing approval flow until you have a verified design for long-running instances and callbacks.

Which receipt proves that an Oracle SOA handoff completed?

An invoice request was acknowledged but remains pending after the ERP response disappeared. Distinguish the durable intake acknowledgment from an ERP receipt or authenticated callback for that invoice's correlation key.

Recovery. If the partner confirms the operation, record its outcome and deduplicate subsequent callbacks. Retry the same operation key only with reliable negative confirmation or documented idempotency. Hold an ambiguous result for reconciliation and keep existing callbacks routed to their owning composite revision.

Cutover check. Replay the same SOAP payload, duplicate request and duplicate callback against both paths. Require the same acknowledgment and correlation, one ERP operation, one terminal result, and distinct validation and business faults that never reach the ERP.

Recreate one invoice service contract and its callback

The sample inputs and expected results in this walkthrough are synthetic.

Start with a completed invoice trace and a trace still waiting for a callback. Record SOA partition, deployed composite revision, sender endpoint and SOAP operation, correlation property/XPath or conversation ID, business fault QName, actual SOAP action, callback operation, partner binding, and retried side effects. Pin the applicable WSDL, XSD, XSLT/DVM versions and composite fault-policy bindings. Oracle BPEL can resolve a callback through conversation ID or correlation, and policies can override default retry behavior. Use actual instance and adapter evidence when selecting the successor's retry rules. Oracle correlation sets · Oracle BPEL recovery · Oracle fault handling

Implement the intake transaction first, then a polling outbox worker and a callback receiver with separate audit state. The intake acknowledgement represents a durable accepted request. The callback or final reply represents the result the partner accepted. Keep those receipts separate. Carry the partner's operation key into status lookup. When the destination offers neither idempotency nor lookup, put ambiguous deliveries in a reconciliation queue with a named owner. Limit retries to the fault classes and timing that the business owner has approved. Compare order of observable effects and fault outcomes, alongside the payload.

Reproduce a correlation race

Send invoice A1 from Billing as transport message m1, amount 2500 minor units, account R01, and business correlation A1/1. The mock ERP accepts outbox key invoice:A1/1 and loses its response. Send m1 again, then send callback cb7 with correlation A1/1 twice. Expect one accepted request, one ERP operation, one completed record and a stable acknowledgement for the duplicate. A callback with a different partner or correlation does not complete A1. Confirm the namespace validation and unknown-account cases produce their distinct expected faults and do not reach the ERP.

Capture the composite and deployed configuration

Oracle documents exporting a deployed composite to a SOA archive JAR, commonly called a SAR, from Enterprise Manager Fusion Middleware Control. Collect the versioned JDeveloper project if available, plus the matching composite revision, deployment configuration plan, and relevant shared MDS artifacts. Shared schemas and other metadata may be stored separately from the composite. Record runtime properties and policy bindings that affect the selected route. Oracle's composite administration guide · Oracle's composite development guide

Use composite.xml to find the service and reference wiring. Read the relevant WSDL and XSD, BPEL or Mediator steps, transformations, adapter configuration, and fault policies. Capture correlation identifiers, callback timing, security requirements, and the transition that makes an invoice eligible to send. Use redacted instance traces and synthetic payloads to compare outcomes with an AI assistant.

Rebuild only the approved invoice delivery

Keep the existing approval system as the authority for an invoice's status. Have the selected integration emit an approved event or retrieve the approved record from its owner. Write an adapter that validates the invoice schema, applies the agreed mapping, and delivers through the required finance API or service endpoint. Preserve the contract's amount and currency handling.

Give the worker a durable ledger keyed by source invoice and approval revision. Store correlation ID, input hash, receipt status, and the finance record ID. Retry transient faults with the same identity and reconcile an ambiguous timeout before sending again. Capture rejected invoices and route them to the owner. If downstream work waits for a callback, preserve the correlation key and an explicit timeout path.

Implementation runbook

Export the deployed composite with postdeployment changes

For Oracle SOA Suite 12.2.1.4 record partition/folder, composite and exact revision in Enterprise Manager. Retrieve the deployment SAR from the release artifact and export the matching deployed revision using the Oracle SOA WLST command so postdeployment changes can be compared. This example uses the Invoicing partition. The server may require approved authentication. Treat SAR and runtime properties as sensitive.

sca_exportComposite(
    'https://soa.example.invalid:8001',
    'all',
    '/secure/sca_ApprovedInvoiceDelivery_rev1.2.jar',
    'ApprovedInvoiceDelivery',
    '1.2',
    folder='Invoicing',
)

Inspect composite.xml, BPEL/Mediator files, WSDL/XSD, transforms, fault policies and bindings, imported MDS metadata, DVM values and configured partner adapter properties. Record the effective revision and policy plus a correlation trace and known fault. all includes postdeployment changes, unlike none, but still collect shared MDS dependencies, endpoint routing, credentials by reference, work queues and live instance state separately. Oracle WLST SOA export · Oracle composite administration

Preserve asynchronous acknowledgement and correlation

Replace the initial service with a contract-preserving receiver that validates headers and XML, assigns the original or derived business correlation key and persists the accepted message before returning its acknowledgement. Use a durable state table keyed by request ID and a uniqueness constraint on source system/message ID. Route an outbox to the downstream service with one stable operation ID. Track callback, timeout, business fault and technical retry separately. Correlate the callback by contract ID before updating state. For ambiguous remote success require a destination receipt lookup or explicit review. A retry never recreates a business request merely because a network response was lost. Route XML validation errors to the contract's original business fault shape, with restricted raw payload storage.

Concrete fixture. Receive request A1 twice. A response goes out only after the durable insert and both requests resolve to A1. The downstream operation returns a timeout after accepting it, then a callback arrives twice. Expect one downstream business operation, one terminal success, two duplicate detections, and the original correlation key on the callback. Submit bad namespace and valid XML with an unknown billing account and assert different outcomes. For cutover, route new requests to the new handler only after isolating callback routes. Retain old revision for in-flight/dehydrated instances until they finish or an owner transfers them with explicit state reconciliation.

Run the acceptance logic locally

Run this self-contained fixture with Python 3. It uses synthetic inputs and no vendor connection. For migration signoff, repeat the same checks against a sandbox on your selected replacement.

requests, effects, callbacks = {}, {}, {}

def receive(request_id, digest):
    prior = requests.setdefault(request_id, digest)
    if prior != digest:
        raise ValueError("Conflicting request identity")
    return request_id

def send(request_id, lose_response=False):
    receipt = effects.setdefault(request_id, f"invoice-{request_id}")
    if lose_response:
        raise TimeoutError("Destination accepted; response lost")
    return receipt

def callback(request_id, receipt):
    if effects.get(request_id) != receipt:
        raise ValueError("Callback does not match the accepted invoice")
    callbacks[request_id] = receipt

assert receive("A1", "hash-A1") == receive("A1", "hash-A1")
try:
    send("A1", lose_response=True)
except TimeoutError:
    receipt = effects["A1"]  # mock destination receipt lookup
callback("A1", receipt)
callback("A1", receipt)
assert effects == callbacks == {"A1": "invoice-A1"}

Use AI to trace the handoff and test the fault paths

Read these redacted SOA composite artifacts, fault policies, and sample traces. Identify the approval gate, message transformations, adapter calls, callback identifiers, and retry paths. Separate the selected finance handoff from BPEL instances or human tasks that must stay in the existing system.

Draft a mock finance adapter and a local replay fixture. Include an unapproved invoice, a repeated approved event, and a timeout after the finance record is created. Show expected receipts and error states. Keep real endpoints, credentials, and deployment steps outside the fixture.

Confirm the receiving record before moving traffic

Use approved invoice I7 for 120.00, an identical replay of I7, and invoice I8 for 80.00 pending approval. Expect exactly one accepted I7 finance record for 120.00 and no I8 delivery. Simulate the destination saving I7 before a timeout and confirm reconciliation finds the original receipt. Use a mismatched approval revision to check that the new worker does not send stale data.

Run the adapter on approved events and schedule a periodic reconciliation of accepted, rejected, and unresolved deliveries. During a shadow period, use a stub or sandbox destination. At cutover, agree where in-flight composite instances and callbacks will finish, then route only new eligible events to the replacement. Keep the previous route available for rollback and reconcile the receipt ledger before restarting its sends.

Need help with the migration?

Explore Oracle SOA migration services or browse all DIY migration guides.