By Lance Robinson - Technical Evangelist, /n software.
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 SFTP adapter, which is used to communicate with SFTP servers.  SFTP (which should not be confused with FTP, FTPS, or FTP over SSH) is the SSH File Transfer Protocol. If you're interested in using SFTP communication in your Biztalk orchestrations, 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

After you run the setup application, all of the necessary files will be installed on your system. However, in order for a particular adapter to be listed as an available transport type within BizTalk Server, you must first add it through the BizTalk Administration Console.  To do so, use the following steps:

1. Click the Start menu, select Programs, Microsoft BizTalk Server, and then BizTalk Server Administration.
2. In the BizTalk Administration Console, double-click the Microsoft BizTalk Server (Local) node.
3. Right-click Adapters, click New, and then click Adapter.
4. In the Add Adapter dialog box, select the adapter you wish to add from the drop-down menu.
5. Enter a name for the adapter's transport type in the top text field. This name is arbitrary and does not affect the adapter itself. It will be the that name shows up in the "Transport Type" drop down box of a send or receive port. For the SFTP adapter, a good name would be "SFTP"
6. Enter any comment you wish to describe the adapter's transport type.
7. Click OK.

Now that the adapters are added to the BizTalk Administration Console, we can begin using them in send and receive ports. If you open the BizTalk Explorer and add a receive port, you'll see that the nsoftware SFTP adapter is now available as the transport type.

Adapter Properties - Send Port

One common situation in which the SFTP adapter might be used is one where files dropped in a local folder need to be sent to a remote 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 files picked up in this folder to a remote SFTP server.

