MQTT Subscriber | X4Documentation

This adapter allows you to subscribe to a topic publish messages in an MQTT broker.

The MQTT protocol provides a simple method of delivering messages via a publish/subscribe model. This makes it particularly suitable for messaging in the Internet of Things environment, such as low-power sensors or mobile devices such as phones, embedded computers or microcontrollers.

Note:

The MQTT Subscriber is usually used in conjunction with the MQTT Publisher.

Properties

Operation

Operation executed by the adapter

Possible values:

Subscribe: Allows you to subscribe to a topic in an MQTT broker.
Unsubscribe: Allows you to unsubscribe from a topic in an MQTT broker.

Parameters

`Adapter`	Adapter main class (do not change!) Possible values: de.softproject.integration.adapter. mqtt.MqttSubscriberAdapter: Main class (default)
`Alias`	Broker alias Possible values: Any string The alias can be defined as an attribute of the `Broker` element within the `mqttconfig.xml` configuration file.
`ClientId`	Identifier for the client that subscribes to the broker Possible values: If the client ID is defined in the `mqttconfig.xml` configuration file: any string If the client ID is not defined in the `mqttconfig.xml` configuration file: UUID The client ID can be defined within the `mqttconfig.xml` configuration file for each broker in the `ClientId` element.
`clientTimeout`	Timeout for ONLINE_ON_DEMAND connections (for the `Subscribe` operation). If `ConnectionMode` differs from `ONLINE_ON_DEMAND`, `ClientTimeout` is not taken into account. Possible values: Integer greater than `0`
`connectionMode`	Connection mode selected to create the client. Depending on the selected value, the client connection is retained or is disconnected after a certain time (`ClientTimeout`). Possible values: `ONLINE_ON_DEMAND`: The `ClientTimeout` parameter is required to configure the client. `ALWAYS_ONLINE_ON_FIRST_PUBLISH`: The client remains connected as soon as an initial publication occurs. Therefore, the `ClientTimeout` parameter is not required. This parameter is not required if `alias` and `clientId` are defined in the configuration file, or if the `alias` and `clientId` values have already been used to connect.
`stateful`	Specifies whether the state between the client and the broker is state-oriented. Possible values: `true` / `false` This parameter is not required if `alias` and `clientId` are defined in the configuration file, or if the `alias` and `clientId` values have already been used to connect.
`keystorePath`	Path to the keystore. If no SSL/TLS configuration is required to connect to the broker, the parameter value can be empty. Possible values: File path This parameter is not required if `alias` and `clientId` are defined in the configuration file, or if the `alias` and `clientId` values have already been used to connect.
`keystorePassword`	Password to the keystore specified for `KeystorePath`. Possible values: Any string This parameter is not required if `alias` and `clientId` are defined in the configuration file, or if the `alias` and `clientId` values have already been used to connect.
`Topic`	Name of the topic the client subscribes to Possible values: Any string The topic can be defined for each broker in the `Filter` attribute of the `Topic` element within the `mqttconfig.xml` configuration file.
`server`	Protocol, host, and port for connecting the client to the broker. Possible values: `tcp://hostname:port`: If no SSL/TLS connection is used. `ssl://hostname:port`: If an SSL/TLS connection is used. This parameter is not required if `alias` and `clientId` are defined in the configuration file, or if the `alias` and `clientId` values have already been used to connect.
`InputFormat`	Input format of the adapter Possible values: `BYTES` `BASE64_STRING` `BASE64_XML`
`loginUsername`	Username used to connect to a broker requesting credentials. Possible values: User name This parameter is not required if `alias` and `clientId` are defined in the configuration file, or if the `alias` and `clientId` values have already been used to connect.
`loginPassword`	Password used to connect to a broker who requires credentials. Possible values: Password This parameter is not required if `alias` and `clientId` are defined in the configuration file, or if the `alias` and `clientId` values have already been used to connect.
`QoS`	Quality of service, for receiving messages when subscribing to a topic. Possible values: `AT_MOST_ONCE` `AT_LEAST_ONCE` (default) `EXACTLY_ONCE` This parameter is not required if `alias` and `clientId` are defined in the configuration file, or if the `alias` and `clientId` values have already been used to connect.
`Process`	Path to the process that runs each time a message from the subscribed topic is received Possible values: Process path in the format `x4db://User/process.wrf`

