Skip to main content

"getMessagesFromMqApiSession" (MQ API)

Use the "getMessagesFromMqApiSession" action to retrieve undelivered messages from an MQ API client-subscribed topic

The "getMessagesFromMqApiSession" action retrieves undelivered messages from topics to which an MQ API client has subscribed. 

The MQ client is identified by the required "clientName" property. An MQ API session with that client identifier must already exist; otherwise, it returns an error. It also returns an error when the "clientName" is used by an MQTT connection.

Each time you call this action with the same "clientName", the server starts where it left off and delivers the next set of messages published to that client. It retrieves undelivered messages up to the number specified by "maxMessages". The message payload is encoded according to the  "binaryFormat" property.

If you subscribe to multiple topics, the server returns messages from all of them. You can use the "topic" property to retrieve messages from only one of your subscribed topics. 

The typical pattern for using this action is to first call the "createMqApiSession" action to create a new session. Then, use the "subscribeToMq" action to subscribe to topics. You can then repeatedly call the "getMessagesFromMqApiSession" action to retrieve messages as clients publish them. 

An application can retrieve messages sent to a shared topic, which is a topic starting with $share/. A shared topic works differently from a normal topic because the server distributes each message to a different subscriber rather than sending each message to each subscriber. Each time a subscriber uses the "getMessagesFromMqApiSession" action to retrieve a message, the server removes the message from the queue and prevents that message from being sent to another subscriber. If the application encounters an error processing a message, it must publish the message back to the topic so it can be processed by another subscriber. 

Tip

An application can use "getMessagesFromMqApiTopic" to retrieve shared messages without removing them from the queue.

Warning

clients must use unique client names so they do not consume each other's messages. If multiple processes use the same value for the "clientName" property in the "getMessagesFromMqApiSession" action, each process denies other processes from retrieving messages that it has retrieved. You may want to do this to implement distributed command processing. On the other hand, if you want to use the event streaming technique to retrieve messages, do not subscribe to topics; Instead, use the "getMessagesFromMqTopic" action to retrieve messages.

Optionally, set  "includeMqttProperties": true to include the message's MQTT properties. It defaults to false.

Optionally, set "includeTransformFields": true to include the custom fields used for the transformation process's inputs and outputs. It defaults to false.

Request examples

Maximal

