MQTT Connector 1.0 Reference | MuleSoft Documentation
# MQTT Connector 1.0 Reference
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
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
The name for this configuration. Connectors reference the configuration with this name.  
Connection | 
  * MQTT 3 URL Connection
  * MQTT 3 Fail-Over Connection
  * MQTT 3 Form Connection

| Connection types for this configuration.  
The identifier of this element used to reference it in other components  
Expiration Policy |  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
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Client ID Generator |  One of:
  * Client ID Random Suffix Generator
  * Client ID Custom Expression Generator

| A Client ID generator that generates a Client ID to identify a connection to the MQTT broker.  
Username | Username to authenticate credentials to the MQTT broker.  
Password | Password authenticate credentials to the MQTT broker.  
URL that represents the broker to connect to.  
Topic to publish the LWTmessage.  
Content of the LWTmessage.  
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 | If set to `true`, the broker retains the LWTmessage.  
Connection Timeout | 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.  
Timeout Unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

| Unit of time for the **Connection Timeout** field.  
Keep Alive Interval | 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.  
Keep Alive Interval Unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

| The unit of time that corresponds to the `keepAliveInterval` parameter. Defaults to SECONDS  
Max In Flight | 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.  
Clean Session | 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.  
Enable File Persistence | 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.  
Data Store Path | 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
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Client ID Generator |  One of: * Client ID Random Suffix Generator * Client ID Custom Expression Generator | A ClientIDGenerator that generates a Client ID to identify a connection to the MQTT broker.  
Username | Username to authenticate credentials to the MQTT broker.  
Password | 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.  
Topic to publish the LWTmessage.  
Content of the LWTmessage.  
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 | If set to `true`, the broker retains the LWTmessage.  
Connection Timeout | 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.  
Timeout Unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

| Unit of time for the **Connection Timeout** field. Defaults to SECONDS  
Keep Alive Interval | 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.  
Keep Alive Interval Unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

| The unit of time that corresponds to the `keepAliveInterval` parameter. Defaults to SECONDS  
Max In Flight | 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.  
Clean Session | 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.  
Enable File Persistence | 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.  
Data Store Path | 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
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Client ID Generator |  One of: * Client ID Random Suffix Generator * Client ID Custom Expression Generator | A Client ID generator that generates a Client ID to identify a connection to the MQTT broker.  
Username | Username to authenticate credentials to the MQTT broker.  
Password | Password to authenticate credentials to the MQTT broker.  
Protocol |  Enumeration, one of:
  * LOCAL

| Transport level protocol to use when connecting to the broker.  
Broker’s host to connect to.  
Broker’s port to connect to  
Topic to publish the LWTmessage.  
Content of the LWTmessage.  
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 | If set to `true`, the broker retains the LWTmessage.  
Connection Timeout | 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.  
Timeout Unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

| Unit of time for the **Connection Timeout** field. Defaults to SECONDS  
Keep Alive Interval | 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.  
Keep Alive Interval Unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS
| Transport level protocol to use when connecting to the broker.  
Broker’s host to connect to.  
Broker’s port to connect to  
Topic to publish the LWTmessage.  
Content of the LWTmessage.  
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 | If set to `true`, the broker retains the LWTmessage.  
Connection Timeout | 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.  
Timeout Unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

| Unit of time for the **Connection Timeout** field. Defaults to SECONDS  
Keep Alive Interval | 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.  
Keep Alive Interval Unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

| The unit of time that corresponds to the `keepAliveInterval` parameter.  
Max In Flight | 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.  
Clean Session | 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.  
Enable File Persistence | 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.  
Data Store Path | 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
#### Associated Sources
  * On New Message


## Operations
### Publish
`<mqtt3:publish>`
Operation that enables you to publish a single MQTT 3 message to a given exchange.
### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Configuration | Name of the configuration to use.  
Topic in which to publish the message.  
Content of the message to publish. | #[payload]  
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 | Whether the broker retains the message.  
Config Ref |  ConfigurationProvider | Name of the configuration to execute the component.  
Reconnection Strategy | 
  *   * Reconnect Forever

