Scenario: Fan-out per device notification

In this scenario, publisher devices publish messages to many topic strings. Each topic string has only one subscriber device.

Background to this scenario

A hire car company wants to be able to instruct each car in the fleet to lock or unlock. These commands are sent from a number of publishing devices. An application on each of those publishing devices connects to the Eclipse Amlen, and sends messages on specific topic strings to the subscriber devices. The publishing devices sit within the company intranet.

Each car in the fleet contains a embedded subscriber device with a receiving application on it. The application on that subscriber device connects to the Eclipse Amlen, and can receive messages that are published to their specific topic string. The subscriber device sits within the internet. The publishing and receiving devices communicate by using satellites. The Eclipse Amlen sits within the DMZ. Complete the steps in the following section to understand how to set up this scenario.

Planning and implementing the solution

Use the following information to help you to plan, and implement your fan-out per device notification scenario.

Understanding your publish/subscribe architecture

In this scenario, one publisher device publishes messages to many topic strings. There are many subcriber devices. Each topic string has one subscriber device that runs a receiving application. Therefore, this scenario is a fan-out per device notification scenario. The following diagram shows the architecture of this fan-out per device notification scenario.

fan-out per device diagram. One publisher device publishes messages to many topic strings. Each message has only one subscriber device.
Understanding the required messaging behavior for your solution

Do you want durable or non-durable subscriptions? What quality of service do you need?

If a subscription is durable, when the subscribing application disconnects, the subscription remains in place and can be used by the subscribing application when it reconnects. In this scenario, the receiving applications must be available to receive a message. Therefore, the subscriptions must be durable. A quality of service of 2 is appropriate because the message delivery across the network must be guaranteed. QoS 2 messages are persistent. The message is stored on the Eclipse Amlen until the message is received by all the subscribers of the message.

Planning your solution
In this scenario, consider the following key points:
  • Which protocol is appropriate?

    Eclipse Amlen natively supports MQTT and JMS. You can also install your own protocol by using the protocol plug-in. You must consider which protocol is appropriate for your business needs. The small publisher and subscriber devices communicate by using satellites which is expensive. The messages between the devices must be sent reliably. The MQTT protocol is designed for exchanging messages between small devices on expensive connections, and to send messages reliably. Therefore, MQTT protocol is appropriate in this scenario.

  • What message size is appropriate?

    In this scenario, the car hire company wants to send large numbers of small, persistent messages. The information that is contained within the message is about locking or unlocking car doors. Therefore, the message size can be relatively small. You can limit the message size that is allowed to be sent through Eclipse Amlen by using the maximum message size attribute of an endpoint. For more information about endpoints, see Message hub, endpoints, and policies.

  • What message count is appropriate?

    Consider what maximum message count is sensible for your messaging needs. In this scenario, the quality of service is 2, so messages are stored until a subscriber receives the message. Therefore, a higher message count might typically be considered. However, as each subscriber device subscribes to a specific topic string, a low maximum message count is sufficient.

  • What is the maximum number of topic levels that you need?

    You can have up to 32 levels in a topic string. Fewer levels are easier to manage, but many levels might be required to set up specific solutions. In this scenario, the topic string length can be relatively short. For example, Car/Car registration number.

  • How are you going to ensure that all of your client IDs are unique?

    In this scenario, it is crucial that all client IDs are unique so that each car receives only messages that are intended for itself. In this scenario, you might decide to use the car registration number as that number is unique to each car. Alternatively, you can generate unique client IDs automatically when you write your application.

  • What message depth is appropriate?

    When the maximum message depth is reached, you cannot publish any more updates to that topic string until the number of messages is reduced. However, as each subscriber device has a specific topic string from which messages are received, the maximum message depth does not need to be as large as it would be if all devices received messages from the same topic string.

For more information about planning your solution, see Planning.

Writing your applications

In this scenario, you must decide the name of the topic strings that you are publishing and subscribing to. The car hire company needs many topic strings because they are sending out information to many cars. For this messaging pattern, each subscriber must subscribe to a unique topic. By using the unique client ID in the topic string, you can ensure that each topic is unique.

