Chapter 18. Connecting to MQTT

MQ Telemetry Transport (MQTT) is a lightweight, machine-to-machine, internet of things, connectivity protocol. In an integration, you can obtain messages from or publish messages to an MQTT broker. To do this, create a connection to the MQTT broker of interest and then add that connection to an integration flow. Details are in the following topics:

18.1. Creating a connection to an MQTT broker

In an integration, to obtain messages from or publish messages to an MQTT broker, create a connection to the MQTT broker of interest and then add that connection to an integration.

Prerequisite

You must know the URL for the MQTT broker that you want to connect to.

Procedure

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. Click Create Connection to display connectors.
  3. Click the MQTT Message Broker connector.
  4. To configure the connection:

    1. In the MQTT broker URL field, enter the location of the MQTT broker that you want to send data to or obtain data from. This is the only required field.
    2. In the User Name field, optionally enter the user name for the MQTT account whose credentials you want to use to access the broker.
    3. In the Password field, if you specified a user name, then specify the password associated with that account.
    4. In the Client ID field, optionally enter the ID that allows connections to close and reopen without missing messages. The connection must subscribe to or publish to a topic.
  5. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the input parameters and try again.
  6. If validation is successful, click Next.
  7. In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter MQTT West.
  8. In the Description field, optionally enter any information that is helpful to know about this connection.
  9. Click Save to see that the connection you created is now available. If you entered the example name, you would see that MQTT West appears as a connection that you can choose to add to an integration.

18.2. Obtaining a message from an MQTT broker to trigger integration execution

To trigger execution of an integration based on receiving a message from an MQTT broker, add an MQTT connection as the start connection. When the integration is running, the MQTT connection continuously watches for messages on the MQTT queue or topic that you specify. When the connection finds a message, it passes it to the next step in the integration. An MQTT connection handles one message at a time.

Prerequisite

You created an MQTT connection.

Procedure

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a connection page, click the MQTT connection that you want to use to start the integration.
  4. On the Choose an action page, select the Subscribe action to receive messages from the queue or topic that you specify.
  5. In the MQTT queue/topic name field, enter the name of the queue or topic to subscribe to in order to receive data.
  6. Click Next to specify the action’s output type.
  7. In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.

    However, a structured data type is recommended. For example, if you want to map the connection output in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.

    To specify the data type, click in the Select Type field and select one of the following as the schema type:

    • JSON schema is a document that describes the structure of JSON data. The document’s media type is application/schema+json.
    • JSON instance is a document that contains JSON data. The document’s media type is application/json.
    • XML schema is a document that describes the structure of XML data. The document’s file extension is .xsd.
    • XML instance is a document that contains XML data. The document’s file extension is .xml.
  8. In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of application/schema+json.
  9. In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify Vendor as the data type name.

    You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Fuse Online displays the type name in the integration visualization and in the data mapper.

  10. In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
  11. Click Next.

Result

The integration now has a start connection and Fuse Online is prompting you to choose the finish connection.

18.3. Publishing a message to an MQTT broker

In an integration, you can publish a message to an MQTT broker in the middle of a flow or to finish a simple integration. To do this, add an MQTT connection to the middle of a flow or as the integration’s finish connection.

Prerequisites

  • You created an MQTT connection.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add an MQTT connection. Skip this step if you are adding a simple integration’s finish connection.
  2. Click the MQTT connection that you want to use to publish a message.
  3. On the Choose an action page, select Publish.
  4. In the MQTT queue/topic name field, specify the name of the queue or topic to publish the message to.
  5. Click Next to specify the action’s input type.
  6. In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.

    However, a structured data type is recommended. For example, if you want to map the connection input in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.

    To specify the data type, click in the Select Type field and select one of the following as the schema type:

    • JSON schema is a document that describes the structure of JSON data. The document’s media type is application/schema+json.
    • JSON instance is a document that contains JSON data. The document’s media type is application/json.
    • XML schema is a document that describes the structure of XML data. The document’s file extension is .xsd.
    • XML instance is a document that contains XML data. The document’s file extension is .xml.
  7. In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of application/schema+json.
  8. In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify Vendor as the data type name.

    You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Fuse Online displays the type name in the integration visualization and in the data mapper.

  9. In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
  10. Click Next.

Result

The connection appears in the integration visualization where you added it.