Configuring destination mapping rules

To send messages between Eclipse Amlen and IBM® MQ, you must create destination mapping rules. Destination mapping rules are created by associating an Eclipse Amlen topic or queue with a IBM MQ topic or queue. You can create a maximum of 64 destination mapping rules.

Destination mapping rules specify a source topic string or queue name, and define the target topic string or queue. Any message that is published to the source topic, or sent to the source queue, is republished to the target topic, or sent to the target queue. For rules that use topic subtrees, all messages that are published to the topic subtree are either routed to a single queue, are republished to a single topic, or are republished to a reprefixed topic.

You can create, update, view, or delete destination mapping rules by using either the Amlen WebUI or REST Administration APIs.
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.

Transitive rules are not supported. That is, you must not create a set of destination mapping rules that route messages from IBM MQ to Eclipse Amlen and then back to IBM MQ. You must not create a set of destination mapping rules that route messages from Eclipse Amlen to IBM MQ and then back to Eclipse Amlen. Messages that are sent by using transitive rules loop between the rules infinitely. Therefore, any messages that are sent by using these rules never reach their destination.

When you create a destination mapping rule, you must specify the following components:
  • Name
    Specifies a label that identifies the destination mapping rule.
    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:

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

  • Queue manager connection
    Specifies one or more queue manager connections to apply the destination mapping rule to.
    You have a choice when you create mapping rules:
    • You can preserve the order of messages by using a single queue manager connection. This option limits the number of messages that can be processed at any time.
    • You can maximize throughput by using multiple queue manager connections. This option does not preserve the order of messages, as two consecutive messages can be sent to two different queue managers.
    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
    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.
  • Rule type
    Specifies the type of source and destination to be used in the rule.

    The rule type can be any value that is detailed in the following table:

    Table 1. The first column details the valid rule types, the second column details the rule source, and the third column details the rule destination.
    Rule type From: To:
    1 Eclipse Amlen topic IBM MQ queue
    2 Eclipse Amlen topic IBM MQ topic
    3 Eclipse Amlen queue IBM MQ topic
    4 Eclipse Amlen topic IBM MQ topic
    5 Eclipse Amlen topic subtree IBM MQ queue
    6 Eclipse Amlen topic subtree IBM MQ topic
    7 IBM MQ topic subtree Eclipse Amlen topic subtree
    8 IBM MQ topic subtree Eclipse Amlen topic
    9 IBM MQ topic subtree Eclipse Amlen topic subtree
    10 Eclipse Amlen queue IBM MQ queue
    11 Eclipse Amlen queue IBM MQ topic
    12 Eclipse Amlen queue IBM MQ queue
    13 Eclipse Amlen topic IBM MQ queue
    14 Eclipse Amlen topic subtree IBM MQ queue
    Note: With rule type 9, a mapping that results in an Eclipse Amlen topic string with more than 32 levels cannot be mapped correctly because Eclipse Amlen has a maximum topic level of 32. In cases where the level limit is exceeded, the messages are handled as follows:
    • For non-persistent messages, the message is discarded.
    • For persistent messages, the message is retained in a loop between IBM MQ and Eclipse Amlen. In this instance, no further messages can be sent on the affected rule until the looped message is removed from the queue manager.
  • Source
    Specifies the topic string, or queue name, that the destination mapping rule maps from.
    With rule types 5, 6, 7, 8, and 9, the mapping is from a topic subtree. For these rules, the source topic string defines the root of the source tree. Any topic string that begins with that string is then mapped to the destination topic string. The topic subtree is equivalent to using a wildcard. For example, specifying the topic subtree of MQRoot/L1 is equivalent to specifying MQRoot/L1/+ or MQRoot/L1/#. For further examples, see the table.
    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 topic string, or queue name, that the destination mapping rule maps to.
    With rule types 7 and 9, where the mapping is to a topic subtree, the destination topic string defines the root of the destination tree. Messages sent to the subtree of the source topic string are reprefixed with the topic string specified in the destination topic string. The topic subtree is equivalent to using a wildcard. For example, specifying the topic subtree of MQRoot/L1 is equivalent to specifying MQRoot/L1/+ or MQRoot/L1/#. For examples, see the table.
    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: ! # $ % & ( ) * + , - . / : ; < = > ? @"
  • Maximum Messages
    Specifies the maximum number of messages that can be buffered for a destination mapping rule. If the maximum number of messages is reached, messages cannot be published to the Eclipse Amlen topic in the destination mapping rule until the backlog of messages is reduced.
    This option is valid only for destination mapping rules from Eclipse Amlen topics to IBM MQ topics and queues. That is, rule types 1, 2, 5, 6, and 7.
    The value must be in the range 1-20000000. The default value is 5000.
  • Retained Messages
    Specifies which messages are forwarded to a topic as retained messages. By default, after a message is published to a topic and is received by the subscribers, the message is discarded. Setting this parameter ensures that a copy of the message is retained, so that it is sent to future subscribers of the topic.
    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 a topic subtree.

For more information about configuring destination mapping rules by using the Amlen WebUI, see Configuring destination mapping rules by using the Amlen WebUI.

For more information about configuring destination mapping rules by using REST Administration APIs, see Configuring destination mapping rules by using REST Administration APIs.

The following table shows example mappings of source topic strings and queues to target topic strings and queues:

Table 2. A source topic or queue can be mapped to a target topic or queue. Example mappings are shown in this table. The first column contains examples of source topics. The second column contains examples of target topics. The third column explains how such mappings function when messages are published.
Rule type Source Destination Explanation
1 Eclipse Amlen topic:
IMARoot/Level1
 IBM MQ queue:
MQ.QUEUE1
 A message that is published to the Eclipse Amlen topic IMARoot/Level1 is MQPUT to the IBM MQ queue MQ.QUEUE1
