Skip to main content

"configureBrokerConnection"

JSON MQ and Hub "configureBrokerConnection" action connects a FairCom Server to an external broker

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

{
  "api": "mq",
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "action": "configureBrokerConnection",
  "params": {
    "brokerConnectionName": "MqttBroker1",
    "brokerHostname": "mqtt.faircom.com"
  }
}

Maximal request

{
  "api": "mq",
  "apiVersion": "1.0",
  "requestId": "2",
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "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

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

Maximal response

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

configureBrokerConnection creates or updates a record in the mqtt_broker table inside the FairCom database in FairCom Edge

API actionsJSON MQ APIjsonActionconfigure broker connectionconfigureBrokerConnectionconfigureBrokerConnectionsconfiguresBrokerConnectionconfiguresBrokerConnections

"params"

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

Properties summary

Table 1. "params" properties summary

Property

Description

Default

Type

Limits (inclusive)

brokerConnectionName

specifies a user-defined unique name for a broker integration

Required - No default value

string

1 to 100 bytes

brokerHostname

specifies a unique broker host name or TCP/IP address

Required - No default value

string

1 to 255 bytes

brokerPort

specifies the TCP/IP port

1883

integer

2 to 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

brokerUserPassword
.encryption

specifies how the password is encrypted

"NONE"

string

"NONE"
"AES"
brokerUserPassword
.password

contains a base64 encoded representation of the password

Required - No default value

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

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

15

integer

reconnectFrequencySeconds

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

15

int32

1 to 65535

tls

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

{}

object

tls
.allowedCipherSuites

specifies an array of ciphers that the server will accept for communication with clients

""

string

tls
.certificateAuthoritiesFilename

specifies the name and optional path of the certificate authorities certificate file (such as "ca.pem")

""

string

tls
.certificateFilename

specifies the name and optional path of a server certificate file (such as "ca.pem")

""

string

tls
.privateKeyFilename

specifies the name and optional path of a server key file (such as "key.pem")

""

string



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

Essential information

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

Essential information

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

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

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

Essential information

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

Essential information

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

"tls"

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. 

Essential information

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

JavaScript Object Notation (JSON) is a simple format for representing data. It requires very little markup and is flexible enough to represent the majority of data structures. It is self-describing, which makes it ideal for schemaless applications and search. It can optionally be paired with a schema to define an expected structure.