subscribeToMq

Add or remove a client's subscriptions

The "subscribeToMq" action returns the retained message of each successfully subscribed topic. The server processes the retained message using the default "variantFormat" value, which is "json". This can be a problem if the retained message contains non-JSON data. To ensure your application can process binary payloads in messages, add "variantFormat": "binary" and "binaryFormat": "base64" or "binaryFormat": "hex" to the "responseOptions" property of the "subscribeToMq" action. 

Your application must retrieve a retained message from the response to the "subscribeToMq" action because it is the only way to retrieve it when using the MQ actions. A subsequent call to the "getMessagesFromMqApiSession" action will not return the retained message.  

You can use the "subscribeToMq" action to manage the subscriptions of any session without disconnecting an MQTT client as long as your account has permission to do so. Thus, you can centrally manage the subscriptions for MQTT and MQ API sessions.

Use the required "clientName" property to identify the client's session. An MQTT or MQ API session with that client identifier must already exist; otherwise, the action returns an error. The FairCom server tracks session statistics so you can monitor the health of a client and its session, including the timestamp of the last received message, the client's subscription receive rate, the topics the session subscribes to, etc.

The "subscriptionActions" property contains a list of subscription objects that can add or remove a topic filter from a client's subscriptions.

  • Use the required "subscriptionAction" property to add or remove a topic filter: "add" adds a topic filter to the subscription and "remove" removes it. 
  • Use the required "topicFilter" property to specify a wildcard topic to subscribe to multiple topics. 
  • Use the optional "subscriptionIdentifier" property to assign a unique identifier to the subscription. When the FairCom server sends an MQTT 5 message to the client, it includes the subscription identifier to help the client identify the subscription quickly and easily.
  • Use the optional "includeExpiredMessages": true to include expired messages in the subscription. It defaults to false.
  • Use the optional "receiveRetainedMessages" property to control when the server sends retained messages to your subscription, which includes never sending the retained message, sending it only when the client subscribes for the first time, or sending it each time the client subscribes. 
  • Use the optional "receiveMyMessages" property to prevent or allow the server to send messages to a client that the client published. 

Tip Use "subscribeToMq" to configure subscriptions for any MQ API and MQTT client. You can set MQTT 5 subscription properties for an MQTT 3.1.1 client. You can centrally manage subscriptions for clients. 

Note The account logged into the MQ API must have permission to access the session identified by "clientName".

 

Request example

Minimal

