Create or update a destination mapping rule

Purpose

Creates or updates a destination mapping rule. A destination mapping rule maps an Eclipse Amlen topic or queue to a IBM® MQ topic or queue.

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 DestinationMappingRule object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json: 


{    
  "DestinationMappingRule": {
    "<NameOfDestinationMappingRule>": {
      "QueueManagerConnection": "string",
      "Enabled": true|false,
      "RuleType": integer,
      "Source": "string",
      "Destination": "string",
      "MaxMessages": integer,

      "RetainedMessages": All|None           
     }
   }
}

Where

NameOfDestinationMappingRule
Required.
Specifies a name for 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 equals 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.
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 for any changes that you make to take effect.
Enabled: true|false
Specifies whether the destination mapping 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.
The rule type can be any of the values that are detailed in the table in the topic 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
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: All|None
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.

Usage Notes®

  • You must disable a destination mapping rule before you can make any changes to that rule. After you have edited the rule, you must enable that destination mapping rule in order for the changes 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 mqconn process in order for any changes to take effect.

Related REST Administration APIs

Example

Creates a destination mapping rule called exampleRule by using cURL::

curl -X POST \
   -H 'Content-Type: application/json'  \
   -d  '{     
         "DestinationMappingRule": {
           "exampleRule": {
            "QueueManagerConnection": "MyQMC",
            "RuleType": 1,
            "Source": "ISMRoot/Level1",
            "Destination": "Queue1",
            "MaxMessages": 7000,
            "Enabled": true,
            "RetainedMessages": All          
          }
        } 
      }
 '  \
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."
}