MQTT V3 Plug-in Reference

CreatePersistenceTopic and AlterPersistenceTopic

Overview

The "CreatePersistenceTopic" and "AlterPersistenceTopic" operations share the same properties. For this reason, they are combined together in the documentation. Notes on each property describe the differences between the two operations:

• The "CreatePersistenceTopic" operation sets up automatic data persistence in the FairCom MQTT Broker.
• The "AlterPersistenceTopic" operation modifies an existing Persistence Topic in the FairCom MQTT Broker.

Required Properties

• "operation"
• "persistenceTopic"
• "mapOfPropertiesToFields"
  • "propertyPath"
  • "fieldName"
  • "fieldType"

Optional Properties to configure the Persistence Topic

• "persistenceTopicMessageFormat"
• "persistenceTopicThreads"
• "mapOfPropertiesToFields"
  • "propertyFormat"
  • "fieldWidth"
  • "fieldScale”
• "extractorLibraryName"

Optional Properties to configure the Persistence Table

• "tableName"
• "tableOwner"
• "tableReplicationReady"
• "tableAutoTimeStamp"
• "tableAutoTimeStampIndex"
• "tableRetentionPeriod"
• "tableRetentionUnit"

Optional properties to configure the Persistence Database

• "databaseConnectionString"
• "databaseName"
• "databaseUserName"
• "databaseUserPassword"

Optional properties for interpreting values stored in JSON properties

• "defaultBinaryFormat"
• "defaultNumberFormat"
• "defaultDateFormat"
• "defaultTimeFormat"

Optional properties to configure an external MQTT Broker as message source

• "subscribeToExternalBroker"
• "brokerHostname"
• "brokerPort"
• "brokerUserName"
• "brokerUserPassword"
• "brokerSSLCert”

Optional properties to configure a Store & Forward Topic

• storeAndForward: "True" | "False"
• "maxDeliveryRatePerSecond"
• "newSubscriberDeliveryMode"
• "newSubscriberMaxStoredMessages"

See MQTT Store & Forward.

CreatePersistenceTopic Operation

The "CreatePersistenceTopic" operation sets up automatic data persistence in c-tree. It creates a Persistence Topic in the FairCom MQTT Broker. This causes c-tree to listen for MQTT messages published with that topic and to extract data from those messages and to persist them to a table.

The following needs to be done to create a Persistence Topic:

• An MQTT client sends a message to the FairCom MQTT Broker.
• The message must be published to the topic of "ctreeAdministration"
• The message’s payload must contain a JSON document.
• The JSON document must have a property called "operation" with a value of "CreatePersistenceTopic".
• c-tree validates that the JSON document contains the proper structure and information.

  If the JSON document is invalid or incomplete, c-tree does not create the persistence topic and it logs an error to its CTSTATUS.FCS file.

AlterPersistenceTopic Operation

The "AlterPersistenceTopic" operation modifies an existing Persistence Topic in the FairCom MQTT Broker.

The JSON documents for altering and creating Persistence Topics are identical except for the JSON "operation" property.

c-tree looks at the settings in the "AlterPersistenceTopic" JSON object and compares them to existing settings of the Persistence Topic. It identifies the differences and modifies the Persistence Topic.

The Constraints section below indicates which properties can and cannot be modified.

In This Chapter Constraints Handling of "CreatePersistenceTopic" MQTT Persistence - Auto-restart Message Properties Persisting to a Remote FairCom Database Server Interpreting JSON Property Values MQTT Persistence API Can Map Nested JSON Structures to Multiple Tables Interpreting Non-JSON Data Types Subscribing to Messages Being Received by a Different MQTT Broker