subscribeToMq

Add or remove a client's subscriptions

The "subscribeToMq" action adds or removes a client's subscriptions, including those created by MQTT and the MQ API. It can change subscriptions without disconnecting an MQTT client. You can use the "subscribeToMq" action to manage the subscriptions of any session 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. 
  • Use the optional "userProperties" property to set user defined subscription properties.

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": "remove",
        "topicFilter": "Test/Topic1",
        "subscriptionIdentifier": 268435455,
        "binaryFormat": "hex",
        "includeExpiredMessages": true,
        "receiveMyMessages": false,
        "receiveRetainedMessages": "onSubscription",
        "receiveRetainedFlagAsPublished": true,
        "userProperties": [
          {
            "key": "some key",
            "value": "some value"
          }
        ]
      },
      {
        "subscriptionAction": "add",
        "topicFilter": "Test/Topic2",
        "userProperties": [
          {
            "key": "some key",
            "value": "some value"
          }
        ]
      }
    ]
  },
  "responseOptions": {
    "dataFormat": "arrays", 
    "numberFormat": "number",
    "binaryFormat": "base64",
    "variantFormat": "json"
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response example

Success

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

 

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. 
  • Use the optional "userProperties" property to set user-defined subscription properties.
Optional with default of [] array

"binaryFormat"

"includeExpiredMessages"

"receiveMyMessages"

"receiveRetainedFlagAsPublished"

"receiveRetainedMessages"

"subscriptionIdentifier"

"topicFilter"

"userProperties"

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

.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

subscriptionActions

userProperties

.key

The "key" property is part of an optional key-value object that is defined in an array in the "userProperties" property. It is a user-defined string value.

Optional with default of "".

 

Required in the Key-Value API 

string 1 to 128 bytes

subscriptionActions

userProperties

.value

The "value" property is used by the server to compare the value assigned to "value" to the appropriate field data in records.

 

In Key-Value actions, the required "value" property contains a JSON value, which may be up to 2 gigabytes in length. It can be any JSON value, such as an object, array, string, number, truefalse, or null.

Required - No default value string

"string"

"integer"

"number"

"boolean"

"null"

 

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