To ensure that subscribers cannot access the topics of other subscribers, you can use the topic string variable substitution available in the Eclipse Amlen topic messaging policies. By using topic string variable substitution you can create a topic messaging policy with single topic string that includes a client ID variable. This substitution ensures that applications can subscribe only to the topic string that matches their client ID. For example, a topic string of Car/${ClientID} is specified in the topic messaging policy. The application with a client ID of 123 is allowed to subscribe to Car/123, but is not allowed to subscribe to Car/456, or Car/789 because the client ID does not match. For more information about messaging policies and variable substitution, see Messaging policies.

In this scenario, the name of the topic string is Car/${ClientID}.

Setting up your Eclipse Amlen infrastructure, and security

Create the infrastructure by configuring message hubs and endpoints. Set up your security by creating connection and topic policies.

In this scenario, the car hire company requires one message hub because there is one goal - locking or unlocking cars. The car hire company requires two endpoints to ensure that internal and external network traffic is kept separate.

Complete the following steps to set up a message hub and endpoints for this scenario:

  1. Create your message hub. A message hub is an organizational configuration object to collect the endpoints, connection policies, and topic policies that are associated with a specific goal in a single place. In this scenario, the message hub is called Car Messaging Hub.


                curl -X POST \
                    -H 'Content-Type: application/json'  \
                    -d  '{
                             "MessageHub":  {
                                "Car Messaging Hub":  {
                                     "Description": "Message Hub for car messaging "
                                }
                             }
                          }
                        '  \
                     http://127.0.0.1:9089/ima/v1/configuration

  2. Create your connection policies. A connection policy is used to authorize a client to connect to an endpoint.
    • Create a connection policy for the subscriber. In this scenario, the connection policy is called Car Messaging External ConPol.

      In this scenario, the car hire company restricts subscriber access so that the subscriber devices must use MQTT protocol.

    • Create a connection policy for the publisher. In this scenario, the connection policy is called Car Messaging Internal ConPol.

      In this scenario, the car hire company restricts publisher access so that the publisher device must use MQTT protocol.

    You can use the following cURL commands to create the connection policies:


                curl -X POST \
                    -H 'Content-Type: application/json'  \
                    -d  '{
                             "ConnectionPolicy":  {
                                "Car Messaging External ConPol":  {
                                "UserID": "*",
                                "Protocol": "MQTT",
                                "AllowDurable": false,
                                "Description": "Car Messaging external connection policy"
                                }
                             }
                          }
                        '  \
                     http://127.0.0.1:9089/ima/v1/configuration


                curl -X POST \
                    -H 'Content-Type: application/json'  \
                    -d  '{
                             "ConnectionPolicy":  {
                                "Car Messaging Internal ConPol":  {
                                "UserID": "*",
                                "Protocol": "MQTT",
                                "AllowDurable": false,
                                "Description": "Car Messaging internal connection policy"
                                }
                             }
                          }
                        '  \
                     http://127.0.0.1:9089/ima/v1/configuration

  3. Create your topic policies. A topic policy is a messaging policy that is used to authorize a client to publish or subscribe to a topic.
    • Create a topic policy for the subscriber. In this scenario, the topic policy is called Car Messaging External TopicPol.

      The car hire company restricts subscriber access so that the subscriber devices can subscribe to the topic string Car/${ClientID} only.

    • Create a topic policy for the publisher. In this scenario, the topic policy is called Car Messaging Internal TopicPol.

      The car hire company restricts publisher access so that the publisher device can publish to the topic string Car/#.

    You can use the following cURL commands to create the topic policies:


                curl -X POST \
                    -H 'Content-Type: application/json'  \
                    -d  '{
                             "TopicPolicy":  {
                                "Car Messaging External TopicPol":  {
                                   "Topic": "Car/${ClientID}",
                                   "UserID": "*",
                                   "ActionList": "Subscribe",
                                   "Protocol": "MQTT",
                                   "MaxMessages": 5000,
                                   "Description": "Car Messaging external topic policy"
                                }
                             }
                          }
                        '  \
                     http://127.0.0.1:9089/ima/v1/configuration


                curl -X POST \
                    -H 'Content-Type: application/json'  \
                    -d  '{
                             "TopicPolicy":  {
                                "Car Messaging Internal TopicPol":  {
                                   "Topic": "Car/#",
                                   "UserID": "*",
                                   "ActionList": "Publish",
                                   "Protocol": "MQTT",
                                   "MaxMessages": 5000,
                                   "Description": "Car Messaging internal topic policy"
                                }
                             }
                          }
                        '  \
                     http://127.0.0.1:9089/ima/v1/configuration

  4. Create your endpoints. An endpoint authorizes a client to connect to the Eclipse Amlen on one or all configured ethernet interfaces, and a specific port. You create endpoints on a message hub.
    • Create an endpoint for internet network requests. In this scenario, the endpoint is called Car Hire External Endpoint. Apply the Car Messaging External ConPol, and the Car Messaging External TopicPol to the endpoint.
    • Create an endpoint for intranet network requests. In this scenario, the endpoint is called Car Hire Internal Endpoint. Apply the Car Messaging Internal ConPol, and the Car Messaging Internal TopicPol to the endpoint.

    You can use the following cURL commands to create the endpoints:


                curl -X POST \
                    -H 'Content-Type: application/json'  \
                    -d  '{
                             "Endpoint":  {
                                "Car Hire External Endpoint":  {
                                   "Enabled": true,
                                   "Port": 1884,
                                   "MaxMessageSize": "1024KB",
                                   "ConnectionPolicies": "Car Messaging External ConPol",
                                   "TopicPolicies": "Car Messaging External TopicPol",
                                   "MessageHub": "Car Messaging Hub",
                                   "Protocol": "MQTT",
                                   "Interface": "All",
                                   "Description": "Car Messaging external endpoint"
                                }
                             }
                          }
                        '  \
                     http://127.0.0.1:9089/ima/v1/configuration


                curl -X POST \
                    -H 'Content-Type: application/json'  \
                    -d  '{
                             "Endpoint":  {
                                "Car Hire Internal Endpoint":  {
                                   "Enabled": true,
                                   "Port": 1885,
                                   "MaxMessageSize": "1024KB",
                                   "ConnectionPolicies": "Car Messaging Internal ConPol",
                                   "TopicPolicies": "Car Messaging Internal TopicPol",
                                   "MessageHub": "Car Messaging Hub",
                                   "Protocol": "MQTT",
                                   "Interface": "All",
                                   "Description": "Car Messaging internal endpoint"
                                }
                             }
                          }
                        '  \
                     http://127.0.0.1:9089/ima/v1/configuration

