FTP Adapter
Overview
The FTP adapter exchanges data between an FTP server and Neuron ESB and allows for the integration of vital data stored on a variety of platforms with line-of-business applications. The FTP adapter can send file to, and receive files from an FTP server. The FTP Adapter operates in both standard FTP and secure FTP (FTPS) mode.
When sending messages with the FTP adapter, the body of the Neuron ESB Message becomes the contents of the file sent to the FTP server. When receiving messages with the FTP adapter, the contents of the file received becomes the body of the Neuron ESB Message. See the property description below for more information.
Requirements
This adapter requires a FTP Server for sending and receiving messages.
Adapter Modes
The adapter supports the following mode of operation.
Mode | Description |
Subscribe | Send a message from Neuron to an FTP Server |
Publish | Receive a message from an FTP Server and publish to Neuron |
Design-Time Properties
Property Name | Description |
General | |
Server Name | The port number of the FTP Server. This is usually 21 |
FTP Connections | The maximum number of concurrent FTP connections to establish. Should not be greater than 25. |
Port | The port number of the FTP Server. This is usually 21. |
Transfer Mode | Method to use when downloading files from FTP Server |
Transfer Type | Indicates how the data is transferred to and from the FTP server. By default, this property is set to Binary. |
Passive FTP | True if the FTP client should initiate the data connection; false otherwise. By default, this property is set to true. |
FTP Operation Timeout | A value, in seconds, representing the period of time after which an FTP operation should timeout. By default, this property is set to 30 seconds. This is NOT the amount of time it takes for a file Transfer. |
Secure Connection | Security options to connect to the FTP Server. These options handle the encryption of the initial connection and handshake established with the FTP Server |
Secure Data Channel | Determines whether or not ALL data transferred between Neuron and the FTP server is encrypted and checksum checked |
Certificate | Select a Certificate configured in the Security section of the Neuron ESB Explorer to secure communication with the FTP Server IF the FTP Server requests a Certificate. |
Anonymous Connection | Connect to the FTP Server using Anonymous logon |
Username | User Id for FTP Server logon. This property is only visible if Anonymous Connection is set to False. |
Password | The password for FTP Server logon. This property is only visible if Anonymous Connection is set to True. |
HTTP Proxy | Connect to the FTP Server using an HTTP Proxy Server |
Address | URL address to HTTP Proxy. This property is only visible if Http Proxy is set to True. |
Port | The port for the HTTP Proxy Server address. This property is only visible if Http Proxy is set to True. |
User Name | User Id for HTTP Proxy Server logon. This property is only visible if Http Proxy is set to True. |
Password | The password for HTTP Proxy Server logon. This property is only visible if Http Proxy is set to True. |
Publish Mode | |
Publish Topic | The Neuron topic that messages will be published to. Required for Publish mode. |
Polling Interval | The Interval between polling executions (seconds). |
Error Reporting | Determines how all errors are reported in Event Log and Neuron Logs. Either as Errors, Warnings or Informational messages. |
Error on Polling | Determines if polling of data source continues on error and if consecutive errors are reported. |
Delete After Download | Deletes the file on the FTP site after it is retrieved. Default is True. |
Enable Timestamp Comparison | If True, compares the last write timestamp of the FTP file to retrieve, with the timestamp of the previously retrieved file of same name. If timestamps are the same, the file is not retrieved. |
FTP Folder | The relative path of the FTP Folder to retrieve files from. Can be a single folder, or a path i.e. ‘RootFolder\SubFolder’. |
File Mask | File spec for retrieving files from the FTP Server. |
File Ready Scheme | Indicates that a method of ensuring that the FTP file(s) to download are ‘ready’ for download is used. |
Method | There are two methods 1.) Exclude downloading files with a specific file extension 2.) look for a ‘completed’ file extension and download its matching file. This property is only available if File Ready Scheme is set to True. |
File Extension | This is the file name extension filter (i.e. ‘.readyfordownload’, ‘.TMP’, ‘.PART’, etc.). This property is only available if File Ready Scheme is set to True. |
Publish Empty Message | Publish empty message if zero byte file is returned from FTP Server. |
Audit Message on Failure | Register failed message and exception with Neuron Audit database. Database must be enabled. |
Subscribe Mode | |
FTP Folder | The relative path of the FTP Folder to send files to. Can be a single folder, or a path i.e. ‘RootFolder\SubFolder’. |
Generate Unique Filename | Automatically generates a unique file name on the FTP Server for the uploaded file. |
PreAllocateStorage | True if FTP server must reserve space before a file is sent. |
Audit Mesage On Failure | Register failed message and exception with Neuron Audit database. Database must be enabled. Only applies if FTP Connections are greater than 1. This will supersede the adapter policy. |
Run-Time Properties
Outbound Properties (Subscribe Mode)
When the Neuron adapter endpoint is configured for subscribe mode and has the include metadata option set, then the adapter will use the following properties in the ESBMessage received from Neuron instead of the properties set in the adapter endpoint UI. The adapter metadata must be specified in the custom properties of the message header.
The names of the properties are case sensitive.
All of the adapter metadata properties are optional even when the include metadata option is set. For more details about each of these properties, reference them from the table above.
Property Name | Description |
General Properties | |
ftp.Filename | Name of file received from, or sent to FTP Server |
To set these properties at run-time, create a new Process, include a Code step, and use code similar to this:
context.Data.SetProperty("ftp", "Filename", "myData.xml");
Inbound Properties (Publish Mode)
When the Neuron adapter endpoint is configured for publish mode and has the include metadata option set, then the adapter will set the following properties in the ESBMessage published to Neuron as custom properties.
The names of the properties are case sensitive.
For more details about each of these properties, reference them from the table above.
Property Name | Description |
General Properties | |
ftp.Server | Name of FTP Server data is sent to or retreived from |
ftp.Port | FTP Server port |
ftp.Address | FTP Server address |
ftp.Username | User name for FTP Server |
ftp.Folder | Name of Ftp folder which file was retrieved |
ftp.Filename | Name of file received from, or sent to FTP Server |
ftp.Length | Lengeth of the file in bytes |
To access these properties at run-time, create a new Process, include a Code step, and use code similar to this:
context.Data.GetProperty("ftp", "Filename");
Subscribe Mode
The FTP adapter endpoint receives a message from the ESB and sends it to an FTP Server, as directed by the properties defined above. When no runtime message properties are provided, the adapter will use all of the properties set at design time using the adapter endpoint UI. Any runtime properties that are set would be used instead of the values provided at design time. For example, it’s common to set the “Filename” property at design time, because you may want control over the name of the file written to the FTP Server.
PreAllocateStorage
This directs the FTP adapter endpoint to reserve enough space on the target FTP Server before the file is sent. If this property is set to true, then you have the option to Audit Message on Failure if the target FTP Server doesn’t have enough space to allocate.
Publish Mode
The FTP adapter endpoint receives a message from an FTP Server and publishes it to the ESB. If the Include Metadata option is set, when the FTP adapter endpoint receives the message it will create the custom properties defined above and add them to the ESBMessage.
Delete After Download
When receiving files from an FTP Server, you have the option to either delete files from the FTP server after they are downloaded or to leave them on the server. This is done using the Delete After Download property. If set to true, the files will be deleted. If set to false, the files will be left on the server. To avoid re-downloading the same file again, you can set the next property, Enable Timestamp Comparison, to true, which will compare the last write timestamp of the file the adapter is about to download with the last write timestamp of the file of the same name previously downloaded. If the timestamps are the same, then the file will not be downloaded. If they are different, the adapter endpoint will download it.
File Ready Scheme
Depending on the polling interval and the size of the files to be downloaded, you may want to use this feature to make sure files are ready for download before actually downloaded them. If you set the File Ready Scheme property to true, then Neuron can use one of two methods to download “ready” files. The first method is ExcludeFileExtension. This will direct the FTP adapter endpoint to ignore files with a specific file extension (i.e. “filename.partial”). If using this method, set the File Extension property equal to the extension to ignore, included the leading period ‘.’ The other method is CompletedFileExtension. This will direct the FTP adapter endpoint to only download files that have a matching file with the extension listed in the File Extension property. For example, if the File Extension property is equal to ‘.completed’, when the FTP adapter endpoint encounters a file on the FTP Server with this extension it will look for and download the file with the same name as the file with the .completed extension and download it.
Publish Empty Message
Sometimes a message with zero bytes is downloaded from the FTP Server. You have the option to suppress publishing these messages to the ESB by setting the Publish Empty Message property to false. If you set it to true, these messages will still be published.