FTP 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 FTP adapter, which is used to communicate with FTP servers. The FTP adapter also supports secure FTP (FTP over SSL). 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. Since the adapters are added to the BizTalk Administration Console during the installation process, we can begin using them in send ports and receive locations. If you open the BizTalk Explorer and add a receive location, you'll see that "nsoftware.FTP 2024" is now available as the transport type.

Adapter Properties - Send Port

One common situation in which the FTP 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 FTP server.

Add a new Send Port and select the "nsoftware.FTP 2024" transport type. Don't forget to set the Filters to associate this send port with the file pickup receive location. Click on the Configure button, and this will bring up a new window called "nsoftware.FTP 2024 Transport Properties" where you will specify the details of how and where the FTP adapter should connect. There are five groups of properties:

• FTP Properties

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

  After Connect	A script that is executed immediately following a successful connection.
  After Put	A script that is executed immediately following each successful FTP PUT operation.
  Append	Controls the adapter's upload behavior. When set to Yes, the adapter will append data to the file specified by Remote File.
  Before Put	A script that is executed immediately before each successful FTP PUT operation.
  Overwrite	Indicates whether or not the adapter should overwrite the file on the server if it exists.
  Remote File	Either an absolute file path (beginning with a "/" or "\", depending on server conventions), or a relative path based on Remote Path.
  Remote Path	This can be set to either an absolute path (beginning with a "/" or "\", depending on server conventions), or a relative path to the user's home directory (does not begin with "/").
  Remote Temp Path	If a value is specified, the adapter will directly upload the file to RemoteTempPath. Once the file transfer is complete, the adapter will move the file to the RemotePath
  Transfer Mode	Controls the FTP transfer mode. Usually the value of Default will not need to be changed.
  Use Simple Dir List	Instructs the adapter to use the NLST command instead of LIST.

• Logging Properties

  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.

• Server Properties

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

  Account	Some servers may require an Account for logon or in order to access specific privileges. Note that this is not the same as a normal login with a username and password.
  FTP Port	The port on which the FTP server is listening. Usually this will be 21 for plain-text or explicit SSL, and 990 for implicit SSL.
  FTP Server	Either the IP Address or host name of the FTP server.
  Passive	We recommend setting this to Yes. When set to Yes the server is responsible for hosting the data connection for file transfers. If set to No, the server will connect to the adapter to establish a data connection, which can be impeded by firewalls.
  Password	The user's password.
  User	The user to authenticate to the FTP server with.

• 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.

  Below is an example of what the certificate selection dialog will look like when specifying a certificate with private key for SSL client authentication in the SSL Cert property.

 

 

• Tuning Properties

  Firewall	This may be expanded to configure the firewall type, host, port, user, and password if needed.
  Other	Accepts configuration settings specified in a name=value format. Only one setting per line should be specified.
  Timeout	The length of time (in seconds) the adapter will wait for a server response.

  As mentioned above the Other property provides a way for you to tweak the operation of the component depending on your requirements. One commonly useful setting is:

  UseRemoteHostAddressForPassive=true

  UseRemoteHostAddressForPassive tells the adapter to use the same host that was specified in Remote Host when attempting to create a data connection for file transfers or directory listings, instead of relying on the server's response to the PASV command. This applies only when Passive is set to yes. This is useful because sometimes a server will not be able to properly translate the IP address that is returned in the result to the PASV command, especially when SSL is used. If you see that you are connecting to the server successfully in the application event log, but see an error when attempting to upload, download, or list a directory, try this setting.

  Please consult the help file's Configuration section for additional supported settings.

 

Usage - Send Port

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

• For the FTP 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 "temp" which is a directory relative to my user's home directory). And, of course, I will fill out my server and account information.
• For the SSL properties, I'll start by expanding the "SSL Accept Server Cert" property by clicking the + symbol and setting the Accept Any field to Yes. This tells the adapter to accept the server's certificate no matter what. I'll use SSL client authentication here by following the steps mentioned above to select a certificate with private key.

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 FTP server.

Adapter Properties - Receive Port

Another common situation in which the FTP adapter might be used is one where files dropped in a folder on a remote FTP 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 "nsoftware.FTP 2024" 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 "nsoftware.FTP 2024", click on the Configuration button. This will bring up a new window called "nsoftware.FTP 2024 Transport Properties" where you will specify the details of how and where the FTP 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 FTP adapter in a send port.

• FTP Properties

  This is where you will tell the adapter where on the FTP server to retrieve the files.  Again, these properties are fairly self explanatory:

  After Get	A script that is executed immediately following each successful FTP GET operation.
  Before Get	A script that is executed immediately before each successful FTP GET operation.
  Delete Mode	Informs the adapter as to whether or not it should delete a remote files from the server after a successful download.
  File Mask	Files in the Remote Path matching the pattern specified will be downloaded from the FTP server (for example, "*.txt")
  Temp Path	Indicates a temporary directory where the adapter can store any data before the adapter processes it.

• Server Properties

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

• SSL Properties

  The adapter has the same 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 download files from the remote FTP server, again I only need to set a few of these properties:

• For the FTP properties, I'll set the "Delete Mode" to "Never" (because I don't want to delete the remote files after I pick them up, and "File Mask" to *.txt.
• For the SSL 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 FTP receive location.  Then I will enable the ports, start BizTalk Server and drop some files in the remote FTP 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 FTP 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.