MQTT system topics

FairCom MQ automatically publishes system messages to three topics

FairCom MQ automatically publishes system messages to three topics:

  • faircomAdmin/connections lists all MQTT connections to the broker.
  • faircomAdmin/subscribers lists all the subscribers and their subscriptions.
  • faircomAdmin/topics lists all topics available for publishing and subscribing.

 

faircomAdmin/connections JSON message example

 {
      "clientName": "Client_0a",
      "connectionDateTime": "2026-02-04T22:07:47",
      "connectionStatus": "connected",
      "defaultBinaryFormat": "hex",
      "defaultVariantFormat": "json",
      "ipaddress": "127.0.0.1",
      "keepAliveSeconds": 60,
      "mqttProtocol": "3.1.1",
      "port": 49743,
      "publishedTopics": [
        "test/client_a0/topic0",
        "test/client_a0/topic1",
        "test/client_a0/topic2"
      ],
      "sessionStatus": "normal",
      "sessionType": "mqtt",
      "stats": {
        "currentDeliveryBacklogged": 0,
        "deliveryBacklogRatePerDay": 0,
        "deliveryBacklogRatePerHour": 0,
        "deliveryBacklogRatePerMinute": 0,
        "deliveryBacklogRatePerMinuteInSession": 0,
        "deliveryBacklogRatePerMinuteLast10Minutes": 0,
        "firstMessagePublishedOn": "2026-02-04T22:07:53",
        "firstMessageReceivedOn": "2026-02-04T22:07:53",
        "lastMessagePublishedOn": "2026-02-04T22:08:08",
        "lastMessageReceivedOn": "2026-02-04T22:08:08",
        "maxHealthyBacklogRatePerMinute": 0,
        "maxHealthySendRatePerMinute": 0,
        "maxHealthySubscribedTopicFiltersCount": 0,
        "minHealthySendRatePerMinute": 0,
        "minHealthySubscribedTopicFiltersCount": 0,
        "publishRatePerHour": 36,
        "publishRatePerMinute": 36,
        "publishRatePerMinuteInSession": 36,
        "publishRatePerMinuteLast10Minutes": 36,
        "receiveMessagesPerHour": 36,
        "receiveMessagesPerMinute": 36,
        "receiveMessagesPerMinuteLast10Minutes": 36,
        "receiveMessagesPerMinuteSinceInSession": 36,
        "sessionHealth": "healthy",
        "totalMessagesPublished": 36,
        "totalMessagesReceived": 36
      },
      "subscribedTopics": [
        {
          "topicFilter": "test/client_a0/topic0",
          "topics": [
            {
              "topic": "test/client_a0/topic0"
            }
          ]
        },
        {
          "topicFilter": "test/client_a0/topic1",
          "topics": [
            {
              "topic": "test/client_a0/topic1"
            }
          ]
        },
        {
          "topicFilter": "test/client_a0/topic2",
          "topics": [
            {
              "topic": "test/client_a0/topic2"
            }
          ]
        }
      ],
      "subscriberCount": 3
},

 

Properties ("params")

Property Description Type Limits (inclusive)

clientName

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

connectionDateTime

 The "connectionDateTime" property indicates when the client's session was connected.  timestamp An ISO 8601 timestamp

connectionStatus

The "connectionStatus" property is returned by the "describeMqSessions" action to indicate if and how a client is connected to an MQ session. It has the following values:

  • "disconnected" indicates no device or software is connected to the MQ session.
  • "connected" indicates a device or software has established a permanent connection to the MQ session.
  • "connectedTemporarily" indicates a device or software has established a temporary connection to the MQ session. When the device or software disconnects, the server removes the data associated with the MQ session.
 string

"disconnected"

"connected"

"connectedTemporarily"

defaultBinaryFormat

 Defines the default value of "binaryFormat".  string One of the following: "base64", "hex", or "byteArray".

defaultVariantFormat

