Cloud Connect Topic Scheme

Atlas Cloud Connect uses a standardized topic scheme internally. There are 4 Atlas topic types:

• Ack: Acknowledgement that a message was received by a specific Node (Note: ack topics are Node specific)
• Cluster: Messages to be sent to all Nodes assigned to a Cluster
• Node: Messages intended only for a specific Node
• System: Messages generated by the "System" (understood as the Experience Manager), typically content updates

This document provides an overview of the different Topic types, their name formatting and permissions required to Read, Write and Subscribe.

Assumptions

When an Agent (such as the Experience Agent, or Limial) are developed, it is assumed that all Nodes with an agent such as the Experience Agent, or Liminal will:

1. Subscribe to the Cluster Topic
2. Subscribe to the Node Topic
3. All Nodes receiving messages SHOULD send acknowledgements back to the sender on the ack topic
4. All AV messages shall be sent on the ctl topic

Ack

The ack Topic is used as an acknowledgement Topic that requesting service performed the requested action.

Action	Permissions Required	Topics Available
Receiving	read + subscribe	ack/<node nanoid> or ack/#
Sending	write	ack/<node nanoid>

WARNING

Subscribing to the wildcard ack/# topic will return all Ack messages from all Nodes. This is generally not recommended, but available when needed.

A typical example is requesting requesting that an appliction launch from the Experience Manager. A io.upswell.xagent.ApplicationStart message is sent on the node/<node nanoid> topic to the Node, the receieves the message and takes action returning a io.upswell.xagent.Ack message on the ack/<node nanoid> Topic.

TIP

When implementing Ack messages in your software, a reasonable timeout such as 10-seconds should be used when waiting for the Ack. If the message is not received during that timeout, it should be assumed that the message was not received.

The Ack message containing the original request, and the Message ID (mid) (if specified on the original request) will be return. Example:

{
    "msg": "io.upswell.xagent.Ack",
    "mid": "abcdefghij",
    "data": {
        "msg": "io.upswell.xagent.ApplicationStart",
        "mid": "abcdefghij"
    },
    "received": "0000-00-00 00:00:00Z00",
    "success": true
}

Cluster

The Cluster Topic allows messages to be sent to all Nodes asigned to a Cluster.

Action	Permissions Required	Topics Available
Receiving	read + subscribe	cluster/<cluster nanoid>
Sending	write	cluster/<cluster nanoid>

Node

The Node Topic allows messages to be sent to specific Nodes.

Action	Permissions Required	Topics Available
Receiving	read + subscribe	node/<node nanoid>
Sending	write	node/<node nanoid>

System

The System Topic is a generall purpose topic used with the Experience Manage web interface to notifify users of System events. These events are typically generated by the Experience Manager and provide notifications for content updates and events (such as a media asset completing processing in the background).

Action	Permissions Required	Topics Available
Receiving	read + subscribe	system
Sending	write	system

WARNING

While it is possible to send messages on the system Topic it is generally advised that applications needing custom messaging implement their own Custom Messaging Protocol.