Adding a MQTT Publish Prefix for Users

In Connectware it is possible to configure specific users so that every MQTT message published by this user gets an additional prefix added to its MQTT topic. That is, if a user UserA has a configured MQTT publish prefix topicA/, and once this user publishes a message to topic some/values, the message will actually be published on the topic topicA/some/values.

This feature simplifies the configuration for use cases where a fixed routing to a downstream application is required. This could be achieved just as well by using Mapping resources, but those would require an additional MQTT message transfer per topic mapping, which can be skipped by the prefix feature. Hence this feature is particularly suited for high-throughput installations with high performance in the MQTT message delivery.

Note: The required MQTT write permissions for this user must be specified including the MQTT prefix, because the permissions should specify the eventual locations on the global MQTT topic tree. In the above example, an UserA with prefix topicA/ would need the MQTT write permission for topicA/some/values in order to be allowed to write to that target topic. If it is needed to omit the prefix in the permission specification, MQTT wildcards might be a useful placeholder instead of the publish prefix, for example by specifying +/some/values.

The configuration of the MQTT prefix can be done either by HTTP requests at the REST endpoint /api/users/<userId>, or in the Admin-UI when editing users in the user management.

Admin-UI Configuration

In the Admin-UI, to add an MQTT prefix to an existing user, edit the MQTT Publish Prefix text field in the Edit User dialog.

1. Toggle the Advanced mode switch in the top right of the dialog.

This will extend the dialog with an Additional permissions section.

2. Edit the MQTT Publish Prefix

The configured MQTT prefix should include the trailing topic level separator / at the end! The topic prefixing feature will not insert any separator automatically, hence the trailing separator must be part of the configuration here.

Example

As an example for setting up and validating a publishing prefix for user newuser:

1. Add the MQTT prefix route-to-downstream/ using the Edit User dialog as explained above.

2. Add an MQTT write permission for the topic ‘route-to-downstream/my-topic’ (i.e. including the prefix) for this user on the user’s management screen.

To validate that this setting works as expected, one can send some MQTT message with some MQTT client, for example the mosquitto_sub and mosquitto_pub command line tools (need to be installed before).

3. Subscribe for a topic route-to-downstream/my-topic with the following command:

mosquitto_sub -h 127.0.0.1 -p 1883 -u admin -P <ADMIN PASSWORD> \
-t 'route-to-downstream/my-topic'

4. Publish a message on the topic my-topic with the following command:

mosquitto_pub -h 127.0.0.1 -p 1883 -u newuser -P <PASSWORD NEW USER> \
-t 'my-topic' -m 'Hello World'

The subscribed client should then receive the published message ‘Hello World’ on the prefixed topic route-to-downstream/my-topic.