"configureTopic" (JSON Action)

A zero-length "databaseName" is invalid.

Its limits are from 0 to 64 bytes.

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", "defaultDatabaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.

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.

If there are no items in the list, it is not an error, FairCom's servers simply do not set up any external forwards.  This is also how you can configure an existing topic to STOP forwarding to external brokers.

If this broker connection name does not already exist:

Each time the "configureTopic" message is sent, FairCom's servers will completely replace its existing list for "forwardToExternalBrokers" with the new list.

If a topic does not already exist, FairCom's servers create it as if an external client sent a message to the topic.

Each time the "ConfigureTopic" message is sent, FairCom's servers will completely replace its existing list for "forwardToTopics" with the new list.

FairCom's servers will not forward a topic to itself. Thus, if the "forwardToTopics" array contains the topic from "ConfigureTopic", FairCom's servers ignore it.

This feature is designed to ease the pain of topic migration, which occurs when clients begin publishing to different topics before subscribers can adjust.

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.

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.

It contains a flexible set of properties.

It typically contains tags and description properties.

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.

It may be set to one of two values:

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.

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, which may be a maximum of 2,147,483,647 messages.

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.

"upsert"

This is the default value. It treats this method as an "upsert". If the connection already exists, it updates it.  If the connection does not exist, it inserts it. It does not throw an error.

"insert"

It treats this method as an insert. If the connection already exists, FairCom's servers log an error stating, "Cannot insert service connection xxx because it already exists."

"update"

It treats this method as an update. If the connection does not already exist, FairCom's servers log an error stating, "Cannot update service connection xxx because it does not exist."

"outputPayloadField" must be one of the following values: 

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

Periodically, the system increments the age of each table partition.

"retentionPeriod" implicitly calculates an upper bound on how many partitions are able to accumulate on your hard drive. However, partitions are not deleted just because this calculated number of partitions is reached. The system also does not restrict the deletion of all partitions.

If the FairCom database is shut down for a month, when the database is started up again, all partitions that are retained for less than one month are immediately deleted.

If someone purposely or accidentally sets the date to a future date, all partitions immediately become older, and auto-deletion ensues accordingly.

Each time the "retentionPeriod" cycles, FairCom's servers automatically and efficiently delete expired data.

The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".

FairCom's servers only use the "retentionPeriod" property when the "retentionPolicy" is "autoPurge".

The "retentionPeriod" can be changed to retain fewer or more messages. Changing it does not necessarily destroy existing data, but data may expire more quickly or be retained longer.

The "retentionPeriod" and "retentionUnit" properties control data granularity as well as the retention time.  In other words, "retentionPeriod" defines how many sets of data are stored, and "retentionUnit" defines how often data is purged.

For example, if "rententionPeriod" is set to 14 , the server stores 14 sets of data. At the beginning of the 15th cycle, the server automatically purges the oldest set of data. If "retentionUnit" is set to day, then data will be purged daily. If set to "week", then data will be purged weekly.

The current calendar date affects purging.

FairCom's servers automatically purge all retained data that has expired. This is noticeable when FairCom's servers come online after having been offline for a long time. When a server comes back online, it automatically purges all expired data.

For example, if a FairCom server is offline for four weeks when it comes online, it will completely purge all retained data that has a retention time of less than 4 weeks.

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

This property is used in concert with "retentionPeriod" to determine retention time.

"retentionUnit" values:

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.

Any client can publish messages to this topic.

A valid Broker Connection must be created before you set "subscribeToExternalBroker" to a value (see "configureBrokerConnection").

If this broker connection name does not already exist, it does not set up an external subscription and it logs an error stating, "Cannot subscribe to the external broker because the Broker Connection name xxx has not yet been defined by ConfigureBrokerConnection."

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

You must specify a non-empty string for an integration table name.

FairCom Edge an FairCom MQ automatically create an integration table for each new MQTT topic they process. The first characters in the table name are "mqtt_msg_" followed by the topic name. Because an MQTT topic can be 65500 bytes and a table name can be 64 bytes, the server may abbreviate the topic name.

To better identify the data it holds, rename an integration using the "tableName" property of the "configureTopic" action.

The default of 1 is enough to handle typical workloads.

For heavy workloads, you may increase the number of threads to 2 or 3.

The "topic" name may be up to 65,500 characters long, but it 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.

A transform is a process that works like a pipeline where the output of one transformation can become the input for another transformation.

The following actions use the "transformName" property to assign a transform to an integration table: