Package com.eqixiac.equinix.messaging

package com.eqixiac.equinix.messaging
Client for the Equinix Messaging Gateway (EMG), Equinix's push channel for notifications: IBX (data center) and network maintenance and incidents (flagged SERVICE_IMPACTING or NON_SERVICE_IMPACTING), Fabric port/virtual-connection up/down, billing start, order status and Managed Services tickets. EMG publishes JSON envelopes ({"Task": {...header, "Body": {...}}, "Signature": "..."}) to a queue dedicated to your organisation on Azure Service Bus, over AMQP 1.0 (AsyncAPI emgv1, production namespace equinixemg.servicebus.windows.net).

Layers

Connection details

Create a subscription in the Equinix Customer Portal under Developer Settings > Messaging Gateway (one active subscription per environment; your user needs the notification permissions for the relevant IBXs), choose the notification types, then open the subscription's Configuration tab and Copy YAML: it holds the queue connection string and queue name. Treat the connection string as a secret (environment variable or secret store). The legacy client-id/client-secret (client_credentials) authentication for EMG was deprecated on 2024-03-18 and is not supported here. EMG Order Management (placing orders through EMG) was deprecated on 2024-09-30 and is not implemented; inbound Order Notifications are.

Delivery semantics

Service Bus delivers at least once. A message whose lock expires, whose handler fails, or whose settlement is lost is delivered again, so handlers must be idempotent: de-duplicate on EmgMessage.id() (unique per notification) and, for ticket updates, order by body().sequence(). Ordering across tickets is not guaranteed.

Example

EmgMessageHandler handler = new EmgMessageHandler() {
    @Override
    public void onIbxNotification(IbxNotification n) {
        if (n.body().isServiceImpacting()) {
            alert(n.category(), n.body().servicerId(), n.body().startDateTime());
        }
    }
};
EmgReceiver receiver = ServiceBusEmgReceiver.forQueue(
        System.getenv("EMG_CONNECTION_STRING"), System.getenv("EMG_QUEUE"));
try (EmgListener listener = new EmgListener(receiver, handler)) {
    Runtime.getRuntime().addShutdownHook(new Thread(listener::close));
    listener.run();   // blocks: complete on success, abandon on handler error,
}                     // dead-letter bodies that are not EMG envelopes