Skip to main content

"publishMessagesToMq" (jsonAction)

Publish messages to a topic from the specified client

This action publishes one or more messages to a topic. MQ API and MQTT clients can subscribe to a topic and receive these messages. The required "clientName" property identifies the MQ API session used to publish the messages. The FairCom server tracks session statistics so you can monitor the health of a client and its session, including the timestamp of the last published message, the publish rate, the topics the session publishes to, etc. 

When you set the "binaryFormat" property to "utf8" or "JSON", the server automatically assigns the MQTT 5 Payload Format Indicator property to 1 to indicate that the message payload contains UTF-8-encoded characters, such as JSON.

Request examples

Minimal

{
  "api":       "mq",
  "action":    "publishMessagesToMq",
  "params":    {
    "clientName": "client1",
    "topic":      "test/topic1",
    "messages":   [
      {
        "payload": "This is the message payload for the minimal example."
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Typical

{
  "api":       "mq",
  "action":    "publishMessagesToMq",
  "params":    {
    "clientName": "client1",
    "topic":      "test/topic1",
    "messages":   [
      {
        "payload":      "This is the first message payload for the typical example.",
        "binaryFormat": "utf8"
      },
      {
        "payload":      "This is the second message payload for the typical example.",
        "binaryFormat": "utf8"
      },
      {
        "payload":      "This is the third message payload for the typical example.",
        "binaryFormat": "utf8"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "apiVersion": "1.0",
  "api":        "mq",
  "action":     "publishMessagesToMq",
  "params":     {
    "clientName": "client1",
    "topic":      "test/topic1",
    "sourcePayloadFormat": "binary",
    "messages":   [
      {
        "payload":         "This is the message payload for the maximal example.",
        "binaryFormat":    "utf8",

        "contentType":     "IanaMediaType or a CustomType",
        "correlationData": "any JSON value up to 65500 bytes",
        "expirySeconds":   60,
        "retain":          true,
        "responseTopic":   "topic/name/for/subscriber/to/respond/to",
        "userProperties":  [
          {
            "key":   "some key",
            "value": "some value"
          }
        ]
      }
    ]
  },
  "authToken":  "replaceWithAuthTokenFromCreateSession",
  "requestId":  "optionalUniqueRequestIdFromTheClient",
  "debug":      "max"
}

Publish one message to topic1

{
  "api": "mq",
  "action": "publishMessagesToMq",
  "params":
  {
    "clientName": "client1",
    "topic": "test/topic1",
    "messages": [
      { 
        "payload": "This is the message payload.",
        "binaryFormat": "utf8"       
      }
    ]
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Publish one message to table mqtt_msg_test_topic1

{
  "api": "mq",
  "action": "publishMessagesToMq",
  "params":
  {
    "clientName": "a unique client identifier",
    "topic": "test/topic1",
    "databaseName": "faircom",
    "ownerName": "admin",
    "tableName": "mqtt_msg_test_topic1",
    "messages": [
      { 
        "payload": "This is the message payload.",
        "binaryFormat": "utf8"       
      }
    ]
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response example

{
  "result": {},
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Use the "publishMessagesToMq" action to publish messages to an MQTT topic from the specified client

publishMessagesToMqpublish messages to mqjsonActionMQ API

"params"

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

clientName

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

""

string

0 to 65,550 bytes

messages

(optional) specifies the message to be published to MQ as well as information about the message

[]

array of objects

messages
.binaryFormat

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

"json"

string

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

messages
.contentType

(optional) specifies the IANA media or custom type

""

string

messages
.correlationData

(optional) can be used to set request-response messages

""

JSON

0 to 65,500 bytes

messages
.expirySeconds

(optional) specifies the number of seconds the message remains active before the server stops delivering it to MQTT 5 subscribers

null

integer

messages
.payload

specifies the action payload of the message

Required - No default value

string

messages
.responseTopic

(optional) specifies the topic name for the response

""

string

messages
.retain

(optional) tells the FairCom server to retain this message for automatically sending to new subscribers as the first message they receive

false

Boolean

true
false
messages
.userProperties

(optional) assigns key-value pairs to MQTT 5 messages

null

array

sourcePayloadFormat

(optional) specifies the variant type format of the "source_payload" field

"binary"

string

"json"
"xml"
"binary"
"jpeg"
"siemensUdt"
"utf8"

topic

(optional) specifies an MQTT topic

""

string



"binaryFormat"

Examples

"hex"

Request

{
  "api": "mq",
  "action": "publishMessagesToMq",
  "params": {
    "clientName": "client1",
    "topic": "test/topic1",
    "messages": [
      {
        "payload": "333231",
        "binaryFormat": "hex"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

The MQTT payload will be 321

"byteArray"

Request

{
  "api": "mq",
  "action": "publishMessagesToMq",
  "params": {
    "clientName": "client1",
    "topic": "test/topic1",
    "messages": [
      {
        "payload": [ 50, 51, 49 ],
        "binaryFormat": "byteArray"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

The MQTT payload will be 231

"base64"

Request

{
  "api": "mq",
  "action": "publishMessagesToMq",
  "params": {
    "clientName": "client1",
    "topic": "test/topic1",
    "messages": [
      {
        "payload": "MTIz",
        "binaryFormat": "base64"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

The MQTT payload will be 123

"clientName"

The "clientName" property is an optional string of up to 65,550 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.

"contentType"

The "contentType" property is an optional string typically set to an IANA media type or a custom type you define. It is used by MQTT 5.

"correlationData"

The "correlationData" property is an optional JSON value with a byte length of up to 65500 bytes. Set it to a useful value when using MQTT for request-response messages. When a published message has a "responseTopic", an MQTT 5 subscriber can send a message response to that topic, and the message will include this "correlationData" value (if any) to connect the response to the published message.

"expirySeconds"

The "expirySeconds" property is an optional number of seconds the message remains active before the server stops delivering it to MQTT 5 subscribers. If you set it to null, the message does not expire. MQTT 3 messages do not expire. The server persists all messages, and the "getMessagesFromMqApiSession" action includes expired messages in its results. The caller can filter out expired messages by setting "includeExpiredMessages" to false when using the "subscribeToMq" action.

"messages"

The "messages" property is a required array of objects that specifies the message to be published to MQ as well as information about the message.

"sourcePayloadFormat"

The "sourcePayloadFormat" property is an optional string that specifies the expected data type of the MQTT payload. When omitted or set to null, it defaults to "binary". When the server receives an MQTT message, it always takes the binary value from the MQTT payload and stores it in the source_payload field. The source_payload field is a variant, which means it stores the type of data it contains. If there are no errors in validating the MQTT payload to match the type specified in "sourcePayloadFormat", the server assigns the value of "sourcePayloadFormat" as the variant field's type. 

Depending on the values of the "sourcePayloadFormat" and "validateMqttPayload" properties, the server may validate the MQTT payload to ensure it matches the type. The default value for the "validateMqttPayload" property is true. The server may also convert the MQTT payload into another form before storing it. If the MQTT payload does not match the type or cannot be converted, the server stores the payload in the source_payload field, sets its variant type to "binary", and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field. 

FairCom's MQTT server does the following when a topic receives an MQTT message and "sourcePayloadFormat" is set to one of the following values:

"sourcePayloadFormat" Value

Description

"binary"

The server stores the MQTT payload in the source_payload field with no validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".

"json"

The server stores the MQTT payload in the source_payload field.

  • If "validateMqttPayload" is true, it validates the MQTT payload as JSON.

    • If successful, it assigns the "json" type to the source_payload field.

    • If unsuccessful, the server assigns a "binary" type to the source_payload field and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field.

  • If "validateMqttPayload" is false, it does not validate the MQTT payload and assigns the "json" type to the source_payload field. The publisher must send MQTT messages containing valid JSON, or database queries may return errors.

"utf8"

The server stores the MQTT payload in the source_payload field.

  • If "validateMqttPayload" is true, it validates the MQTT payload as a UTF-8 string.

    • If successful, it assigns the "utf8" type to the source_payload field.

    • If unsuccessful, the server assigns a "binary" type to the field and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field.

  • If "validateMqttPayload" is false, it does not validate the MQTT payload and assigns the "utf8" type to the source_payload field. The publisher must send MQTT messages containing valid UTF-8, or database queries may return errors.

"variantObject"

The server validates the payload as a variant object.

  • If successful, the server extracts the value from the variant object’s "value" property and assigns it to the value of the source_payload field. It also assigns the variant object’s type to the type of the source_payload field.

  • If unsuccessful, the server writes the MQTT payload to the source_payload field, assigns a  "binary"  type to the field, and sets the error field to  1, to indicate that it also adds an error entry to the JSON array in the log field.

The server ignores the value of "validateMqttPayload". The server always validates "variantObject".

"siemensUdt"

The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".

"jpeg"

The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".

"xml"

The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".

  • This property is a hint to the server about the format and type of the MQTT message payload.

  • This property does not cause server to validate the MQTT payload to see if it matches the type you set. The server stores the payload as is without validation. For example, setting the type to "json", it does not stop the server from receiving and storing a non-JSON value or invalid JSON document in the source payload.

  • The FairCom Edge Explorer application may use the value of this property to determine the default way to display a topic's payload.

  • The transform engine may use the value of this property to help it transform the source payload.

"messages"."payload"

The "payload" property is a required string that specifies the actual payload of the message.

"responseTopic"

The "responseTopic" property is an optional string containing a topic name. When a published message has a "responseTopic", an MQTT 5 subscriber can send a message response to that topic, and the message will include the "correlationData" value (if any) to connect the response to the published message.

"retain"

The "retain" property is optional in the "publishMessagesToMq" action and defaults to false. When true, it tells the FairCom server to retain this message for automatically sending to new subscribers as the first message they receive. When an action returns the "retain" property, it indicates the publisher published the message as a retained message.

"topic"

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

"userProperties"

The "userProperties" property is optional in the "publishMessagesToMq" action and defaults to null. When present, it is an array of key-value objects. 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"
  }
]