The "defaultVariantFormat" property sets the default value of the "variantFormat" property when a JSON Action request does not include it.

 string

"json"

"binary"

"string"

"variantObject"

ipaddress

 The "ipAddress" property specifies the PLC/Equipment IPV4 Address. string A valid IP address

keepAliveSeconds

The "keepAliveSeconds" property specifies how often (in seconds) the broker expects a message to be sent. The server will retain a temporary session as long as the client performs an MQ Message action within the keep alive timeout period, which is "keepAliveSeconds" x 1.5. Once there is no activity, the server starts the session expiry timer to remove the temporary session. If there is no session activity within the number of seconds specified in the "sessionExpiryInternal" property, the server removes the session.

 integer No limit

mqttProtocol

 The "mqttProtocol" property specifies the version of MQTT protocol to use in your session. string enum

"3.1.1"

"5.0"

port

The "port" property is an integer that specifies the port number.

 integer an integer port number

publishedTopics

The "publishedTopics" property returns a list of the topics the client has published since the session was first created.

 string 1 to 65,500 bytes

sessionStatus

The "sessionStatus" property specifies the status of an MQTT or MQ API session as "normal", "hidden", "banned", or "inactive" to hide its visibility in API results and the dashboard views, ban a client from connecting, or mark a client as inactive. A banned session prevents clients from using the session to publish and subscribe to messages. When "sessionStatus" is omitted, it defaults to "normal".

  • "normal" resets a client to its default normal state. The client is not hidden in API results and dashboard views and may connect, publish, and subscribe to messages. The engine preserves all information about the client. Use it to unhide, unban, and activate a client.
  • "hidden" hides a client from most API results and dashboard views while allowing the client to connect, publish, and subscribe to messages. The engine preserves all information about the client. Use it to hide administrative client connections.
  • "banned" prevents a client from connecting in the future while preserving all information about the client. Use it to prevent unwanted clients from connecting again using the session's "clientName" to publish and subscribe to messages.
  • "inactive" marks a client session as inactive while allowing the client to connect, publish, and subscribe to messages. The server does not remove an "inactive" session's data so that historical message data sent and received by the client can continue to be associated with the deleted client. If a client connects to an inactive session, the server changes the session to "normal".
    • Use the "deleteMqSession" action to permanently delete the session which removes all session information. The server can no longer associate sent and received messages with the client. The client can reconnect in the future to establish a new session, but this will create a new session. It is common to permanently delete temporary client connections created during testing and troubleshooting.
 string enum

"normal"

"hide"

"ban"

sessionType

 "sessionType" specifies which type of session the requested client is currently running. string

"mqApi"

"mqtt"

"both"

stats

 Contains stats about describeMqSessions. object

"currentDeliveryBacklogged"

"deliveryBacklogRatePerDay"

"deliveryBacklogRatePerHour"

"deliveryBacklogRatePerMinute"

"deliveryBacklogRatePerMinuteInSession"

"deliveryBacklogRatePerMinuteLast10Minutes"

"maxHealthyBacklogRatePerMinute"

"maxHealthySendRatePerMinute"

"maxHealthySubscribedTopicFiltersCount"

"minHealthySendRatePerMinute"

"minHealthySubscribedTopicFiltersCount"

"publishedTopics"

"publishRatePerHour"

"publishRatePerMinute"

"publishRatePerMinuteInSession"

"publishRatePerMinuteLast10Minutes"

"receiveMessagesPerHour"

"receiveMessagesPerMinute"

"receiveMessagesPerMinuteLast10Minutes"

"receiveMessagesPerMinuteSinceInSession"

"sessionHealth"

"totalMessagesPublished"

"totalMessagesReceived"

stats

.currentDeliveryBacklogged

 The "currentDeliveryBacklogged" property specifies how many deliveries are currently waiting in the backlog.  integer Any positive integer

stats

.deliveryBacklogRatePerDay

 The "deliveryBacklogRatePerDay" property specifies the number of deliveries that can be backlogged per day. integer Any positive integer

