--- schema_version: "1" id: 26bfa49336df9c62f6c96fd4ab50bc4d41d4ab0ec21a32b5ab9ed5e9424140ee title: Using Anypoint Studio to Configure MQTT Connector 1.1 collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mqtt3-connector/latest/mqtt3-connector-studio-configuration.md canonical_url: https://docs.mulesoft.com/mqtt3-connector/latest/mqtt3-connector-studio-configuration source_site: docs.mulesoft.com content_type: documentation content_hash: b65e2c89d5a11817bd53c7b68b0877c47e619e440e8d9d4af719b446da1fb25e description: MuleSoft Documentation Site release: "1.1" latest: true --- --- 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)