Comment on page

Configuration

This section explains each of the properties in the configuration blade.
General
Property
Description
Collection
This associates the Agent to a specific Collection (defaults to that of the current Data Stream).
Refer to Collections and Stream Hosts to understand more about Collections.
Broker Connection
Property
Description
Use Variables
Tick to select saved variables; or enter the text manually.
Broker Address
The MQTT broker URL.
Topic
The name of the topic to listen for messages on the broker. To subscribe to multiple sites/assets in one Agent, the below wildcards can be used:
Single-level (+) replaces one topic level e.g.  'myhome/groundfloor/+/temperature'
Multi-level (#) is used at end end e.g. 'myhome/groundfloor/#'
Clean Session
Tick to have the MQTT broker keep undelivered messages for a short period in the event of connection issues, which will be delivered to the listener when connection is re-established; otherwise, any messages that arrive during a connection issue will not be received.
Client ID
A string to uniquely identify this stream object among the listeners on the topic (applies when Clean Session is not ticked).
Use Advanced Settings
Tick to use Advanced Settings, Channel, and Authentication for the Broker Connection.
Advanced Settings
This applies when Use Advanced Settings is ticked.
Property
Description
Port
The listener Port for the MQTT broker. 

Defaults to Port 1883 if left blank or Use Advanced Settings is not ticked.
QoS
The Quality of Service defines the guarantee of delivery of messages to the MQTT broker. The options are:
At most once - (QoS 0) Guarantees a best-effort delivery. There is no guarantee of delivery.
At least once - (QoS 1) Guarantees that a message is delivered at least one time to the receiver.
Exactly once - (QoS 2) Guarantees that each message is received only once by the intended recipients.
Defaults to Exactly Once when Use Advanced Settings is not ticked.
Channel
TLS and SSL provide a secure communication channel between the client and the MQTT broker. It can be used in the Agent if the MQTT broker is configured to support Certificate-based TLS/SSL. This applies when Use Advanced Settings is ticked.
Property
Description
Secure Channel
Tick to use a Secure Channel when connecting to the MQTT broker.
Protocol
The TLS/SSL protocol and version options to use on the Secure Channel are (applies when Secure Channel is ticked):
SSL v3
TLS v1.0
TLS v1.1
TLS v1.2
Root Certificate
The Root CA Certificate of the MQTT broker - usually provided by the MQTT broker owner (applies when Secure Channel is ticked).
Client Certificate
The Client Certificate contains the Public/Private Key pair, which verifies the identity of the client (applies when Secure Channel is ticked).

The Client Certificate must be generated from the same CA used by the MQTT broker. This is bundled with its Private key into a PFX format and password protected when exporting.
Client Certificate Password
The Password used to export the Public/Private Key pair of the Client Certificate (applies when Secure Channel is ticked).
The client certificate and password are not required if the MQTT broker is configured to not require a client certificate. In this case, the root certificate will suffice.
Authentication
This applies when Use Advanced Settings is ticked. Anonymous authentication will be used if these values are not provided.
Property
Description
Username
The Username to authentice the broker connection.
Password
The Password to authenticate the broker connection.
Payload
Property
Description
Payload Format
The expected format of the received messages. The options are JSON (default), HEX and Plain Text.
Specify JSON Path to Payload
Tick to allow complex JSON objects to be read from the message by specifying a dot-notation path for each property (applies to JSON Payload Format only).
Include Source Message in Payload
Tick to add a "SourceMessage" string property to the output payload which contains the original message.
Include Topic in Payload
Tick to add a "Topic" string property to the output payload which contains the message's topic name. 
​
This is useful when using wildcards in the Topic property to distinguish data coming from multiple topics.
Include Timestamp in Payload
Tick to add a "CurrentTimestampInUTC" datetime property to the output payload which contains the message's current timestamp in UTC.
Payload Definition
(Name, JSON Path, Type, Indexes)
Defines the shape of records that will be received and output:
Name - The name of the property.
JSON Path - The JSON path to the property value to be extracted (applies to JSON Payload Format when Specify JSON path to payload is ticked).
Eg. Given a payload of:
{"store":{"book":{"category": "reference","author": "Nigel Rees"}}}
The JSON Path to the "author" attribute would be "store.book.author"
Type - The property type options are String, Int, Long, Double, Boolean, and DateTime (applies to JSON and Plain Text Payload Format only).
Indexes - The Indexes of the property from the HEX payload (applies to HEX Payload Format only).
When using a Plain Text Payload Format, adding or removing grid rows is disabled. One row is made available with "Value" as the Name and "String" as the data type. The data type can be amended.
Endpoints
Name
Description
Output
An event per received message is made available to this endpoint, with attributes as specified by the Payload configuration.
Error
Errors encountered during the execution of this Agent will be published on this endpoint.

Property	Description
Collection	This associates the Agent to a specific Collection (defaults to that of the current Data Stream).

Property	Description
Use Variables	Tick to select saved variables; or enter the text manually.
Broker Address	The MQTT broker URL.
Topic	The name of the topic to listen for messages on the broker. To subscribe to multiple sites/assets in one Agent, the below wildcards can be used: Single-level (+) replaces one topic level e.g. 'myhome/groundfloor/+/temperature' Multi-level (#) is used at end end e.g. 'myhome/groundfloor/#'
Clean Session	Tick to have the MQTT broker keep undelivered messages for a short period in the event of connection issues, which will be delivered to the listener when connection is re-established; otherwise, any messages that arrive during a connection issue will not be received.
Client ID	A string to uniquely identify this stream object among the listeners on the topic (applies when Clean Session is not ticked).
Use Advanced Settings	Tick to use Advanced Settings, Channel, and Authentication for the Broker Connection.

Property	Description
Port	The listener Port for the MQTT broker. Defaults to Port 1883 if left blank or Use Advanced Settings is not ticked.
QoS	The Quality of Service defines the guarantee of delivery of messages to the MQTT broker. The options are: At most once - (QoS 0) Guarantees a best-effort delivery. There is no guarantee of delivery. At least once - (QoS 1) Guarantees that a message is delivered at least one time to the receiver. Exactly once - (QoS 2) Guarantees that each message is received only once by the intended recipients. Defaults to Exactly Once when Use Advanced Settings is not ticked.

Property	Description
Secure Channel	Tick to use a Secure Channel when connecting to the MQTT broker.
Protocol	The TLS/SSL protocol and version options to use on the Secure Channel are (applies when Secure Channel is ticked): SSL v3 TLS v1.0 TLS v1.1 TLS v1.2
Root Certificate	The Root CA Certificate of the MQTT broker - usually provided by the MQTT broker owner (applies when Secure Channel is ticked).
Client Certificate	The Client Certificate contains the Public/Private Key pair, which verifies the identity of the client (applies when Secure Channel is ticked). The Client Certificate must be generated from the same CA used by the MQTT broker. This is bundled with its Private key into a PFX format and password protected when exporting.
Client Certificate Password	The Password used to export the Public/Private Key pair of the Client Certificate (applies when Secure Channel is ticked).

Property	Description
Username	The Username to authentice the broker connection.
Password	The Password to authenticate the broker connection.

Property	Description
Payload Format	The expected format of the received messages. The options are JSON (default), HEX and Plain Text.
Specify JSON Path to Payload	Tick to allow complex JSON objects to be read from the message by specifying a dot-notation path for each property (applies to JSON Payload Format only).
Include Source Message in Payload	Tick to add a "SourceMessage" string property to the output payload which contains the original message.
Include Topic in Payload	Tick to add a "Topic" string property to the output payload which contains the message's topic name. This is useful when using wildcards in the Topic property to distinguish data coming from multiple topics.
Include Timestamp in Payload	Tick to add a "CurrentTimestampInUTC" datetime property to the output payload which contains the message's current timestamp in UTC.
Payload Definition (Name, JSON Path, Type, Indexes)	Defines the shape of records that will be received and output: Name - The name of the property. JSON Path - The JSON path to the property value to be extracted (applies to JSON Payload Format when Specify JSON path to payload is ticked). Eg. Given a payload of: `{"store":{"book":{"category": "reference","author": "Nigel Rees"}}}` The JSON Path to the "author" attribute would be "store.book.author" Type - The property type options are String, Int, Long, Double, Boolean, and DateTime (applies to JSON and Plain Text Payload Format only). Indexes - The Indexes of the property from the HEX payload (applies to HEX Payload Format only). When using a Plain Text Payload Format, adding or removing grid rows is disabled. One row is made available with "Value" as the Name and "String" as the data type. The data type can be amended.

Name	Description
Output	An event per received message is made available to this endpoint, with attributes as specified by the Payload configuration.
Error	Errors encountered during the execution of this Agent will be published on this endpoint.

Last modified 2mo ago