Adapters
An adapter is a live, named bridge between two systems. It owns one end of a connection, applies the processing rules you configure, and delivers each message to its target. The platform brings an adapter up when you enable it and keeps it running until you disable it, edit its configuration, or delete it.
Adapters are the unit you reason about when things go wrong, when you provision capacity, and when you decide how much redundancy a connection needs. Everything on the Adapters list and every operator control in the Portal is scoped to a single adapter.
Typical shapes:
- Receive messages from an external system and deliver them to an internal topic.
- Read from an internal topic and send messages to an external system.
- Accept inbound connections from a counterparty and forward messages internally.
Adapter fields
The Adapters list surfaces five fields on each row. Together they tell you what the adapter is, what you have asked it to do, and what the platform is actually doing about it.
| Field | What it tells you |
|---|---|
| Name | The label you gave the adapter when you created it. Used to identify the adapter in the Portal. |
| Logical ID | The stable identifier used by Infrastructure-as-Code and bundle export. It does not change when you rename the adapter. |
| Admin State | Your instruction to the platform: enabled (run it) or disabled (hold it off). |
| Operational Status | The live state the platform reports: Running when healthy, Provisioning or Standby while starting or waiting, and Degraded, Error, or Inactive when it needs attention. |
| Mode | How the adapter is deployed: Single Writer (one pod serves the connection at a time) or Scale Out (multiple pods serve it concurrently). |
Admin State and Operational Status are not the same field
Admin State is your command. Operational Status is the platform's answer. The two can disagree, and that disagreement is the signal to act.
An adapter set to enabled should reach Running. If it shows Inactive or Error while enabled, the platform is telling you it tried and could not complete. When the two agree (enabled with Running, or disabled with Inactive), the adapter is in the state you asked for.
Operational status
Use Operational Status as a quick read on whether the connection is actually doing its job. The platform reports one status at a time, derived from where the adapter is in its lifecycle and the health it reports.
| Status | What's happening | What to do |
|---|---|---|
| Running | The connection is established and the pipeline is processing messages. | Nothing. This is the healthy state. |
| Provisioning | The platform is placing the adapter on a server and starting it. The session is not yet established. | Expect it to clear shortly. If it stays in Provisioning, or keeps returning to it, the startup is not progressing: open the adapter and read the event log. |
| Standby | The adapter is enabled and waiting for the primary lease, because another instance currently holds the connection. | Nothing. This is normal for a redundant Single Writer configuration; the standby takes over automatically if the active instance fails. |
| Degraded | The connection is up but the adapter is reporting warnings. | Open the adapter and read the event log for the warnings. |
| Error | The adapter is running but reported an unhealthy state. | Open the adapter. The event log entry before the Error names the cause. |
| Inactive | The adapter is not running, either because it is disabled or because no server had capacity to start it. | If it should be running, enable it or confirm there is server capacity. Otherwise this is expected. |
The console also shows a few shorter-lived states: Releasing while the platform removes an adapter, Paused when an operator has paused processing, and Ports Exhausted when no network port is free. A Provisioning state that does not progress points to a startup problem: a misconfigured connection, a missing artifact, or no adapter server available to host the session. See Monitoring for the full status reference and Troubleshooting to diagnose a stuck start.
Turning an adapter on and off
Admin State controls whether the adapter participates in the fleet. Set it to enabled and the platform schedules the adapter on an available server and attempts to establish the connection. Set it to disabled and the platform takes the adapter out of rotation after closing the current session cleanly.
The shutdown is graceful by design. The external system sees a proper disconnect rather than a dropped link, which matters for any counterparty that tracks session state or treats abnormal terminations as an incident.
Deployment modes
An adapter runs in one of two deployment modes, set when you create it. In the wizard's Pattern step (titled Configuration Strategy), reusing an existing configuration as Link (Shared) makes the adapter Scale Out; otherwise it is Single Writer. The mode decides whether one pod or several serve the connection, and how it survives the loss of a pod. Pick the mode that matches your protocol and the cost of downtime, not a fleet-wide default.
| Mode | Serving pods | How it survives a pod failure | When to use |
|---|---|---|---|
| Single Writer | One pod serves the connection at a time. | Run two or more pods so a standby can claim the connection when the active pod fails. Run a single pod only when a brief outage during a restart is acceptable. | Single-owner, session-based protocols where two pods must not connect at once (FIX, an exclusive consumer, a custom TCP link). |
| Scale Out | Several pods serve concurrently. | The external system distributes work across the pods and rebalances around a failed one. Run enough pods to absorb one going down. | Protocols that are natively partitioned or stateless enough for concurrent workers (a message-cluster consumer group, load-balanced inbound endpoints), or volume beyond a single pod. |
Running a Single Writer with standby pods, or running Scale Out, both use more than one pod and need capacity for the extra copies. Confirm capacity with your administrator before relying on either for high availability.
Choosing the mode
The deciding question is whether two pods can serve the same connection at once without breaking the protocol. If they cannot, because the protocol has a single owner of the session, choose Single Writer and run standby pods for failover. If they can, because the external system distributes work across consumers, Scale Out gives you concurrency and throughput. For the mechanics behind each, how failover is arbitrated, sizing, and split-brain safeguards, see Deployment Topologies.
Managing adapters
Adapter operations are reached from two places: the adapter's Operational Console, opened by clicking the adapter name, and the Adapters list, where selecting one or more rows exposes bulk actions.
| Action | What it does |
|---|---|
| Click the adapter name | Opens the adapter's Operational Console (status, detail fields, and a link to the event log). |
| Enable / Disable | Sets Admin State. Enable schedules the adapter; Disable stops it after a clean shutdown. Available as a toggle on the Operational Console and as a bulk action from the list. |
| Pause / Resume | On the Operational Console: Pause holds message processing while keeping the instance in place; Resume starts it again. |
| Restart | A bulk action from the Adapters list: stops the instance and lets the platform start it again. Use it when the session is stuck but the configuration is correct. |
| Configuration (Edit) | From the row menu, opens the adapter's configuration for editing; on the Operational Console an Edit Configuration button appears once the adapter is disabled. The platform restarts the adapter to apply the change. |
| Delete | Removes the adapter permanently. Deleted adapters cannot be recovered from the Portal. |
See also
- Creating an Adapter: building a new connection from scratch.
- Monitoring: watching adapters once they are running.
- Troubleshooting: diagnosing stuck or failing adapters.