publishMessagesToMq

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

{
    "action": "publishMessagesToMq",
    "params": {
        "clientName": "client1",
        "topic": "test/topic1",
        "messages": [
            {
                "payload": "A143C2F"
            }
        ]
    },
    "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.",
        "mqttPayloadType": "utf8"
      },
      {
        "payload":      "This is the second message payload for the typical example.",
        "mqttPayloadType": "utf8"
      },
      {
        "payload":      "This is the third message payload for the typical example.",
        "mqttPayloadType": "utf8"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
    "apiVersion": "1.0",
    "api": "mq",
    "action": "publishMessagesToMq",
    "params": {
        "clientName": "client1",
        "topic": "test/topic1",
        "messages": [
            {
                "payload": "DEADBEEF",
                "binaryFormat": "hex",
                "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": "3",
    "debug": "max"
}
 
 

Publish one message to topic1

{
  "api": "mq",
  "action": "publishMessagesToMq",
  "params":
  {
    "clientName": "client1",
    "topic": "test/topic1",
    "messages": [
      { 
        "payload": "This is the message payload.",
        "mqttPayloadType": "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.",
        "mqttPayloadType": "utf8"       
      }
    ]
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response example

Success

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

 

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

databaseName

The "databaseName" property specifies the database that contains an object, such as a table or code package. If it is set to null or is omitted, it defaults to the default database of the JSON Action session, see "createSession" and the "defaultDatabaseName" property. 

You specify this property when you want to use a different database instead of the default. 

This property is useful because objects, such as tables and code packages, can have the same name in multiple databases. This feature allows you to create multiple environments in the same server and reuse the same JSON actions in each environment. For example, you can create "dev", "test", "stage", and "prod" databases on the same server and use the "defaultDatabaseName" or "databaseName" properties to specify the desired environment.

It is an error to set "databaseName" to the empty string "".

If no default database is specified during "createSession", the server sets the "defaultDatabaseName" to the "defaultDatabaseName" value specified in the services.json file.

 Defaults to the session's "defaultDatabaseName" property string 1 to 64 bytes

messages

The "messages" property specifies the message to be published to MQ as well as information about the message.

 Optional with default of [] array of objects

1 or more objects including some or all of the following properties:

"binaryFormat"

"contentType"

"correlationData"

"expirySeconds"

"payload"

"responseTopic"

"retain"

"userProperties"

messages

.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".

messages

.contentType

The "contentType" property specifies the content type, typically set to an IANA media type or a custom type you define. It is used by MQTT 5.

 Optional with default of "" string an IANA media or custom type

messages

.correlationData

The "correlationData" property can be used to set 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.

 Optional with default of "" JSON 0 to 65,500 bytes

messages

.expirySeconds

The "expirySeconds" property specifies the 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.

 Optional with default of null integer No limits

messages

.mqttPayloadType

The "mqttPayloadType" property specifies the variant type format of the "source_payload" field. For more details, see mqttPayloadType. 

 Optional with default of "json" string enum

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

"variantObject"

messages

.payload

The "payload" property specifies the actual payload of the message.

 Required - No default value string The message's payload

messages

.responseTopic

The "responseTopic" property contains 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.

 Optional with default of "" string topic name for the response

messages

.retain

The "retain" property tells the FairCom server to retain this message for automatically sending to new subscribers as the first message they receive when set to true. When an action returns the "retain" property, it indicates the publisher published the message as a retained message.

 Optional with default of false Boolean

true

false

messages

.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

messages

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

messages

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, true, false, or null.

 Required - No default value string

"string"

"integer"

"number"

"boolean"

"null"

ownerName

The "ownerName" property specifies the account that owns an object, such as a table or code package. See "createSession" and the "defaultOwnerName" property for more details. 

You specify this property when you want to use a different account instead of the default. Your session's account must have the appropriate privileges to access the code package. 

This property is useful because objects, such as tables and code packages, can have the same name in the same database as long as different accounts own each object. This feature allows you to create duplicate objects for different users on the same server and reuse the same JSON actions on those objects. For example, an administrator can copy objects from a production environment to her account so she can troubleshoot an issue using the same JSON actions, JavaScript, and SQL code.

It is an error to set "ownerName" to the empty string "".

If no default owner is specified during "createSession", the server sets the "defaultOwnerName" to the "defaultOwnerName" value specified in the services.json file.

 Optional with default of the session's "defaultOwnerName" property string 1 to 64 bytes

tableName

The "tableName" property contains the unique, user-defined name of a table.

See table name in System limits for the table naming requirements and limitations.

 

"params": {
  "tableName": "ctreeTable"
}
 Required - No default value string 1 to 64 bytes

topic

The "topic" property specifies the unique, user-defined name for the topic.

  • The "topic" name is typically less than 150 characters.
  • The "topic" name will be used in all subsequent references to the topic, such as when re-configuring or deleting the topic.

 

 Optional with default of "" string 1 to 65,500 bytes

 

Was this article helpful?

Give feedback about this article

Related Articles