Skip to main content

"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",
  "apiVersion": "1.0",
  "requestId": "00000001",
  "authToken": "anAuthorizationTokenFromTheServer",
  "action": "configureBrokerConnection",
  "params": {
    "brokerConnectionName": "MqttBroker1",
    "brokerHostname": "https://mqtt.faircom.com/"
  }
}
{
  "api": "mq",
  "apiVersion": "1.0",
  "requestId": "00000001",
  "authToken": "anAuthorizationTokenFromTheServer",
  "action": "configureBrokerConnection",
  "params": {
    "brokerConnectionName": "MqttBroker1",
    "brokerHostname": "https://mqtt.faircom.com/",
    "brokerPort": 8883,
    "brokerUserName": "admin",
    "brokerUserPassword": "admin",
    "reconnectFrequencySeconds": 20,
    "command": "disconnect",
    "brokerTLS": {},
    "metadata": {},
    "reconnectFrequency":15
  }
}

Response examples

{
    "result": {},
    "requestId": "00000039",
    "errorCode": 0,
    "errorMessage": ""
}
{
    "result": {},
    "requestId": "00000041",
    "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"

defines a user-defined unique name for a broker integration

Required - No default value

string

Minimum length: 1
Maximum length: 100

"brokerHostname"

defines a unique broker host name or TCP/IP address

"localhost"

string

Minimum length: 1
Maximum length: 255

"brokerPort"

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

"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



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

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

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

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

Limits (inclusive)

"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

""



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

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



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:
  • ""

    The empty string default does nothing.

  • "pause"

    This temporarily stops a service.

    • An input service stops inserting data into the table. Pausing causes most input services to discard data they receive or to stop retrieving data.

    • An output service stops delivering data.  Pausing an output service does not cause data to be lost. When the service is resumed it picks up from where it left off.

  • "resume"

    This unpauses a service.

  • "removeIntegration"

    This removes an integration.

  • "restoreIntegration"

    This restores a previously removed integration.

    Note

    These commands do NOT affect the SQL, JSON RPC, and REST services.  They also do not apply to MQTT services. MQTT cannot be paused or resumed. Also MQTT services are exclusively managed by "configureTopic".

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

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