AMQP 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 AMQP adapter, which adds AMQP messaging capabilities to your BizTalk Server. If you're interested in using AMQP 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 AMQP adapter is now available as a transport type.

Adapter Properties - Send Port

One common situation in which the AMQP adapter might be used is one where files dropped in a local folder need to be sent as messages to an AMQP broker. 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 AMQP broker.

After you add a new Send Port and set the transport type to "nsoftware.AMQP 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.AMQP 2024 Transport Properties" where you will specify the details of how and where the AMQP adapter should connect. There are six groups of properties:

• AMQP

  The first group of properties are AMQP properties. These include some connection details as follows:

  Auth Scheme	The authentication scheme to use when connecting.
  Container Id	The container Id the adapter should advertise when connecting.
  Idle Timeout	The maximum period of inactivity the adapter will allow before disconnecting.

• 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 Value	This property specifies the contents to send in this message. If left unspecified the BizTalk message body will be used as the message content. The MessageValueType property should be used to specify the data type of the value.
  Message Value Type	This property specifies the message's value data type. See the full documentation for the possible values.
  MessageAbsoluteExpiryTime	The absolute time at which this message should be considered expired.
  Message Durable	Whether this message is durable.
  Message Subject	The subject of this message.

   
• Server Properties

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

  Link Name	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 AQMP server (default is 5672).
  Send Target	The address of the node at the target receiver.
  Session Name	The name of the session.
  User	A username to use for SASL authentication.

 
• 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 AMQP 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 AMQP broker you wish to connect to. Additionally, "Link Name", "Send Target", and "Session Name" must be set.
• The message properties including a "hard-coded" "Message Value" 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 AMQP broker.

Adapter Properties - Receive Port

Another common situation in which the AMQP adapter might be used is one where messages on an AMQP broker 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 AMQP would be configured in BizTalk to monitor this.

After you add a new Receive Location and set the transport type to "nsoftware.AMQP 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.AMQP 2024 Transport Properties" where you will specify the details of how and where the AMQP 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 AMQP adapter in a send port.

• AMQP, Logging, and SSL Properties

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

• Tuning Properties

  Error Threshold	This property limits the number of errors that the adapter can incur before it shuts down and stops processing messages.
  Max Batch Size	This property limits the maximum amount of data the adapter can store before finalizing and processing the current batch to the number of bytes indicated. The default value of 0 indicates no limit.
  Max File Count	This property places a limit on the number of files that can be transmitted in a single batch.
  Max File Size	This property limits the maximum size of any file in the current transmission batch to the number of bytes indicated. The default value of 0 indicates no limit.
  Polling Interval	The number of seconds to wait between download attempts (default is 60 seconds, so for example every 60 seconds the adapter would check the server for new files).

 

Usage - Receive Port

In order to configure a receive port to receive messages from the remote AMQP 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, though I will swap "Send Target" with "Receive Source".

To test, I will create a send port of transport type FILE with a filter pointing to this new AMQP receive location. Then I will enable the ports, start BizTalk Server and publish a message to the AMQP broker. On the next polling interval the adapter will connect to the AMQP broker, 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 AMQP 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.