Status values

`1`	The operation was successful.
`-1`	There was an error while connecting, disconnecting, publishing, or subscribing.

Input

The adapter does not expect any input document.

Output

The output corresponds to the input.

Configuration file

To define broker, client, SSL/TLS configurations, etc., a configuration file with a specified structure can be used, which is loaded at server startup. The mqttconfig.xml configuration file must be stored under the path X4DB/0. If the broker and client are defined in the configuration file, then only the values for alias and cliendId must be specified in the adapter parameters.

The file contains the following elements:

KeyStore	The path and password of the keystore used to establish an SSL connection to the broker. If this optional element is not specified, a trust manager is created to accept all certificates. Both absolute and relative paths to the `X4DB/0` directory can be specified when specifying the path. Example: Relative path specification XML `<RootElement> <KeyStore password="p4ssw0rd">keystore.jks</KeyStore> </RootElement>` Absolute path specification XML `<RootElement> <KeyStore password="p4ssw0rd">C:\Path\To\Keystore\keystore.jks</KeyStore> </RootElement>`
Broker	MQTT server Relevant information is embedded in the `alias` attribute. This attribute must be unique. The broker contains the following elements: `Server`: Broker URL; TSL and TCP protocols are supported. `ssl://host:port` : The connection to the broker takes place via the TSL protocol. The host is replaced by the host server and the port is replaced by the port server. `tcp://host:port` : The connection to the broker takes place via the TCP protocol (without SSL encryption). The host is replaced by the host server and the port is replaced by the port server. `ClientId`: Unique client ID with the following attributes: `mode`: Type of connection `ALWAYS_ONLINE_ON_STARTUP` ( default: The adapter connects at server startup and maintains the connection all the time `ALWAYS_ONLINE_ON_FIRST_PUBLISH` : The connection is established on the first request (Publish) and maintained all the time `ONLINE_ON_DEMAND` : The adapter connects when there is no connection yet and has an additional `timeout` attribute that is only valid in this mode. The attribute disconnects the connection after the specified time (in seconds) after the last message has been sent. If `mode` has an invalid value or is empty, the default value `ALWAYS_ONLINE_ON_STARTUP` is assumed. `timeout`: Timeout in seconds. This attribute is only valid for the `ONLINE_ON_DEMAND` connection type and disconnects after the specified time (in seconds) after the last message is sent. If `timeout` is empty, the default value of 20 seconds is assumed.
Topic	Topic that can be subscribed to receive the published message. It has the following attributes: `filter`: Name of the topic filter `qos`: Quality of service `AT MOST ONCE` : The message is delivered once at most or not once. There will be no notification when the delivery has been made. `AT LEAST ONCE` : The message is delivered at least once. If the sender does not receive a notification, the message with the DUP flag is redelivered until a notification is received. `EXACTLY ONCE` : The message must be stored locally at the sender and the recipient until it is processed. If the `QoS` attribute is not specified, the default value is `AT_LEAST_ONCE`. A process is defined for each topic that is to be executed after the message is received. The Process element has the following attributes: `url`: Process path in the format x4db://User/process.wrf

KeyStore

The path and password of the keystore used to establish an SSL connection to the broker. If this optional element is not specified, a trust manager is created to accept all certificates.

Both absolute and relative paths to the X4DB/0 directory can be specified when specifying the path.

Example:

Relative path specification

XML

<RootElement>
    <KeyStore password="p4ssw0rd">keystore.jks</KeyStore>
</RootElement>

Absolute path specification

XML

<RootElement>
    <KeyStore password="p4ssw0rd">C:\Path\To\Keystore\keystore.jks</KeyStore>
</RootElement>

Broker

MQTT server

Relevant information is embedded in the alias attribute. This attribute must be unique.
The broker contains the following elements:

Server: Broker URL; TSL and TCP protocols are supported.
- ssl://host:port : The connection to the broker takes place via the TSL protocol.
- The host is replaced by the host server and the port is replaced by the port server.
- tcp://host:port : The connection to the broker takes place via the TCP protocol (without SSL encryption).
  The host is replaced by the host server and the port is replaced by the port server.
ClientId: Unique client ID with the following attributes:
- mode: Type of connection
  - ALWAYS_ONLINE_ON_STARTUP ( default: The adapter connects at server startup and maintains the connection all the time
  - ALWAYS_ONLINE_ON_FIRST_PUBLISH : The connection is established on the first request (Publish) and maintained all the time
  - ONLINE_ON_DEMAND : The adapter connects when there is no connection yet and has an additional timeout attribute that is only valid in this mode. The attribute disconnects the connection after the specified time (in seconds) after the last message has been sent.
  If mode has an invalid value or is empty, the default value ALWAYS_ONLINE_ON_STARTUP is assumed.
- timeout: Timeout in seconds. This attribute is only valid for the ONLINE_ON_DEMAND connection type and disconnects after the specified time (in seconds) after the last message is sent.
  If timeout is empty, the default value of 20 seconds is assumed.

Topic

Topic that can be subscribed to receive the published message. It has the following attributes:

filter: Name of the topic filter
qos: Quality of service
- AT MOST ONCE : The message is delivered once at most or not once. There will be no notification when the delivery has been made.
- AT LEAST ONCE : The message is delivered at least once. If the sender does not receive a notification, the message with the DUP flag is redelivered until a notification is received.
- EXACTLY ONCE : The message must be stored locally at the sender and the recipient until it is processed.
If the QoS attribute is not specified, the default value is AT_LEAST_ONCE.
A process is defined for each topic that is to be executed after the message is received. The Process element has the following attributes:

url: Process path in the format x4db://User/process.wrf

Example configuration

XML

<?xml version='1.0' encoding='UTF-8'?>
<RootElement>
	<!-- Both, relative and absolute paths to X4DB/0 are allowed -->
    <KeyStore password="password">C:/Users/MaxMustermann/Documents/MQTT/Keystore/application.keystore</KeyStore>
    <Broker alias="Mosquitto_MQTT">
        <Server>ssl://localhost:8883</Server>
        <ClientId mode="ALWAYS_ONLINE_ON_STARTUP">C1</ClientId>
        <ClientId mode="ALWAYS_ONLINE_ON_FIRST_PUBLISH">C2</ClientId>
        <ClientId timeout="40" mode="ONLINE_ON_DEMAND">C3</ClientId>
        <ClientId timeout="20" mode="ONLINE_ON_DEMAND">C4</ClientId>
        <Topic filter="topic/action1" qos="AT_LEAST_ONCE">
            <Process url="x4db://1/X4Experience/ESB/3-Reference/1-AdapterSuites/X4MQTTAdapter/Processes/TopicProcesses/ProcessTopic1.wrf"/>
        </Topic>
        <Topic filter="topic/action2" qos="AT_MOST_ONCE">
            <Process url="x4db://1/X4Experience/ESB/3-Reference/1-AdapterSuites/X4MQTTAdapter/Processes/TopicProcesses/ProcessTopic2.wrf"/>
        </Topic>
        <Topic filter="topic/action1" qos="EXACTLY_ONCE">
            <Process url="x4db://1/X4Experience/ESB/3-Reference/1-AdapterSuites/X4MQTTAdapter/Processes/TopicProcesses/ProcessTopic3.wrf"/>
        </Topic>
    </Broker>
</RootElement>