Integration of WebSphere MQ Telemetry with queue managers

The MQTT client is integrated with WebSphere MQ as a publish/subscribe application. It can either publish or subscribe to topics in WebSphere MQ, creating new topics, or using existing topics. It receives publications from WebSphere MQ as a result of MQTT clients, including itself, or other WebSphere 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 WebSphere MQ, are not supported. MQTT client to WebSphere MQ publish/subscribe broker and WebSphere 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 WebSphere MQ publish/subscribe broker.

In WebSphere 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 WebSphere 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 WebSphere 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 a WebSphere MQ application, or an administrator creates a subscription, the subscription is named. List subscriptions using WebSphere 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 WebSphere MQ publish/subscribe broker

An MQTT client has sent a publication to WebSphere MQ. The telemetry (MQXR) service converts the publication to a WebSphere MQ message. The WebSphere 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 WebSphere MQ administrator for the telemetry channel.
Priority MQLONG

MQPRI_PRIORITY_AS_Q_DEF (Default for WebSphere 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 WebSphere 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 a WebSphere MQ message:

Table 3. Message contents
Message contents Type Contents
Buffer MQBYTEn

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

WebSphere MQ to an MQTT client

A client has subscribed to a publication topic. A WebSphere MQ application has published to the topic, resulting in a publication being sent to the MQTT subscriber by the WebSphere MQ publish/subscribe broker. Alternatively, a WebSphere 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 WebSphere MQ message header, or any other headers, are discarded. The message data in the WebSphere 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 WebSphere MQ is set depends on the incoming publication. It depends on whether the incoming publication was sent from an MQTT client, or from a WebSphere MQ application.
MQTT
Lower value of the QoS in the incoming publication, and in the QoS requested by the subscriber.
WebSphere 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.