Oracle Integration 3 Connectivity Agent HA: Design, Failover Tests and Troubleshooting

A connectivity agent can make an Oracle Integration flow look healthy in development and unreliable in production. The integration may be unchanged: the difference is often the host, network route, agent group, or adapter behavior behind the connection. Before adding a second agent, identify which failure you want to prevent.

What the connectivity agent actually does

Oracle Integration 3 uses the connectivity agent to reach resources in an on-premises network or private environment. The agent is installed on a host that can reach the target system and establishes communication with Oracle Integration. It is not a replacement for network design, database resilience, or application-level retry logic.

Oracle documents that an agent group can contain up to two agent instances. The two instances can run actively together or, for selected adapters, operate with only one active at a time. That choice changes how you test failover. See Oracle's agent planning guide.

Choose the operating mode before installing

Two active agents for eligible adapters

For many adapters, Oracle recommends leaving the Use only one agent at a time option disabled. Both agents can then process work, improving throughput and reducing dependence on a single host. This is useful when two independent hosts have equivalent access to the target service.

Do not interpret two active agents as a guarantee of exactly-once processing. If an integration writes to an external system and then times out before receiving confirmation, a retry may repeat the write. Design the receiving operation with an idempotency key, business-key check, or another supported deduplication strategy.

One active agent at a time for adapter-specific cases

Oracle's planning guidance requires the single-active setting for File Adapter, FTP Adapter, and MLLP Adapter agent groups. In this configuration, the second installed agent acts as standby when both are present. A design that ignores this restriction can behave differently from what the team expects.

For file-based integrations, confirm that both hosts can access the required directories and remote systems. A standby host that cannot see the same file share is not a useful recovery path. The high-availability documentation calls out endpoint access and adapter considerations.

A practical production design

Consider an illustrative integration that reads purchase-order updates from an on-premises application and sends them to a cloud service. The target application is available from two internal virtual machines, but only through an approved outbound proxy.

1. Map dependencies. Document the internal hostname, port, TLS certificate chain, DNS resolver, proxy, firewall rules, and allowlists. Test from each candidate agent host, not just from a developer laptop.
2. Create the agent group. Choose a descriptive name and correct active-mode setting. Oracle notes that the group identifier and active-mode selection cannot simply be edited later; recreating the group may be necessary.
3. Install on separate hosts. Use two independently maintained hosts for genuine host-level resilience. Two processes on the same VM still share its failure modes.
4. Use the same target access. Ensure each host can reach the same endpoint and, where applicable, the same file paths. Keep configuration and supported runtime versions aligned.
5. Test actual transactions. A green agent status alone does not prove that a target API, database listener, file share, or business operation works.

The installation guide also advises minimal privileges, protecting the agent installation directory, and deleting the installation key after successful setup. Refer to Oracle's installation instructions for the supported runtime and prerequisites for your specific release.

How to test failover without confusing it with application errors

Build a controlled test that records the input business key, integration instance identifier, start time, target response, and final state. Run several successful transactions first to establish a baseline. Then stop one agent using the documented operational procedure while leaving the second host and target system available.

Observe whether new transactions continue, how long recovery takes, and whether in-flight work requires resubmission. A transient error during handover does not necessarily mean the second agent failed; compare agent health, connection errors, and target logs before assigning the cause.

Repeat the exercise with a different failure: make the target endpoint unavailable while both agents remain healthy. If both agents depend on the same database or proxy, adding another agent will not resolve that shared outage. This distinction matters when deciding whether the next investment should be agent redundancy, network redundancy, or application recovery.

Troubleshooting: agent online, integration failing

When the agent shows as available but an integration fails, work from the connection outward. Avoid immediately reinstalling the agent: that can erase useful evidence and introduce a second problem.

• Connection test fails: Verify DNS resolution, firewall access, proxy configuration, target port, TLS trust, and credentials from the host running the agent.
• Only one host fails: Compare network routes, certificates, runtime versions, time synchronization, and target permissions. Host-specific differences are more informative than a generic integration error.
• File polling behaves unexpectedly: Check required active mode, shared directory visibility, file locks, permissions, and whether the file was already consumed.
• Timeout after target update: Check the target system using the business key before resubmitting. A timeout does not prove that the target rolled back the transaction.
• Agent upgrade causes errors: Consult version-specific Java and upgrade prerequisites rather than assuming the old runtime remains supported.

What to log in an OIC support runbook

A useful runbook links each integration to its agent group, active mode, hostnames, adapter, target endpoint, owning team, and recovery steps. Include a sample correlation identifier and the method for confirming whether the target transaction committed. Never store passwords or installation keys in the runbook.

For a write operation, an illustrative tracking record might look like this:

{
  "businessKey": "PO-EXAMPLE-1042",
  "integrationInstanceId": "illustrative-instance-id",
  "targetOutcome": "unknown-after-timeout",
  "nextAction": "check-target-before-retry"
}

This is an example of support metadata, not an Oracle-defined payload or API response. Its value is in preventing a blind retry that could duplicate a transaction.

When a second agent is not the answer

High availability improves resilience to a host or agent-instance failure, but it does not fix incorrect mappings, expired target credentials, shared network outages, overloaded downstream services, or a non-idempotent target API. It also does not eliminate the need for monitoring and recovery procedures.

Start with the failure mode, then choose the design. For most eligible adapters, two active agents on separate hosts are a sensible production pattern. For adapters that require single-active operation, configure that deliberately and test standby behavior. In either case, the real acceptance criterion is not merely two green icons: it is a business transaction that completes correctly during the failures your architecture claims to tolerate.