Testing your solution

For information about troubleshooting any problems that arise during testing, see Troubleshooting.

Monitoring your solution

There are various statistics that you can monitor. In this scenario, use topic monitor, connection monitor, and subscription monitor to understand the health of the solution.

Strengthening your security

You can increase the level of security of a solution in a number of ways:

  • Using a server certificate.
    1. Create a certificate profile.
    2. Create a security profile to encrypt wire traffic.
      • Set UsePasswordAuthentication to True on your security profile in order to force authentication on user ID and password.
    3. Apply the security profile to your endpoints.
    4. Add the server certificate that you are using to the clients so that the clients can authenticate the server.

    For more information about certificates, see Transport Layer Security.

  • Using a client certificate. You must have a sever certificate installed before you use a client certificate.
    1. Upload a client certificate, or CA certificate and key on each client.
    2. Add the specific client certificate, or the CA certificate to the trustStore on Eclipse Amlen. The trustStore points to a file containing trusted certificates, so that the server can authenticate the client.
  • Using FIPS.

    FIPS increases message security by using cryptography that complies with the Federal Information Processing Standards (FIPS). Enable FIPS mode by setting the FIPS parameter to True. You can set FIPS to True either by using REST Administration APIs, or by using the Amlen WebUI. For more information about enabling FIPS mode, see Configuring security.