# mulesoft MQTT Connector - Full Documentation --- product: MQTT Connector version: 1.0 --- # Configure the Last Will and Testament Messages for MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt In this example, you set a Last Will and Testament (LWT) message for Anypoint Connector for MQTT (MQTT Connector) to ensure that a message is sent to all of the subscribers of a specific LWT topic if the client disconnects temporarily or permanently from the broker. The LWT message is sent when the connection to the broker is established. Configure the LWT message in the configuration element and specify whether or not you want the broker to retain that message. If an MQTT message is set for retention, the broker stores the last message marked as retained that arrived at a specific topic. If no listeners are subscribed to a matching topic at the time the message is sent, the broker stores the message until a listener connects to that topic. Then, the broker delivers the listener to the last message retained for that topic. 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In **MQTT3 Config** > **Connection**, select **MQTT3 Form Connection**. 6. For **Client id generator**, select **Client id random suffix generator**. 7. Set the following fields: - **Client ID**: `smart-bentley-123` - **Username**: `usertest` - **Password**: `passtest` - **URL**: `tcp://127.0.0.1:1883` 8. Click **LWT**. 9. Set the following fields: - **Topic**: `LWT` - **Body**: `Testing body message` - **Is retained**: **True**. 10. Click **OK**. ![MQTT Config window with Last Will and Testament configuration window selected](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-lwt-configuration.png) In the **Configuration XML** editor, the `` configuration looks like this: ```xml ``` ## See Also - [MQTT Connector Examples](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # Configure the Last Will and Testament Messages for MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt In this example, you set a Last Will and Testament (LWT) message for Anypoint Connector for MQTT (MQTT Connector) to ensure that a message is sent to all of the subscribers of a specific LWT topic if the client disconnects temporarily or permanently from the broker. The LWT message is sent when the connection to the broker is established. Configure the LWT message in the configuration element and specify whether or not you want the broker to retain that message. If an MQTT message is set for retention, the broker stores the last message marked as retained that arrived at a specific topic. If no listeners are subscribed to a matching topic at the time the message is sent, the broker stores the message until a listener connects to that topic. Then, the broker delivers the listener to the last message retained for that topic. 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In **MQTT3 Config** > **Connection**, select **MQTT3 Form Connection**. 6. For **Client id generator**, select **Client id random suffix generator**. 7. Set the following fields: - **Client ID**: `smart-bentley-123` - **Username**: `usertest` - **Password**: `passtest` - **URL**: `tcp://127.0.0.1:1883` 8. Click **LWT**. 9. Set the following fields: - **Topic**: `LWT` - **Body**: `Testing body message` - **Is retained**: **True**. 10. Click **OK**. ![MQTT Config window with Last Will and Testament configuration window selected](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-lwt-configuration.png) In the **Configuration XML** editor, the `` configuration looks like this: ```xml ``` ## See Also - [MQTT Connector Examples](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # Configure the Quality of Service for MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The MQTT protocol enables you to specify levels of delivery assurance for inbound or outbound messages. These levels are referred to as _quality of service_ (QoS). The available QoS levels to configure for MQTT Connector are: - **AT\_MOST\_ONCE** Messages are delivered at most one time ("fire and forget") and delivery is not guaranteed. - **AT\_LEAST\_ONCE** Messages are delivered correctly at least one time. The message could be delivered more than once. - **EXACTLY\_ONCE** Messages are sent once and delivery is ensured. The quality of service is sometimes different between message publishing and message subscribing, even if the published message and the subscription have a common topic. For example, a message published with QoS 1 or 2 might not be successfully delivered to the **On New Message** source, if that listener source is subscribed with QoS **AT\_MOST\_ONCE** (QoS=0). ## See Also - [MQTT3 Connector Examples](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # Configure the Quality of Service for MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The MQTT protocol enables you to specify levels of delivery assurance for inbound or outbound messages. These levels are referred to as _quality of service_ (QoS). The available QoS levels to configure for MQTT Connector are: - **AT\_MOST\_ONCE** Messages are delivered at most one time ("fire and forget") and delivery is not guaranteed. - **AT\_LEAST\_ONCE** Messages are delivered correctly at least one time. The message could be delivered more than once. - **EXACTLY\_ONCE** Messages are sent once and delivery is ensured. The quality of service is sometimes different between message publishing and message subscribing, even if the published message and the subscription have a common topic. For example, a message published with QoS 1 or 2 might not be successfully delivered to the **On New Message** source, if that listener source is subscribed with QoS **AT\_MOST\_ONCE** (QoS=0). ## See Also - [MQTT3 Connector Examples](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # Deploy MQTT Connector Apps in a Cluster > For the full documentation index, see: https://docs.mulesoft.com/llms.txt MQTT broker establishes a connection with a client using its client ID. For example, if the broker establishes a connection with a client whose client ID is `smart-bentley-123`, and then the broker receives a new connection with the same client ID, the broker closes the previous connection (assuming it is stale) and accepts the new connection. This mechanism is known as a client takeover. MQTT brokers employ this mechanism to prevent situations such as TCP connections reaching a half-open or invalid state due to a crash in one of the communication ends, which is undesirable. Because of client takeover, Mule runtime engine (Mule) applications that use MQTT Connector deployed in a cluster must include a unique client ID for each active node in the cluster. To avoid client takeovers in this kind of scenario, you can supply these unique IDs either by using the application-provided client ID generators or by providing your own client ID generator. ## See Also - [Set a Client ID with MQTT Connector](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-client-id) - [MQTT Connector Examples](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # Deploy MQTT Connector Apps in a Cluster > For the full documentation index, see: https://docs.mulesoft.com/llms.txt MQTT broker establishes a connection with a client using its client ID. For example, if the broker establishes a connection with a client whose client ID is `smart-bentley-123`, and then the broker receives a new connection with the same client ID, the broker closes the previous connection (assuming it is stale) and accepts the new connection. This mechanism is known as a client takeover. MQTT brokers employ this mechanism to prevent situations such as TCP connections reaching a half-open or invalid state due to a crash in one of the communication ends, which is undesirable. Because of client takeover, Mule runtime engine (Mule) applications that use MQTT Connector deployed in a cluster must include a unique client ID for each active node in the cluster. To avoid client takeovers in this kind of scenario, you can supply these unique IDs either by using the application-provided client ID generators or by providing your own client ID generator. ## See Also - [Set a Client ID with MQTT Connector](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-client-id) - [MQTT Connector Examples](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # Listen and Publish Messages with MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt In these examples, you configure the Anypoint Connector for MQTT (MQTT Connector) **On New Message** source and the **Publish** operation to listen and publish messages to a specific topic. ## Create a Mule App to Listen and Publish Messages In the following example, you configure the **On New Message** source and the **Publish** operation to listen and publish messages to a specific topics. ![MQTT Listen and Publish example in Studio canvas](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-example-1.png) ### Create a Listener Flow In the first part of the example, create a flow with an **On New Message** source that triggers an event for incoming messages on topics matching the filter `topic/quotes/#`, and add a **Logger** component that logs the received message: 1. In Studio > **Mule Palette** view, select **MQTT3 > On New Message**. 2. Drag the **On New Message** source to the Studio canvas. 3. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 4. In **MQTT3 Config** > **Connection** select **MQTT3 URL Connection**. 5. For **Client id generator**, select **Client id custom expression generator**. 6. Set the following fields: - **Client ID**: `crowley123` - **Username**: `mosquitto` - **Password**: `mosquitto` - **URL**: `tcp://0.0.0.0:1883` 7. Click **LWT**. 8. Set the following fields: - **Topic**: `topic/lwt` - **Body**: `This is the LWT message` - **Is retained**: **True** 9. Click **OK**. 10. In the **On New Message** configuration screen, set **Topics** to **Edit inline**. 11. Click the plus sign (**+**) to add a new topic. 12. In **Topic filter**, set `topic/quotes/#`. 13. Click **OK**. 14. Drag a **Logger** component to the right of the **On New Message** source. 15. Set **Message** to `Received message '#[payload]' with at topic #[attributes.topic] with qos #[attributes.qos]`. ### Create a Publisher Flow For the second part of the example, create a flow with a **Publish** operation that publishes messages to the topic `topic/quotes/shakespeare` and triggers an event in `listener-flow`: 1. In Studio, drag an HTTP **Listener** source below the first `listener-flow`. 2. Set **Path** to `publish/message`. 3. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 4. Set **Host** to `0.0.0.0` and **Port** to `8081`. 5. Click **OK**. 6. Drag an MQTT3 **Publisher** operation next to the HTTP **Listener** source. 7. For **Connector configuration**, select the `MQTT3_Config_1` configuration created in `listener-flow`. 8. Set the following fields: - **Topic**: `topic/quotes/shakespeare` - **Message**: `"Uneasy lies the head that wears a crown"` 9. Drag a **Set Payload** component to the right of the **Publish** operation. 10. Set **Value** to `SUCCESSFULLY PUBLISHED MESSAGE!`. 11. Save and run your Mule application. 12. To publish the message, send a request to the HTTP endpoint using the following curl command: `curl -v --request GET localhost:8081/publish/message`. ### XML for Listening and Publishing Messages with MQTT Connector Paste this code into your Studio XML editor to quickly load the flow for this example into your Mule app: ```xml ``` ## Create a Mule App and Subscribe to a LWT Message Topic In the following example, you use the previous listener flow and create a second listener flow subscribed to the same LWT message topic as the first flow. If the Mule app crashes and the first listener flow gets disconnected, the MQTT broker sends the LWT message to the configured topic and retains the message. When the Mule app restarts, the second listener flow listens for the retained LWT message and logs it. ![MQTT Listener flows example in Studio canvas](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-example-2.png) ### Create the First Listener Flow In the first part of the example, create a flow with an **On New Message** source that triggers an event for incoming messages on topics matching the filter `topic/quotes/#`, and add a **Logger** component that logs the received message: 1. In Studio, in the **Mule Palette** view, select **MQTT3 > On New Message**. 2. Drag the **On New Message** source to the Studio canvas. 3. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 4. In the **MQTT3 Config** window, for **Connection** select **MQTT3 URL Connection**. 5. For **Client id generator**, select **Client id custom expression generator**. 6. Set the following fields: - **Client ID**: `crowley123` - **Username**: `mosquitto` - **Password**: `mosquitto` - **URL**: `tcp://0.0.0.0:1883` 7. Click the **LWT** tab. 8. Set the following fields: - **Topic**: `topic/lwt` - **Body**: `This is the LWT message` - **Is retained**: **True** 9. Click **OK**. 10. In the **On New Message** configuration screen, set **Topics** to **Edit inline**. 11. Click the plus sign (**+**) to add a new topic. 12. In **Topic filter** set `topic/quotes/#`. 13. Click **OK**. 14. Drag a **Logger** component to the right of the **On New Message** source. 15. Set **Message** to `Received message '#[payload]' with at topic #[attributes.topic] with qos #[attributes.qos]`. ### Create the Second Listener Flow For the second part of the example, create a second listener flow by adding another **On New Message** source that subscribes to the topic `topic/lwt`, and add a **Logger** component that logs the received message: 1. In Studio, drag another **On New Message** source below the first `listener-flow`. 2. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 3. In the **MQTT3 Config** window, for **Connection** select **MQTT3 URL Connection**. 4. For **Client id generator**, select **Client id random suffix generator**. 5. Set the following fields: - **Client ID**: `azfell123` - **Username**: `mosquitto` - **Password**: `mosquitto` - **URL**: `tcp://0.0.0.0:1884` 6. Click **OK**. 7. In the **On New Message** configuration screen, set **Topics** to **Edit inline**. 8. Click the plus sign (**+**) to add a new topic. 9. In **Topic filter** set `topic/lwt`. 10. Click **OK**. 11. Drag a **Logger** component to the right of the **On New Message** source. 12. Set **Message** to `Received message '#[payload]' with at topic #[attributes.topic] with qos #[attributes.qos]`. 13. Save and run the Mule app. 14. Simulate an app crash by locating the process ID of the Mule app and killing it in your terminal by using a command like `kill -9 `. Because the Mule app crashes, the first listener flow is disconnected. 15. Restart the Mule app. The MQTT broker retains the LWT message, and the second listener flow logs the LWT message that was configured in the first listener flow. ### XML for Listening Messages Subscribed to an LWT Message Topic Paste this code into your Studio XML editor to quickly load the flow for this example into your Mule app: ```xml ``` ## See Also - [MQTT Connector Examples](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # Listen and Publish Messages with MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt In these examples, you configure the Anypoint Connector for MQTT (MQTT Connector) **On New Message** source and the **Publish** operation to listen and publish messages to a specific topic. ## Create a Mule App to Listen and Publish Messages In the following example, you configure the **On New Message** source and the **Publish** operation to listen and publish messages to a specific topics. ![MQTT Listen and Publish example in Studio canvas](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-example-1.png) ### Create a Listener Flow In the first part of the example, create a flow with an **On New Message** source that triggers an event for incoming messages on topics matching the filter `topic/quotes/#`, and add a **Logger** component that logs the received message: 1. In Studio > **Mule Palette** view, select **MQTT3 > On New Message**. 2. Drag the **On New Message** source to the Studio canvas. 3. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 4. In **MQTT3 Config** > **Connection** select **MQTT3 URL Connection**. 5. For **Client id generator**, select **Client id custom expression generator**. 6. Set the following fields: - **Client ID**: `crowley123` - **Username**: `mosquitto` - **Password**: `mosquitto` - **URL**: `tcp://0.0.0.0:1883` 7. Click **LWT**. 8. Set the following fields: - **Topic**: `topic/lwt` - **Body**: `This is the LWT message` - **Is retained**: **True** 9. Click **OK**. 10. In the **On New Message** configuration screen, set **Topics** to **Edit inline**. 11. Click the plus sign (**+**) to add a new topic. 12. In **Topic filter**, set `topic/quotes/#`. 13. Click **OK**. 14. Drag a **Logger** component to the right of the **On New Message** source. 15. Set **Message** to `Received message '#[payload]' with at topic #[attributes.topic] with qos #[attributes.qos]`. ### Create a Publisher Flow For the second part of the example, create a flow with a **Publish** operation that publishes messages to the topic `topic/quotes/shakespeare` and triggers an event in `listener-flow`: 1. In Studio, drag an HTTP **Listener** source below the first `listener-flow`. 2. Set **Path** to `publish/message`. 3. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 4. Set **Host** to `0.0.0.0` and **Port** to `8081`. 5. Click **OK**. 6. Drag an MQTT3 **Publisher** operation next to the HTTP **Listener** source. 7. For **Connector configuration**, select the `MQTT3_Config_1` configuration created in `listener-flow`. 8. Set the following fields: - **Topic**: `topic/quotes/shakespeare` - **Message**: `"Uneasy lies the head that wears a crown"` 9. Drag a **Set Payload** component to the right of the **Publish** operation. 10. Set **Value** to `SUCCESSFULLY PUBLISHED MESSAGE!`. 11. Save and run your Mule application. 12. To publish the message, send a request to the HTTP endpoint using the following curl command: `curl -v --request GET localhost:8081/publish/message`. ### XML for Listening and Publishing Messages with MQTT Connector Paste this code into your Studio XML editor to quickly load the flow for this example into your Mule app: ```xml ``` ## Create a Mule App and Subscribe to a LWT Message Topic In the following example, you use the previous listener flow and create a second listener flow subscribed to the same LWT message topic as the first flow. If the Mule app crashes and the first listener flow gets disconnected, the MQTT broker sends the LWT message to the configured topic and retains the message. When the Mule app restarts, the second listener flow listens for the retained LWT message and logs it. ![MQTT Listener flows example in Studio canvas](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-example-2.png) ### Create the First Listener Flow In the first part of the example, create a flow with an **On New Message** source that triggers an event for incoming messages on topics matching the filter `topic/quotes/#`, and add a **Logger** component that logs the received message: 1. In Studio, in the **Mule Palette** view, select **MQTT3 > On New Message**. 2. Drag the **On New Message** source to the Studio canvas. 3. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 4. In the **MQTT3 Config** window, for **Connection** select **MQTT3 URL Connection**. 5. For **Client id generator**, select **Client id custom expression generator**. 6. Set the following fields: - **Client ID**: `crowley123` - **Username**: `mosquitto` - **Password**: `mosquitto` - **URL**: `tcp://0.0.0.0:1883` 7. Click the **LWT** tab. 8. Set the following fields: - **Topic**: `topic/lwt` - **Body**: `This is the LWT message` - **Is retained**: **True** 9. Click **OK**. 10. In the **On New Message** configuration screen, set **Topics** to **Edit inline**. 11. Click the plus sign (**+**) to add a new topic. 12. In **Topic filter** set `topic/quotes/#`. 13. Click **OK**. 14. Drag a **Logger** component to the right of the **On New Message** source. 15. Set **Message** to `Received message '#[payload]' with at topic #[attributes.topic] with qos #[attributes.qos]`. ### Create the Second Listener Flow For the second part of the example, create a second listener flow by adding another **On New Message** source that subscribes to the topic `topic/lwt`, and add a **Logger** component that logs the received message: 1. In Studio, drag another **On New Message** source below the first `listener-flow`. 2. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 3. In the **MQTT3 Config** window, for **Connection** select **MQTT3 URL Connection**. 4. For **Client id generator**, select **Client id random suffix generator**. 5. Set the following fields: - **Client ID**: `azfell123` - **Username**: `mosquitto` - **Password**: `mosquitto` - **URL**: `tcp://0.0.0.0:1884` 6. Click **OK**. 7. In the **On New Message** configuration screen, set **Topics** to **Edit inline**. 8. Click the plus sign (**+**) to add a new topic. 9. In **Topic filter** set `topic/lwt`. 10. Click **OK**. 11. Drag a **Logger** component to the right of the **On New Message** source. 12. Set **Message** to `Received message '#[payload]' with at topic #[attributes.topic] with qos #[attributes.qos]`. 13. Save and run the Mule app. 14. Simulate an app crash by locating the process ID of the Mule app and killing it in your terminal by using a command like `kill -9 `. Because the Mule app crashes, the first listener flow is disconnected. 15. Restart the Mule app. The MQTT broker retains the LWT message, and the second listener flow logs the LWT message that was configured in the first listener flow. ### XML for Listening Messages Subscribed to an LWT Message Topic Paste this code into your Studio XML editor to quickly load the flow for this example into your Mule app: ```xml ``` ## See Also - [MQTT Connector Examples](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # Listen for New Messages with MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt In these examples, you configure the Anypoint Connector for MQTT (MQTT Connector) **On New Message** source, which enables you to listen for new incoming messages using one or more topic filters. Each topic filter has a specific quality of service (QoS) configured. In the following example, you configure the **On New Message** source: 1. In Studio > **Mule Palette**, select **MQTT3 > On New Message**. 2. Drag **On New Message** to the Studio canvas. 3. In the **On New Message** configuration screen, optionally change the value of the **Display Name** field. 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 5. In **MQTT3 Config** > **Connection**, select one of the connection types to provide to this configuration: - **MQTT3 URL Connection** - **MQTT3 Fail-Over Connection** - **MQTT3 Form Connection** 6. Specify a unique and intuitive **Client ID** to identify an MQTT connection to a broker. 7. On the **General** tab, also specify connection information such as required libraries for the broker and advanced connection options. 8. On the **LWT** tab, optionally specify a Last Will and Testament message. 9. On the **TLS/SSL** tab, optionally specify a TLS configuration. 10. On the **Advanced** tab, optionally specify a reconnection strategy. 11. Click **OK** to close the window. 12. In the **On New Message** configuration screen, in **Topics**, select **Edit inline** to list the topics that the listener subscribes to. 13. Click the plus sign (**+**) to configure a topic. 14. In the **Topic** configuration screen, set **Topic filter** to configure a single or multilevel subscription to a topic. 15. Set **QoS** to any of the following quality of service levels: - **AT\_MOST\_ONCE** - **AT\_LEAST\_ONCE** - **EXACTLY\_ONCE** 16. Click **Finish**: ![MQTT On New Message source configuration in Studio with Topic filters configured](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-onnewmessage.png) In the **Configuration XML** editor, the ``, ``, and `topicFilter` configurations look like this: ```xml ``` ## Configure Listener Topics Using Bean Reference To reuse topic subscriptions across multiple listeners, in **Topics**, select **Bean reference** instead of **Edit inline**. This option is useful when you want to centralize the list of subscriptions and avoid manually duplicating topic filter and QoS values in each listener. Use **Edit inline** when you configure only one listener or a small set of topics that are specific to a single flow. In the **Configuration XML** editor, the listener can reference a topic list bean: ```xml ``` For example, you can define a `List` bean and reference it from the listener: ```xml ``` ## Configure Single-Level Wildcards in Topic Filters Configure single-level wildcards to listen to multiple topics. Single-level wildcards (`+`) enable the subscriber to receive messages published to all topics that match a specific structure. In the following example, you configure the `topicFilter` parameter with the structure `quotes/+/authors`: ```xml ``` Messages published to the following topics trigger the listener: - `quotes/british/authors` - `quotes/american/authors` However, messages published to the following topics do not trigger the listener: - `names/british/authors` - `quotes/american/writers` ## Configure Multi-Level Wildcards in Topic Filters Configure multi-level wildcards to enable the listener to subscribe to all topics that share the same root (everything that comes before the hash `#` symbol). In the following example, you configure the `topicFilter` parameter with the structure `quotes/england/#`: ```xml ``` Messages published to the following topics trigger the listener: - `quotes/england/authors/terryPratchett` - `quotes/england/authors/neilGaiman` - `quotes/england/actors` However, messages published to the following topics do not trigger the listener: - `quotes/american/actors` - `phrases/england/authors/neilGaiman` ## Listeners Sharing a Configuration Listeners that share a configuration element also share a connection and client ID. This is important to remember, especially when one of the listeners is stopped but the other isn’t. In the following example, the listeners of the flows `listenerReaderA` and `listenerReaderB` share the same connection `MQTT_Config` configuration and client ID. From the broker’s perspective, both listeners are indistinguishable: ```xml ``` As you can see, the listeners also share a subscription to the topic `terryPratchett`. Whichever listener subscribes first to the topic can set the subscription quality of service (QoS). Only one subscription with one quality of service level can exist for that topic. If the `listenerReaderB` flow stops, the `listenerReaderA` flow still receives and processes the messages for the `terryPratchett` topic. Even if the configuration element specifies `cleanSession=false`, the messages processed while `listenerReaderB` was offline are not resent to `listenerReaderB`. ## See Also - [MQTT Connector Examples](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # Listen for New Messages with MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt In these examples, you configure the Anypoint Connector for MQTT (MQTT Connector) **On New Message** source, which enables you to listen for new incoming messages using one or more topic filters. Each topic filter has a specific quality of service (QoS) configured. In the following example, you configure the **On New Message** source: 1. In Studio > **Mule Palette**, select **MQTT3 > On New Message**. 2. Drag **On New Message** to the Studio canvas. 3. In the **On New Message** configuration screen, optionally change the value of the **Display Name** field. 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 5. In **MQTT3 Config** > **Connection**, select one of the connection types to provide to this configuration: - **MQTT3 URL Connection** - **MQTT3 Fail-Over Connection** - **MQTT3 Form Connection** 6. Specify a unique and intuitive **Client ID** to identify an MQTT connection to a broker. 7. On the **General** tab, also specify connection information such as required libraries for the broker and advanced connection options. 8. On the **LWT** tab, optionally specify a Last Will and Testament message. 9. On the **TLS/SSL** tab, optionally specify a TLS configuration. 10. On the **Advanced** tab, optionally specify a reconnection strategy. 11. Click **OK** to close the window. 12. In the **On New Message** configuration screen, in **Topics**, select **Edit inline** to list the topics that the listener subscribes to. 13. Click the plus sign (**+**) to configure a topic. 14. In the **Topic** configuration screen, set **Topic filter** to configure a single or multilevel subscription to a topic. 15. Set **QoS** to any of the following quality of service levels: - **AT\_MOST\_ONCE** - **AT\_LEAST\_ONCE** - **EXACTLY\_ONCE** 16. Click **Finish**: ![MQTT On New Message source configuration in Studio with Topic filters configured](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-onnewmessage.png) In the **Configuration XML** editor, the ``, ``, and `topicFilter` configurations look like this: ```xml ``` ## Configure Listener Topics Using Bean Reference To reuse topic subscriptions across multiple listeners, in **Topics**, select **Bean reference** instead of **Edit inline**. This option is useful when you want to centralize the list of subscriptions and avoid manually duplicating topic filter and QoS values in each listener. Use **Edit inline** when you configure only one listener or a small set of topics that are specific to a single flow. In the **Configuration XML** editor, the listener can reference a topic list bean: ```xml ``` For example, you can define a `List` bean and reference it from the listener: ```xml ``` ## Configure Single-Level Wildcards in Topic Filters Configure single-level wildcards to listen to multiple topics. Single-level wildcards (`+`) enable the subscriber to receive messages published to all topics that match a specific structure. In the following example, you configure the `topicFilter` parameter with the structure `quotes/+/authors`: ```xml ``` Messages published to the following topics trigger the listener: - `quotes/british/authors` - `quotes/american/authors` However, messages published to the following topics do not trigger the listener: - `names/british/authors` - `quotes/american/writers` ## Configure Multi-Level Wildcards in Topic Filters Configure multi-level wildcards to enable the listener to subscribe to all topics that share the same root (everything that comes before the hash `#` symbol). In the following example, you configure the `topicFilter` parameter with the structure `quotes/england/#`: ```xml ``` Messages published to the following topics trigger the listener: - `quotes/england/authors/terryPratchett` - `quotes/england/authors/neilGaiman` - `quotes/england/actors` However, messages published to the following topics do not trigger the listener: - `quotes/american/actors` - `phrases/england/authors/neilGaiman` ## Listeners Sharing a Configuration Listeners that share a configuration element also share a connection and client ID. This is important to remember, especially when one of the listeners is stopped but the other isn’t. In the following example, the listeners of the flows `listenerReaderA` and `listenerReaderB` share the same connection `MQTT_Config` configuration and client ID. From the broker’s perspective, both listeners are indistinguishable: ```xml ``` As you can see, the listeners also share a subscription to the topic `terryPratchett`. Whichever listener subscribes first to the topic can set the subscription quality of service (QoS). Only one subscription with one quality of service level can exist for that topic. If the `listenerReaderB` flow stops, the `listenerReaderA` flow still receives and processes the messages for the `terryPratchett` topic. Even if the configuration element specifies `cleanSession=false`, the messages processed while `listenerReaderB` was offline are not resent to `listenerReaderB`. ## See Also - [MQTT Connector Examples](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # MQTT Connector 1.0 > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint Connector for MQTT (MQTT Connector) is an MQTT (Message Queuing Telemetry Transport) v3.x protocol-compliant MuleSoft extension. MQTT is a lightweight publish/subscribe messaging protocol designed for connecting remote devices with a small code footprint and minimal network bandwidth. MQTT today is used in a wide variety of industries, such as automotive, manufacturing, telecommunications, and oil and gas. The connector supports capabilities specified in MQTT v3.x protocol, including but not limited to reliable message delivery, persistent sessions, support for unreliable and low bandwidth networks, message retention, and last will and testament (LWT) messages. The connector supports TLS to securely connect and communicate with a MQTT broker. For compatibility information and fixed issues, see the MQTT Connector Release Notes. ## Before You Begin To use this connector, you must be familiar with: - MQTT v3.x protocol - Anypoint Connectors - Mule runtime engine (Mule) - Elements and global elements in a Mule flow - Creating a Mule app using Anypoint Studio or Anypoint Code Builder Before creating an app, you must have Anypoint Platform and Anypoint Studio. ## Common Use Cases for the Connector These are some common use cases for MQTT Connector based on MQTT version3.x protocol: - Connect to MQTT brokers by specifying a failover server list that the client iterates over until a connection is successfully established. - Connect to MQTT brokers in a reliable messaging schema and publish messages. - Connect to an MQTT broker and set a last will and testament (LWT) message to notify all the subscribers of the client’s disconnection. - Connect to an MQTT broker with Transport Layer Security (TLS) and listen for messages. - Listen for messages in a single or multiple topics. - Listen for messages on multiple topics using single-level or multi-level wildcards. - Publish messages to a topic. - Publish messages with retention. - Publish messages to an MQTT topic and set different Quality of Service (QoS) levels of delivery assurance for inbound or outbound messages. ## MQTT Architecture MQTT uses the publish/subscribe model, in which a client publishes messages to a particular address, known as a `Topic`. Client receivers subscribe to the topic and receive the published message. In this model, neither the publisher nor the subscriber is aware of each other. The connection between the publisher and subscriber is managed by an MQTT broker. ### MQTT Client A MQTT Client is any device that runs an MQTT library and connects to an MQTT server over a network. ### MQTT Broker The MQTT Broker is a server that receives messages from the clients and then routes the messages to the appropriate destination clients. ### MQTT Topic As the broker acts as a post office, MQTT doesn’t use the address of the intended recipient but uses the subject line called `Topic`, and anyone who wants a copy of that message subscribes to that topic. Multiple clients can receive the message from a single broker (one to many). ## Next Step After you complete the prerequisites, you are ready to create your own app and configure the connector using [Anypoint Studio](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-studio-configuration). ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Use Exchange to Discover Connectors, Templates, and Examples](https://docs.mulesoft.com/connectors/introduction/intro-use-exchange) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # MQTT Connector 1.0 Reference > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint Connector for MQTT (MQTT Connector) is an MQTT (Message Queuing Telemetry Transport) v3.x protocol-compliant MuleSoft extension. MQTT is a lightweight publish/subscribe messaging protocol designed for connecting remote devices with a small code footprint and minimal network bandwidth. MQTT today is used in a wide variety of industries, such as automotive, manufacturing, telecommunications, and oil and gas. The connector consumes and produces MQTT messages and supports all MQTT v3.x functionalities including message retention, LWT(LWT) messages, and persistent sessions. ## Configurations --- ### Config Default configuration. #### Parameters
NameTypeDescriptionDefault ValueRequired

