Integration of IBM MQ Telemetry with queue managers

The MQTT client is integrated with IBM® MQ as a publish/subscribe application. It can either publish or subscribe to topics in IBM MQ, creating new topics, or using existing topics. It receives publications from IBM MQ as a result of MQTT clients, including itself, or other IBM MQ applications publishing to the topics of its subscriptions. Rules are applied to decide the attributes of a publication.

Many of the attributes associated with topics, publications, subscriptions, and messages that are provided by IBM MQ, are not supported. MQTT client to IBM MQ publish/subscribe broker and IBM MQ to an MQTT client describe how attributes of publications are set. The settings depend on whether the publication is going to or from the IBM MQ publish/subscribe broker.

In IBM MQ publish/subscribe topics are associated with administrative topic objects. The topics created by MQTT clients are no different. When an MQTT client creates a topic string for a publication the IBM MQ publish/subscribe broker associates it with an administrative topic object. The broker maps the topic string in the publication to the nearest administrative topic object parent. The mapping is the same as for IBM MQ applications. If there is no user created topic, the publication topic is mapped to SYSTEM.BASE.TOPIC. The attributes that are applied to the publication are derived from the topic object.

When an IBM MQ application, or an administrator creates a subscription, the subscription is named. List subscriptions using MQ Explorer, or by using runmqsc or PCF commands. All MQTT client subscriptions are named. They are given a name of the form: ClientIdentifier:Topic name

MQTT client to IBM MQ publish/subscribe broker

An MQTT client has sent a publication to IBM MQ. The telemetry (MQXR) service converts the publication to an IBM MQ message. The IBM MQ message contains three parts:
  1. MQMD
  2. RFH2
  3. Message

MQMD properties are set to their default values, except where noted in Table 1.

Table 1. MQMD
MQMD field Type Value
Format MQCHAR8

MQFMT_RF_HEADER_2

UserIdentifier MQCHAR12
Set to one of:
  • MqttClient.ClientIdentifier
  • MqttConnectOptions.UserName
  • A user ID set by the IBM MQ administrator for the telemetry channel.
Priority MQLONG

MQPRI_PRIORITY_AS_Q_DEF (Default for IBM MQ, which is different to JMS that has a default of 4.)

Persistence MQLONG
  • QoS=0→MQPER_NOT_PERSISTENT
  • QoS=1→MQPER_PERSISTENT
  • QoS=2→MQPER_PERSISTENT

The RFH2 header does not contain an <msd> folder to define the type of the JMS message. The telemetry (MQXR) service creates the IBM MQ message as a default JMS message. The default JMS message-type is a jms-bytes message. An application can access additional header information as message properties; see Message properties.

RFH2 values are set as shown in Table 2. The Format property is set in the RFH2 fixed header and the other values are set in RFH2 folders.

Table 2. RFH2
RFH2 property Type/Folder Header
Format MQCHAR8

MQFMT_NONE

ClientIdentifier mqtt/clientId

Copy MqttClient.ClientIdentifier with a length of 1...23 bytes.

QoS mqtt/qos

Copy QoS from incoming MQTT message.

Message ID mqtt/msgid

Copy Message ID from incoming MQTT message, if QoS is 1 or 2.

MQIsRetained mqps/Ret

Set if the original MQTT publication was sent with the RETAIN property set and the message is received as a retained publication.

MQTopicString mqps/Top

The topic to which the MQTT message was published.

The payload in an MQTT publication is mapped to the contents of an IBM MQ message:

Table 3. Message contents
Message contents Type Contents
Buffer MQBYTE n

Copy of bytes from incoming MQTT message. The length can be zero.

IBM MQ to an MQTT client

A client has subscribed to a publication topic. An IBM MQ application has published to the topic, resulting in a publication being sent to the MQTT subscriber by the IBM MQ publish/subscribe broker. Alternatively, an IBM MQ application has sent an unsolicited message directly to an MQTT client. Table 4 describes how the fixed message headers are set in the message that is sent to the MQTT client. Any other data in the IBM MQ message header, or any other headers, are discarded. The message data in the IBM MQ message is sent as the message payload in the MQTT message, with no alteration. The MQTT message is sent to the MQTT client by the telemetry (MQXR) service.

Table 4. MQTT fixed header properties
MQTT field Type Value
DUP boolean

Set if QoS = 1 or 2, and the message was sent to this client in a previous transmission, and the message has not been acknowledged after a time.

QoS int
The way the value of QoS in an outgoing publication from the publish/subscribe broker in IBM MQ is set depends on the incoming publication. It depends on whether the incoming publication was sent from an MQTT client, or from an IBM MQ application.
MQTT
Lower value of the QoS in the incoming publication, and in the QoS requested by the subscriber.
IBM MQ
Lower value of the QoS derived from the incoming publication:
  • MQPER_NOT_PERSISTENT→QoS=0
  • MQPER_PERSISTENT→QoS=2
and the QoS requested by the subscriber. If the message is sent to the client without a subscription, QoS is set by default to 2. A client can alter this value by subscribing to DEFAULT.QoS with a different QoS.
RETAIN boolean

Set if the incoming publication has the retained property set.

Table 5 describes how the variable message headers are set in the MQTT message that is sent to the MQTT client.

Table 5. MQTT Variable header properties
MQTT field Type Value
Topic name String

The topic string the message was published with.

Message ID String

The last 2 bytes of the MQMD.MsgId property of the publication when it is placed in SYSTEM.MQTT.TRANSMIT.QUEUE.

Payload byte[]

Direct copy of bytes from incoming publication to the publish/subscribe broker. The length can be zero.