stats

.deliveryBacklogRatePerHour

 The "deliveryBacklogRatePerDay" property specifies the number of deliveries that can be backlogged per hour. integer Any positive integer

stats

.deliveryBacklogRatePerMinute

 The "deliveryBacklogRatePerDay" property specifies the number of deliveries that can be backlogged per minute. integer Any positive integer

stats

.deliveryBacklogRatePerMinuteInSession

 The "deliveryBacklogRatePerDay" property specifies the number of deliveries that can be backlogged per minute in the current session. integer Any positive integer

stats

.deliveryBacklogRatePerMinuteLast10Minutes

 The "deliveryBacklogRatePerDay" property specifies the number of deliveries that can be backlogged in the last 10 minutes. integer Any positive integer

stats

.firstMessagePublishedOn

 The "firstMessagePublishedOn" property specifies the date and time when the first message for the specified connection was published. timestamp An ISO 8601 timestamp

stats

.firstMessageReceivedOn

 The "firstMessageReceivedOn" property specifies the date and time when the first message for the specified connection was received.  timestamp An ISO 8601 timestamp

stats

.lastMessagePublishedOn

 The "lastMessagePublishedOn" property specifies the date and time when the last message for the specified connection was published. timestamp An ISO 8601 timestamp

stats

.lastMessageReceivedOn

 The "lastMessageReceivedOn" property specifies the date and time when the last message for the specified connection was received.  timestamp An ISO 8601 timestamp

stats

.maxHealthyBacklogRatePerMinute

The "maxHealthyBacklogRatePerMinute" property sets the maximum number of backlog messages per minute for a healthy session. A backlog message is one the server has not yet published to subscribers. The backlog of a topic grows when the incoming message rate exceeds the outgoing. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no upper bound.

A connected session is healthy when its message backlog rate does not exceed the maximum. The "describeMqSessions" action returns the "maxHealthyBacklogRatePerMinute" property and the "sessionHealth" property to report the health of a session.

 integer Any positive integer

stats

.maxHealthySendRatePerMinute

The "maxHealthySendRatePerMinute" property sets the maximum number of messages per minute for a healthy session. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no upper bound.

A connected session is healthy when its message send rate does not exceed the maximum. The "describeMqSessions" action returns the "maxHealthySendRatePerMinute" property and the "sessionHealth" property to report the health of a session.

 integer Any positive integer

stats

.maxHealthySubscribedTopicFiltersCount

The "maxHealthySubscribedTopicFiltersCount" property sets the maximum number of topic filters for a healthy session. You can set it to any positive integer, such as 10. The default value is 0, which sets no upper bound.

A connected session is healthy when it has subscribed to at most the maximum number of topic filters. The "describeMqSessions" action returns the "maxHealthySubscribedTopicFiltersCount" property and the "sessionHealth" property to report the health of a session.

A topic filter may include MQTT wildcard characters, which allows one topic filter to subscribe to many topics. The "maxHealthySubscribedTopicFiltersCount" property does not limit the number of topics.

 integer Any positive integer

stats

.minHealthySendRatePerMinute

The "minHealthySendRatePerMinute" property sets the minimum number of messages per minute for a healthy session. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no lower bound.

A connected session is healthy when its message send rate exceeds the minimum. The "describeMqSessions" action returns the "minHealthySendRatePerMinute" property and the "sessionHealth" property to report the health of a session.

 integer Any positive number

stats

.minHealthySubscribedTopicFiltersCount

The "minHealthySubscribedTopicFiltersCount" property sets the minimum number of topic filters for a healthy session. You can set it to any positive integer, such as 10. The default value is 0, which sets no lower bound.

A connected session is healthy when it has subscribed to at least the minimum number of topic filters. The "describeMqSessions" action returns the "minHealthySubscribedTopicFiltersCount" property and the "sessionHealth" property to report the health of a session.