Name

String

The name for this configuration. Connectors reference the configuration with this name.

x

Connection

Connection types for this configuration.

x

Name

String

The identifier of this element used to reference it in other components

x

Expiration Policy

Configures an expiration policy for the configuration.

#### Connection Types ##### MQTT 3 URL Connection Cached connection provider that creates MQTT connections. Enables you to specify a connection URL for the broker. ###### Parameters
NameTypeDescriptionDefault ValueRequired

Client ID Generator

A Client ID generator that generates a Client ID to identify a connection to the MQTT broker.

x

Username

String

Username to authenticate credentials to the MQTT broker.

Password

String

Password authenticate credentials to the MQTT broker.

URL

String

URL that represents the broker to connect to.

TLS Context

Topic

String

Topic to publish the LWTmessage.

Body

String

Content of the LWTmessage.

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the LWTmessage is published. Defaults to AT_LEAST_ONCE.

AT_LEAST_ONCE

Is Retained

Boolean

If set to true, the broker retains the LWTmessage.

false

Connection Timeout

Number

The socket connection timeout value. This attribute works in tandem with timeoutUnit. If multiple fail-over URLs are provided, the timeout applies to each URL individually.

30

Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Unit of time for the Connection Timeout field.

SECONDS

Keep Alive Interval

Number

The amount of time that the connection between the client and broker is kept alive without any messages exchanged. If the keep-alive interval is 0, then the keep-alive mechanism is disabled.

0

Keep Alive Interval Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The unit of time that corresponds to the keepAliveInterval parameter. Defaults to SECONDS

SECONDS

Max In Flight

Number

Maximum number of messages that can be unacknowledged at a given time. If you set the parameter to 0, there can be unlimited in-flight messages.

10

Clean Session

Boolean

If set to true, the session is cleaned each time the client disconnects from the broker. Subscriptions are not saved and offline (QoS 1 and 2) messages for that client are lost.

