Relay

What is the Relay?

The Relay is the AMI component responsible for streaming real-time data from external sources into the Center and for executing on-demand queries and uploads against external systems on the Center's behalf.

This page provides an introduction to the Relay and its core concepts.

Overview

The Relay is AMI's data integration layer, running as an independent process alongside the Center and Web. It connects to a wide range of external systems, including messaging platforms, databases, APIs, files, and custom applications. It streams real-time data into the Center and can also execute queries and uploads from the Center on request.

The Relay primarily uses feed handlers to maintain persistent connections to external sources and push real-time data continuously.

Note

Datasource adapters can be configured to execute queries on a Relay instead of a Center process. However, the datasource registration itself is always stored in the Center.

The Relay can also perform optional transformations on data before it reaches a Center, acting as a pre-processing layer to reduce computational overhead in the Center.

AMI Relay Architecture

The Relay runs as a separate process from the Center and Web. It connects to one or more Centers via two message channels:

1. Outbound (Relay-to-Center)

   • Carries single-operation change events at the row-level (insert, update, delete) from feed handlers, along with responses to requests issued by the Center.

2. Inbound (Center-to-Relay)

   • Carries requests and commands issued by the Center, including acknowledgments, snapshot and replay requests, AMI command execution, and datasource queries.

When the Center issues a command, or is invoked to by the Web, the Relay dispatches it to the appropriate feed handler or external system and returns the response.

Feed handlers are Java-based plugins that feed data into the Relay. They do not connect to the Center directly. Events are pushed into the Relay via the AmiRelayIn interface. Transformations and routing rules, if configured, are then applied before events are journaled and then forwarded to connected Centers on the outbound channel.

3forge natively supports a large number of messaging services, the full list of which can be found here. Users can also configure their own custom feed handlers for proprietary messaging systems via the custom feed handler plugin.

Datasource adapters can be configured to run on a Relay rather than on the Center. When a query is executed against a Relay-configured datasource, the Center forwards the request on the inbound channel. The Relay creates an adapter instance, executes the query against the external system, and returns the result on the outbound channel.

Note

This is legacy behavior. For most use cases, datasource adapters should be run on their host Centers.

A single Relay instance can connect to multiple Centers and manage multiple feed handlers, and execute queries for multiple datasource adapters concurrently.

Key Relay Concepts

Concept	Description
Feed handler	A plugin that manages a persistent connection to an external source and streams real-time data into the Relay continuously.
Datasource adapter	A plugin that executes on-demand queries and bulk data uploads against an external database or API; the adapter can be run either on a Relay or directly on the Center, depending on configuration.
Relay Transforms	A configurable rule applied to inbound messages from feed handlers, enabling payload modification, schema translation, and data enrichment prior to Center processing.
Relay Routes	A rule-based layer that directs processed messages to one or more Centers, or drops them, based on defined logic.
Guaranteed messaging	An opt-in durability mode (controlled by the ami.relay.guaranteed.messaging.enabled property) in which outbound event batches are written to a recovery journal on disk and retained until every connected Center has acknowledged them, allowing replay from the last acknowledged sequence number on Center reconnect.
Replay command	A Relay command that replays historical messages from AmiMessages.log through a synthetic feed handler session for auditing, debugging, and rebuilding state.

Delta Processing

AMI delivers data changes as row-level events rather than full table snapshots. The Relay is the transport layer; it receives events from feed handlers, applies configured transforms and routing rules, then forwards batched events to connected Centers.

Feed handlers push change events as updates occur at the source, populating only the fields relevant to each change. The Relay assigns each outgoing batch a sequence number so connected Centers can track what they have received.

Each connected Center acknowledges processed sequence numbers back to the Relay. Acknowledgements are tracked independently per Center, so a slow or disconnected Center does not affect the Relay's delivery to other connected Centers.

Durability and Replay

The Relay provides durability support for improved resilience and historical re-execution for easy auditing. The two main mechanisms for this are:

1. Guaranteed messaging

   • Set by the ami.relay.guaranteed.messaging.enabled property (disabled by default).
   • When enabled, each outbound event batch is written to a recovery journal on disk (amione/persist/messages.recovery) before being forwarded. Journal entries are retained until every connected Center has acknowledged them.
   • If a Center disconnects and reconnects, the Relay replays journal events from the last acknowledged sequence number, avoiding a full resync. Without guaranteed messaging, pending events at the moment of a Relay restart are lost.
   • See Relay Properties for configuration details.

2. Replay command

   • Every inbound message is recorded automatically in the Relay's AmiMessages.log file.
   • The Replay command reads these log files and replays the messages through a synthetic feed handler session, enabling historical re-runs for auditing, debugging, and rebuilding state.
   • See Replay for syntax and examples.

Adding some information