A topic filter may include MQTT wildcard characters, which allows one topic filter to subscribe to many topics. The "minHealthySubscribedTopicFiltersCount" property does not limit the number of topics the wildcards match - rather, it establishes a lower bound on the number of subscribed topic filters an MQ Session is allowed to have.

 integer Any positive number

stats

.publishRatePerHour

 The "publishRatePerHour" property specifies the rate at which messages are published per hour.  integer Any positive number

stats

.publishRatePerMinute

 The "publishRatePerMinute" property specifies the rate at which messages are published per minute.  integer Any positive number

stats

.publishRatePerMinuteInSession

 The "publishRatePerMinuteInSession" property specifies the rate at which messages are published per minute in the current session.  integer Any positive number

stats

.publishRatePerMinuteLast10Minutes

 The "publishRatePerMinuteLast10Minutes" property specifies the rate at which messages are published in the last 10 minutes.  integer Any positive number

stats

.receiveMessagesPerHour

 The "receiveMessagesPerHour" property specifies the rate at which messages are received per hour.  integer Any positive number

stats

.receiveMessagesPerMinute

 The "receiveMessagesPerMinute" property specifies the rate at which messages are received per minute.  integer Any positive number

stats

.receiveMessagesPerMinuteLast10Minutes

 The "receiveMessagesPerMinuteLast10Minutes" property specifies the rate at which messages were received in the last 10 minutes.  integer Any positive number

stats

.receiveMessagesPerMinuteSinceInSession

 The "receiveMessagesPerMinuteSinceInSession" property specifies the rate at which messages are received per minute since the session started.  integer Any positive number

stats

.sessionHealth

The "sessionHealth" property describes the session health. For more details, see "sessionHealth". 

 enum

"healthy"

"unhealthy"

"offline"

stats

.totalMessagesPublished

 The "totalMessagesPublished" property specifies the total number of messages published.  integer Any positive number

stats

.totalMessagesReceived

 The "totalMessagesReceived" property specifies the total number of messages received.  integer Any positive number

subscribedTopics

 The "subscribedTopics" property lists the topics that the specified topic is subscribed to. array No limits

subscribedTopics

.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

subscribedTopics

.topics

The "topics" property specifies the name of each "topic" that you want to be described in the results.

array

 0 or more topic strings

subscribedTopics

topics

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

 

 string 1 to 65,500 bytes

subscriberCount

 Specifies the number of subscribers. integer Number of subscribers

 

faircomAdmin/subscribers JSON message example

{
  "subscribedTopics": [
    {
      "subscriberConnectionList": [],
      "topicFilter": "test/client_a0/topic0",
      "topics": [
        {
          "topic": "test/client_a0/topic0"
        }
      ]
    },
    {
      "subscriberConnectionList": [],
      "topicFilter": "test/client_a0/topic1",
      "topics": [
        {
          "topic": "test/client_a0/topic1"
        }
      ]
    },
    {
      "subscriberConnectionList": [],
      "topicFilter": "test/client_a0/topic2",
      "topics": [
        {
          "topic": "test/client_a0/topic2"
        }
      ]
    },
    {
      "subscriberConnectionList": [],
      "topicFilter": "test/client_a1/topic0",
      "topics": [
        {
          "topic": "test/client_a1/topic0"
        }
      ]
    },
    {
      "subscriberConnectionList": [],
      "topicFilter": "test/client_a1/topic1",
      "topics": [
        {
          "topic": "test/client_a1/topic1"
        }
      ]
    },
    {
      "subscriberConnectionList": [],
      "topicFilter": "test/client_a1/topic2",
      "topics": [
        {
          "topic": "test/client_a1/topic2"
        }
      ]
    }
  ]
}

 

Properties ("params")

Property Description Type Limits (inclusive)

subscribedTopics

 The "subscribedTopics" property lists the topics that the specified topic is subscribed to. array No limits

subscribedTopics