true

Enable File Persistence

Boolean

If set to true, creates a file-based persistent data store, used to store outbound and inbound messages while they are in flight, enabling delivery to the QoS specified.

false

Data Store Path

String

The directory where the file-based persistent data store is created if enableFilePersistence is set to true.

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy.

##### MQTT 3 Fail-Over Connection ###### Parameters
NameTypeDescriptionDefault ValueRequired

Client ID Generator

A ClientIDGenerator that generates a Client ID to identify a connection to the MQTT broker.

x

Username

String

Username to authenticate credentials to the MQTT broker.

Password

String

Password to authenticate credentials to the MQTT broker.

Fail Over Servers

Array of Fail Over URL

The list of server URLs used to establish a connection to the broker.

x

TLS Context

Topic

String

Topic to publish the LWTmessage.

Body

String

Content of the LWTmessage.

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the LWTmessage is published. Defaults to AT_LEAST_ONCE

AT_LEAST_ONCE

Is Retained

Boolean

If set to true, the broker retains the LWTmessage.

false

Connection Timeout

Number

The socket connection timeout value. This attribute works in tandem with timeoutUnit. If multiple fail-over URLs are provided, the timeout applies to each URL individually.

30

Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Unit of time for the Connection Timeout field. Defaults to SECONDS

SECONDS

Keep Alive Interval

Number

The amount of time that the connection between the client and broker is kept alive without any messages being exchanged. If the keep-alive interval is 0, then the keep-alive mechanism is disabled.

0

Keep Alive Interval Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The unit of time that corresponds to the keepAliveInterval parameter. Defaults to SECONDS

SECONDS

Max In Flight

Number

Maximum number of messages that can be unacknowledged at a given time. If you set the parameter to 0, there can be unlimited in-flight messages.

10

Clean Session

Boolean

If set to true, the session is cleaned each time the client disconnects from the broker. Subscriptions are not saved and offline (QoS 1 and 2) messages for that client are lost.

true

Enable File Persistence

Boolean

If set to true, creates a file-based persistent data store, used to store outbound and inbound messages while they are in flight, enabling delivery to the QoS specified.

false

Data Store Path

String

The directory where the file-based persistent data store is created if enableFilePersistence is set to true.

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy.

##### MQTT 3 Form Connection Cached connection provider that creates MQTT connections. Enables you to specify a protocol, host, and port to establish a connection with the broker. ###### Parameters
NameTypeDescriptionDefault ValueRequired

Client ID Generator

A Client ID generator that generates a Client ID to identify a connection to the MQTT broker.

x

Username

String

Username to authenticate credentials to the MQTT broker.

Password

String

Password to authenticate credentials to the MQTT broker.

Protocol

Enumeration, one of:

  • TCP

  • WS

  • WSS

  • SSL

  • LOCAL

Transport level protocol to use when connecting to the broker.

TCP

URL

String

Broker’s host to connect to.

x

Port

String

Broker’s port to connect to

1883

TLS Context

Topic

String

Topic to publish the LWTmessage.

Body

String

Content of the LWTmessage.

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the LWTmessage is published. Defaults to AT_LEAST_ONCE

AT_LEAST_ONCE

Is Retained

Boolean

If set to true, the broker retains the LWTmessage.

false

Connection Timeout

Number

The socket connection timeout value. This attribute works in tandem with timeoutUnit. If multiple fail-over URLs are provided, the timeout applies to each URL individually.

30

Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Unit of time for the Connection Timeout field. Defaults to SECONDS

SECONDS

Keep Alive Interval

Number

The amount of time that the connection between the client and broker is kept alive without any messages being exchanged. If the keep-alive interval is 0, then the keep-alive mechanism is disabled.

0

Keep Alive Interval Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The unit of time that corresponds to the keepAliveInterval parameter.

SECONDS

Max In Flight

Number

Maximum number of messages that can be unacknowledged at a given time. If you set the parameter to 0, there can be unlimited in-flight messages.

10

Clean Session

Boolean

If set to true, the session is cleaned each time the client disconnects from the broker. Subscriptions are not saved and offline (QoS 1 and 2) messages for that client are lost.

true

Enable File Persistence

Boolean

If set to true, creates a file-based persistent data store, used to store outbound and inbound messages while they are in flight, enabling delivery to the QoS specified.

false

Data Store Path

String

The directory where the file-based persistent data store is created if enableFilePersistence is set to true.

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy.

#### Associated Operations - [Publish](#Publish) #### Associated Sources - [On New Message](#Listener) ## Operations ### Publish `` Operation that enables you to publish a single MQTT 3 message to a given exchange. ### Parameters
NameTypeDescriptionDefault ValueRequired

Configuration

String

Name of the configuration to use.

x

Topic

String

Topic in which to publish the message.

x

Message

Any

Content of the message to publish.

#[payload]

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the message is published.

AT_LEAST_ONCE

Is Retained

Boolean

Whether the broker retains the message.

false

Config Ref

ConfigurationProvider

Name of the configuration to execute the component.

x

Reconnection Strategy

A retry strategy in case of connectivity errors.

### For Configurations - [Config](#Config) ### Throws - MQTT3:CONNECTIVITY The client became disconnected from the broker while attempting to publish a message. - MQTT3:INVALID\_TOPIC The topic is invalid because, for example, the name is too short, too long, or contains invalid characters. - MQTT3:PERSISTENCE When publishing a message, an error occurred while reading or writing persistent data for reliable messaging. - MQTT3:PUBLISH An error occurred while attempting to publish a message. - MQTT3:RETRY\_EXHAUSTED All reconnection attempts failed. - MQTT3:WRITE\_TIMEOUT An error occurred when the client timed out waiting to write messages to the server. ## Sources ### On New Message `` Source that listens for new incoming messages for one or more topic filters. Each topic filter has a specific QoS configured. ### Parameters
NameTypeDescriptionDefault ValueRequired

Configuration

String

Name of the configuration to use.

x

Topics

Array of Topic

List of topics that the listener subscribes to. You can configure this field by using either Edit inline or Bean reference. For source configuration examples, see Listen for New Messages with MQTT Connector.

x

Config Ref

ConfigurationProvider

Name of the configuration to execute the component.

x

Primary Node Only

Boolean

Determines whether to execute the source only on the primary node when running Mule instances in a cluster.

Redelivery Policy

Defines a policy for processing the redelivery of the same message.

Reconnection Strategy

A retry strategy in case of connectivity errors.

### Output

Type

Any

Attributes Type

### For Configurations - [Config](#Config) ## Types ### TLS Configures TLS to provide secure communications for the Mule app.
FieldTypeDescriptionDefault ValueRequired

Enabled Protocols

String

Comma-separated list of protocols enabled for this context.

Enabled Cipher Suites

String

Comma-separated list of cipher suites enabled for this context..

Trust Store

Key Store

Revocation Check

### Trust Store Configures the truststore for TLS.
FieldTypeDescriptionDefault ValueRequired

Path

String

Path to the truststore. Mule resolves the path relative to the current classpath and file system, if possible.

Password

String

Password used to protect the trust store.

Type

String

Type of truststore.

Algorithm

String

Encryption algorithm that the trust store uses.

Insecure

Boolean

If true, no certificate validations will be performed, rendering connections vulnerable to attacks. Use at your own risk.

### Key Store Configures the keystore for the TLS protocol. The keystore you generate contains a private key and a public certificate.
FieldTypeDescriptionDefault ValueRequired

Path

String

Path to the keystore. Mule resolves the path relative to the current classpath and file system, if possible.

Type

String

Type of keystore.

Alias

String

Alias of the key to use when the keystore contains multiple private keys. By default, Mule uses the first key in the file.

Key Password

String

Password used to protect the private key.

Password

String

Password used to protect the keystore.

Algorithm

String

Encryption algorithm that the keystore uses.

### Standard Revocation Check Configures standard revocation checks for TLS certificates.
FieldTypeDescriptionDefault ValueRequired

Only End Entities

Boolean

Verify the last element of the certificate chain only.

Prefer Crls

Boolean

Try CRL instead of OCSP first.

No Fallback

Boolean

Do not use the secondary checking method, which is the method not specified in the Prefer Crls field.

Soft Fail

Boolean

Avoid verification failure when the revocation server cannot be reached or is busy.

### Custom OCSP Responder Configures a custom OCSP responder for certification revocation checks.
FieldTypeDescriptionDefault ValueRequired

Url

String

URL of the OCSP responder.

Cert Alias

String

Alias of the signing certificate for the OCSP response. If specified, the alias must be in the truststore.

### CRL File Specifies the location of the certification revocation list (CRL) file.
FieldTypeDescriptionDefault ValueRequired

Path

String

Path to the CRL file.

### Reconnection Configures a reconnection strategy for an operation.
FieldTypeDescriptionDefault ValueRequired

Fails Deployment

Boolean

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy.

Reconnection Strategy

Reconnection strategy to use.

### Reconnect Configures a standard reconnection strategy, which specifies how often to reconnect and how many reconnection attempts the connector source or operation can make.
FieldTypeDescriptionDefault ValueRequired

Frequency

Number

How often in milliseconds to reconnect.

Blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

Count

Number

How many reconnection attempts to make.

### Reconnect Forever Configures a forever reconnection strategy by which the connector operation source or operation attempts to reconnect at a specified frequency for as long as the Mule app runs.
FieldTypeDescriptionDefault ValueRequired

Frequency

Number

How often to attempt to reconnect, in milliseconds.

Blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

### Fail Over URL
FieldTypeDescriptionDefault ValueRequired

Protocol

Enumeration, one of:

  • TCP

  • WS

  • WSS

  • SSL

  • LOCAL

Transport level protocol to use when connecting to the broker.

TCP

Host

String

Broker’s host to connect to.

localhost

Port

String

Broker’s port to connect to.

1883

### Expiration Policy Configures the minimum amount of time that a dynamic configuration instance can remain idle before Mule considers it eligible for expiration.
FieldTypeDescriptionDefault ValueRequired

Max Idle Time

Number

A scalar time value for the maximum amount of time a dynamic configuration instance should be allowed to be idle before it’s considered eligible for expiration.

Time Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Time unit for the Max Idle Time field.

### MQTT 3 Message Attributes
FieldTypeDescriptionDefault ValueRequired

Topic

String

Topic to which the broker directed the message.

x

Message Id

Number

MQTT ID that identifies a message received from the broker.

x

QoS

Number

Quality of service of the message delivered by the broker.

x

Is Duplicate

Boolean

If set to true, the message can duplicate another received message.

false

Is Retained

Boolean

If set to true, the message was either sent from a current publisher, or was retained by the server as the last message published on the topic.

false

### Topic
FieldTypeDescriptionDefault ValueRequired

Topic Filter

String

Topic filter that represents a single or multilevel subscription to a topic.

x

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which messages destined to the topic’s Topic filter field should be sent by the broker.

AT_LEAST_ONCE

### Redelivery Policy Configures the redelivery policy for executing requests that generate errors. You can add a redelivery policy to any source in a flow.
FieldTypeDescriptionDefault ValueRequired

Max Redelivery Count

Number

Maximum number of times that a delivered request can be processed unsuccessfully before returning a REDELIVERY_EXHAUSTED error.

Message Digest Algorithm

String

Secure hashing algorithm to use if the Use Secure Hash field is true. If the payload of the message is a Java object, Mule ignores this value and returns the value that the payload’s hashCode() returned.

Message Identifier

Defines which strategy to identify the messages.

Object Store

ObjectStore

Configures the object store that stores the redelivery counter for each message.

### Redelivery Policy Message Identifier Configures how to identify a redelivered message and how to find out when the message was redelivered.
FieldTypeDescriptionDefault ValueRequired

Use Secure Hash

Boolean

If true, Mule uses a secure hash algorithm to identify a redelivered message.

Id Expression

String

One or more expressions that determine when a message was redelivered. You can set this property only if the Use Secure Hash field is false.

### Client ID Random Suffix Generator
FieldTypeDescriptionDefault ValueRequired

Client Id

String

Client ID to identify the connection to the MQTT broker.

### Client ID Custom Expression Generator
FieldTypeDescriptionDefault ValueRequired

Client Id

String

Client ID to identify the connection to the MQTT broker.

Custom Client Id Suffix

String

Custom client ID suffix used to identify the connection to the MQTT broker.

## See Also [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # MQTT Connector 1.1 > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint Connector for MQTT (MQTT Connector) is an MQTT (Message Queuing Telemetry Transport) v3.x protocol-compliant MuleSoft extension. MQTT is a lightweight publish/subscribe messaging protocol designed for connecting remote devices with a small code footprint and minimal network bandwidth. MQTT today is used in a wide variety of industries, such as automotive, manufacturing, telecommunications, and oil and gas. The connector supports capabilities specified in MQTT v3.x protocol, including but not limited to reliable message delivery, persistent sessions, support for unreliable and low bandwidth networks, message retention, and last will and testament (LWT) messages. The connector supports TLS to securely connect and communicate with a MQTT broker. For compatibility information and fixed issues, see the MQTT Connector Release Notes. ## Before You Begin To use this connector, you must be familiar with: - MQTT v3.x protocol - Anypoint Connectors - Mule runtime engine (Mule) - Elements and global elements in a Mule flow - Creating a Mule app using Anypoint Studio or Anypoint Code Builder Before creating an app, you must have Anypoint Platform and Anypoint Studio. ## Common Use Cases for the Connector These are some common use cases for MQTT Connector based on MQTT version3.x protocol: - Connect to MQTT brokers by specifying a failover server list that the client iterates over until a connection is successfully established. - Connect to MQTT brokers in a reliable messaging schema and publish messages. - Connect to an MQTT broker and set a last will and testament (LWT) message to notify all the subscribers of the client’s disconnection. - Connect to an MQTT broker with Transport Layer Security (TLS) and listen for messages. - Listen for messages in a single or multiple topics. - Listen for messages on multiple topics using single-level or multi-level wildcards. - Publish messages to a topic. - Publish messages with retention. - Publish messages to an MQTT topic and set different Quality of Service (QoS) levels of delivery assurance for inbound or outbound messages. ## MQTT Architecture MQTT uses the publish/subscribe model, in which a client publishes messages to a particular address, known as a `Topic`. Client receivers subscribe to the topic and receive the published message. In this model, neither the publisher nor the subscriber is aware of each other. The connection between the publisher and subscriber is managed by an MQTT broker. ### MQTT Client A MQTT Client is any device that runs an MQTT library and connects to an MQTT server over a network. ### MQTT Broker The MQTT Broker is a server that receives messages from the clients and then routes the messages to the appropriate destination clients. ### MQTT Topic As the broker acts as a post office, MQTT doesn’t use the address of the intended recipient but uses the subject line called `Topic`, and anyone who wants a copy of that message subscribes to that topic. Multiple clients can receive the message from a single broker (one to many). ## Next Step After you complete the prerequisites, you are ready to create your own app and configure the connector using [Anypoint Studio](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-studio-configuration). ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Use Exchange to Discover Connectors, Templates, and Examples](https://docs.mulesoft.com/connectors/introduction/intro-use-exchange) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # MQTT Connector 1.1 Reference > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint Connector for MQTT (MQTT Connector) is an MQTT (Message Queuing Telemetry Transport) v3.x protocol-compliant MuleSoft extension. MQTT is a lightweight publish/subscribe messaging protocol designed for connecting remote devices with a small code footprint and minimal network bandwidth. MQTT today is used in a wide variety of industries, such as automotive, manufacturing, telecommunications, and oil and gas. The connector consumes and produces MQTT messages and supports all MQTT v3.x functionalities including message retention, LWT(LWT) messages, and persistent sessions. ## Configurations --- ### Config Default configuration. #### Parameters
NameTypeDescriptionDefault ValueRequired

Name

String

The name for this configuration. Connectors reference the configuration with this name.

x

Connection

Connection types for this configuration.

x

Name

String

The identifier of this element used to reference it in other components

x

Expiration Policy

Configures an expiration policy for the configuration.