After you add a new Send Port and set the transport type to SFTP (also don't forget to set the Filters to associate this send port with the file pickup receive location), click on the "Address (URI)" property, and then click on the ellipsis that comes up for this property. This will bring up a new window called "SFTP Transport Properties" where you will specify the details of how and where the SFTP adapter should connect. There are four groups of properties:

• Firewall Properties

  The first group of properties are Firewall properties. These are only necessary if you have to pass through a local firewall on the way to the server. In most cases, you won't need to worry about this, but in the event that you do, three firewall types are supported here: SOCKS4, SOCKS5, and tunneling firewalls. Specify the type of firewall to pass through using the Firewall Type property. Then set the Firewall Host and Firewall Port to the IP address and port to use on the firewall. Finally, if your firewall requires authentication set the Firewall User and Firewall Password properties.

• SFTP Properties

  The next group of properties are SFTP properties. This is where you will tell the adapter where on the SFTP server to write the files.  All of these properties are fairly self explanatory:

  Overwrite	If set to false, an error will occur if a file with the same name already exists on the remote server. If set to true, the file of the same name will be overwritten.
  Remote File	The name of the destination file on the remote SFTP server.
  Remote Path	The path of the remote SFTP server to which the Remote File should be uploaded.
  Remote Temp Dir	A temporary directory on the remote SFTP server where files will be stored during the upload process. When the upload is complete, the temporary file(s) will be moved to Remote Path. If this property is left blank, files will be uploaded straight to Remote Path.
  Temp Dir	A temporary directory where data can be stored before the adapter processes it. This defaults to the system TEMP folder.

• SSH Properties

  The SSH properties specify where and how to connect for the SFTP connection.

  SSH Accept Server Host Key	Instructs the adapter to accept the server host key that matches the supplied key (base64 encoded, or "ANY").
  SSH Auth Mode	The type of authentication used by the adapter (public key or password authentication).
  SSH Cert	This property shows the subject of the certificate that is currently specified for public key authentication. Clicking the ellipses of this property will open the certificate selector dialog where you will be able to easily load your certificate. With the certificate selector dialog you can load certificates from the User and Machine stores, as well as from PFX or PEM files.
  SSH Compression Algorithm	Can be either "none" (default) or "zlib".
  SSH Host	The internet address of the SSH host.
  SSH Password	The password to use when connecting to the SSH host.
  SSH Port	The port on the SSH host on which to connect.
  SSH User	The user id to use when connecting to the SSH host.

  It is very important to understand these SSH properties, since a complete understanding will help ensure the security of your transactions. To that end, I will go into a more complete discussion of each of these properties.

  The "SSH Cert" property will allow you to specify a certificate in a variety of forms as mentioned above. The design of the certificate selector dialog is intended to allow you to easily select a certificate for public key authentication. If you are specifying a PEM File, please note that you must specify a SSH2 RSA private key.
   

   

  The "SSH Accept Server Host Key" setting tells the adapter what host key to accept during the security handshaking procedure of the connection to the remote server. If the value specified here does not match the key that the server presents, the connection will be terminated with an error. This property may be set to either the full, Base64-encoded text of the server key or its 16-byte MD5 fingerprint. If you choose to specify the fingerprint, you may use either the Base-64 encoded fingerprint or you can HEX-encode it in the form "0a:1b:2c:3d". You may also use the keywords "ANY" or "ALL" to instruct the adapter to accept any server host key. "ANY" or "ALL" should only be used for testing purposes.

  The "SSH Auth Mode" specifies which form of authentication you would like to perform when connecting to the SSH server. The adapter supports either regular "User/Password" authentication, or public key authentication. If you choose to use public key authentication, you'll also need to set the "SSH Cert" property to point the adapter to the key pair it should use. This article is not meant to explain how public key authentication works, however if you would like to use this form of authentication you should generate a key pair on your own computer, and copy the public key to the SSH server. Then when you connect to the server, you can point the adapter to your private key to authenticate. The "SSH Cert" property is only used if you choose to use public key authentication.

  The "SSH Compression Algorithm" property should be set to "ZLIB" if you'd like to implement ZLIB compression in your SSH communications. Use of compression will likely depend on your trading partner's requirements, but it's entirely optional. Generally, it's a good idea to compress large documents but inefficient to use it for small documents.

  The "SSH Host", "SSH Port", "SSH User" and "SSH Password" settings are all self explanatory - just specify the server you'd like to connect to, on what port (the default is port 22), and the user and password to use to connect with. Note that if you use public key authentication, you will still need to specify an "SSH User", but the "SSH Password" will be ignored.

• Tuning Properties

  Error Threshold	Allows you to control how many errors will be encountered before the adapter stops processing messages (defaults to 5).
  Trace Mode	The degree of activity that is written to the event log. You can set the trace mode to Debug if you encounter an error and want to log more details.

 

Usage - Send Port

In order to configure a send port to upload files from the pick-up folder to my remote SFTP server, I only need to set a few of these properties:

• I'll leave the firewall properties to their defaults since I don't need to pass through any proxies to reach my server. 
• As for the SFTP properties, I'll set the "Remote File" to %SourceFileName%, and the "Remote Path" to the name of the specific folder location on the remote server where I want to store the files (in my case "\users\lance\temp\").
• For the SSH properties, I'll start by using the value "ANY" for the "SSH Accept Server Host Key", just for testing.  Later I'll change this to the correct value as documented above.  I'll use public key authentication since it is generally considered to be more secure, so I'll set the "SSH Auth Mode" to "Public Key". I'll get my certificate from a PEM file, so I'll use the certificate selector dialog from the "SSH Cert" to specify the PEM File.  Then all that's left is to set the "SSH Host" and "SSH User" and I'm ready to go.

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 files to my remote SFTP server.

Adapter Properties - Receive Port

Another common situation in which the SFTP adapter might be used is one where files dropped in a folder on a remote SFTP folder need to be retrieved in a BizTalk orchestration or passthrough configuration so that these remote files can be used locally or automatically transferred elsewhere.  In this situation, a receive location of transport type SFTP would be configured in BizTalk to monitor a remote folder.  You could configure a Send port that will send files picked up in this folder to a local folder using the FILE adapter.

After you add a new Receive Location and set the transport type to SFTP, click on the "Address (URI)" property, and then click on the ellipsis that comes up for this property. This will bring up a new window called "SFTP Transport Properties" where you will specify the details of how and where the SFTP 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 SFTP adapter in a send port.

• Firewall Properties

  These are all the same as in a Send Port. 

• SFTP Properties

  The next group of properties are SFTP properties. This is where you will tell the adapter where on the SFTP server to retrieve the files.  Again, these properties are fairly self explanatory:

  Delete	Whether or not the remote file should be deleted after download.
  File Mask	Indicates the type of files to download from the FTP server (for example, "*.txt").
  Local File	The path to a local file for download.
  Overwrite	If set to false, an error will occur if a file with the same name already exists on the remote server. If set to true, the file of the same name will be overwritten.
  Temp Dir	This property indicates a temporary directory where the adapter can store any data before the adapter processes it.

• SSH Properties

  The adapter has the same SSH properties in a receive location as in a send port.

• Tuning Properties

  File Count	The maximum number of files in the current batch (0 indicates no limit).
  File Size	The maximum size, in MB, of a file in the current batch (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).
  Suspend On Error	Whether or not the receive should suspend incoming messages if an error is encountered while submitting it to BizTalk.

 

Usage - Receive Port

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

• I'll leave the firewall properties to their defaults since I don't need to pass through any proxies to reach my server. 
• As for the SFTP properties, I'll set the "Delete" to "Yes" (because I want to delete the remote files after I pick them up, "File Mask" to *.* (because I want to get all the files), and "Local File" to "File-%MessageId%" (to give each download file a unique local name).
• For the SSH properties, I'll use the same settings as in the above send port example since I am connecting to the same server.

To test, I will create a send port of transport type FILE with a filter pointing to this new SFTP receive location.  Then I will enable the ports, start BizTalk Server and drop some files in the remote SFTP server folder.  The files will be picked up by the adapter during the next poll, downloaded and deleted from the server, and passed to the BizTalk Message Box for consumption by the FILE send port!

Conclusions

This article demonstrates the ease of use of the SFTP 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.

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.