"configureBrokerConnection"
The "configureBrokerConnection"
action creates or updates a broker table in FairCom Edge
The "configureBrokerConnection"
creates or updates a reusable connection to an external broker, which may be another instance of FairCom MQ, FairCom Edge, or an MQTT broker from another vendor.configureBrokerConnection creates or updates a record in the mqtt_broker table inside the FairCom database in FairCom Edge.
The "configureBrokerConnection"
creates or updates a reusable connection to an external broker, which may be another instance of FairCom MQ, FairCom Edge, or an MQTT broker from another vendor. It stores this information in the "mqtt_broker"
table inside the embedded FairCom database. There is one record for each connection to an external MQTT broker.
Essential information
The
"brokerConnectionName"
is a unique user-defined name for the connection. It may be up to 100 characters long. It is used in all subsequent references to the connection, such as when configuring a topic to subscribe or forward messages to an external broker or when altering or deleting a broker connection.If the
"brokerConnectionName"
already exists, then when running"configureBrokerConnection"
FairCom's servers update the record rather than creating it.Care should be taken when editing an existing broker connection because multiple MQTT topics may use it.
If you do not wish to share a broker connection between multiple topics/integration tables (so you can control the broker connections independently), it is permissible to create multiple broker connections which all connect to the same external MQTT broker - giving each broker connection record a different
"brokerConnectionName"
.
Request examples
Minimal request example
{ "api": "mq", "authToken": "anAuthorizationTokenFromTheServer", "action": "configureBrokerConnection", "params": { "brokerConnectionName": "MqttBroker1", "brokerHostname": "mqtt.faircom.com" } }
{ "api": "mq", "apiVersion": "1.0", "requestId": "2", "authToken": "anAuthorizationTokenFromTheServer", "action": "configureBrokerConnection", "params": { "brokerConnectionName": "MqttBroker1", "brokerHostname": "mqtt.faircom.com", "brokerPort": 1883, "brokerUserName": "admin", "brokerUserPassword": "admin", "reconnectFrequencySeconds": 20, "command": "disconnect", "brokerTLS": {}, "metadata": {}, "reconnectFrequency":15 } }
Response examples
{ "result": {}, "errorCode": 0, "errorMessage": "" }
{ "result": {}, "requestId": "2", "errorCode": 0, "errorMessage": "" }
"params"
The "params"
property is an object that contains an action's parameters. Each action defines its own required and optional properties.
Properties summary
"params"
properties summaryProperty | Description | Default | Type | Limits (inclusive) | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
specifies a user-defined unique name for a broker integration | Required - No default value | string | 1 to 100 bytes | |||||||||
specifies a unique broker host name or TCP/IP address |
| string | 1 to 255 bytes | |||||||||
specifies the TCP/IP port |
| integer |
| |||||||||
defines login name to the external broker |
| string | ||||||||||
defines the login password to the external broker and information about how that password might be encrypted |
| string | ||||||||||
| specifies how the password is encrypted |
| string |
| ||||||||
| contains a base64 encoded representation of the password | Required - No default value | string | |||||||||
controls the behavior of a broker connection |
| string |
| |||||||||
exists primarily for the user interface to find integration information |
| object | May contain any number and type of user-defined properties | |||||||||
reconnectFrequency | specifies the number of seconds that the broker waits between attempts to reconnect to an external broker |
| integer | |||||||||
specifies the number of seconds that the broker waits between attempts to reconnect to an external broker |
| int32 |
| |||||||||
specifies the public server certificate filename, the certificate authority filename, and the Colon-delimited list of allowed ciphers |
| object | ||||||||||
| specifies an array of ciphers that the server will accept for communication with clients |
| string | |||||||||
| specifies the name and optional path of the certificate authorities certificate file (such as |
| string | |||||||||
| specifies the name and optional path of a server certificate file (such as |
| string | |||||||||
| specifies the name and optional path of a server key file (such as |
| string |
The "brokerConnectionName"
property is a required string that is a unique user-defined name for the connection. It may be up to 100 characters long.
The unique name defined in the "
brokerConnectionName"
property is used in all subsequent references to the connection, such as when configuring a topic to subscribe or forward messages to an external broker or when altering or deleting a broker connection.If the
"brokerConnectionName"
already exists, FairCom's server will update the record rather than create it.If you do not wish to share a broker connection between multiple topics/integration tables (so you can control the broker connections independently), you can create multiple broker connections which all connect to the same external MQTT broker - giving each broker connection record a different
"brokerConnectionName"
.
The "brokerHostname"
property is required. It must not be a zero-length string or contain only whitespace. It has a maximum length of 255 characters.
When creating a new broker connection, FairCom's servers log an error stating, "Cannot create the broker connection named xxx because brokerHostname is empty."
When updating an existing broker connection, FairCom's servers log an error stating, "Cannot update the broker connection named xxx because the new "brokerHostname" is empty. The current brokerHostname xxx and brokerPort xxx remain unchanged."
The "brokerPort"
property is optional. It defines the TCP/IP port. If it is not present, it defaults to 1883
.
If present, it must be a number between
1
and65535
inclusive.If the port is already in use, FairCom's server will not be able to run.
When it is set to a non-numeric value, or is out of range, FairCom's servers log an error stating, "Cannot create the broker connection named xxx because the brokerPort property is missing or is set to an invalid value. It must be present and set to a number greater than zero and less than 65536."
The "tls"
property is a JSON file that defines the public server certificate filename, the certificate authority filename, and the private key filename. This property is optional. It defaults to the empty object.
You can give the files any name.
The
"tls"
property also defines the allowed encryption methods or cipher suites.
Example
"tls": { "certificateFilename": "server.crt", "privateKeyFilename": "server.key", "certificateAuthoritiesFilename": "ca.crt", "allowedCipherSuites": "AES256-SHA256" }
The "brokerUsername"
property is the login name to the external broker. This property is an optional string from 1 to 64 bytes. If omitted, it defaults to an empty string.
Note
Unlike some other properties containing the "name", the "name" in "brokerUsername"
is all lowercase.
A zero-length username is invalid.
It is VARCHAR(500).
The "brokerUserPassword"
property is in JSON format and contains the login password to the external broker and information about how that password might be encrypted. This property is optional. It is VARCHAR(500). If omitted, it defaults to the empty string. Additional properties may be added in the future.
Example
{ "encryption": "NONE", "password": "myPassword" }
The "command"
property is optional. When omitted, it defaults to the empty string. If set to a valid command string, it executes the command.
"disconnect"
Tells the server to disconnect this broker connection.
"reconnect"
Tells the server to reconnect this broker connection..
"applySettingsNow"
Immediately applies the settings from this command.
"applySettingsWhenDisconnected"
Postpones the application of the settings within this command until the broker connection has been disconnected.
The "metadata"
property is an optional JSON object. It exists primarily for the user interface to find integration information. By default, it is an empty JSON object.
It contains a flexible set of properties.
It typically contains tags and description properties.
Example
{ "description": "", "tags": [""], "yourOwnProperties": "usage, purpose, notes, location, etc.", }
The "reconnectFrequencySeconds"
property is the number of seconds that the broker waits between attempts to reconnect to an external broker. This property is optional. If omitted, it defaults to 15
seconds.
If it is set to
0
, the broker does not attempt to reconnect when it loses a connection or fails to connect.FairCom's servers attempt to connect to an external broker when it is configured as a subscriber to topics on an external broker or when it is configured to forward messages to an external broker.
To stop the reconnect process, send the
"configureBrokerConnection"
message with the command property set to"disconnect"
.To restart the reconnect process, send the
"configureBrokerConnection"
message with the command property set to"reconnect"
.