#### Connection Types ##### MQTT 3 URL Connection Cached connection provider that creates MQTT connections. Enables you to specify a connection URL for the broker. ###### Parameters
NameTypeDescriptionDefault ValueRequired

Client ID Generator

A Client ID generator that generates a Client ID to identify a connection to the MQTT broker.

x

Username

String

Username to authenticate credentials to the MQTT broker.

Password

String

Password authenticate credentials to the MQTT broker.

URL

String

URL that represents the broker to connect to.

x

TLS Context

Topic

String

Topic to publish the LWTmessage.

Body

String

Content of the LWTmessage.

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the LWTmessage is published. Defaults to AT_LEAST_ONCE.

AT_LEAST_ONCE

Is Retained

Boolean

If set to true, the broker retains the LWTmessage.

false

Connection Timeout

Number

The socket connection timeout value. This attribute works in tandem with timeoutUnit. If multiple fail-over URLs are provided, the timeout applies to each URL individually.

30

Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Unit of time for the Connection Timeout field.

SECONDS

Keep Alive Interval

Number

The amount of time that the connection between the client and broker is kept alive without any messages exchanged. If the keep-alive interval is 0, then the keep-alive mechanism is disabled.

0

Keep Alive Interval Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The unit of time that corresponds to the keepAliveInterval parameter. Defaults to SECONDS

SECONDS

Max In Flight

Number

Maximum number of messages that can be unacknowledged at a given time. If you set the parameter to 0, there can be unlimited in-flight messages.

10

Clean Session

Boolean

If set to true, the session is cleaned each time the client disconnects from the broker. Subscriptions are not saved and offline (QoS 1 and 2) messages for that client are lost.

true

Enable File Persistence

Boolean

If set to true, creates a file-based persistent data store, used to store outbound and inbound messages while they are in flight, enabling delivery to the QoS specified.

false

Data Store Path

String

The directory where the file-based persistent data store is created if enableFilePersistence is set to true.

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy.

##### MQTT 3 Fail-Over Connection ###### Parameters
NameTypeDescriptionDefault ValueRequired

Client ID Generator

A ClientIDGenerator that generates a Client ID to identify a connection to the MQTT broker.

x

Username

String

Username to authenticate credentials to the MQTT broker.

Password

String

Password to authenticate credentials to the MQTT broker.

Fail Over Servers

Array of Fail Over URL

The list of server URLs used to establish a connection to the broker.

x

TLS Context

Topic

String

Topic to publish the LWTmessage.

Body

String

Content of the LWTmessage.

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the LWTmessage is published. Defaults to AT_LEAST_ONCE

AT_LEAST_ONCE

Is Retained

Boolean

If set to true, the broker retains the LWTmessage.

false

Connection Timeout

Number

The socket connection timeout value. This attribute works in tandem with timeoutUnit. If multiple fail-over URLs are provided, the timeout applies to each URL individually.

30

Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Unit of time for the Connection Timeout field. Defaults to SECONDS

SECONDS

Keep Alive Interval

Number

The amount of time that the connection between the client and broker is kept alive without any messages being exchanged. If the keep-alive interval is 0, then the keep-alive mechanism is disabled.

0

Keep Alive Interval Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The unit of time that corresponds to the keepAliveInterval parameter. Defaults to SECONDS

SECONDS

Max In Flight

Number

Maximum number of messages that can be unacknowledged at a given time. If you set the parameter to 0, there can be unlimited in-flight messages.

10

Clean Session

Boolean

If set to true, the session is cleaned each time the client disconnects from the broker. Subscriptions are not saved and offline (QoS 1 and 2) messages for that client are lost.

true

Enable File Persistence

Boolean

If set to true, creates a file-based persistent data store, used to store outbound and inbound messages while they are in flight, enabling delivery to the QoS specified.

false

Data Store Path

String

The directory where the file-based persistent data store is created if enableFilePersistence is set to true.

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy.

##### MQTT 3 Form Connection Cached connection provider that creates MQTT connections. Enables you to specify a protocol, host, and port to establish a connection with the broker. ###### Parameters
NameTypeDescriptionDefault ValueRequired

Client ID Generator

A Client ID generator that generates a Client ID to identify a connection to the MQTT broker.

x

Username

String

Username to authenticate credentials to the MQTT broker.

Password

String

Password to authenticate credentials to the MQTT broker.

Protocol

Enumeration, one of:

  • TCP

  • WS

  • WSS

  • SSL

  • LOCAL

Transport level protocol to use when connecting to the broker.

TCP

URL

String

Broker’s host to connect to.

x

Port

String

Broker’s port to connect to

1883

TLS Context

Topic

String

Topic to publish the LWTmessage.

Body

String

Content of the LWTmessage.

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the LWTmessage is published. Defaults to AT_LEAST_ONCE

AT_LEAST_ONCE

Is Retained

Boolean

If set to true, the broker retains the LWTmessage.

false

Connection Timeout

Number

The socket connection timeout value. This attribute works in tandem with timeoutUnit. If multiple fail-over URLs are provided, the timeout applies to each URL individually.

30

Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Unit of time for the Connection Timeout field. Defaults to SECONDS

SECONDS

Keep Alive Interval

Number

The amount of time that the connection between the client and broker is kept alive without any messages being exchanged. If the keep-alive interval is 0, then the keep-alive mechanism is disabled.

0

Keep Alive Interval Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The unit of time that corresponds to the keepAliveInterval parameter.

SECONDS

Max In Flight

Number

Maximum number of messages that can be unacknowledged at a given time. If you set the parameter to 0, there can be unlimited in-flight messages.

10

Clean Session

Boolean

If set to true, the session is cleaned each time the client disconnects from the broker. Subscriptions are not saved and offline (QoS 1 and 2) messages for that client are lost.

true

Enable File Persistence

Boolean

If set to true, creates a file-based persistent data store, used to store outbound and inbound messages while they are in flight, enabling delivery to the QoS specified.

false

Data Store Path

String

The directory where the file-based persistent data store is created if enableFilePersistence is set to true.

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy.

#### Associated Operations - [Publish](#Publish) #### Associated Sources - [On New Message](#Listener) ## Operations ### Publish `` Operation that enables you to publish a single MQTT 3 message to a given exchange. ### Parameters
NameTypeDescriptionDefault ValueRequired

Configuration

String

Name of the configuration to use.

x

Topic

String

Topic in which to publish the message.

x

Message

Any

Content of the message to publish.

#[payload]

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the message is published.

AT_LEAST_ONCE

Is Retained

Boolean

Whether the broker retains the message.

false

Config Ref

ConfigurationProvider

Name of the configuration to execute the component.

x

Reconnection Strategy

A retry strategy in case of connectivity errors.

### For Configurations - [Config](#Config) ### Throws - MQTT3:CONNECTIVITY The client became disconnected from the broker while attempting to publish a message. - MQTT3:INVALID\_CLIENT\_ID The client ID is invalid. - MQTT3:INVALID\_TOPIC The topic is invalid because, for example, the name is too short, too long, or contains invalid characters. - MQTT3:PERSISTENCE When publishing a message, an error occurred while reading or writing persistent data for reliable messaging. - MQTT3:PUBLISH An error occurred while attempting to publish a message. - MQTT3:RETRY\_EXHAUSTED All reconnection attempts failed. - MQTT3:UNAUTHORIZED The client is not authorized to publish a message. - MQTT3:WRITE\_TIMEOUT An error occurred when the client timed out waiting to write messages to the server. ## Sources ### On New Message `` Source that listens for new incoming messages for one or more topic filters. Each topic filter has a specific QoS configured. ### Parameters
NameTypeDescriptionDefault ValueRequired

Configuration

String

Name of the configuration to use.

x

Topics

Array of Topic

List of topics that the listener subscribes to. You can configure this field by using either Edit inline or Bean reference. For source configuration examples, see Listen for New Messages with MQTT Connector.

x

Config Ref

ConfigurationProvider

Name of the configuration to execute the component.

x

Primary Node Only

Boolean

Determines whether to execute the source only on the primary node when running Mule instances in a cluster.

true

Redelivery Policy

Defines a policy for processing the redelivery of the same message.

Reconnection Strategy

A retry strategy in case of connectivity errors.

### Output

Type

Any

Attributes Type

### For Configurations - [Config](#Config) ## Types ### TLS Configures TLS to provide secure communications for the Mule app.
FieldTypeDescriptionDefault ValueRequired

Enabled Protocols

String

Comma-separated list of protocols enabled for this context.

Enabled Cipher Suites

String

Comma-separated list of cipher suites enabled for this context..

Trust Store

Key Store

Revocation Check

### Trust Store Configures the truststore for TLS.
FieldTypeDescriptionDefault ValueRequired

Path

String

Path to the truststore. Mule resolves the path relative to the current classpath and file system, if possible.

Password

String

Password used to protect the trust store.

Type

String

Type of truststore.

Algorithm

String

Encryption algorithm that the trust store uses.

Insecure

Boolean

If true, no certificate validations will be performed, rendering connections vulnerable to attacks. Use at your own risk.

### Key Store Configures the keystore for the TLS protocol. The keystore you generate contains a private key and a public certificate.
FieldTypeDescriptionDefault ValueRequired

Path

String

Path to the keystore. Mule resolves the path relative to the current classpath and file system, if possible.

Type

String

Type of keystore.

Alias

String

Alias of the key to use when the keystore contains multiple private keys. By default, Mule uses the first key in the file.

Key Password

String

Password used to protect the private key.

Password

String

Password used to protect the keystore.

Algorithm

String

Encryption algorithm that the keystore uses.

### Standard Revocation Check Configures standard revocation checks for TLS certificates.
FieldTypeDescriptionDefault ValueRequired

Only End Entities

Boolean

Verify the last element of the certificate chain only.

Prefer Crls

Boolean

Try CRL instead of OCSP first.

No Fallback

Boolean

Do not use the secondary checking method, which is the method not specified in the Prefer Crls field.

Soft Fail

Boolean

Avoid verification failure when the revocation server cannot be reached or is busy.

### Custom OCSP Responder Configures a custom OCSP responder for certification revocation checks.
FieldTypeDescriptionDefault ValueRequired

Url

String

URL of the OCSP responder.

Cert Alias

String

Alias of the signing certificate for the OCSP response. If specified, the alias must be in the truststore.

### CRL File Specifies the location of the certification revocation list (CRL) file.
FieldTypeDescriptionDefault ValueRequired

Path

String

Path to the CRL file.

### Reconnection Configures a reconnection strategy for an operation.
FieldTypeDescriptionDefault ValueRequired

Fails Deployment

Boolean

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy.

Reconnection Strategy

Reconnection strategy to use.

### Reconnect Configures a standard reconnection strategy, which specifies how often to reconnect and how many reconnection attempts the connector source or operation can make.
FieldTypeDescriptionDefault ValueRequired

Frequency

Number

How often in milliseconds to reconnect.

Blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

Count

Number

How many reconnection attempts to make.

### Reconnect Forever Configures a forever reconnection strategy by which the connector operation source or operation attempts to reconnect at a specified frequency for as long as the Mule app runs.
FieldTypeDescriptionDefault ValueRequired

Frequency

Number

How often to attempt to reconnect, in milliseconds.

Blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

### Fail Over URL
FieldTypeDescriptionDefault ValueRequired

Protocol

Enumeration, one of:

  • TCP

  • WS

  • WSS

  • SSL

  • LOCAL

Transport level protocol to use when connecting to the broker.

TCP

Host

String

Broker’s host to connect to.

localhost

Port

String

Broker’s port to connect to.

1883

### Expiration Policy Configures the minimum amount of time that a dynamic configuration instance can remain idle before Mule considers it eligible for expiration.
FieldTypeDescriptionDefault ValueRequired

Max Idle Time

Number

A scalar time value for the maximum amount of time a dynamic configuration instance should be allowed to be idle before it’s considered eligible for expiration.

Time Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Time unit for the Max Idle Time field.

### MQTT 3 Message Attributes
FieldTypeDescriptionDefault ValueRequired

Topic

String

Topic to which the broker directed the message.

x

Message Id

Number

MQTT ID that identifies a message received from the broker.

x

QoS

Number

Quality of service of the message delivered by the broker.

x

Is Duplicate

Boolean

If set to true, the message can duplicate another received message.

false

Is Retained

Boolean

If set to true, the message was either sent from a current publisher, or was retained by the server as the last message published on the topic.

false

### Topic
FieldTypeDescriptionDefault ValueRequired

Topic Filter

String

Topic filter that represents a single or multilevel subscription to a topic.

x

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which messages destined to the topic’s Topic filter field should be sent by the broker.

AT_LEAST_ONCE

### Redelivery Policy Configures the redelivery policy for executing requests that generate errors. You can add a redelivery policy to any source in a flow.
FieldTypeDescriptionDefault ValueRequired

Max Redelivery Count

Number

Maximum number of times that a delivered request can be processed unsuccessfully before returning a REDELIVERY_EXHAUSTED error.

Message Digest Algorithm

String

Secure hashing algorithm to use if the Use Secure Hash field is true. If the payload of the message is a Java object, Mule ignores this value and returns the value that the payload’s hashCode() returned.

Message Identifier

Defines which strategy to identify the messages.

Object Store

ObjectStore

Configures the object store that stores the redelivery counter for each message.

### Redelivery Policy Message Identifier Configures how to identify a redelivered message and how to find out when the message was redelivered.
FieldTypeDescriptionDefault ValueRequired

Use Secure Hash

Boolean

If true, Mule uses a secure hash algorithm to identify a redelivered message.

Id Expression

String

One or more expressions that determine when a message was redelivered. You can set this property only if the Use Secure Hash field is false.

### Client ID Random Suffix Generator
FieldTypeDescriptionDefault ValueRequired

Client Id

String

Client ID to identify the connection to the MQTT broker.

### Client ID Custom Expression Generator
FieldTypeDescriptionDefault ValueRequired

Client Id

String

Client ID to identify the connection to the MQTT broker.

Custom Client Id Suffix

String

Custom client ID suffix used to identify the connection to the MQTT broker.