.subscriberConnectionList

 The "subscriberConnectionList" property lists the connections the specified subscriber has made.  array No limits

subscribedTopics

.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

subscribedTopics

.topics

The "topics" property specifies the name of each "topic" that you want to be described in the results.

array

 0 or more topic strings

subscribedTopics

topics

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

 

 string 1 to 65,500 bytes

 

faircomAdmin/topics JSON message example

    {
      "averageMessagesPerDay": 36,
      "averageMessagesPerHour": 36,
      "averageMessagesPerMinute": 5,
      "creationTime": "2026-02-04T22:07:29.009",
      "lastMessageTime": "2026-02-04T22:14:31.232",
      "messageCount": 36,
      "name": "faircomAdmin/connections",
      "persistence": {
        "databaseName": "faircom",
        "downgradeQoS": false,
        "maxDeliveryRatePerSecond": 0,
        "maxInflightMessages": 20,
        "mqttPayloadType": "json",
        "newSubscriberDeliveryMode": "default",
        "newSubscriberMaxDeliveredMessages": 0,
        "outputPayloadField": "source_payload",
        "ownerName": "admin",
        "retentionPeriod": 4,
        "retentionPolicy": "autoPurge",
        "retentionUnit": "week",
        "retrySeconds": 60,
        "storeAndForward": true,
        "tableAutoTimeStamp": true,
        "tableAutoTimeStampIndex": true,
        "tableName": "mqtt_msg_faircomadmin_connections",
        "tableReplicationReady": true,
        "threads": 1,
        "topic": "faircomAdmin/connections",
        "validateMqttPayload": true
      },
      "subscribedTopics": []
    },

 

Properties ("params")

Property Description Type Limits (inclusive)

averageMessagesPerDay

 The "averageMessagesPerDay" property describes how many messages the specified topic publishes per day on average. integer The average number of messages published per day

averageMessagesPerHour

 The "averageMessagesPerHour" property indicates the average number of messages the specified topic publishes per hour. integer The average number of messages published per hour

averageMessagesPerMinute

 The "averageMessagesPerMinute" property indicates the average number of messages the specified topic publishes per minute. integer The average number of messages published per minute

creationTime

 The "creationTime" property details the date and time when the specified topic was created. This property stores the creation date in an ISO 8601 timestamp. timestamp An ISO 8601 timestamp

lastMessageTime

 The "lastMessageTime" property specifies the time the most recent message was received. timestamp An ISO 8601 timestamp

messageCount

 The "messageCount" property defines the total number of messages published by the topic. BigInteger 0 to 9223372036854775807

name

The "name" property is the name of a label or field. 

The "group" and "name" properties combined uniquely identify each label. The "createLabel" and "alterLabel" actions return an error if the "group" and "name" properties do not create a unique label name.

The "id" property also uniquely identifies each label so you can rename a label's group and name without breaking "id" references to the label.

 

 string 1 to 64 bytes

persistence

 The "persistence" property defines the parameters of the persistence table. object

"databaseConnectionString"

"databaseName"

"databaseUserName"

"maxDeliveryRatePerSecond"

"mqttPayloadType"

"newSubscriberDeliveryMode"

"newSubscriberMaxDeliveredMessages"

"outputPayloadField"

"ownerName"

"retentionPeriod"

"retentionPolicy"

"retentionUnit"

"retrySeconds"

"tableName"

"tableReplicationReady"

"threads"

"topic"

“validateMqttPayload”

persistence

.databaseName

The "databaseName" property specifies the database that contains the tables. 

Note In the API Explorer, "defaultDatabaseName" is set to "ctreeSQL" in the "createSession" action that happens at login.

  • If the "databaseName" property is omitted or set to null, the server will use the default database name specified at login.
  • If no default database is specified during "createSession", "databaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.
  • This property's value is case insensitive. 
 string 1 to 64 bytes

persistence

.downgradeQoS

The "downgradeQoS" property controls how FairCom's servers manage the Quality of Service (QoS) of subscriptions to this topic. 

  • When false, FairCom's servers honor the QoS requested by each subscriber regardless of the QoS of publishers.
  • When true, FairCom's servers downgrade the QoS of subscribers to match the QoS of the publisher.
 Boolean

true

false

persistence

.maxDeliveryRatePerSecond

The "maxDeliveryRatePerSecond" property sets the throttle rate for current and new subscribers of the topic. If this property is omitted, it defaults to 0, which means no throttling is applied.

  • It must be a value between 0 and 2,147,483,647, but a more realistic range is between 0 and 1,000. It is useful to keep a client from being overwhelmed with too many messages sent too quickly.
  • You can set it to a number greater than 0 to throttle the delivery rate. This allows you to avoid saturating the network and other resources.
    • For example, you can set it to 100 to throttle the delivery to 100 messages per second. This is a maximum setting because the actual message delivery rate is bounded by the network, local resources, the hardware running FairCom's servers, and a client’s ability to process messages quickly.
 integer 0 to 2147483647

persistence

.maxInflightMessages

The "maxInflightMessages" property protects subscribers from receiving messages faster than they can handle.

  • The default value of 0 means there is no maximum limit.
  • This property defines the maximum number of unacknowledged messages that FairCom's servers will send to each subscriber of this topic.
    • For example, setting this property to 10 allows FairCom's servers to send up to 10 publish packets to a subscriber before the servers wait for the subscriber to acknowledge receipt of at least one publish packet.

int32

0 to 2147483647

persistence

.mqttPayloadType

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

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

persistence

.newSubscriberDeliveryMode

The "newSubscriberDeliveryMode" property defines how new subscribers receive messages. 

  • It may be set to one of two values:
    • "newMessages" (default)
    • "storedMessages"
  • When set to "newMessages" new subscribers only receive new messages.
  • When set to "storedMessages" new subscribers will receive some or all previously sent messages. The "newSubscriberDeliveryMode" property defines the maximum number of messages.
 string enum

"newMessages"

"storedMessages"

persistence

.newSubscriberMaxDeliveredMessages

The "newSubscriberMaxDeliveredMessages" property is the maximum number of previously stored historical messages a client receives automatically when subscribing to a topic.

  • A value of -1 or "all" defaults to delivering all currently stored messages.
  • A non-negative number limits the delivery of currently stored messages to that number. 
  • This property only applies when the "newSubscriberDeliveryMode" property is set to "storedMessages".
  • The broker can only send messages stored in the topic’s integration table. The table's retention policy automatically removes old messages.
  • Each time a client unsubscribes from a topic and then subscribes to the topic, the broker sends historical messages as specified by this property. A client can use this behavior to reprocess messages, such as refresh a local data cache or recalculate aggregates.

Note A topic’s "retentionPolicy", "retentionUnit", and "retentionPeriod" properties define how long the broker retains messages in a topic’s integration table.

 integer -1 to 2147483647

persistence

.outputPayloadField

The "outputPayloadField" property specifies the field that the MQTT Subscription service should use as the payload when it sends the payload to subscribers. 

  • "outputPayloadField" must be one of the following values: 
    • "source_payload" (default) allows
    • A user-defined field

This makes it possible for the output from any transform to be used as the payload delivered to subscribers.

 string "source_payload" or a user-defined field

persistence

.ownerName

 The "ownerName" property identifies the user who owns an object (see Object owner).  string 0 to 64 bytes

persistence

.retentionPeriod

The "retentionPeriod" property specifies how many units of data to retain. It refers to the unit of time specified by the "retentionUnit" property. For more details, see "retentionPeriod".

 integer 1 to 100

persistence

.retentionPolicy

The "retentionPolicy" property controls how messages are persisted. 

If not specified, the default found in the services.json file is used. Initially, it is "autoPurge".

 