2 Eclipse Amlen topic:
IMARoot/L1/Subject1
 IBM MQ topic:
MQRoot/L1/Target
 A message that is published to the Eclipse Amlen topic IMARoot/L1/Subject1 is republished to the IBM MQ topic MQRoot/L1/Target
3 IBM MQ queue:
MQ.QUEUE1
 Eclipse Amlen topic:
IMARoot/L1
 A message that is sent to the IBM MQ queue MQ.QUEUE1 is published to the Eclipse Amlen topic IMARoot/L1
4 IBM MQ topic:
MQRoot/L1/Subject
 Eclipse Amlen topic:
IMARoot/L1/Target
 A message that is published to the IBM MQ topic MQRoot/L1/Subject is republished to the Eclipse Amlen topic IMARoot/L1/Target
5 Eclipse Amlen topic subtree: 
IMARoot/L1
 IBM MQ queue: 
MQ.QUEUE1
 A message that is published to any Eclipse Amlen topic that starts with IMARoot/L1 is MQPUT to the IBM MQ queue MQ.QUEUE1 For example, a message that is published to the Eclipse Amlen topic IMARoot/L1/Subject is MQPUT to the IBM MQ queue MQ.QUEUE1
6 Eclipse Amlen topic subtree: 
IMARoot/L1
 IBM MQ topic: 
MQRoot/L1/Target
 Using a topic subtree is equivalent to using a wildcard. That is, the subtree of IMARoot/L1, is the same as IMARoot/L1/+ or IMARoot/L1/#. Therefore, any message that is published to any Eclipse Amlen topic that starts with IMARoot/L1 is republished to a IBM MQ topic MQRoot/L1/TargetFor example, messages that are published to the Eclipse Amlen topics IMARoot/L1/Subject1, andIMARoot/L1/Subject2 are sent to the IBM MQ topicMQRoot/L1/Target
7 Eclipse Amlen topic subtree: 
IMARoot/L1
 IBM MQ topic subtree: 
MQRoot/L1/L2
 Using a topic subtree is equivalent to using a wildcard. That is, the subtree of IMARoot/L1, is the same as IMARoot/L1/+ or IMARoot/L1/#. Therefore, any message that is published to any Eclipse Amlen topic that starts with IMARoot/L1 is republished to a IBM MQ topic with the same basic topic string, but a different prefix. The prefix is defined by the destination topic string specified. For example, a message that is published to the Eclipse Amlen topic IMARoot/L1/Subject1 is republished to the IBM MQ topic MQRoot/L1/L2/Subject1For example, a message that is published to the Eclipse Amlen topic IMARoot/L1/Subject2/A is republished to the IBM MQ topic MQRoot/L1/L2/Subject2/A
8 IBM MQ topic subtree: 
MQRoot/L1
 Eclipse Amlen topic: 
IMARoot/L1/Target
 Using a topic subtree is equivalent to using a wildcard. That is, the subtree of MQRoot/L1, is the same as MQRoot/L1/+ or MQRoot/L1/#. Therefore, any message that is published to any IBM MQ topic string that starts with MQRoot/L1 is republished to anEclipse Amlen topic IMARoot/L1/TargetFor example, messages that are published to the IBM MQ topics MQRoot/L1/Subject1, andMQRoot/L1/Subject2are sent to the Eclipse Amlen topicIMARoot/L1/Target
9 IBM MQ topic subtree:
MQRoot/L1
 Eclipse Amlen topic subtree: 
IMARoot/L1
 Using a topic subtree is equivalent to using a wildcard. That is, the subtree of MQRoot/L1, is the same as MQRoot/L1/+ or MQRoot/L1/#. Therefore, any message that is published to any IBM MQ topic that starts with MQRoot/L1 is republished to an Eclipse Amlen topic with the same basic topic string, but a different prefix. The prefix is defined by the destination topic string specified. For example, a message that is published to the IBM MQ topic MQRoot/L1/Subject1 is republished to the Eclipse Amlen topic IMARoot/L1/Subject1A message that is published to the IBM MQ topic MQRoot/L1/Subject2/A is republished to the Eclipse Amlen topic IMARoot/L1/Subject2/A
10 Eclipse Amlen queue:
IMA.QUEUE1
 IBM MQ queue:
MQ.QUEUE1
 A message that is sent to the Eclipse Amlen queue IMA.QUEUE1 is MQPUT to the IBM MQ queue MQ.QUEUE1
11 Eclipse Amlen queue:
IMA.QUEUE1
 IBM MQ topic:
MQRoot/L1/Target
 A message that is sent to the Eclipse Amlen queue IMA.QUEUE1 is published to the IBM MQ topic MQRoot/L1/Target
12 Eclipse Amlen queue:
MQ.QUEUE1
 Eclipse Amlen queue:
IMA.QUEUE1
 A message that is sent to the IBM MQ queue MQ.QUEUE1 is forwarded to the Eclipse Amlen queue IMA.QUEUE1
13 IBM MQ topic:
MQRoot/L1/Subject
 Eclipse Amlen queue:
IMA.QUEUE1
 A message that is published to the IBM MQ topic MQRoot/L1/Subject is sent to the Eclipse Amlen queue IMA.QUEUE1
14 IBM MQ topic subtree:
MQRoot/L1
 Eclipse Amlen queue:
IMA.QUEUE1
 A message that is published to any IBM MQ topic that starts with MQRoot/L1 is sent to the Eclipse Amlen queue IMA.QUEUE1For example, messages that are published to the IBM MQ topics MQRoot/L1/Subject1, andMQRoot/L1/Subject2are sent to the Eclipse Amlen queue IMA.QUEUE1