Configuration
Last updated
Was this helpful?
Last updated
Was this helpful?
This section explains each of the properties in the configuration blade.
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.
Use Variables
Tick to select saved variables; or enter the text manually.
Broker Address
The MQTT broker URL.
Topic Source
The options to get the value from are (applies only when User Variables is Ticked):
User Input - Topic is entered manually. Use this option if you want to enter the topic manually, but Use Variables is ticked.
Variable - Topic is selected from the Server Variables.
Topic
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.
This applies when Use Advanced Settings is ticked.
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.
Send Status Message
Tick to enable sending the current status of the Agent as a message to the MQTT broker using the configured Status Topic.
The status message values are:
"online" is sent when the Data Stream is published and the Agent is connected successfully.
"offline" is sent when the Data Stream is unpublished - or there is an unexpected shutdown - and the Agent is disconnected.
Status Topic
The Topic on the MQTT Broker where the status message is sent (applies when Send Status Message? is ticked).
Tip: Use a structure on the Status Topics so that another MQTT Listener could monitor the status of multiple agents using a wildcard.
i.e. xmpro/datastream/{agentname}/status
Use Message Correlation
Correlation Types
The types of messages to wait for before outputting the received messages as a single event (applies when Use Message Correlation is ticked).
Max Queue
The maximum number of unique Correlation Ids that are queued while waiting to complete all of its Correlation Types (defaults to 100, maximum 10 000) (applies when Use Message Correlation is ticked).
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.
Secure Channel
Tick to use a Secure Channel when connecting to the MQTT broker.
Security 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.
This applies when Use Advanced Settings is ticked. Anonymous authentication will be used if these values are not provided.
Username
The Username to authenticate the broker connection.
Password
The Password to authenticate the broker connection.
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.
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.
The name of the topic to listen for messages on the broker. To subscribe to multiple sites/assets in one Agent, the below can be used:
Tick to synchronize multiple MQTT Messages using the added properties on its Correlation Data. Messages received are grouped by their Correlation Id and wait for all selected Correlation Types to arrive before being outputted it as a single event. Using Message Correlation allows you to do parallel processing on multiple Data Streams, ensuring that the results from all those Data Streams are received before doing additional processing. See on how to receive Correlation Data and synchronize messages.