Tutorial - FTP Adapter for Microsoft BizTalk
By Spencer Brown - Technical Support, /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 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
- Adapter Installation
- Adapter Properties - Send Port
- Usage - Send Port
- Adapter Properties - Receive Port
- Usage - Receive Port
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 v2" is now available as the transport type.
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.
After you add a new Send Port and select the "nsoftware.FTP v2" 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 v2 Transport Properties"
where you will specify the details of how and where the FTP adapter should connect. There are five 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.
-
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 this can also be set to the value "ANY" (without quotes). 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
|
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. |
|
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. |
As mentioned above the Other property provides a way for you to tweak the operation of the component depending on your requirements. Two commonly useful settings are:
UseRemoteHostAddressForPassive=true
UseSimpleDirList=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.
UseSimpleDirList can be set to tell the adapter to use the NLST command instead of the LIST command when obtaining the contents of a directory. the NLST command tells the server to return only a list of names, instead of detailed information. This can be helpful if the server returns a non-standard directory entry format (detailed information) that the adapter can't understand.
Please consult the help file's Configuration section for additional supported settings.
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:
- 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 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 using the value "ANY" for the "SSL Accept Server Cert" property,
just for testing. Later I'll change this
to the correct value as documented above. 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.
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 v2" 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 v2", click on
the Configuration button. This will bring up a new window called "nsoftware.FTP v2 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.
- Firewall Properties
These are all the same as in a Send Port.
- FTP Properties
The next group of properties are 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") |
|
Local File |
The path to a local file for download. Usually this will not be set as you'll want a corresponding send port to process the data, instead of saving the file to disk from the receive location.
|
|
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 |
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 |
Limits the number of errors that the adapter can incur before it shuts down and stops processing messages (0 indicates no limit).
|
|
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.
|
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:
- 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 FTP properties, I'll set the "Delete" to "Yes" (because
I 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.
We appreciate your feedback. If you have any questions, comments, or
suggestions about this article please contact our support team at
kb@nsoftware.com.
