Create or update a queue policy

Purpose

Creates or updates a queue policy. A queue policy is a type of messaging policy that is used to control which clients can send to, receive from, or browse a specified queue.

URI

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

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

Object configuration data

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

{    
   "QueuePolicy": {
     "<NameOfQueuePolicy>": {
       "Description": "string",
       "Queue": "string",
       "ActionList": "string",
       "MaxMessageTimeToLive": "string",
       "ClientID": "string",
       "UserID": "string",
       "GroupID": "string",
       "CommonNames": "string",
       "ClientAddress": "string",
       "Protocol": "string"             
    }
  }
}
Where:
NameOfQueuePolicy
Required.
Specifies the name of the queue 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 queue policy is created, this name cannot be changed.
Description
Optional.
Specifies a description for the queue policy.
If you do not want a description, omit "Description": "description".
Queue
Required if you are creating a queue policy.
Specifies the queue or queues that the queue policy applies to.
You can use an asterisk (*) as a wildcard. 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 Queue field. To use these characters as literals, use ${$} for a dollar sign, and use ${*} for an asterisk.
You can use variable substitution in the queue field to ensure that only clients with specific user IDs, group IDs, client IDs, or client certificate common names can access a queue. 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 queue name in a queue policy is ${ClientID}, then a client with an ID of client_a can access queue client_a. A client with an ID of client_b cannot access queue client_a, but can access queue client_b.
ActionList
Required if you are creating a queue policy.
Specifies which messaging actions can be used by clients that connect to endpoints associated with this queue policy.
You can specify the following values for a queue policy. To specify more than one, separate each value with a comma:
  • Send

    Allows clients to send messages to the queue that is specified in the queue policy.

  • Receive

    Allows clients to receive messages from the queue that is specified in the queue policy.

  • Browse

    Allows clients to browse messages on the queue that is specified in the queue policy.

MaxMessageTimeToLive
Optional.
Specifies the maximum time, in seconds, that a published message that is associated with the queue 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 send.
Ensure that client and server times are synchronized in order to minimize the possibility of expired messages being received.

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 queue policy. The messaging user 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 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 queue policy. The messaging group 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 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 queue policy. The client certificate common name allows clients 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 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 queue policy. The client IP addresses are allowed to use the messaging actions only on the queues that are specified in the 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 queue policy on the queues that are specified in the policy.
You can choose from JMS and any protocol plug-ins that have specified support for queues. 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, ClientID, 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 queue policy is created that specifies: "ActionList": "Publish" "GroupID": "SILVER" "ClientID": "SIL*" "Protocol": "JMS". A client with User ID SIL1, in group SILVER, that is using JMS can publish messages. A client with a User ID SIL2, in group GOLD, that is using JMS cannot publish messages because not all of the filter conditions are met.

Related REST Administration APIs

Example

Creates a queue policy called "MyQueuePolicy" by using cURL:

curl -X POST  \
   -H 'Content-Type: application/json'  \
   -d  '{                          
           "QueuePolicy": {   
               "MyQueuePolicy": {
                "Description": "Queue policy to authorize a client to send messages to and receive messages from a queue.",
                "Queue": "*",
                "ClientID": "*",
                "ActionList": "Send,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."
}