{
  "action": "subscribeToMq",
  "params": {
    "clientName": "client1",
    "subscriptionActions": [
      {
        "subscriptionAction": "add",
        "topicFilter": "test/topic1"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": "00000001"
}
 
 

Maximal

{
  "apiVersion": "1.0",
  "api": "mq",
  "action": "subscribeToMq",
  "params": {
    "clientName": "client1",
    "subscriptionActions": [
      {
        "subscriptionAction": "add",
        "topicFilter": "myTopic",
        "qos": 0,
        "subscriptionIdentifier": 268435455,
        "binaryFormat": "base64",
        "includeExpiredMessages": true,
        "receiveMyMessages": false,
        "receiveRetainedMessages": "onSubscription",
        "receiveRetainedFlagAsPublished": true,
        "userProperties": [
          {
            "key": "some key",
            "value": "some value"
          }
        ]
      },
      {
        "subscriptionAction": "add",
        "topicFilter": "some/topic2/name/#",
        "userProperties": [
          {
            "key": "some key",
            "value": "some value"
          }
        ]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": "00000001",
  "debug": "max"
}
 
 

 

Response example

Success

Notice that the subscription object’s "errorCode" and "errorMessage" properties include the error information, but the response’s the subscription object’s "errorCode" and "errorMessage" properties do not.

{
  "authToken": "authToken",
  "result": {
    "subscriptions": [
      {
        "matchingTopics": [
        ],
        "topicFilter": "Test/Topic1",
        "errorCode": 0,
        "errorMessage": "",
        "debugInfo": {
        }
      },
      {
        "matchingTopics": [
        ],
        "topicFilter": "Test/Topic2",
        "errorCode": 0,
        "errorMessage": "",
        "debugInfo": {
        }
      }
    ]
  },
  "requestId": "5",
}
 
 

Failure

When using the "subscribeToMq" action to subscribe to one or more topics, a failure of one subscription does not set the "errorCode" to a failure value. This is because some topics may be successfully subscribed to and some may not. The caller must check the "subscriptions" property in the response. It is an array of subscription objects and each object contains the status of each topic in the subscription request. If a topic has an error, the subscription object’s "errorCode" and "errorMessage" properties include the error information. 

Notice that the subscription object’s "errorCode" and "errorMessage" properties include the error information, but the response’s the subscription object’s "errorCode" and "errorMessage" properties do not. 

{
  "authToken": "authToken",
  "result": {
    "subscriptions": [
      {
        "matchingTopics": [
          "myTopic"
        ],
        "topicFilter": "myTopic",
        "retainedMessages": [
          {}
        ],
        "errorCode": 12012,
        "errorMessage": "Not able to subscribe - 12012 - Invalid JSON payload. Please retry with [variantformat] of [variantObject] to identify the correct message payload format.",
        "debugInfo": {}
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

clientName

 The "clientName" property specifies the unique name that identifies the client to the FairCom MQ engine. Optional with default of "" string 0 to 65,550 bytes

subscriptionActions

The "subscriptionActions" property adds or removes a topic filter from a client's subscriptions. Each subscription object contains a "topicFilter" and an optional "subscriptionIdentifier".

  • Use the required "subscriptionAction" property to add or remove a topic filter: "add" adds a topic filter to the subscription and "remove" removes it. 
  • Use the required "topicFilter" property to a wildcard topic to subscribe to multiple topics. 
  • Use the optional "subscriptionIdentifier" property to assign a unique identifier to the subscription. When the FairCom server sends an MQTT 5 message to the client, it includes the subscription identifier to help the client identify the subscription quickly and easily.
  • Use the optional "receiveRetainedMessages" property to control when the FairCom server sends the retained message to a topic subscription event, which includes never sending the retained message, sending it only when the client subscribes for the first time, or sending it each time the client subscribes. 
  • Use the optional "receiveMyMessages" property to prevent or allow the FairCom server to send messages to a client that the client published. 
 Optional with default of [] array

"binaryFormat"

"includeExpiredMessages"

"receiveMyMessages"

"receiveRetainedFlagAsPublished"

"receiveRetainedMessages"

"subscriptionIdentifier"

"topicFilter"

 

subscriptionActions

.binaryFormat

 The "binaryFormat" property designates the format of binary values embedded in JSON strings. For more details, see "binaryFormat".  Optional with default of "hex" string One of the following: "base64", "hex", or "byteArray".

subscriptionActions

.includeExpiredMessages

The "includeExpiredMessages" property includes expired messages in a subscription when set to true. A message has expired when the "messageHasExpired" property in the response is true.

 

 Optional with default of true Boolean

true

false

subscriptionActions

.qos

 The "qos" property defines the MQTT quality of service for publishing the message that will be sent to the MQTT broker. Optional with default of 1 enumerated integer

0 - does not guarantee message delivery.

1 - provides balance between performance and guaranteed message delivery.

2 - guarantees message delivery once and only once. 

subscriptionActions

.receiveMyMessages

The "receiveMyMessages" property allows a client's subscription to receive messages published by the client.

 Optional with default of true Boolean

true

false

subscriptionActions

.receiveRetainedFlagAsPublished

The "receiveRetainedFlagAsPublished" specifies how the FairCom server sets the "retain" property on messages it sends to subscribers. When a client publishes a message, it sets the "retain" property to true to tell the FairCom server that it should retain the message and publish this message on behalf of the client when another client subscribes to a topic. A retained message is typically a special message that provides a new subscriber with status information about the topic.

When "receiveRetainedFlagAsPublished" is true, the FairCom server follows the MQTT 3 specification and passes the value of the "retain" property set by the publisher to the subscriber. Thus, a subscriber sees the value of the "retain" property that is set by the publisher. This notifies the subscriber that the message is a special status message from the client. This approach has the downside that a subscriber does not know when it gets a message sent by the FairCom server on behalf of the client in response to subscribing to a topic.

When "receiveRetainedFlagAsPublished" is false, the FairCom server follows the MQTT 5 specification and sets the "retain" property to true only when the FairCom server sends a retain message to a subscriber on behalf of a publisher, such as when a client subscribes to a topic. The MQTT 5 approach lets a subscriber know when it receives a retain message sent by the FairCom server vs. when it receives a normally published message from a client. This approach has the downside that a subscriber does not get the value of the "retain" property as set by the client who published the message. The MQTT 5 approach is generally better because the subscriber can tell when it is receiving a retained message in response to a subscription as opposed to a message published by a client.

 Optional with default of true Boolean

true

false

subscriptionActions

.receiveRetainedMessages

The "receiveRetainedMessages" property specifies how MQTT 5 subscribers receive retained messages. It has three enumerated values: "onSubscription", "onNewSubscription", and "never". 

  • "onSubscription" - the server sends a topic's retained message each time a client subscribes to a topic. Thus, a client can resubscribe to a topic to get the latest retained message.
  • "onNewSubscription" - the server only sends a topic's retained message when a client subscribes to a topic for the first time.
  • "never" - the server never sends a topic's retained message.
 Optional with default of "onSubscription" enum

"onSubscription"

"onNewSubscription"

"never"

subscriptionActions

.subscriptionAction

 The "subscriptionAction" property specifies whether the action will add or remove the specified subscription. Optional with default of "add" string enum

"add"

"remove"

subscriptionActions

.subscriptionIdentifier

The "subscriptionIdentifier" property is provided by the subscriber and uniquely identifies the "topicFilter" to the subscriber. Each subscriber may assign its own "subscriptionIdentifier" to each "topicFilter". When the FairCom server delivers a message to the subscriber, it includes the "subscriptionIdentifier" with the message. The purpose of Subscription Identifiers is to make it easy and fast for an MQTT 5 client to process an incoming message. The client can use the Subscription Identifier in a message to associate a message with a specific handler. A client receiving a message with multiple Subscription Identifiers can send the message to multiple handlers – one for each Subscription Identifier.

 Optional with default of 268435455 integer 0 to 268435455

subscriptionActions

.topicFilter

The "topicFilter" property contains a topic filter, which may contain MQTT wildcard characters, #, and +. Without wildcard characters, it matches one topic. When containing wildcard characters, it may match one or more topics.

 Optional with default of "" UTF-8 string topic names

subscriptionActions

.userProperties

The "userProperties" property specifies an array of key-value objects used to describe a user. A key-value object contains a "key" property and a "value" property with string values. You can assign multiple key-value pairs to an MQTT 5 message; the server includes them in the messages it delivers to subscribers. The server may process specific key-value pairs as instructions that modify its behavior.

"userProperties": [
  {
    "key": "some key",
    "value": "some value"
  }
]
 Optional with default of null array 0 or more key/value pairs

 

Response properties ("result")

Property Description Type Limits (inclusive)

subscriptions

 The "subscriptions" property details information about each subscription that matches the parameters of the request. array

"debugInfo"

"errorCode"

"errorMessage"

"matchingTopics"

"topicFilter"

subscriptions

.debugInfo

 The "debugInfo" property specifies debugging information for use in troubleshooting. object No limit

subscriptions

.errorCode

 The "errorCode" property indicates an error when set to a non-zero integer or success when 0. integer -2147483648 to 2147483647

subscriptions

.errorMessage

 The "errorMessage" property displays a human-readable error message. string 0 to 256 bytes

subscriptions

.matchingTopics

 The "matchingTopics" property lists the topics that match the parameters specified in the request. array No limit

subscriptions

.topicFilter

The "topicFilter" property contains a topic filter, which may contain MQTT wildcard characters, #, and +. Without wildcard characters, it matches one topic. When containing wildcard characters, it may match one or more topics.

 UTF-8 string topic names

 

subscribe receive follow register message command broker mqtt mq

Was this article helpful?

Give feedback about this article

Related Articles