Custom Messaging Protocols

Cloud Connect is easily extendable to support custom message protocols to bring real-time messaging to your application. This document steps thourgh the considerations and design of custom message protocols with Cloud Connect.

What’s Needed

To create a custom message protocol, you will need to:

1. Define a messaging protocol
2. Specify a Topic scheme
3. Assign permissions

Message Protocol

The Atlas Message Protocol defines a simple JSON structure consisting of a message type, message ID and additional data payload structure. This schema may easily be expanded for you own application:

{

    "msg": "message type",
    "mid": "message id",
    "data": {}
}

See Cloud Connect Message Protocol for more details.

While Atlas relies on a stringified JSON based messaging protocol, applications may define any string/bytes based messaging to be sent over Cloud Connect.

Custom Topic Schemes

WARNING

It is strongly recommended that Custom Message Protocols utilize their own Topic Scheme to isolate the messaging from system topics with other uses within Atlas. Especially if messages do not conform with the Cloud Connect Message Protocol.

When designing your prototcol, consider if you will unicast (one-to-one) or multicast (one-to-all) messages. Understanding if you need to message to a specific node, or broadcast to all will assist in selecting a Topic Scheme.

• Unicast: When unicasting, the topic scheme will spefiy the destination such as Node Nano ID. For example: my-app/<node nanoid>.
• Multicast: When multicasting, a single topic may be specified, for example: my-app. You may also Multicast to a Cluster of Nodes, not just a specific Node with a Topic such as my-app/<cluster nanoid>.

Assign Permissions

Because Nodes have limited access to Topics, you will need to manually assign permissions for your Custom Messaging Protocol Topics.

Topic permissions may only be managed via the Admin console. To assign permissions:

1. From the Admin landing screen, select Cluster Management and Broker Authrorized Topics
2. Select + Add Broker Authorized Topic
3. Select the user the wish you grant access to your custom topic
4. Add the Topic defined in your Custom Topic Scheme and select the permission (Note that receieving messages requires both the subscribe and read permissions)
5. Save and add additional permissions as needed

Using Custom Message Protocols

Once you have assigned permissions to your users, Node users and Service Accounts, your Custom Protocol is ready to use.

For more information on using Cloud Connect, see Get Connected.