Creating and updating a topic policy by using REST Administration APIs

http://<admin-endpoint-IP:Port>/ima/v1/configuration/

{    
   "TopicPolicy": {
     "<NameOfTopicPolicy>": {
       "Description": "string",
       "Topic": "string",
       "ActionList": "string",
       "MaxMessages": integer,
       "MaxMessagesBehavior": "RejectNewMessages"|"DiscardOldMessages",
       "MaxMessageTimeToLive": "string",
       "DisconnectedClientNotification": true|false,
       "ClientID": "string",
       "UserID": "string",
       "GroupID": "string",
       "CommonNames": "string",
       "ClientAddress": "string",
       "Protocol": "string"             
    }
  }
}

NameOfTopicPolicy

Required.

Specifies the name of the topic policy.

The name must not have leading or trailing spaces and cannot contain control characters, commas, double quotation marks, backslashes, or equal signs. The first character must not be a number or any of the following special characters:

! # $ % & ' ( ) * + - . / : ; < > ? @

After the topic policy is created, you cannot change this name.

Description

Optional.

Specifies a description for the topic policy.

If you do not want a description, omit "Description":"description".

Topic

Required.

Specifies the topic string or strings that the topic policy applies to.

You can use an asterisk (*) as a wildcard. For example, to apply the topic policy to topic strings TOPICA/#, enter a topic of TOPICA/*. You must take care when you use a wildcard to ensure that you do not grant greater authority to topics than intended. For more information about how wildcard characters can be used, see Wildcards.

The dollar sign ($) and asterisk (*) have special meanings in the Topic field. To use these characters as literals, use ${$} for a dollar sign, and use ${*} for an asterisk.

You can use variable substitution in the topic string to ensure that only clients with specific user IDs, group IDs, client IDs, or client certificate common names can access a topic. The variables are:

• ${UserID} for the user ID.
• ${GroupID} for the group ID.
• ${ClientID} for the client ID.
• ${CommonName} for the client certificate common name.

For example, if a topic string in a topic policy is ExampleTopic/TopicA/${ClientID}, a client with an ID of client_a can access topic ExampleTopic/TopicA/client_a. A client with an ID of client_b cannot access topic ExampleTopic/TopicA/client_a, but can access ExampleTopic/TopicA/client_b.

ActionList

Required.

Specifies which messaging actions can be used by clients that connect to endpoints associated with this topic policy.

You can specify the following values for a topic policy. To specify more than one, separate each value with a comma:

• Publish

  Allows clients to publish to the topic that is specified in the topic policy.

• Subscribe

  Allows clients to subscribe to the topic that is specified in the topic policy.

MaxMessages

Optional.

Specifies the maximum number of messages that are kept for a subscription. This value is a guideline, rather than an absolute limit. If the system is running under stress, then the number of buffered messages on a subscription might be slightly higher than the MaxMessages value.

The default value is 5000.

MaxMessagesBehavior

Optional.

Specifies the behavior that is applied when the number of messages in the buffer for a subscription reaches the max messages value. That is, when the buffer for a subscription is full. The behavior is applied to both durable and non-durable subscriptions.

The behavior can be one of the following options:

• RejectNewMessages

  New messages are not accepted on the buffer for the subscription.

• DiscardOldMessages

  A percentage of the old messages on the buffer for the subscription are discarded. If a retained message is one of the old messages, it is discarded. The quality of service, persistence, and priority of the message does not prevent a message from being discarded. Therefore, if all messages must be received in order for your applications to function correctly, you cannot set MaxMessagesBehavior to DiscardOldMessages.

The default behavior is RejectNewMessages.

MaxMessageTimeToLive

Optional.

Specifies the maximum time, in seconds, that a published message that is associated with the topic policy can exist for in Eclipse Amlen.

The value must be either unlimited or in the range 1-2147483647.

The default value is unlimited and means that messages will not expire unless the publishing application specifies a time for messages to exist for.

This value is applied only when the topic policy includes an action of publish.

Ensure that client and server times are synchronized in order to minimize the possibility of expired messages being received.

DisconnectedClientNotification: true|false

Optional.

Specifies whether notification messages are published for disconnected MQTT clients on arrival of a message.

The default value is false.

This value is applied only when the MQTT protocol is used.

The notification messages are published to the reserved system topic $SYS/DisconnectedClientNotification

You can check that the configuration of your policy is as expected by using the Eclipse Amlen REST Administration API GET method. For more information about the GET method, see Viewing configuration details of objects that can be named by using REST Administration APIs.