| A retry strategy in case of connectivity errors.  
### For Configurations
### 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
`<mqtt3:listener>`
Source that listens for new incoming messages for one or more topic filters. Each topic filter has a specific QoS configured.
### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Configuration | Name of the configuration to use.  
Array of Topic | List of topics that the listener subscribes to.  
Config Ref |  ConfigurationProvider | Name of the configuration to execute the component.  
Primary Node Only | Determines whether to execute the source only on the primary node when running Mule instances in a cluster.  
Redelivery Policy |  Redelivery Policy | Defines a policy for processing the redelivery of the same message.  
Reconnection Strategy | 
  *   * Reconnect Forever

| A retry strategy in case of connectivity errors.  
### Output
**Attributes Type** |  MQTT 3 Message Attributes  
---|---  
### For Configurations
## Types
Configures TLS to provide secure communications for the Mule app.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Enabled Protocols | Comma-separated list of protocols enabled for this context.  
Enabled Cipher Suites | Comma-separated list of cipher suites enabled for this context..  
Trust Store  
Key Store  
Revocation Check | 
  * Standard Revocation Check
  * Custom OCSP Responder

  
### Trust Store
Configures the truststore for TLS.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Path to the truststore. Mule resolves the path relative to the current classpath and file system, if possible.  
Password | Password used to protect the trust store.  
Type of truststore.  
Algorithm | Encryption algorithm that the trust store uses.  
Insecure | 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.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Path to the keystore. Mule resolves the path relative to the current classpath and file system, if possible.  
Type of keystore.  
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 | Password used to protect the private key.  
Password | Password used to protect the keystore.  
Algorithm | Encryption algorithm that the keystore uses.  
### Standard Revocation Check
Configures standard revocation checks for TLS certificates.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Only End Entities | Verify the last element of the certificate chain only.  
Prefer Crls | Try CRL instead of OCSP first.  
No Fallback | Do not use the secondary checking method, which is the method not specified in the Prefer Crls field.  
Soft Fail | 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.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
URL of the OCSP responder.  
Cert Alias | 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.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Path to the CRL file.  
### Reconnection
Configures a reconnection strategy for an operation.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Fails Deployment | 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 | 
  *   * Reconnect Forever

| 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.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Frequency | How often in milliseconds to reconnect.  
Blocking | If `false`, the reconnection strategy runs in a separate, non-blocking thread.  
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.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Frequency | How often to attempt to reconnect, in milliseconds.  
Blocking | If `false`, the reconnection strategy runs in a separate, non-blocking thread.  
### Fail Over URL
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Protocol |  Enumeration, one of:
  * LOCAL
| 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.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Frequency | How often in milliseconds to reconnect.  
Blocking | If `false`, the reconnection strategy runs in a separate, non-blocking thread.  
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.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Frequency | How often to attempt to reconnect, in milliseconds.  
Blocking | If `false`, the reconnection strategy runs in a separate, non-blocking thread.  
### Fail Over URL
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Protocol |  Enumeration, one of:
  * LOCAL

| Transport level protocol to use when connecting to the broker.  
Broker’s host to connect to. | localhost  
Broker’s port to connect to.  
### Expiration Policy
Configures the minimum amount of time that a dynamic configuration instance can remain idle before Mule considers it eligible for expiration.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Max Idle Time | 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

| Time unit for the **Max Idle Time** field.  
### MQTT 3 Message Attributes
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Topic to which the broker directed the message.  
Message Id | MQTT ID that identifies a message received from the broker.  
Quality of service of the message delivered by the broker.  
Is Duplicate | If set to `true`, the message can duplicate another received message.  
Is Retained | 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.  
### Topic
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Topic Filter | Topic filter that represents a single or multilevel subscription to a topic.  
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.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Max Redelivery Count | Maximum number of times that a delivered request can be processed unsuccessfully before returning a REDELIVERY_EXHAUSTED error.  
Message Digest Algorithm | 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 |  Redelivery Policy 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.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Use Secure Hash | If `true`, Mule uses a secure hash algorithm to identify a redelivered message.  
Id Expression | 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
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Client Id | Client ID to identify the connection to the MQTT broker.  
### Client ID Custom Expression Generator
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Client Id | Client ID to identify the connection to the MQTT broker.  
Custom Client Id Suffix | Custom client ID suffix used to identify the connection to the MQTT broker.  
## See Also
MuleSoft Help Center