## See Also [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # MQTT Connector Examples > For the full documentation index, see: https://docs.mulesoft.com/llms.txt To fully benefit from using Anypoint Connector for MQTT (MQTT Connector), see the following examples of configuring the connector: - [Configure Quality of Service](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-quality-of-service) Configure the quality of service (QoS) to specify levels of delivery assurance for inbound or outbound messages. - [Configure the Last Will and Testament Message](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-lwt-message) Configure the Last Will and Testament message to notify all the topic subscribers of the client’s disconnection from the broker. - [Set a client ID with MQTT Connector](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-client-id) Configure client ID generators that enable you to set a client ID. - [Listen for New Messages](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-listener) Configure the **On New Message** source to listen for messages on a unique or multiple topics, and listen for messages on multiple topics using single-level or multilevel wildcards. - [Publish a Message](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-publish) Configure the **Publish** operation to publish a message to the desired topic with a specific quality of service. - [Listen and Publish Messages](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-publish-receive) Configure the **On New Message** source and the **Publish** operation to listen and publish messages to a specific topic. - [Deploy MQTT Connector Apps in a Cluster](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-cluster) Understand the client ID behavior of MQTT Connector when deploying Mule apps in a cluster. ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # MQTT Connector Examples > For the full documentation index, see: https://docs.mulesoft.com/llms.txt To fully benefit from using Anypoint Connector for MQTT (MQTT Connector), see the following examples of configuring the connector: - [Configure Quality of Service](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-quality-of-service) Configure the quality of service (QoS) to specify levels of delivery assurance for inbound or outbound messages. - [Configure the Last Will and Testament Message](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-lwt-message) Configure the Last Will and Testament message to notify all the topic subscribers of the client’s disconnection from the broker. - [Set a client ID with MQTT Connector](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-client-id) Configure client ID generators that enable you to set a client ID. - [Listen for New Messages](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-listener) Configure the **On New Message** source to listen for messages on a unique or multiple topics, and listen for messages on multiple topics using single-level or multilevel wildcards. - [Publish a Message](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-publish) Configure the **Publish** operation to publish a message to the desired topic with a specific quality of service. - [Listen and Publish Messages](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-publish-receive) Configure the **On New Message** source and the **Publish** operation to listen and publish messages to a specific topic. - [Deploy MQTT Connector Apps in a Cluster](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-cluster) Understand the client ID behavior of MQTT Connector when deploying Mule apps in a cluster. ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # MQTT Connector FAQ > For the full documentation index, see: https://docs.mulesoft.com/llms.txt MQTT Connector frequently asked questions (FAQ) are: ## Does MQTT Connector use an object store for the Enable File Persistence feature? The **Enable file persistence** feature is available only on the on-premises installation and uses a file for persistent messages. Note that an object store enables persistent storage for CloudHub applications. Refer to the [object store](https://docs.mulesoft.com/object-store/) documentation for details. ## Is MQTT Connector supported on CloudHub and Cluster environments? Yes, MQTT Connector is supported on CloudHub and on cluster environments. ## Is MQTT Connector cluster-aware? MQTT Connector is cluster-aware. MQTT brokers usually implement a client takeover mechanism that closes an old connection if a new connection request with the same client ID as the existing (old) connection is received and then accepts the new connection. The client takeover mechanism can become a problem if you want to deploy an application in a cluster, and still provide an explicit client ID that identifies the client. MQTT Connector provides client ID generators that help you set a static client ID, set a client ID with a dynamic component to adjust to different deployment scenarios, or define your custom client ID generator. For further information, refer to the [set a Client ID with MQTT Connector](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-client-id) documentation. ## What are the authentication types supported? MQTT Connector authentication supports user and password, and certificate-based authentication (TLS or WSS). Refer to the [configure credentials for authentication](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-studio-configuration#configure-authentication) documentation. ## Does MQTT Connector trace connection and operation executions? Refer to the [Troubleshooting MQTT Connector](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-troubleshooting) documentation to learn how to enable verbose logging in DEBUG mode for the connector, for Eclipse Paho driver and the Mosquitto broker. ## What is the server-side configuration required for MQTT Connector to work? MQTT Connector works with any MQTT version 3.x compliant server also known as MQTT broker. To configure the server, refer to your MQTT broker’s documentation, for example, the [Eclipse Mosquitto](https://mosquitto.org/documentation) broker documentation. ## Does MQTT Connector use a 3rd party library to connect with the external system? MQTT Connector uses Eclipse Mosquitto libraries. The ArtifactID is `org.eclipse.paho.client.mqttv3`. ## Is there any documentation or release notes for the Eclipse Mosquitto external library? To get release notes for Eclipse Mosquitto library, refer to the [Eclipse public repository](https://github.com/eclipse-paho/paho.mqtt.java/releases). ## Are there any permission, roles, or additional configuration required on the broker side to connect with our credentials using MQTT Connector? No, there aren’t any additional permissions or configuration requirements to connect to MQTT version 3.x compliant MQTT brokers. On the MQTT broker side, you do need to configure the listeners properly. ## See Also - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # MQTT Connector FAQ > For the full documentation index, see: https://docs.mulesoft.com/llms.txt MQTT Connector frequently asked questions (FAQ) are: ## Does MQTT Connector use an object store for the Enable File Persistence feature? The **Enable file persistence** feature is available only on the on-premises installation and uses a file for persistent messages. Note that an object store enables persistent storage for CloudHub applications. Refer to the [object store](https://docs.mulesoft.com/object-store/) documentation for details. ## Is MQTT Connector supported on CloudHub and Cluster environments? Yes, MQTT Connector is supported on CloudHub and on cluster environments. ## Is MQTT Connector cluster-aware? MQTT Connector is cluster-aware. MQTT brokers usually implement a client takeover mechanism that closes an old connection if a new connection request with the same client ID as the existing (old) connection is received and then accepts the new connection. The client takeover mechanism can become a problem if you want to deploy an application in a cluster, and still provide an explicit client ID that identifies the client. MQTT Connector provides client ID generators that help you set a static client ID, set a client ID with a dynamic component to adjust to different deployment scenarios, or define your custom client ID generator. For further information, refer to the [set a Client ID with MQTT Connector](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-client-id) documentation. ## What are the authentication types supported? MQTT Connector authentication supports user and password, and certificate-based authentication (TLS or WSS). Refer to the [configure credentials for authentication](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-studio-configuration#configure-authentication) documentation. ## Does MQTT Connector trace connection and operation executions? Refer to the [Troubleshooting MQTT Connector](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-troubleshooting) documentation to learn how to enable verbose logging in DEBUG mode for the connector, for Eclipse Paho driver and the Mosquitto broker. ## What is the server-side configuration required for MQTT Connector to work? MQTT Connector works with any MQTT version 3.x compliant server also known as MQTT broker. To configure the server, refer to your MQTT broker’s documentation, for example, the [Eclipse Mosquitto](https://mosquitto.org/documentation) broker documentation. ## Does MQTT Connector use a 3rd party library to connect with the external system? MQTT Connector uses Eclipse Mosquitto libraries. The ArtifactID is `org.eclipse.paho.client.mqttv3`. ## Is there any documentation or release notes for the Eclipse Mosquitto external library? To get release notes for Eclipse Mosquitto library, refer to the [Eclipse public repository](https://github.com/eclipse-paho/paho.mqtt.java/releases). ## Are there any permission, roles, or additional configuration required on the broker side to connect with our credentials using MQTT Connector? No, there aren’t any additional permissions or configuration requirements to connect to MQTT version 3.x compliant MQTT brokers. On the MQTT broker side, you do need to configure the listeners properly. ## See Also - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # MQTT Connector XML and Maven Support > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Although you can manually code a Mule app in XML, it is more efficient to use Anypoint Studio: If you manually code a Mule runtime engine (Mule) app in XML, either from the Anypoint Studio XML editor or from a text editor, you can access the connector from your app by adding reference statements to both your XML Mule flow and the Apache Maven `pom.xml` file. If you add the connector in Studio, Studio automatically populates the XML code with the connector’s namespace and schema location and it also adds a dependency to the `pom.xml` file. ## Add a Namespace for the Connector Paste the following code inside the `` tag of the header of your configuration XML: ```xml http://www.mulesoft.org/schema/mule/mqtt3 http://www.mulesoft.org/schema/mule/mqtt3/current/mule-mqtt3.xsd ``` This example shows how the namespace statements are placed in the `` XML block: ```xml ``` ## Add a POM File Dependency The Apache Maven `pom.xml` file generated by Anypoint Studio contains dependencies for a Mule app. If you code a Mule app manually, include this XML snippet in your `pom.xml` file to enable access to this connector: ```xml com.mulesoft.connectors mule4-mqtt3-connector x.x.x mule-plugin ``` Replace `x.x.x` with the version that corresponds to the connector you are using. To obtain the most up-to-date `pom.xml` file information: 1. Go to [Anypoint Exchange](https://www.mulesoft.com/exchange/). 2. In Exchange, click **Login** and supply your Anypoint Platform username and password. 3. In Exchange, search for `mqtt3 connector`. 4. Select the connector. 5. Click **Dependency Snippets** near the upper right of the screen. ## Next Step After completing your namespace and `pom.xml` file, you can try the [examples](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-examples). ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # MQTT Connector XML and Maven Support > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Although you can manually code a Mule app in XML, it is more efficient to use Anypoint Studio: If you manually code a Mule runtime engine (Mule) app in XML, either from the Anypoint Studio XML editor or from a text editor, you can access the connector from your app by adding reference statements to both your XML Mule flow and the Apache Maven `pom.xml` file. If you add the connector in Studio, Studio automatically populates the XML code with the connector’s namespace and schema location and it also adds a dependency to the `pom.xml` file. ## Add a Namespace for the Connector Paste the following code inside the `` tag of the header of your configuration XML: ```xml http://www.mulesoft.org/schema/mule/mqtt3 http://www.mulesoft.org/schema/mule/mqtt3/current/mule-mqtt3.xsd ``` This example shows how the namespace statements are placed in the `` XML block: ```xml ``` ## Add a POM File Dependency The Apache Maven `pom.xml` file generated by Anypoint Studio contains dependencies for a Mule app. If you code a Mule app manually, include this XML snippet in your `pom.xml` file to enable access to this connector: ```xml com.mulesoft.connectors mule4-mqtt3-connector x.x.x mule-plugin ``` Replace `x.x.x` with the version that corresponds to the connector you are using. To obtain the most up-to-date `pom.xml` file information: 1. Go to [Anypoint Exchange](https://www.mulesoft.com/exchange/). 2. In Exchange, click **Login** and supply your Anypoint Platform username and password. 3. In Exchange, search for `mqtt3 connector`. 4. Select the connector. 5. Click **Dependency Snippets** near the upper right of the screen. ## Next Step After completing your namespace and `pom.xml` file, you can try the [examples](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-examples). ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # Publish Messages to an MQTT Broker with MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt In the following example, you configure the Anypoint Connector for MQTT (MQTT Connector) **Publish** operation, which enables you to publish a message to the desired topic and with a specific quality of service (QoS). 1. In Studio > **Mule Palette**, select **HTTP > Listener**. 2. Drag **Listener** to the Studio canvas. 3. Set **Path** to `/mqtt3/publish`. 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 5. Configure the HTTP Listener global element and click **OK**. 6. In Studio > **Mule Palette**, select **MQTT3 > On New Message**. 7. Drag **On New Message** to the Studio canvas. 8. In the **On New Message** configuration screen, optionally change the value of the **Display Name** field. 9. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 10. In **MQTT3 Config** > **Connection**, select **MQTT3 URL Connection**. 11. For **Client id generator**, select **Client id random suffix generator**. 12. Set the following fields: - **Client ID**: `smart-bentley-123` - **Username**: `usertest` - **Password**: `passtest` - **URL**: `tcp://127.0.0.1:1883` 13. Click **OK**. 14. In the **Publish** configuration screen, set the following fields: - **Topic**: `quotes/terryPratchett` - **Message** `#["Stories of imagination tend to upset those without one."]` - **QoS**: **AT\_LEAST\_ONCE (Default)** - **Is retained**: **True** ![MQTT Publish operation configuration in Studio](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-publish.png) In the **Configuration XML** editor, the `` and `topic` configurations look like this: ```xml #["Stories of imagination sample quote."] ``` ## Mark Messages as Retained By default, a broker discards a received message on a topic for which there are no current subscribers. If you want the broker to retain the message, configure **Is retained** to `True`. The broker stores the last retained message and the corresponding quality of service for the selected topic. Each client that subscribes to a topic pattern that matches the topic of the retained message receives the retained message after they subscribe. The broker stores only one retained message per topic. This enables new subscribers to receive the most current existing value rather than waiting for the next update from a publisher. ## See Also - [MQTT3 Connector Examples](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # Publish Messages to an MQTT Broker with MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt In the following example, you configure the Anypoint Connector for MQTT (MQTT Connector) **Publish** operation, which enables you to publish a message to the desired topic and with a specific quality of service (QoS). 1. In Studio > **Mule Palette**, select **HTTP > Listener**. 2. Drag **Listener** to the Studio canvas. 3. Set **Path** to `/mqtt3/publish`. 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 5. Configure the HTTP Listener global element and click **OK**. 6. In Studio > **Mule Palette**, select **MQTT3 > On New Message**. 7. Drag **On New Message** to the Studio canvas. 8. In the **On New Message** configuration screen, optionally change the value of the **Display Name** field. 9. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 10. In **MQTT3 Config** > **Connection**, select **MQTT3 URL Connection**. 11. For **Client id generator**, select **Client id random suffix generator**. 12. Set the following fields: - **Client ID**: `smart-bentley-123` - **Username**: `usertest` - **Password**: `passtest` - **URL**: `tcp://127.0.0.1:1883` 13. Click **OK**. 14. In the **Publish** configuration screen, set the following fields: - **Topic**: `quotes/terryPratchett` - **Message** `#["Stories of imagination tend to upset those without one."]` - **QoS**: **AT\_LEAST\_ONCE (Default)** - **Is retained**: **True** ![MQTT Publish operation configuration in Studio](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-publish.png) In the **Configuration XML** editor, the `` and `topic` configurations look like this: ```xml #["Stories of imagination sample quote."] ``` ## Mark Messages as Retained By default, a broker discards a received message on a topic for which there are no current subscribers. If you want the broker to retain the message, configure **Is retained** to `True`. The broker stores the last retained message and the corresponding quality of service for the selected topic. Each client that subscribes to a topic pattern that matches the topic of the retained message receives the retained message after they subscribe. The broker stores only one retained message per topic. This enables new subscribers to receive the most current existing value rather than waiting for the next update from a publisher. ## See Also - [MQTT3 Connector Examples](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # Set a Client ID with MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Client IDs are important for MQTT because they identify a connection to an MQTT broker. Moreover, they identify a specific device or client, and it can be useful in terms of traceability to set a client ID that clearly identifies a device’s connection to the broker. MQTT brokers usually implement a mechanism that closes an old connection if a new connection request with the same client ID as the existing (old) connection is received and then accepts the new connection. MQTT brokers employ this mechanism to prevent situations such as TCP connections reaching a half-open or invalid state due to a crash in one of the communication ends, which is undesirable. The broker assumes the new incoming connection to be valid, closes the older connection, and continues using the newly established connection. The client takeover mechanism can become a problem if you want to deploy an application in a cluster, and still provide an explicit client ID that identifies the client. Anypoint Connector for MQTT (MQTT Connector) provides client ID generators that help you set a static client ID, set a client ID with a dynamic component to adjust to different deployment scenarios, or define your custom client ID generator. ## Configure the Client ID Custom Expression Generator This generator enables you to set a static string prefix and an expression as a suffix. Both parameters are optional but you must provide at least one of them in order to generate a client ID. If you do not provide any parameter, an `INVALID_CLIENT_ID` exception is thrown. In the following example, you configure the client ID string to include the current date at the end, generating a client ID similar to `principality-123-2020-09-03`: 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In **MQTT3 Config** > **Connection**, select **MQTT3 URL Connection**. 6. For **Client id generator**, select **Client id custom expression generator**. 7. Set the following fields: - **Client ID**: `principality-123-` - **Custom Client ID Suffix**: `#[%dw 2.0 output text/plain --- now() as String {format: 'y-MM-dd'}]"` - **Username**: `mosquitto` - **Password**: `password` - **URL**: `tcp://broker.hivemq.com:1883` 8. Click **OK**. ![Client ID Custom Expression Generator configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-custom-generator.png) In the **Configuration XML** editor, the `` and `customClientIdSuffix` configurations look like this: ```xml ``` You can also specify an expression as a client ID. In the following example, dynamic configurations generate new connections for each new expression value: ```xml ``` In the following example, you configure a simple string as the client ID, which generates a static client ID `principality-123`: ```xml ``` ## Configure the Client ID Random Suffix Generator This generator enables you to set an optional static string prefix and adds a random UUID as a suffix. If you provide a static prefix, it is separated from the random UUID suffix with a `-` character. In the following example, you configure the generator to generate a client ID similar to `smart-bentley-123-0f321a85-fddf-429f-ba89-26d201db9777`, but each new connection has its own randomly generated UUID suffix: 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In **MQTT3 Config** > **Connection**, select **MQTT3 URL Connection**. 6. For **Client id generator**, select **Client id random suffix generator**. 7. Set the following fields: - **Client ID**: `smart-bentley-123` - **Username**: `mosquitto` - **Password**: `password` - **URL**: `tcp://127.0.0.1:${mosquitto.port1}` 8. Click **OK**. ![Client ID Random Suffix Generator configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-random-generator.png) In the **Configuration XML** editor, the `<` configuration looks like this: ```xml ``` You can also omit the client ID prefix, in which case the generator assigns a random UUID as your client ID. In the following example, you configure the generator to generate a client ID similar to `0f321a85-fddf-429f-ba89-26d201db9777`: ```xml ``` ## Configure a Custom Client ID Generator If you want to supply your own custom client ID generator, you must be familiar with the Mule SDK subtypes, and the import and export annotations. In the following example, you configure your own client ID generator: 1. Create your own Java connector project. 2. In the `pom.xml` file of your connector project, add MQTT Connector as a dependency, for example: ```xml 4.0.0 org.example mqtt3-extended-connector 1.0.0-SNAPSHOT mule-extension MQTT Extended Connector org.mule.extensions mule-ee-core-modules-parent com.mulesoft.connectors mule4-mqtt3-connector 1.0.0 mule-plugin ``` 3. Create your connector’s definition class, for example: ```java @Xml(prefix = "mqtt3-extended") @Extension(name = "MQTT3Extended", category = SELECT) public class MQTT3ExtendedConnector { } ``` 4. In your custom extension, define your implementation for the `ClientIDGenerator` interface, exposed by MQTT Connector. MQTT Connector exposes the `ClientIDGenerator` interface, which requires only that you implement the method `generateClientID()`. At this point, you import this interface using the `@Import` annotation, which is then exported by MQTT Connector. ```java @Xml(prefix = "mqtt3-extended") @Extension(name = "MQTT3Extended", category = SELECT) @Import(type = ClientIDGenerator.class) public class MQTT3ExtendedConnector { } ``` 5. Define an implementation for the `ClientIDGenerator` interface: ```java @Alias("custom-client-id") public class MyClientIdGenerator implements ClientIDGenerator { /** * Client id to be used to identify the connection to the MQTT broker. */ @Parameter @DisplayName("Client ID") @Optional(defaultValue = "") @Expression(NOT_SUPPORTED) @ClientId protected String clientId; private String suffix = "my-custom-suffix"; /** * @return a client ID that results from concatenating the clientId and a randomly generated UUID string. */ @Override public String generateClientID() { return clientId + (clientId.isEmpty() ? "" : "-") + suffix; } } ``` 6. Define the subtype in your connector definition and export your custom implementation: To do so, make the previously defined implementation available to MQTT Connector by defining your custom implementation as a `ClientIDGenerator` subtype in your connector class. Also, export your `MyClientIdGenerator` class using the `@Export` annotation: ```java @Xml(prefix = "mqtt3-extended") @Extension(name = "MQTT3Extended", category = SELECT) @Import(type = ClientIDGenerator.class) @Export(classes = {MyClientIdGenerator.class}) @SubTypeMapping(baseType = ClientIDGenerator.class, subTypes = {MyClientIdGenerator.class}) public class MQTT3ExtendedConnector { } ``` After you set up your custom connector project, you are ready to access the new implementation from your application using MQTT Connector. 7. In Studio, import both your custom connector and MQTT Connector in your application’s `pom.xml` file, for example: ```xml com.mycompany mqtt-custom-id-generator 1.0.0-SNAPSHOT mule-application mqtt-custom-id-generator UTF-8 UTF-8 4.3.0-20210719 3.5.2 org.apache.maven.plugins maven-clean-plugin 3.0.0 org.mule.tools.maven mule-maven-plugin ${mule.maven.plugin.version} true org.eclipse.paho org.eclipse.paho.client.mqttv3 org.mule.connectors mule-http-connector 1.5.25 mule-plugin org.mule.connectors mule-sockets-connector 1.2.1 mule-plugin org.eclipse.paho org.eclipse.paho.client.mqttv3 1.2.5 org.example mqtt3-extended-connector 1.0.0-SNAPSHOT mule-plugin com.mulesoft.connectors mule4-mqtt3-connector 1.0.0 mule-plugin ``` When you subsequently create a new MQTT Connector configuration in your application, your custom client ID implementation appears in the list of available client ID generators. 8. To use your custom ID generator in an MQTT Connector configuration, navigate to the **Global Elements** tab. 9. Click **Create**. 10. In the filter box, type `mqtt` and select **MQTT3 Config**. 11. Click **OK**. 12. In **MQTT3 Config** > **Connection**, select **MQTT3 URL Connection**. 13. For **Client id generator**, select **Custom client id**. 14. Set the following fields: - **Client ID**: `123` - **Username**: `mosquitto` - **Password**: `password` - **URL**: `tcp://broker.hivemq.com:1883"` 15. Click **OK**. ![Custom Client ID Generator configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-custom-generator.png) In the **Configuration XML** editor, the `` and `` configurations look like this: ```xml ``` ## See Also - [MQTT Connector Examples](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # Set a Client ID with MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Client IDs are important for MQTT because they identify a connection to an MQTT broker. Moreover, they identify a specific device or client, and it can be useful in terms of traceability to set a client ID that clearly identifies a device’s connection to the broker. MQTT brokers usually implement a mechanism that closes an old connection if a new connection request with the same client ID as the existing (old) connection is received and then accepts the new connection. MQTT brokers employ this mechanism to prevent situations such as TCP connections reaching a half-open or invalid state due to a crash in one of the communication ends, which is undesirable. The broker assumes the new incoming connection to be valid, closes the older connection, and continues using the newly established connection. The client takeover mechanism can become a problem if you want to deploy an application in a cluster, and still provide an explicit client ID that identifies the client. Anypoint Connector for MQTT (MQTT Connector) provides client ID generators that help you set a static client ID, set a client ID with a dynamic component to adjust to different deployment scenarios, or define your custom client ID generator. ## Configure the Client ID Custom Expression Generator This generator enables you to set a static string prefix and an expression as a suffix. Both parameters are optional but you must provide at least one of them in order to generate a client ID. If you do not provide any parameter, an `INVALID_CLIENT_ID` exception is thrown. In the following example, you configure the client ID string to include the current date at the end, generating a client ID similar to `principality-123-2020-09-03`: 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In **MQTT3 Config** > **Connection**, select **MQTT3 URL Connection**. 6. For **Client id generator**, select **Client id custom expression generator**. 7. Set the following fields: - **Client ID**: `principality-123-` - **Custom Client ID Suffix**: `#[%dw 2.0 output text/plain --- now() as String {format: 'y-MM-dd'}]"` - **Username**: `mosquitto` - **Password**: `password` - **URL**: `tcp://broker.hivemq.com:1883` 8. Click **OK**. ![Client ID Custom Expression Generator configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-custom-generator.png) In the **Configuration XML** editor, the `` and `customClientIdSuffix` configurations look like this: ```xml ``` You can also specify an expression as a client ID. In the following example, dynamic configurations generate new connections for each new expression value: ```xml ``` In the following example, you configure a simple string as the client ID, which generates a static client ID `principality-123`: ```xml ``` ## Configure the Client ID Random Suffix Generator This generator enables you to set an optional static string prefix and adds a random UUID as a suffix. If you provide a static prefix, it is separated from the random UUID suffix with a `-` character. In the following example, you configure the generator to generate a client ID similar to `smart-bentley-123-0f321a85-fddf-429f-ba89-26d201db9777`, but each new connection has its own randomly generated UUID suffix: 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In **MQTT3 Config** > **Connection**, select **MQTT3 URL Connection**. 6. For **Client id generator**, select **Client id random suffix generator**. 7. Set the following fields: - **Client ID**: `smart-bentley-123` - **Username**: `mosquitto` - **Password**: `password` - **URL**: `tcp://127.0.0.1:${mosquitto.port1}` 8. Click **OK**. ![Client ID Random Suffix Generator configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-random-generator.png) In the **Configuration XML** editor, the `<` configuration looks like this: ```xml ``` You can also omit the client ID prefix, in which case the generator assigns a random UUID as your client ID. In the following example, you configure the generator to generate a client ID similar to `0f321a85-fddf-429f-ba89-26d201db9777`: ```xml ``` ## Configure a Custom Client ID Generator If you want to supply your own custom client ID generator, you must be familiar with the Mule SDK subtypes, and the import and export annotations. In the following example, you configure your own client ID generator: 1. Create your own Java connector project. 2. In the `pom.xml` file of your connector project, add MQTT Connector as a dependency, for example: ```xml 4.0.0 org.example mqtt3-extended-connector 1.0.0-SNAPSHOT mule-extension MQTT Extended Connector org.mule.extensions mule-ee-core-modules-parent com.mulesoft.connectors mule4-mqtt3-connector 1.0.0 mule-plugin ``` 3. Create your connector’s definition class, for example: ```java @Xml(prefix = "mqtt3-extended") @Extension(name = "MQTT3Extended", category = SELECT) public class MQTT3ExtendedConnector { } ``` 4. In your custom extension, define your implementation for the `ClientIDGenerator` interface, exposed by MQTT Connector. MQTT Connector exposes the `ClientIDGenerator` interface, which requires only that you implement the method `generateClientID()`. At this point, you import this interface using the `@Import` annotation, which is then exported by MQTT Connector. ```java @Xml(prefix = "mqtt3-extended") @Extension(name = "MQTT3Extended", category = SELECT) @Import(type = ClientIDGenerator.class) public class MQTT3ExtendedConnector { } ``` 5. Define an implementation for the `ClientIDGenerator` interface: ```java @Alias("custom-client-id") public class MyClientIdGenerator implements ClientIDGenerator { /** * Client id to be used to identify the connection to the MQTT broker. */ @Parameter @DisplayName("Client ID") @Optional(defaultValue = "") @Expression(NOT_SUPPORTED) @ClientId protected String clientId; private String suffix = "my-custom-suffix"; /** * @return a client ID that results from concatenating the clientId and a randomly generated UUID string. */ @Override public String generateClientID() { return clientId + (clientId.isEmpty() ? "" : "-") + suffix; } } ``` 6. Define the subtype in your connector definition and export your custom implementation: To do so, make the previously defined implementation available to MQTT Connector by defining your custom implementation as a `ClientIDGenerator` subtype in your connector class. Also, export your `MyClientIdGenerator` class using the `@Export` annotation: ```java @Xml(prefix = "mqtt3-extended") @Extension(name = "MQTT3Extended", category = SELECT) @Import(type = ClientIDGenerator.class) @Export(classes = {MyClientIdGenerator.class}) @SubTypeMapping(baseType = ClientIDGenerator.class, subTypes = {MyClientIdGenerator.class}) public class MQTT3ExtendedConnector { } ``` After you set up your custom connector project, you are ready to access the new implementation from your application using MQTT Connector. 7. In Studio, import both your custom connector and MQTT Connector in your application’s `pom.xml` file, for example: ```xml com.mycompany mqtt-custom-id-generator 1.0.0-SNAPSHOT mule-application mqtt-custom-id-generator UTF-8 UTF-8 4.3.0-20210719 3.5.2 org.apache.maven.plugins maven-clean-plugin 3.0.0 org.mule.tools.maven mule-maven-plugin ${mule.maven.plugin.version} true org.eclipse.paho org.eclipse.paho.client.mqttv3 org.mule.connectors mule-http-connector 1.5.25 mule-plugin org.mule.connectors mule-sockets-connector 1.2.1 mule-plugin org.eclipse.paho org.eclipse.paho.client.mqttv3 1.2.5 org.example mqtt3-extended-connector 1.0.0-SNAPSHOT mule-plugin com.mulesoft.connectors mule4-mqtt3-connector 1.0.0 mule-plugin ``` When you subsequently create a new MQTT Connector configuration in your application, your custom client ID implementation appears in the list of available client ID generators. 8. To use your custom ID generator in an MQTT Connector configuration, navigate to the **Global Elements** tab. 9. Click **Create**. 10. In the filter box, type `mqtt` and select **MQTT3 Config**. 11. Click **OK**. 12. In **MQTT3 Config** > **Connection**, select **MQTT3 URL Connection**. 13. For **Client id generator**, select **Custom client id**. 14. Set the following fields: - **Client ID**: `123` - **Username**: `mosquitto` - **Password**: `password` - **URL**: `tcp://broker.hivemq.com:1883"` 15. Click **OK**. ![Custom Client ID Generator configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-custom-generator.png) In the **Configuration XML** editor, the `` and `` configurations look like this: ```xml ``` ## See Also - [MQTT Connector Examples](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-examples) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.0 --- # Troubleshooting MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt To troubleshoot Anypoint Connector for MQTT (MQTT Connector), become familiar with the information about enabling verbose logging and interpreting commonly thrown messages. ## Enable Verbose Logging To enable verbose logging on the connector, you need to activate logging for the connector and for the Eclipse Paho driver. ### Enable Verbose Logging for MQTT Connector To enable verbose logging in the configuration file: 1. Access Anypoint Studio and navigate to the **Package Explorer** view. 2. Open your application’s project name. 3. Open the `src/main/resources` path folder. 4. Open the `log4j2.xml` file inside the folder. 5. Add an `` tag inside the `` tag: ```xml ... ... ``` 6. Save your application changes. 7. Click the project name in **Package Explorer** and then click **Run** > **Run As** > **Mule Application**. ### Enable Verbose Logging for Eclipse Paho Driver Eclipse Paho, the underlying driver for MQTT Connector uses Java Util Logging. If you want to see the driver’s log messages in the application’s log file, follow the next steps to provide your application with the latest `log4j-jul-2.xx.x.jar` version: 1. Identify the `log4j` core module version by checking the version suffix in the file name of `log4j-core-2.xx.x.jar` in `{MULE_HOME}/lib/boot`. For an embedded Mule runtime engine (Mule), find the folder that is similar to `{AnypointStudio Folder}/Contents/Eclipse/plugins/org.mule.tooling.server.4.3.0.ee_7.3.5.202005112043/mule/lib/boot` 2. Download the same version of `log4j-jul-2.xx.x.jar` from the public Maven repository, for example, for Mule 4.3.0, it’s `log4j-jul-2.13.1.jar`. 3. Put the `log4j-jul-2.xx.x.jar` into `{MULE_HOME}/lib/boot`. 4. In the Mule app, add the corresponding `java.util.logging` category as per the logging level mapping documented on the [Apache Logging Services](https://logging.apache.org/log4j/2.3.x/log4j-jul/index.html) site, for example: ```xml `` ``` For the `level` attribute, you must provide a Java Util Logging Level. Check the [Apache Logging Services](https://logging.apache.org/log4j/2.3.x/log4j-jul/index.html) conversion table of Java Util Logging levels and its equivalent Log4j levels for further details. ## Enable Verbose Logging for Mosquitto Broker Each broker has different mechanisms to configure logging. To set up a Mosquitto broker and configure logging levels, follow these steps: 1. Set up a Mosquitto broker by using the official Docker image. To do so, run the following command: `docker run -it -p 1883:1883 \ -v /your/local/path/mosquitto.log:/mosquitto/mosquitto.log \ -v /your/local/path/mosquitto.conf:/mosquitto/config/mosquitto.conf eclipse-mosquitto` By using this command, you supply the log file `mosquitto.log` and the configuration file `mosquitto.conf`. - The `mosquitto.log` is a file for the broker to write log messages to. - The `mosquitto.conf` is the broker configuration file. 2. Set the desired log level in the `mosquitto.conf` configuration file, for example: ```text # Unencrypted MQTT over TCP # for listener at port 1883 listener 1883 allow_anonymous true # ================================================================= # Logging # ================================================================= # Route log messages to log file log_dest file /mosquitto/mosquitto.log # Types of messages to log. Use multiple log_type lines for logging # multiple types of messages. log_type debug log_type error log_type warning log_type notice log_type information ``` In the first two lines of the previous file you set up a listener in port 1883, with no authentication credentials required. In the logging section you specify that the logs should be written to the `mosquitto.log` file that you mounted, and that you want the broker to log messages of all levels. You can add different listeners with different configurations, depending on what you need to test, for example: ```text per_listener_settings true # Unencrypted MQTT over TCP listener 1883 allow_anonymous true # Unencrypted MQTT over TCP listener 1884 password_file /mosquitto/config/mosquitto.passwd listener 8080 protocol websockets allow_anonymous true ``` In the previous file you configured 3 separate listeners: - On port 1883 you specified an endpoint that allows anonymous connections over MQTT. - On port 1884 you specified a password file where the broker expects to find the usernames and passwords for authentication. - On port 8080 you specified that you will admit websockets connections. To set each individual listener with separate configurations you must first set the `per_listener_settings true`. ## Understand Common Throws Here is a list of common throw messages and how to interpret them: - MQTT3:CONNECTIVITY The client became disconnected from the broker while attempting to publish a message. - MQTT3:INVALID\_TOPIC The topic is invalid because, for example, the name is too short, too long, or contains invalid characters. - MQTT3:PERSISTENCE When publishing a message, an error occurred while reading or writing persistent data for reliable messaging. - MQTT3:PUBLISH An error occurred while attempting to publish a message. - MQTT3:RETRY\_EXHAUSTED All reconnection attempts failed. - MQTT3:WRITE\_TIMEOUT An error occurred when the client timed out waiting to write messages to the server. ## See Also - [Salesforce Help](https://help.salesforce.com) - [Known Issues](https://help.salesforce.com/s/issues) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # Troubleshooting MQTT Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt To troubleshoot Anypoint Connector for MQTT (MQTT Connector), become familiar with the information about enabling verbose logging and interpreting commonly thrown messages. ## Enable Verbose Logging To enable verbose logging on the connector, you need to activate logging for the connector and for the Eclipse Paho driver. ### Enable Verbose Logging for MQTT Connector To enable verbose logging in the configuration file: 1. Access Anypoint Studio and navigate to the **Package Explorer** view. 2. Open your application’s project name. 3. Open the `src/main/resources` path folder. 4. Open the `log4j2.xml` file inside the folder. 5. Add an `` tag inside the `` tag: ```xml ... ... ``` 6. Save your application changes. 7. Click the project name in **Package Explorer** and then click **Run** > **Run As** > **Mule Application**. ### Enable Verbose Logging for Eclipse Paho Driver Eclipse Paho, the underlying driver for MQTT Connector uses Java Util Logging. If you want to see the driver’s log messages in the application’s log file, follow the next steps to provide your application with the latest `log4j-jul-2.xx.x.jar` version: 1. Identify the `log4j` core module version by checking the version suffix in the file name of `log4j-core-2.xx.x.jar` in `{MULE_HOME}/lib/boot`. For an embedded Mule runtime engine (Mule), find the folder that is similar to `{AnypointStudio Folder}/Contents/Eclipse/plugins/org.mule.tooling.server.4.3.0.ee_7.3.5.202005112043/mule/lib/boot` 2. Download the same version of `log4j-jul-2.xx.x.jar` from the public Maven repository, for example, for Mule 4.3.0, it’s `log4j-jul-2.13.1.jar`. 3. Put the `log4j-jul-2.xx.x.jar` into `{MULE_HOME}/lib/boot`. 4. In the Mule app, add the corresponding `java.util.logging` category as per the logging level mapping documented on the [Apache Logging Services](https://logging.apache.org/log4j/2.3.x/log4j-jul/index.html) site, for example: ```xml `` ``` For the `level` attribute, you must provide a Java Util Logging Level. Check the [Apache Logging Services](https://logging.apache.org/log4j/2.3.x/log4j-jul/index.html) conversion table of Java Util Logging levels and its equivalent Log4j levels for further details. ## Enable Verbose Logging for Mosquitto Broker Each broker has different mechanisms to configure logging. To set up a Mosquitto broker and configure logging levels, follow these steps: 1. Set up a Mosquitto broker by using the official Docker image. To do so, run the following command: `docker run -it -p 1883:1883 \ -v /your/local/path/mosquitto.log:/mosquitto/mosquitto.log \ -v /your/local/path/mosquitto.conf:/mosquitto/config/mosquitto.conf eclipse-mosquitto` By using this command, you supply the log file `mosquitto.log` and the configuration file `mosquitto.conf`. - The `mosquitto.log` is a file for the broker to write log messages to. - The `mosquitto.conf` is the broker configuration file. 2. Set the desired log level in the `mosquitto.conf` configuration file, for example: ```text # Unencrypted MQTT over TCP # for listener at port 1883 listener 1883 allow_anonymous true # ================================================================= # Logging # ================================================================= # Route log messages to log file log_dest file /mosquitto/mosquitto.log # Types of messages to log. Use multiple log_type lines for logging # multiple types of messages. log_type debug log_type error log_type warning log_type notice log_type information ``` In the first two lines of the previous file you set up a listener in port 1883, with no authentication credentials required. In the logging section you specify that the logs should be written to the `mosquitto.log` file that you mounted, and that you want the broker to log messages of all levels. You can add different listeners with different configurations, depending on what you need to test, for example: ```text per_listener_settings true # Unencrypted MQTT over TCP listener 1883 allow_anonymous true # Unencrypted MQTT over TCP listener 1884 password_file /mosquitto/config/mosquitto.passwd listener 8080 protocol websockets allow_anonymous true ``` In the previous file you configured 3 separate listeners: - On port 1883 you specified an endpoint that allows anonymous connections over MQTT. - On port 1884 you specified a password file where the broker expects to find the usernames and passwords for authentication. - On port 8080 you specified that you will admit websockets connections. To set each individual listener with separate configurations you must first set the `per_listener_settings true`. ## Understand Common Throws Here is a list of common throw messages and how to interpret them: - MQTT3:CONNECTIVITY The client became disconnected from the broker while attempting to publish a message. - MQTT3:INVALID\_TOPIC The topic is invalid because, for example, the name is too short, too long, or contains invalid characters. - MQTT3:PERSISTENCE When publishing a message, an error occurred while reading or writing persistent data for reliable messaging. - MQTT3:PUBLISH An error occurred while attempting to publish a message. - MQTT3:RETRY\_EXHAUSTED All reconnection attempts failed. - MQTT3:WRITE\_TIMEOUT An error occurred when the client timed out waiting to write messages to the server. ## See Also - [Salesforce Help](https://help.salesforce.com) - [Known Issues](https://help.salesforce.com/s/issues) --- product: MQTT Connector version: 1.0 --- # Using Anypoint Studio to Configure MQTT Connector 1.0 > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint Studio (Studio) editors help you design and update your Mule applications, properties, and configuration files. To add and configure a connector in Studio: 1. [Create a Mule project](#create-mule-project). 2. [Add the connector to your Mule project](#add-connector-to-project). 3. [Configure a source for the connector’s flow](#configure-input-source). 4. [Add a connector operation to the flow](#add-connector-operation). 5. [Configure a global element for the connector](#configure-global-element). 6. [Configure a connection protocol](#configure-protocol). 7. [Configure credentials for authentication](#configure-authentication). 8. [Configure a fail-over server list](#configure-failover). 9. [Enable file persistence](#enable-file-persistence). 10. [Configure advanced connection options](#configure-advanced-options). When you run the connector, you can view the app log to check for problems, as described in [View the App Log](#view-app-log). If you are new to configuring connectors in Studio, see [Using Anypoint Studio to Configure a Connector](https://docs.mulesoft.com/connectors/introduction/intro-config-use-studio). If, after reading this topic, you need additional information about the connector fields, see the [MQTT Connector Reference](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-reference). ## Create a Mule Project In Studio, create a new Mule project in which to add and configure the connector: 1. In Studio, select **File > New > Mule Project**. 2. Enter a name for your Mule project and click **Finish**. ## Add the Connector to Your Mule Project Add Anypoint Connector for MQTT (MQTT Connector) to your Mule project to automatically populate the XML code with the connector’s namespace and schema location and to add the required dependencies to the project’s `pom.xml` file: 1. In the **Mule Palette** view, click **(X) Search in Exchange**. 2. In the **Add Dependencies to Project** window, type `mqtt` in the search field. 3. Click **MQTT 3 Connector** in **Available modules**. 4. Click **Add**. 5. Click **Finish**. Adding a connector to a Mule project in Studio does not make that connector available to other projects in your Studio workspace. ## Configure a Source A source initiates a flow when a specified condition is met. You can configure one of these input sources to use with MQTT Connector: - **MQTT3 > On New Message** Initiates a flow by listening for incoming messages - **HTTP > Listener** Initiates a flow each time it receives a request on the configured host and port - **Scheduler** Initiates a flow when a time-based condition is met For example, to configure an **On New Message** source, follow these steps: 1. In the **Mule Palette** view, select **MQTT3 > On New Message**. 2. Drag **On New Message** to the Studio canvas. 3. In the **On New Message** configuration screen, optionally change the value of the **Display Name** field. 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 5. In the **MQTT3 Config** window, for **Connection**, select one of the connection types to provide to this configuration: - **MQTT3 URL Connection** - **MQTT3 Fail-Over Connection** - **MQTT3 Form Connection** 6. Specify a unique and intuitive **Client ID** to identify an MQTT connection to a broker. 7. On the **General** tab, also specify connection information such as required libraries for the broker. 8. On the **LWT** tab, optionally specify the Last Will and Testament message. 9. On the **TLS/SSL** tab, optionally specify a TLS configuration. 10. On the **Advanced** tab, optionally specify advanced connection options and reconnection strategy. 11. Click **OK**. 12. In the **On New Message** configuration screen, in **Topics**, select either: - **Edit inline** to define topics directly in the listener. - **Bean reference** to reuse a predefined set of topic subscriptions. 13. Click the plus sign (**+**) to configure a topic. 14. In the **Topic** configuration screen, set **Topic filter**, which represents a single or multilevel subscription to a topic. 15. Set **QoS** to any of the following quality of service levels: - **AT\_MOST\_ONCE** - **AT\_LEAST\_ONCE** - **EXACTLY\_ONCE** 16. Click **Finish**. ## Add a Connector Operation to the Flow When you add a connector operation to your flow, you immediately define a specific operation for that connector to perform. To add an operation for MQTT Connector, follow these steps: 1. In the **Mule Palette** view, select **MQTT3** and then select the desired operation. 2. Drag the operation onto the Studio canvas and to the right of the input source. ![Select any of the MQTT Connector or from the Mule Palette view on the right side of Anypoint Studio](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-operations.png) ## Configure a Global Element for the Connector When you configure a connector, it’s best to configure a global element that all instances of that connector in the app can use. MQTT Connector comes with default values for both publishing and consuming messages. To use the connector, the only requirement is that you must configure which connection to use and that you specify a value for the client ID, which will uniquely identify that connection. The client ID is mandatory because it identifies an MQTT connection to a broker. Define a meaningful name that uniquely identifies a client or device that connects to an MQTT broker and not a random string. To configure the global element for MQTT Connector, follow these steps: 1. Select the operation in the Studio canvas. 2. In the configuration screen for the operation, click the plus sign (**+**) next to the **Connector configuration** field to access the global element configuration fields. 3. In the **MQTT3 Config** window, for **Connection**, select one of the connection types to provide to this configuration: - **MQTT3 URL Connection** - **MQTT3 Fail-Over Connection** - **MQTT3 Form Connection** 4. Specify a unique and intuitive **Client ID** to identify an MQTT connection to a broker, for example `smart-bentley-123`. 5. Specify the **URL** to connect to a broker, for example `tcp://127.0.0.1:1883`. 6. On the **General** tab, also specify connection information such as required libraries for the broker. 7. On the **LWT** tab, optionally specify the Last Will and Testament message. 8. On the **SSL/TLS** tab, optionally specify a TLS configuration. 9. On the **Advanced** tab, optionally specify advanced connection options and reconnection strategy. 10. Click **OK** to close the window. ![MQTT 3 Connector Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-global-configuration.png) In the **Configuration XML** editor, the ``, `clientId`, and `url` configurations look like this: ```xml ``` You can also specify each URL field separately for the connection by configuring the **MQTT3 Form Connection**, which enables you to specify a protocol, host, and port to establish a connection with the broker: 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In the **MQTT3 Config** window, for **Connection**, select **MQTT3 Form Connection**. 6. Set the following fields: - **Client id generator**: `Client id random suffix generator` - **Client ID**: `smart-bentley-123` - **Username**: `username` - **Protocol**: **TCP (Default)** - **URL**: `127.0.0.1` - **Port**: `1883` 7. Click **OK**. ![MQTT 3 Form Connection configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-form-connection.png) In the **Configuration XML** editor, the ``, `protocol`, `host`, `port`, and `clientId` configurations look like this: ```xml ``` ## Configure a Connection Protocol MQTT supports protocols that you can use to connect to and exchange MQTT messages with the broker. You can configure any of the following protocols in the connection string of the connector configuration: - **LOCAL** - **SSL** - **TCP (Default)** - **WS** - **WSS** ## Configure Credentials for Authentication Authentication credentials are optional, but you can provide a username and a password if required. In the following example, you configure the authentication by providing a basic username and password: 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In the **MQTT3 Config** window, for **Connection**, select **MQTT3 URL Connection**. 6. Set the following fields: - **Client id generator**: `Client id random suffix generator` - **Client ID**: `smart-bentley-123` - **Username**: `username` - **Password**: `passtest` - **URL**: `tcp://127.0.0.1:1883"` 7. Click **OK**. In the **Configuration XML** editor, the ``, `username`, and `password` configurations look like this: ```xml ``` You can also provide a client certificate to authenticate the connection by setting a TLS context: 1. In Studio, navigate to the **Global Elements** tab. 2. Select your **MQTT3 Config** and click **Edit**. 3. In **MQTT3 Config**, click **SSL/TLS**. 4. For **TLS Context**, select **Edit inline**. 5. In **Trust Store Configuration**, set the following fields: - **Path**: `tls/truststore.jks` - **Password**: `racing` - **Type**: `jks` 6. Click **OK**. ![MQTT TLS Context configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-tls-configuration.png) In the **Configuration XML** editor, the ``,`path`, `password`, and `type` configurations look like this: ```xml ``` ## Configure a Failover Server List There are certain deployment schemas that consist of multiple brokers working together to provide clients with several connection endpoints. When there is more than one available server that the client can connect to, there are two possible scenarios: either each MQTT server operates separately, or they might work together and share a state (cluster mode), in which case you might want to specify how the MQTT client behaves in the event of a reconnection. When you provide a failover server list, the connector can iterate over the list until it successfully establishes a connection with one of the provided endpoints. In the following example, you configure the failover server list for an **MQTT3 Fail-Over Connection**: 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In the **MQTT3 Config** window, for **Connection**, select **MQTT3 Fail-Over Connection**. 6. Set **Client ID** to `smart-bentley-123`. 7. In **Fail over servers**, click the plus sign (**+**). 8. Set the following fields: - **Protocol**: **TCP (Default)** - **Host**: `127.9.0.2` - **Port**: `1883` 9. Click **Finish**. 10. Repeat Steps 7 through 9 twice to add the other new host and port values. ![MQTT 3 Fail-Over Server List configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-failover-serverlist.png) In the **Configuration XML** editor, the `` and ` ``` ## Configure the Clean Session Value In the **MQTT3 Config** window, configure the **Clean session** field to `False` so the broker remembers the client the next time it connects. While the client is offline, all its subscriptions are saved, and Quality of Service (QoS) 1 and 2 messages that the client would want to receive are saved too, until the client reconnects. Some brokers support the clustering of MQTT brokers in which the nodes share a state. In this case, setting the clean session flag to `False` is useful if the node the connector happens to go offline. This enables the client to reconnect to a different node that is aware of the client’s subscriptions so that any messages the connector might have missed while offline are delivered. If the clean session is set to `True (Default)`, then when the connector disconnects, for whatever reason, all its subscriptions are dropped and the connector has to resubscribe upon reconnection. All messages sent while offline are lost. In the following example, you configure the clean session: 1. In Studio, navigate to the **Global Elements** tab. 2. Select your **MQTT3 Config** and click **Edit**. 3. In the **MQTT3 Config** window, on the **Advanced** tab for **Connection**, select **MQTT3 URL Connection**. 4. Set the following fields: - **Clean session**: `False` 5. Click **OK**. ![MQTT Clean session configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-cleansession.png) In the **Configuration XML** editor, the `cleanSession` configuration looks like this: ```xml ``` ## Enable File Persistence In the **MQTT3 Config** window, set the **Enable file persistence** field to `True` to enable the MQTT client to persist its state to a file that is used to store any outbound or inbound in-flight messages that the client might have with QoS ≥ 1. In contrast, if you set the field to `False (Default)`, the client state is saved only in memory and in the event of a crash, the client cannot recover its state. The enable file persistence feature does not use an object store. The file feature relies on the driver to use a file for persistent messages and can only be used in on-premise installations. In the following example, you enable the file persistence: 1. In Studio, navigate to the **Global Elements** tab. 2. Select your **MQTT3 Config** and click **Edit**. 3. In the **MQTT3 Config** window, for **Connection**, select **MQTT3 URL Connection**. 4. On the **Advanced** tab, set the following fields: - **Clean session**: **False** - **Enable file persistence**: **True** 5. Set **Datastore** to `mqtt/store` to specify where you want the persistent store to be generated. 6. Click **OK**. ![MQTT3 Enable File Persistence configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-enablefilepersistence.png) Figure 1. MQTT3 Enable File Persistence configuration In the **Configuration XML** editor, the `enableFilePersistence` and `dataStorePath` configurations look like this: ```xml ``` > [!WARNING] If you set a dynamic client ID, MQTT Connector cannot recover the persisted files in > the event of a crash. You must set a client ID that does not change in the event of an application > restart after a crash. ## Configure Advanced Connection Options MQTT Connector enables you to define multiple default parameters while consuming or publishing messages. This way, you can define a global default behavior for all the operations associated with the configurations. In the following example, you configure the **Keep alive internal** and **Keep alive internal unit** fields to set the maximum period of time that the connection is kept alive without any messages being exchanged between the client and broker. You also configure the **Max in flight** field to indicate the maximum number of in-flight messages allowed: 1. In Studio, navigate to the **Global Elements** tab. 2. Select your **MQTT3 Config** and click **Edit**. 3. In the **MQTT3 Config** window, for **Connection**, select **MQTT3 URL Connection**. 4. Select the **Advanced** tab, set the following fields: - **Keep alive internal**: `60` - **Keep alive internal unit**: **SECONDS (Default)** - **Max in flight**: `60` 5. Click **OK**. ![MQTT3 Connector Advanced Connection configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/1.0/_images/mqtt3-advanced-connection.png) In the **Configuration XML** editor, the `keepAliveInterval`, `keepAliveIntervalUnit`, and `maxInFlight` configurations look like this: ```xml ``` ## View the App Log To check for problems, you can view the app log as follows: - If you’re running the app from Anypoint Platform, the output is visible in the Anypoint Studio console window. - If you’re running the app using Mule from the command line, the app log is visible in your OS console. Unless the log file path is customized in the app’s log file (`log4j2.xml`), you can also view the app log in the default location `MULE_HOME/logs/.log`. ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Using Anypoint Studio to Configure a Connector](https://docs.mulesoft.com/connectors/introduction/intro-config-use-studio) - [MQTT Connector Reference](https://docs.mulesoft.com/mqtt3-connector/1.0/mqtt3-connector-reference) - [Salesforce Help](https://help.salesforce.com) --- product: MQTT Connector version: 1.1 is-latest-version: true --- # Using Anypoint Studio to Configure MQTT Connector 1.1 > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint Studio (Studio) editors help you design and update your Mule applications, properties, and configuration files. To add and configure a connector in Studio: 1. [Create a Mule project](#create-mule-project). 2. [Add the connector to your Mule project](#add-connector-to-project). 3. [Configure a source for the connector’s flow](#configure-input-source). 4. [Add a connector operation to the flow](#add-connector-operation). 5. [Configure a global element for the connector](#configure-global-element). 6. [Configure a connection protocol](#configure-protocol). 7. [Configure credentials for authentication](#configure-authentication). 8. [Configure a fail-over server list](#configure-failover). 9. [Enable file persistence](#enable-file-persistence). 10. [Configure advanced connection options](#configure-advanced-options). When you run the connector, you can view the app log to check for problems, as described in [View the App Log](#view-app-log). If you are new to configuring connectors in Studio, see [Using Anypoint Studio to Configure a Connector](https://docs.mulesoft.com/connectors/introduction/intro-config-use-studio). If, after reading this topic, you need additional information about the connector fields, see the [MQTT Connector Reference](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-reference). ## Create a Mule Project In Studio, create a new Mule project in which to add and configure the connector: 1. In Studio, select **File > New > Mule Project**. 2. Enter a name for your Mule project and click **Finish**. ## Add the Connector to Your Mule Project Add Anypoint Connector for MQTT (MQTT Connector) to your Mule project to automatically populate the XML code with the connector’s namespace and schema location and to add the required dependencies to the project’s `pom.xml` file: 1. In the **Mule Palette** view, click **(X) Search in Exchange**. 2. In the **Add Dependencies to Project** window, type `mqtt` in the search field. 3. Click **MQTT 3 Connector** in **Available modules**. 4. Click **Add**. 5. Click **Finish**. Adding a connector to a Mule project in Studio does not make that connector available to other projects in your Studio workspace. ## Configure a Source A source initiates a flow when a specified condition is met. You can configure one of these input sources to use with MQTT Connector: - **MQTT3 > On New Message** Initiates a flow by listening for incoming messages - **HTTP > Listener** Initiates a flow each time it receives a request on the configured host and port - **Scheduler** Initiates a flow when a time-based condition is met For example, to configure an **On New Message** source, follow these steps: 1. In the **Mule Palette** view, select **MQTT3 > On New Message**. 2. Drag **On New Message** to the Studio canvas. 3. In the **On New Message** configuration screen, optionally change the value of the **Display Name** field. 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app. 5. In the **MQTT3 Config** window, for **Connection**, select one of the connection types to provide to this configuration: - **MQTT3 URL Connection** - **MQTT3 Fail-Over Connection** - **MQTT3 Form Connection** 6. Specify a unique and intuitive **Client ID** to identify an MQTT connection to a broker. 7. On the **General** tab, also specify connection information such as required libraries for the broker. 8. On the **LWT** tab, optionally specify the Last Will and Testament message. 9. On the **TLS/SSL** tab, optionally specify a TLS configuration. 10. On the **Advanced** tab, optionally specify advanced connection options and reconnection strategy. 11. Click **OK**. 12. In the **On New Message** configuration screen, in **Topics**, select either: - **Edit inline** to define topics directly in the listener. - **Bean reference** to reuse a predefined set of topic subscriptions. 13. Click the plus sign (**+**) to configure a topic. 14. In the **Topic** configuration screen, set **Topic filter**, which represents a single or multilevel subscription to a topic. 15. Set **QoS** to any of the following quality of service levels: - **AT\_MOST\_ONCE** - **AT\_LEAST\_ONCE** - **EXACTLY\_ONCE** 16. Click **Finish**. ## Add a Connector Operation to the Flow When you add a connector operation to your flow, you immediately define a specific operation for that connector to perform. To add an operation for MQTT Connector, follow these steps: 1. In the **Mule Palette** view, select **MQTT3** and then select the desired operation. 2. Drag the operation onto the Studio canvas and to the right of the input source. ![Select any of the MQTT Connector or from the Mule Palette view on the right side of Anypoint Studio](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-operations.png) ## Configure a Global Element for the Connector When you configure a connector, it’s best to configure a global element that all instances of that connector in the app can use. MQTT Connector comes with default values for both publishing and consuming messages. To use the connector, the only requirement is that you must configure which connection to use and that you specify a value for the client ID, which will uniquely identify that connection. The client ID is mandatory because it identifies an MQTT connection to a broker. Define a meaningful name that uniquely identifies a client or device that connects to an MQTT broker and not a random string. To configure the global element for MQTT Connector, follow these steps: 1. Select the operation in the Studio canvas. 2. In the configuration screen for the operation, click the plus sign (**+**) next to the **Connector configuration** field to access the global element configuration fields. 3. In the **MQTT3 Config** window, for **Connection**, select one of the connection types to provide to this configuration: - **MQTT3 URL Connection** - **MQTT3 Fail-Over Connection** - **MQTT3 Form Connection** 4. Specify a unique and intuitive **Client ID** to identify an MQTT connection to a broker, for example `smart-bentley-123`. 5. Specify the **URL** to connect to a broker, for example `tcp://127.0.0.1:1883`. 6. On the **General** tab, also specify connection information such as required libraries for the broker. 7. On the **LWT** tab, optionally specify the Last Will and Testament message. 8. On the **SSL/TLS** tab, optionally specify a TLS configuration. 9. On the **Advanced** tab, optionally specify advanced connection options and reconnection strategy. 10. Click **OK** to close the window. ![MQTT 3 Connector Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-global-configuration.png) In the **Configuration XML** editor, the ``, `clientId`, and `url` configurations look like this: ```xml ``` You can also specify each URL field separately for the connection by configuring the **MQTT3 Form Connection**, which enables you to specify a protocol, host, and port to establish a connection with the broker: 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In the **MQTT3 Config** window, for **Connection**, select **MQTT3 Form Connection**. 6. Set the following fields: - **Client id generator**: `Client id random suffix generator` - **Client ID**: `smart-bentley-123` - **Username**: `username` - **Protocol**: **TCP (Default)** - **URL**: `127.0.0.1` - **Port**: `1883` 7. Click **OK**. ![MQTT 3 Form Connection configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-form-connection.png) In the **Configuration XML** editor, the ``, `protocol`, `host`, `port`, and `clientId` configurations look like this: ```xml ``` ## Configure a Connection Protocol MQTT supports protocols that you can use to connect to and exchange MQTT messages with the broker. You can configure any of the following protocols in the connection string of the connector configuration: - **LOCAL** - **SSL** - **TCP (Default)** - **WS** - **WSS** ## Configure Credentials for Authentication Authentication credentials are optional, but you can provide a username and a password if required. In the following example, you configure the authentication by providing a basic username and password: 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In the **MQTT3 Config** window, for **Connection**, select **MQTT3 URL Connection**. 6. Set the following fields: - **Client id generator**: `Client id random suffix generator` - **Client ID**: `smart-bentley-123` - **Username**: `username` - **Password**: `passtest` - **URL**: `tcp://127.0.0.1:1883"` 7. Click **OK**. In the **Configuration XML** editor, the ``, `username`, and `password` configurations look like this: ```xml ``` You can also provide a client certificate to authenticate the connection by setting a TLS context: 1. In Studio, navigate to the **Global Elements** tab. 2. Select your **MQTT3 Config** and click **Edit**. 3. In **MQTT3 Config**, click **SSL/TLS**. 4. For **TLS Context**, select **Edit inline**. 5. In **Trust Store Configuration**, set the following fields: - **Path**: `tls/truststore.jks` - **Password**: `racing` - **Type**: `jks` 6. Click **OK**. ![MQTT TLS Context configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-tls-configuration.png) In the **Configuration XML** editor, the ``,`path`, `password`, and `type` configurations look like this: ```xml ``` ## Configure a Failover Server List There are certain deployment schemas that consist of multiple brokers working together to provide clients with several connection endpoints. When there is more than one available server that the client can connect to, there are two possible scenarios: either each MQTT server operates separately, or they might work together and share a state (cluster mode), in which case you might want to specify how the MQTT client behaves in the event of a reconnection. When you provide a failover server list, the connector can iterate over the list until it successfully establishes a connection with one of the provided endpoints. In the following example, you configure the failover server list for an **MQTT3 Fail-Over Connection**: 1. In Studio, navigate to the **Global Elements** tab. 2. Click **Create**. 3. In the filter box, type `mqtt` and select **MQTT3 Config**. 4. Click **OK**. 5. In the **MQTT3 Config** window, for **Connection**, select **MQTT3 Fail-Over Connection**. 6. Set **Client ID** to `smart-bentley-123`. 7. In **Fail over servers**, click the plus sign (**+**). 8. Set the following fields: - **Protocol**: **TCP (Default)** - **Host**: `127.9.0.2` - **Port**: `1883` 9. Click **Finish**. 10. Repeat Steps 7 through 9 twice to add the other new host and port values. ![MQTT 3 Fail-Over Server List configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-failover-serverlist.png) In the **Configuration XML** editor, the `` and ` ``` ## Configure the Clean Session Value In the **MQTT3 Config** window, configure the **Clean session** field to `False` so the broker remembers the client the next time it connects. While the client is offline, all its subscriptions are saved, and Quality of Service (QoS) 1 and 2 messages that the client would want to receive are saved too, until the client reconnects. Some brokers support the clustering of MQTT brokers in which the nodes share a state. In this case, setting the clean session flag to `False` is useful if the node the connector happens to go offline. This enables the client to reconnect to a different node that is aware of the client’s subscriptions so that any messages the connector might have missed while offline are delivered. If the clean session is set to `True (Default)`, then when the connector disconnects, for whatever reason, all its subscriptions are dropped and the connector has to resubscribe upon reconnection. All messages sent while offline are lost. In the following example, you configure the clean session: 1. In Studio, navigate to the **Global Elements** tab. 2. Select your **MQTT3 Config** and click **Edit**. 3. In the **MQTT3 Config** window, on the **Advanced** tab for **Connection**, select **MQTT3 URL Connection**. 4. Set the following fields: - **Clean session**: `False` 5. Click **OK**. ![MQTT Clean session configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-cleansession.png) In the **Configuration XML** editor, the `cleanSession` configuration looks like this: ```xml ``` ## Enable File Persistence In the **MQTT3 Config** window, set the **Enable file persistence** field to `True` to enable the MQTT client to persist its state to a file that is used to store any outbound or inbound in-flight messages that the client might have with QoS ≥ 1. In contrast, if you set the field to `False (Default)`, the client state is saved only in memory and in the event of a crash, the client cannot recover its state. The enable file persistence feature does not use an object store. The file feature relies on the driver to use a file for persistent messages and can only be used in on-premise installations. In the following example, you enable the file persistence: 1. In Studio, navigate to the **Global Elements** tab. 2. Select your **MQTT3 Config** and click **Edit**. 3. In the **MQTT3 Config** window, for **Connection**, select **MQTT3 URL Connection**. 4. On the **Advanced** tab, set the following fields: - **Clean session**: **False** - **Enable file persistence**: **True** 5. Set **Datastore** to `mqtt/store` to specify where you want the persistent store to be generated. 6. Click **OK**. ![MQTT3 Enable File Persistence configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-enablefilepersistence.png) Figure 1. MQTT3 Enable File Persistence configuration In the **Configuration XML** editor, the `enableFilePersistence` and `dataStorePath` configurations look like this: ```xml ``` > [!WARNING] If you set a dynamic client ID, MQTT Connector cannot recover the persisted files in > the event of a crash. You must set a client ID that does not change in the event of an application > restart after a crash. ## Configure Advanced Connection Options MQTT Connector enables you to define multiple default parameters while consuming or publishing messages. This way, you can define a global default behavior for all the operations associated with the configurations. In the following example, you configure the **Keep alive internal** and **Keep alive internal unit** fields to set the maximum period of time that the connection is kept alive without any messages being exchanged between the client and broker. You also configure the **Max in flight** field to indicate the maximum number of in-flight messages allowed: 1. In Studio, navigate to the **Global Elements** tab. 2. Select your **MQTT3 Config** and click **Edit**. 3. In the **MQTT3 Config** window, for **Connection**, select **MQTT3 URL Connection**. 4. Select the **Advanced** tab, set the following fields: - **Keep alive internal**: `60` - **Keep alive internal unit**: **SECONDS (Default)** - **Max in flight**: `60` 5. Click **OK**. ![MQTT3 Connector Advanced Connection configuration in Global Element Properties window](/mulesoft/current/en-us/mqtt3-connector/latest/_images/mqtt3-advanced-connection.png) In the **Configuration XML** editor, the `keepAliveInterval`, `keepAliveIntervalUnit`, and `maxInFlight` configurations look like this: ```xml ``` ## View the App Log To check for problems, you can view the app log as follows: - If you’re running the app from Anypoint Platform, the output is visible in the Anypoint Studio console window. - If you’re running the app using Mule from the command line, the app log is visible in your OS console. Unless the log file path is customized in the app’s log file (`log4j2.xml`), you can also view the app log in the default location `MULE_HOME/logs/.log`. ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Using Anypoint Studio to Configure a Connector](https://docs.mulesoft.com/connectors/introduction/intro-config-use-studio) - [MQTT Connector Reference](https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-reference) - [Salesforce Help](https://help.salesforce.com)