Configuring administrative subscriptions

You might want to use administrative subscriptions (admin subscriptions) to allow ephemeral clients to share a subscription that is not removed, along with any buffered messages, in the event of all clients being disconnected due to a network outage. Examples of ephemeral clients might include MQTT v3.1.1 clients with a clean session flag set to true, or MQTT v5 clients with a session expiry interval set to 0.

When multiple MQTT clients are connected to a shared subscription, and one client disconnects after receiving messages but before sending an acknowledgment, it can be useful to have those messages sent to another client rather than waiting for the original client to reconnect and complete transmission of the acknowledgment. Resending the messages to another client prevents the messages waiting for the original client to reconnect but does create duplicate messages, as the message is sent to two clients that might both process the message.

For all three types of subscription, the name of the configuration object must match the subscription name. For admin subscriptions, the name must include the topic filter and a leading forward slash character '/' . For the other subscriptions, the name must not contain slashes, and the topic filter must form part of the definition. This naming convention makes it possible to link the results that come from Subscription monitor with the configuration objects.

The following example shows the format of the payload that is required to create an admin subscription:

"AdminSubscription": {
                    "/{ShareName}/{TopicFilter}": {      
                          "SubscriptionPolicy": "{PolicyName}",
                          "MaxQualityOfService": {MaxQualityOfService},
                          "AddRetainedMsgs": {AddRetainedMsgs},
                          "QualityOfServiceFilter": "{QualityOfServiceFilter}"
                          }
                      }

The following example shows the format of the payload that is required to create a global-shared durable admin subscription:

"DurableNamespaceAdminSub": {
                     "{SubName}": {
                             "SubscriptionPolicy": "{PolicyName}",
                             "TopicFilter": "{TopicFilter}",
                             "MaxQualityOfService": {MaxQualityOfService},      
                             "AddRetainedMsgs": {AddRetainedMsgs},
                             "QualityOfServiceFilter": "{QualityOfServiceFilter}"   
                             } 
                       }

The following example shows the format of the payload that is required to create a global-shared non-durable admin subscription:

"NonpersistentAdminSub": {
                  "{SubName}": { 
                      "TopicPolicy": "{PolicyName}",
                      "TopicFilter": "{TopicFilter}",
                      "MaxQualityOfService": {MaxQualityOfService}, 
                      "AddRetainedMsgs": {AddRetainedMsgs},
                      "QualityOfServiceFilter": "{QualityOfServiceFilter}"
                          }
                    }

These types of subscription are not created by a connected client application, and therefore do not come through an endpoint. The policies that are used to provide the subscription properties do not have to appear on an endpoint either, so you can define these types of subscription with specific policies that are not used for authorization, and that use other policies on the endpoint to allow consumers to use the subscription. This configuration means that it is possible to have a subscription policy that only allows a 'Read' action from a subscription, because the creation of the subscription is handled by the administrative subscription.

Subscription monitoring results include a ConfigType field for subscriptions that have an associated configuration object. The ConfigType can be set to either AdminSubscription, DurableNamespaceAdminSub, or NonpersistentAdminSub so that a user can see which object type is associated with the subscription.

To delete a subscription that has an associated configuration type, use the configuration/ConfigType interface to ensure that the configuration and engine view of the subscriptions is consistent. Using the service/Subscription interface to delete the subscription generates an error message.

When deleting a subscription, the additional query parameter, DiscardSharers, can be set to either false or true. A value of false means that the delete request stops the subscription from having an associated ConfigType, so that the subscription is deleted when all clients stop sharing it. A value of true additionally discards sharers, so the subscription is deleted. The default value is false.