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.