`"configureBrokerConnection"`

Abstract

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.

Things to know

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

Maximal request example

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

Minimal response example

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

Maximal response example

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

Property summary

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

"brokerConnectionName"

specifies a user-defined unique name for a broker integration

Required - No default value

string

Minimum length: 1

Maximum length: 100

"brokerHostname"

specifies a unique broker host name or TCP/IP address

"localhost"

string

Minimum length: 1

Maximum length: 255

"brokerPort"

specifies the TCP/IP port

1883

integer

2 - 65534

"brokerUsername"

defines login name to the external broker

""

string

"brokerUserPassword"

defines the login password to the external broker and information about how that password might be encrypted

""

string

"command"

controls the behavior of a broker connection

"applySettingsWhenDisconnected"

string

"disconnect"

"reconnect"

"applySettingsNow"

"applySettingsWhenDisconnected"

"pause"

"resume"

"removeIntegration"

"restoreIntegration"

"metadata"

exists primarily for the user interface to find integration information

{}

object

May contain any number and type of user-defined properties

"reconnectFrequency"

defines the number of seconds that the broker waits between attempts to reconnect to an external broker

15

integer

"reconnectFrequencySeconds"

defines the number of seconds that the broker waits between attempts to reconnect to an external broker

15

int32

1 - 65,535

"tls"

defines the public server certificate filename, the certificate authority filename, and the Colon-delimited list of allowed ciphers

{}

object

`"brokerConnectionName"`

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.

Things to know:

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

`"brokerHostname"`

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 these rules are violated the following errors will be displayed:

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

`"brokerPort"`

The "brokerPort" property is optional. It defines the TCP/IP port. If it is not present, it defaults to 1883.

Things to know:

If present, it must be a number between 1 and 65535 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."

`"tls"`

The "tls" property is 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.

Things to know:

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

Property summary

Table 2. "tls" property summaries

Element	Description	Type	Default
`"allowedCipherSuites"`	specifies an array of ciphers that the server will accept for communications with clients	string	`""`
`"certificateAuthoritiesFilename"`	specifies the name and optional path of the certificate authorities certificate file (such as `"ca.pem"`)	string	`""`
`"certificateFilename"`	specifies the name and optional path of a server certificate file (such as `"ca.pem"`)	string	`""`
`"privateKeyFilename"`	specifies the name and optional path of a server key file (such as `"key.pem"`)	string	`""`

"allowedCipherSuites"

The "allowedCiperSuites" property is an optional string that specifies an array of ciphers that the server will accept for communications with clients. It defaults to an empty string.

Things to know:

It specifies the encryption ciphers that are allowed to be used for encrypting a TLS (SSL) connection.
A client is allowed to connect to the server only if it uses one of the ciphers in this list.
The default setting of an empty string supports maximally secure connections.
The default value requires clients to use full AES 256-bit encryption when they talk to the server.
If a client cannot support AES 256-bit encryption, a lower encryption level should be added to the list.
Note
This is undesirable because malicious users will attempt to connect at the lowest possible level so they can harm the system (for more information see ciphers main page at OPENSSL.org.
Example settings:
- Maximally secure example:
  Note
  Only allows clients to connect securely.
```
["AES256-SHA256", "AES256-GCM-SHA38", "DHE-RSA-AES256-SHA256"]
```
- Minimally secure example with the broadest client support:
```
["!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
```
- Insecure example allowing clients to connect using any level of security from none to the maximal:
```
["ALL", "!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
```
Add @STRENGTH to the end of the list to force the server to prioritize the strongest algorithms first.
Place an exclamation point before a cipher to disable it.

"certificateAuthoritiesFilename"

The "certificateAuthoritiesFilename" property is an optional string that specifies the name and optional path of the CA certificate file (such as "ca.pem"). It defaults to an empty string.

Things to know:

You must include "certificateAuthoritiesFilename" to allow clients to use X509 certificates to authenticate with the server.
The certificate authorities file contains the list of certificate authorities the server uses to validate X509 certificates that clients present as authentication credentials.
In order for an X509 certificate to be accepted by the server, the certificate must be signed by a certificate authority that is present in the certificate authorities certificate file.

`"brokerUsername"`

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

`"brokerUserPassword"`

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

Property summary

Table 3. "brokerUserPassword" property summaries

Property

Description

Default

Type

Limits (inclusive)

"encryption"

defines how the password is encrypted

"NONE"

string

"NONE"

"AES"

"password"

contains a base64 encoded representation of the password

Required - No default value

string

`"command"`

The "command" property is optional. When omitted, it defaults to the empty string. If set to a valid command string, it executes the command.

The following service commands are available:

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

`"metadata"`

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.

Things to know:

It contains a flexible set of properties.
It typically contains tags and description properties.

Example

{
  "description": "",
  "tags": [""],
  "yourOwnProperties": "usage, purpose, notes, location, etc.",
}

`"reconnectFrequencySeconds"`

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.

Things to know:

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