{
  "api": "mq",
  "action": "getMessagesFromMqApiSession",
  "params":
  {
    "topic": "optional topic name",
    "clientName": "required unique MQ API client name",
    "maxMessages": 100,
    "binaryFormat": "base64 | hex | utf8 | json | byteArray",
    "includeMessageMetadata": true,
    "includeMqttProperties": true,
    "includeTransformFields": true
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve the next batch of 100 messages

{
  "api": "mq",
  "action": "getMessagesFromMqApiSession",
  "params":
  {
    "clientName": "required unique MQ API client identifier",
    "maxMessages": 100
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve all undelivered messages

{
  "api": "mq",
  "action": "getMessagesFromMqApiSession",
  "params":
  {
    "clientName": "required unique MQ API client identifier"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve up to 100 unsent messages from the subscription, format the message payload as JSON, and include all expired messages, MQTT metadata, MQTT properties, and transform fields

{
  "api": "mq",
  "action": "getMessagesFromMqApiSession",
  "params":
  {
    "clientName": "required unique MQ API client identifier",
    "topicFilter": "topic#",
    "maxMessages": 100,
    "binaryFormat": "json",

    "includeMessageMetadata": true,
    "includeMqttProperties": true,
    "includeTransformFields": true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response example

{
  "result": {

    "messages":
    [
      {
        "clientName": "Client identifier",
        "topic": "test/topic1",
        "subscriptionIdentifiers": [123],
        "databaseName": "faircom",
        "ownerName": "admin",
        "tableName": "mqtt_msg_test_topic1",

        "payload": "C3A3",
        "binaryFormat": "base64 | hex | utf8 | json | byteArray",

        "id": "263",
        "timestamp": "2023-12-18T18:04:20:085",
        "error": false,
        "log": null,

        "contentType": "IanaMediaType or a CustomType",
        "correlationData": "any JSON value up to 65500 bytes",
        "expirySeconds": 60,
        "messageHasExpired": true,
        "payloadFormat": "binary | utf8",
        "publishedQoS": 2,
        "retain": true,
        "responseTopic": "topic/name/for/subscriber/to/respond/to",
        "userProperties": [
          {
            "key": "some key",
            "value": "some value"
          }
        ], 

        "faircomClientId": 6732,
        "faircomTopicId": 457,
        "faircomForwardTopicId": 0,
        "faircomMqttPacketId": 53736,
        "faircomMqttSentReason": "Client | Retained | Will | Forwarded",

        "transformFields": [
          { "fieldName": "t1", "fieldData": "some value" }
        ]

      }
    ]

  },
  "errorCode": 0,
  "errorMessage": "",
  "debugInfo": {
  },
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Use the "getMessagesFromMqApiSession" action to retrieve undelivered messages from an MQ API client-subscribed topic

getMessagesFromMqApiSessionget messages from mq api sessionjsonActionMQ API

"params"

Table 1. Params property summaries

Property

Description

Default

Type

Limits (inclusive)

binaryFormat

(optional) specifies how the "payload" property is encoded

"json"

string

One of the following: "base64", "hex", or "byteArray".

clientName

(optional) specifies the unique name that identifies the client to the FairCom MQ engine

""

string

0 to 65,550 bytes

includeMessageMetadata

(optional) returns the message's "id", "timestamp", "error", and "log" properties in the response

false

Boolean

true
false

includeMqttProperties

(optional) returns MQTT properties in the response

false

Boolean

true
false

includeTransformFields

(optional) returns custom transform fields in the response

false

Boolean

true
false

maxMessages

(optional) specifies the number of messages to return from a "getMessages..." action

20

integer

0 to 100000

topic

(optional) specifies the name of a topic

""

UTF-8 string



"binaryFormat"

"clientName"

The "clientName" property is an optional string of up to 65550 characters. It is the client identifier (or clientId) in the MQTT protocol. It uniquely identifies an MQ session, which contains information about a client's subscriptions, settings, and queue position of each topic to which the client is subscribed. The FairCom MQ engine stores this information and retrieves it when an MQTT or MQ API client connects.

Connection authorization is done using an account name with a password or a client certificate.

The "clientName" property does not authorize an MQTT or MQ API session. Another authentication technique authorizes the connection, such as an account name and password or a client certificate. Thus, any account may be used to authorize an MQ connection. Each account is assigned to roles that authorize access to specific topics, client names, actions, etc.

The MQ API allows multiple processes to simultaneously use the same client name to manage sessions, subscribe to topics, send messages to topics, and retrieve messages from topics. 

The MQTT protocol allows only one connection per client identifier because each connection is stateful. If another client with the same "clientName" is already connected, the FairCom server disconnects the other client and vice-versa.

"includeMessageMetadata"

Set the "includeMessageMetadata" property to true to include the message's "id", "timestamp", "error", and "log" properties.

"includeMqttProperties"

Set the "includeMqttProperties" property to true to include the MQTT properties in the response. Otherwise, omit the property or set it to false or null. MQTT properties are helpful when you need to troubleshoot MQTT messages.

"includeTransformFields"

Set the "includeTransformFields" property to true to include custom transform fields (if any) that a customer added to the integration table. Otherwise, omit the property or set it to false or null. Custom transform fields are helpful when you want to see the outputs and inputs of transformations assigned to the integration table.maxMessages.

"maxMessages"

The "maxMessages" property is optional and defaults to 20. It has a minimum value of 1 and a maximum value of 100000. It specifies the number of messages to return from a "getMessages…" action. The number of returned messages will be equal to or less than this maximum.

"topic"

The "topic" property is a required, case-sensitive UTF-8 string containing the name of a topic. It must not contain MQTT wildcard characters, #, or +. It may contain multiple / characters, which segment a topic into a set of positional properties.