Creating and updating a destination mapping rule by using REST Administration APIs

System administrators can create and update destination mapping rules by using the REST Administration APIs.

Before you can create a destination mapping rule, you must create the queue manager connection that you want to use in the rule. For more information about creating a queue manager connection, see Configuring queue manager connections.

You can create and update a destination mapping rule by using a REST Administration API, or by using the Amlen WebUI. For more information about using the Amlen WebUI to create or update a destination mapping rule, see Configuring destination mapping rules by using the Amlen WebUI.
Note: You must disable a destination mapping rule before you can make any changes to that rule. After editing, you must enable the destination mapping rule in order for the changes that you made to take effect. To edit a queue manager connection, all destination mapping rules that use that queue manager connection must be disabled. You do not need to restart the mqconnectivity process in order for any changes to take effect.
  1. To create or update a destination mapping rule, use the Eclipse Amlen REST API POST method with the following Eclipse Amlen configuration URI:

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

  2. Provide DestinationMappingRule object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown. 
    
{    
  "DestinationMappingRule": {
    "<NameOfDestinationMappingRule>": {
      "QueueManagerConnection": "string",
      "Enabled": true|false,
      "RuleType": integer,
      "Source": "string",
      "Destination": "string",
      "MaxMessages": integer,

      "RetainedMessages": true|false           
     }
   }
}
    Where:
    • NameOfDestinationMappingRule
      Specifies the name of the destination mapping rule. After the destination mapping rule is created, you cannot change this name.
      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:

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

    • QueueManagerConnection
      Specifies the name of one or more queue manager connections. The queue manager connections identify which queue managers the rule maps to. You can specify more than one queue manager connection by using a comma-separated list.
      To preserve the order of the messages, you must use only one queue manager connection for each destination mapping rule. If you create multiple destination mapping rules with the same destination, but which use different queue manager connections, the message order is not preserved.
    • Enabled=true|false
      Specifies whether the rule is enabled (true) or disabled (false).
      The default value is true.
      To edit a destination mapping rule, the rule must first be disabled. Once all changes are complete, the rule must be enabled for any changes to take effect.
    • RuleType
      Specifies the rule type that you want to use. For more information about the values that you can use, see Configuring destination mapping rules.
    • Source
      Specifies the source topic string or queue for the rule.
      The source that is specified must follow the naming rules for the source type.
      For IBM MQ queues, the value can contain characters in the ranges a-z, A-Z, and 0-9, and any of the following characters:% . / _
      For Eclipse Amlen, the value 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, quotation mark, or any of the following special characters:

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

    • Destination
      Specifies the destination topic string or queue for the rule.
      The destination that is specified must follow the naming rules for the destination type.
      For IBM MQ queues, the value can contain characters in the ranges a-z, A-Z, and 0-9, and any of the following characters:% . / _
      For Eclipse Amlen, the value 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, quotation mark, or any of the following special characters:

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

    • MaxMessages
      Optional.
      Specifies the maximum number of messages that can be buffered for the destination mapping rule.
      This option is valid only for destination mapping rules from Eclipse Amlen topics to IBM MQ. That is, rule types 1, 2, 5, 6, and 7.
      The value must be in the range 1-20000000. The default value is 5000.
    • RetainedMessages
      Optional.
      Specifies which messages are forwarded as to a topic as retained messages.
      This parameter overrides the retained message setting of the original message publisher.
      This option is only valid for destination mapping rules that forward messages to a topic or topic subtree.
      This value can be one of the following values:
      • All
        All messages are forwarded to the topic as retained messages.
      • None
        No messages are forwarded to the topic as retained messages.
      The default value is None.

This example demonstrates creating a destination mapping rule called exampleRule. It uses rule type 1: Eclipse Amlen topic to IBM MQ queue.


curl -X POST \
   -H 'Content-Type: application/json'  \
   -d  '{     
         "DestinationMappingRule": {
           "exampleRule": {
            "QueueManagerConnection": "MyQMC",
            "Enabled": true,
            "RuleType": 1,
            "Source": "ISMRoot/Level1",
            "Destination": "Queue1",
            "MaxMessages": 7000,
            "RetainedMessages": true           
          }
        } 
      }
 '  \
http://127.0.0.1:9089/ima/v1/configuration/

The following example shows an example response to the POST method:


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