# 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 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.

<figure><img src="https://639096190-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfDpOJO2upcq5EpoSahvK%2Fuploads%2Fgit-blob-ef1686bc38c461e73eb7f4a5832c82d7031172f2%2Fusers_update_advanced_mode.png?alt=media" alt=""><figcaption><p>This will extend the dialog with an <code>Additional permissions</code> section.</p></figcaption></figure>

<figure><img src="https://639096190-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfDpOJO2upcq5EpoSahvK%2Fuploads%2Fgit-blob-3afe80178e0c3343d8397676637d00244f1a978b%2Fusers_update_advanced_view.png?alt=media" alt=""><figcaption></figcaption></figure>

2. Edit the MQTT Publish Prefix

<figure><img src="https://639096190-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfDpOJO2upcq5EpoSahvK%2Fuploads%2Fgit-blob-3f10a213077c89f459036bc291b3c149e28d6f2e%2Fusers_update_mqtt_prefix.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
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.
{% endhint %}

## 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:

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

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