MQTT Adapter for Microsoft BizTalk

Requirements: /n software Adapters for Microsoft BizTalk

Introduction

The /n software Adapters for Microsoft BizTalk include fully-managed .NET Adapters that seamlessly integrate with the BizTalk Messaging Pipeline. The /n software Adapters extend the features of BizTalk with advanced Internet communications and secure messaging capabilities.

There are many different BizTalk adapters currently supported:  AS2 Adapters for EDI communications, FTPS, FTP, SFTP, SSH, Email adapters, etc. These adapters have completed the official adapter certification program (administered by Unisys) established by Microsoft for BizTalk server, which tests for scalability and interoperability with Microsoft BizTalk Server.

This guide will focus specifically on the MQTT adapter, which adds MQTT messaging capabilities to your BizTalk Server. If you're interested in using MQTT communication in your BizTalk solution, you're in the right place. Before you continue reading, I recommend that you go ahead and download the product and follow along with me through the tutorial.

Contents

1. Adapter Installation
2. Adapter Properties - Send Port
3. Usage - Send Port
4. Adapter Properties - Receive Port
5. Usage - Receive Port

Adapter Installation

Before installing you should stop the BizTalk host instance and close the BizTalk Administration Console. After you run the setup application, all of the necessary files will be installed on your system. The adapters will automatically be added to the BizTalk Administration Console, so we can begin using them in send ports and receive locations. If you open the BizTalk Administration Console and create a new receive location or send port, you'll see that the /n software MQTT adapter is now available as a transport type.

Adapter Properties - Send Port

One common situation in which the MQTT adapter might be used is one where files dropped in a local folder need to be sent as messages to an MQTT server. In this situation, a receive location of transport type FILE would be configured in BizTalk to monitor a folder, and you would configure a Send port that will send the file payload picked up in this folder to the MQTT server.

After you add a new Send Port and set the transport type to "nsoftware.MQTT 2024" (also don't forget to set the Filters to associate this send port with the file pickup receive location), Clicking on the Configure button will bring up a new window called "nsoftware.MQTT 2024 Transport Properties" where you will specify the details of how and where the MQTT adapter should connect. There are six groups of properties:

• Logging

  The Transport Log property is the only property here. If you click the + symbol next to the property this will expand the property and expose it's fields. You will see Location, Log Mode, and Log Type. By default the adapter will log only errors to the application event log. You can change the Log Mode to a mode with greater detail so that information event log entries are written to the event log during the course of execution. You may also change the Log Type so that events will be written to file instead of the event log. In that case you'll need to specify the full path to a file in the Location field.

 

• Message

  The Message properties specify details about the message to send. The following is a list of common properties used when downloading files. For complete details see the online help documentation.

  Message Text	The messages payload. If left unspecified the BizTalk message body will be used as the message content.
  QOS	The messages QoS level. See the full documentation for the possible values.

• MQTT

  The next group of properties are MQTT properties. These include some details for the MQTT session, topic and more:

  Clean Session	Determines whether a clean session is used once connected.
  Client Id	A string that uniquely identifies this instance of the adapter to the server.
  Protocol Version	The MQTT protocol version that the adapter will conform to.
  Topic	The topic to publish to.
  Will Message	The message that the server should publish in the event of an ungraceful disconnection.
  Will Topic	The topic that the server should publish the WillMessage to in the event of an ungraceful disconnection.

Server Properties

The Server properties allow you to specify the login credentials and remote host information.

Password	The user's password.
Remote Host	The address of the remote host. Domain names are resolved to IP addresses.
Remote Port	The port of the MQTT server (default is 1883).
User	A username if authentiation is to be used.

 

SSL Properties

The SSL Properties govern whether or not a server's certificate is accepted, whether SSL client (certificate based) authentication is performed, and what type of SSL is performed.

SSL Accept Server Cert	Instructs the adapter to accept the server certificate which matches the one specified if it is not already trusted by the system. For testing you can expand this property and set the Accept Any field to Yes. This tells the adapter to always accept the server's certificate.
SSL Cert	If set to a valid certificate the adapter will attempt SSL client (certificate based) authentication. Typically this is not required.
SSL Start Mode	Determines what type SSL is performed. This can be set to automatic, explicit, implicit, or none. With a value of automatic the adapter will use the value of Remote Port to determine what type of SSL to perform.

 

Tuning Properties

Firewall	This may be expanded to configure the firewall type, host, port, user, and password if needed.
Other	This allows you to specify additional configuration settings in the format configname1=value1. See the Configuration section of the documentation for a list of supported settings.

Usage - Send Port

In order to configure a send port to send message data from the pick-up folder to an MQTT broker, I only need to set a few of these properties:

• There are five required properties that must be set in the Server properties. "Remote Host" and "Remote Port" should be set to the MQTT server you wish to connect to. Additionally, "Topic" you wish to publish to must be set.
• The message properties including a "hard-coded" "Message Text" may be set. Otherwise the contents of a file in a receive location will be sent as the message content.
See the documentation for more details on these properties.

To test, I'll set the Filter of the send port to BTS.InboundTransportLocation == "C:\test\in\*.*", the location of my File adapter receive location.  Then I'll enable the ports, start BizTalk Server and drop some test files.  The adapter will transfer the picked up file content to the MQTT server.

Adapter Properties - Receive Port

Another common situation in which the MQTT adapter might be used is one where messages on an MQTT server need to be retrieved in a BizTalk orchestration or passthrough configuration so that these messages can be used locally or automatically transferred elsewhere.  In this situation, a receive location of transport type MQTT would be configured in BizTalk to monitor this.

After you add a new Receive Location and set the transport type to "nsoftware.MQTT 2024" (also don't forget to set the Filters to associate this receive location with the file send port), Clicking on the Configure button will bring up a new window called "nsoftware.MQTT 2024 Transport Properties" where you will specify the details of how and where the MQTT adapter should connect. Many of these properties are the same as those documented above in the Send Port section.  Here I will only document the properties specific to using the adapter in a receive location, since many of the properties have the same meaning as in the above description of the MQTT adapter in a send port.

• MQTT, Logging, and SSL Properties

  The adapter has the same MQTT, Logging, Server, and SSL properties in a receive location as in a send port.

 

Usage - Receive Port

In order to configure a receive port to receive messages from the remote MQTT server, again I only need to set a few of these properties:

• For the Server properties, I'll use the same settings as in the above send port example since I am connecting to the same server. I will also set "QOS" to 1 and specify a "Topic".

To test, I will create a send port of transport type FILE with a filter pointing to this new MQTT receive location. Then I will enable the ports, start BizTalk Server and publish a message to the MQTT server on the specified Topic. On the next polling interval the adapter will connect to the MQTT server, receive the message, and pass to the BizTalk Message Box for consumption by the FILE send port. The response received by the adapter will be used as the body of the submitted BizTalk message.

Conclusions

This article demonstrates the ease of use of the MQTT adapter in particular, but /n software provides a full set of adapters for connecting to various types of internet servers.  The adapter properties are kept to a minimum for simplicity, but we make an effort to provide those properties that are necessary for effective control over configurations.