retentionPolicy values:
  • "autoPurge"
    • This is the default. It is automatically applied when a new topic is created. It is preferred because it allows FairCom's servers to automatically remove messages that are older than the retention time. This helps ensure message data does not consume all storage space. It also minimizes storage costs and speeds up data access. The server partitions a table into multiple files so it can efficiently delete expired files.
  • "neverPurge"
    • This stores messages on disk and never removes them. This is useful when you need the entire history of the message stream. If message velocity is high, this can consume all storage space and cause an outage. The server creates a non-partitioned table, which is slightly faster than a partitioned table because it stores all records in one file.
 string

"autoPurge"

"neverPurge"

persistence

.retentionUnit

The "retentionUnit" property specifies a unit of time that the server will use to purge expired messages. For example, if you want a week's worth of messages to be purged once a week, set "retentionUnit" to "week". This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "week". 

  • This property is used in concert with "retentionPeriod" to determine retention time.
  • "retentionUnit" values:
    • "minute"
    • "hour"
    • "day"
    • "week"
    • "month"
    • "year"
    • "forever"

Note 

  • For best performance, set the "retentionUnit" to a value that keeps "retentionPeriod" between 5 and 30. 
  • When you set "retentionUnit" property to "forever" the server will not purge messages. This setting is the same as setting "retentionPolicy" to "neverPurge".
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".

string

"minute"

"hour"

"day"

"week"

"month"

"year"

persistence

.retrySeconds

The "retrySeconds" property specifies the number of seconds that FairCom's MQTT broker will wait for the next expected packet from a client during a QoS 1 or QoS 2 PUBLISH packet exchange/PUBLISH handshake with an MQTT client. It applies when a client is publishing to the broker and when the broker is publishing to a client. This property does not apply to QoS 0 PUBLISH operations because QoS 0 PUBLISH operations are not answered. "retrySeconds" is optional.

  • If the "retrySeconds" time expires, FairCom's broker will disconnect the MQTT client with MQTT error code 7. MQTT 5 clients will also receive a Reason Code. An error message will be logged to <faircom>/data/CTSTATUS.FCS explaining why the disconnect happened. For example: 
    • MQTT connection for client ID [myMqttClient7] has been disconnected due to inactivity timeout. retrySeconds is set to [25] seconds for topic [my/test/topic12].: 14226
    • When the MQTT client reconnects, FairCom's MQTT broker will attempt to resume the PUBLISH handshake by resending the unanswered packet to the client, hoping that the client will reply with the next step of the handshake.
  • The minimum value is 1 and the maximum value is 65535.
  • If "retrySeconds" is omitted or its range is exceeded, FairCom's broker uses the default value.
  • Note that this parameter is not related to MQTT Keep Alive or when PINGREQ packets should be sent by the client.
 integer

1 to 65535

persistence

.storeAndForward

      

persistence

.tableAutoTimeStamp

      

persistence

.tableAutoTimeStampIndex

      

persistence

.tableName

The "tableName" property is a string containing the name of a table.

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

 string 1 to 64 bytes

persistence

.tableReplicationReady

 The "tableReplicationReady" property enables the transaction log on the persistence table. Transaction logs must be enabled before a table can be replicated. Boolean

true

false

persistence

.threads

The "threads" property specifies the number of threads assigned to a topic to write published messages to disk. 

  • The default of 1 is enough to handle typical workloads.
  • For heavy workloads, you may increase the number of threads to 2 or 3.
 integer

1

2

3

persistence

.topic

The "topic" property specifies the MQTT topic on the external broker to which messages will be forwarded.

 string A topic name between 1 and 65,500 bytes

persistence

.validateMqttPayload

 The "validateMqttPayload" property determines whether the FairCom server will attempt to validate the incoming MQTT message payload against the expected data type specified in the "mqttPayloadType" property. Boolean

true

false

subscribedTopics

 Specifies the number of subscribers integer Number of subscribers

 

messaging topics

Was this article helpful?

Give feedback about this article

Related Articles