Create or update a subscription policy

Purpose

Creates or updates a subscription policy. Subscription policies are used to control which clients can receive messages from a specified global-shared durable subscription. Subscription policies are also used to control which clients can control the creation and deletion of global-shared durable subscriptions on a specified subscription name.

URI

Use the Eclipse Amlen REST API POST method with the following Eclipse Amlen configuration URI:

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

Object configuration data

Provide SubscriptionPolicy object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json: 


{    
   "SubscriptionPolicy": {
     "<NameOfSubscriptionPolicy>": {
       "Description": "string",
       "Subscription": "string",
       "ActionList": "string",
       "MaxMessages": integer,
       "MaxMessagesBehavior": "RejectNewMessages"|"DiscardOldMessages",
       "ClientID": "string",
       "UserID": "string",
       "GroupID": "string",
       "CommonNames": "string",
       "ClientAddress": "string",
       "Protocol": "string"             
    }
  }
}
Where:
NameOfSubscriptionPolicy
Required.
Specifies the name of the subscription 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 subscription policy is created, this name cannot be changed.
Description
Optional.
Specifies a description for the subscription policy.
If you do not want a description, omit "Description": "description".
Subscription
Required if you are creating a subscription policy.
Specifies the global-shared durable subscription name that the subscription policy applies to.
If you are using MQTT global-shared subscriptions, you must configure a topic policy and a subscription policy. The Topic parameter in the topic policy and the Subscription parameter in the subscription policy must be correctly specified. For more information, see Topic filters for MQTT global-shared subscriptions.
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.
If the subscription policy applies to a global-shared subscription that is to be used by MQTT applications, ensure that you do not include the forward slash character ( /) in Subscription.
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 to ensure that only clients with specific user IDs, group IDs, or client certificate common names can receive messages from a specified global-shared durable subscription. The variables are:
  • ${UserID} for the user ID.
  • ${GroupID} for the group ID.
  • ${CommonName} for the client certificate common name.
ActionList
Required if you are creating a subscription policy.
Specifies which messaging actions can be used by clients that connect to endpoints associated with this subscription policy.
You can specify the following values for a subscription policy for global-shared durable subscriptions. To specify more than one, separate each value with a comma:
  • Receive

    Allows clients to receive messages from the global-shared durable subscription that is specified in the Subscription field of the subscription policy.

  • Control

    Allows global-shared durable subscriptions to be created and deleted. The name of the global-shared durable subscription is specified in the Subscription field of the subscription policy.

    To create or delete a global-shared durable subscription, a client must be allowed to receive messages. Therefore, if you select Control, you must also select Receive within the same subscription policy.

MaxMessages
Required for a global-shared durable subscription.
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 only to global-shared 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.

Specify at least one of the following filters:

ClientID
Specifies the client ID that is allowed to use the messaging actions that are specified in the queue policy. The client ID is allowed to use the messaging actions only on the queues that are specified in the policy.
You can use an asterisk (*) at the end of the value to match 0 or more characters.
To use the default value, where all client ID values are allowed to use the actions, omit "ClientID":"ClientID"
UserID
Specifies the messaging user ID that is allowed to use the messaging actions that are specified in the subscription policy. The messaging user ID is allowed to use the messaging actions only on the topics that are specified in the policy.
You can use an asterisk (*) at the end of the value to match 0 or more characters.
To use the default value, where all user ID values are allowed to use the actions, omit "UserID": "UserID".
GroupID
Specifies the messaging group that is allowed to use the messaging actions that are specified in the subscription policy.
You can use an asterisk (*) at the end of the value to match 0 or more characters.
To use the default value, where all groups are allowed to use the actions, omit "GroupID": "GroupID".
CommonNames
Specifies the client certificate common name that must be used for a client to be allowed to use the actions that are specified in the subscription policy.
You can use an asterisk (*) at the end of the value to match 0 or more characters.
To use the default value, where all client certificates are allowed to use the actions, omit "CommonNames": "CommonNames".
ClientAddress
Specifies the client IP addresses that are allowed to use the messaging actions that are specified in the subscription policy.
The IP address can contain an asterisk (*), or a comma-separated list of IPv4 or IPv6 addresses or ranges. For example, 192.0.2.32, 192.0.0.0, 192.0.2.0-192.0.2.100. The range must be specified from low to high.
However, each IPv6 address must be enclosed in brackets [ ] either when expressed singly or in a range of addresses. IPv6 addresses cannot contain asterisks.
The maximum number of client addresses that you can specify is 20.
To use the default value, where all client IP addresses are allowed to connect, omit "ClientAddress":"IP_Address" or specify "ClientAddress":"*".
Protocol
Specifies which protocols are allowed to use the actions that are specified in the subscription policy.
You can choose from JMS and MQTT protocols. If there are any protocol plug-ins installed on the Eclipse Amlen server, you can specify these as well. To specify more than one value, separate each value with a comma. To select all protocols, specify a null value for Protocol or omit the parameter from the command.

Usage Notes®

  • Capitalization and double quotation marks must be used as shown.
  • Each of the filters, ClientAddress, UserID, GroupID, CommonNames, and Protocol, is applied in combination. If you specify several filters, each condition must be met in order for the actions that are specified in the messaging policy to be allowed. For each filter that you do not specify, all values for that filter are allowed.

    For example, a subscription policy is created that specifies: "ActionList": "Receive" "GroupID": "SILVER" "UserID": "SIL*" "Protocol": "JMS". A client with User ID SIL1, in group SILVER, that is using JMS can receive messages. A client with a User ID SIL2, in group GOLD, that is using JMS cannot receive messages because not all of the filter conditions are met.

Related REST Administration APIs

Example

Creates a subscription policy called "MySubscriptionPolicy" by using cURL:

curl -X POST  \
   -H 'Content-Type: application/json'  \
   -d  '{                          
           "SubscriptionPolicy": {   
               "MySubscriptionPolicy": {
                "Description": "Subscription policy to authorize a client to  receive messages from a global-shared durable subscription.",
                "Subscription": "*",
                "ClientAddress": "*",
                "ActionList": "Receive"
              }
          }
      }
  '   \
http://127.0.0.1:9089/ima/v1/configuration/
An example response to the POST method:

{        
  "Version": "v1",
  "Code": "CWLNA6011",
  "Message": "The requested configuration change has completed successfully."
}