FTP - Download
Declaration
<AMFTP SERVER="text" ANONYMOUSLOGIN="yes/no" PORT="number" LOGFILE="text" TIMEOUT="number" MEASURE="text (options)" UPLOADBUFFERSIZE="number" FTPOPTIONS="text (options)" PASSIVEMODE="yes/no" COMPRESSION="yes/no" PROXYTYPE="text (options)" PROXYSERVER="text" PROXYPORT="number" PROXYUSERNAME="text" PROXYPASSWORD="text (encrypted)" SOURCE="text" DEST="text" RESULTDATASET="text" SUBFOLDERS="yes/no" KEEPFOLDERSTRUCT="yes/no" ONLYFOLDERSTRUCT="yes/no" APPEND="yes/no" KEEPDATETIME="yes/no" MATCHCASE="yes/no" VALIDATECHECKSUM="yes/no" CHECKSUMTYPE="text (options)" EXCLUDE="text" ISNEWERTHAN="%DateSerial+TimeSerial" />
Description: Downloads the file(s) specified from the FTP server. This activity supports multi-file downloads. To specify more than one file, use wildcard characters (e.g., * or ?). To specify multiple files or wildcard masks, separate them with a pipe character (e.g., *.txt|*.bak).
Practical Usage
Ideal for automated retrieval of files from an FTP server.
Connection Parameters
Property |
Type |
Required |
Default |
Markup |
Description |
---|---|---|---|---|---|
Connection |
|
|
|
|
Indicates where this activity's FTP logon credentials and other settings should originate from. This is a visual mode parameter used interactively only duringdesign time, thus, contains no markups. The available options are:
|
Session |
Text |
Yes if connection set to session |
FTPSession1 |
SESSION="FTPSession2" |
The name of an existing session that this activity should be linked to. This allows several FTP activities to be linked to a specific session. Numerous sessions can be used within a single task. This property is active only if the Connection parameter is set to Session. |
Host |
Text |
Yes if connection set to host |
(Empty) |
|
The FTP server to connect to. This can be an IP address (e.g., xxx.xxx.xxx.xxx) or a server and domain name (e.g., server.domain.com). This property is active only if the Connection parameter is set to Host. |
Username |
Text |
Yes if connection set to host |
(Empty) |
USERNAME="ClarkKent" |
The username that should be used when logging onto the FTP server. The username should be pre-configured at the server level. This property is active only if the Connection parameter is set to Host. |
Password |
Text |
Yes if connection set to host |
(Empty) |
PASSWORD="encrypted" |
The password that should be used to authenticate connection to the FTP server. This parameter is active only if the Connection parameter is set to Host. |
Use anonymous logon |
Yes/No |
Yes if connection set to host |
No |
ANONYMOUSLOGIN="YES" |
If set to YES, specifies that the FTP connection should be logged on as an "anonymous" user. The server must be configured to accept anonymous connections. If this property is set to YES, the Username and Password parameters are ignored. The default value is NO. This property is active only if the Connection parameter is set to Host. |
Connection type |
Options |
Yes if connection set to host |
FTP (Standard FTP) |
|
Specifies the type of FTP connection that should be used. Some parameters may or may not appear depending on the connection type selected. The available options are:
NOTE: Certain parameters may or may not appear depending on the connection type selected. |
Port |
Text |
Yes |
21 |
PORT="1000" |
The port that should be used to connect to the FTP server. Most standard FTP servers operate on port 21 (the default port specified), however, this parameter can be customized incase the FTP server operates on other ports. NOTE: Other default ports may be assigned depending on the server connection type selected. |
Passive mode (for firewalls) |
Yes/No |
No |
No |
PASSIVEMODE="YES" |
If set to YES, issues the PASV command and the server tells where to establish the data connection. initiates both connections to the server, solving the problem of firewalls filtering the incoming data port connection to the client from the server. If set to NO, the PORT method is used. listens for a data connection which is established by the server and the PORT command tells the server where to connect to. then connects to the server indicated. This property is available only if the Connection type parameter is set to FTP (standard), FTP with SSL (implicit) or FTP with SSL (explicit). NOTE: Passive mode method is sometimes used with some proxy configurations, however, some proxy configurations require PORT transfers and some FTP servers do not support PASV transfers. |
Encrypt data channel |
Yes/No |
No |
No |
ENCRYPTDATACHANNEL="YES" |
If set to YES, specifies that all data channel communication between the FTP client (EFT Event Rules) and server are to be encrypted. The default value is NO. This property is available only if the Connection type parameter is set to FTP with SSL (implicit) or FTP with SSL (explicit). NOTE: It may not be advantageous to use data channel encryption if the files being transferred are of a non-sensitive nature, making encryption unnecessary, or if the files being transferred are already encrypted at the file level, making encryption redundant. |
Ignore invalid server certificates |
Yes/No |
No |
No |
IGNOREINVALIDCERTIFICATE="YES" |
If set to YES, specifies that this activity will ignore invalid certificates when connecting to an FTP server using SSL. The default value is NO. This property is available only if the Connection type parameter is set to FTP with SSL (implicit) or FTP with SSL (explicit). |
Clear command channel |
Yes/No |
No |
No |
CLEARCOMMANDCHANNEL="YES" |
If set to YES, enables support for Clear Command Channel (CCC) functionality. The CCC command can be issued by a remote FTPS client and will cause FTP client to fall out of secure mode and back into unsecure mode. This option is useful for clients who only need to secure the authentication portion of the session. Once the USER/PASS has completed, some clients will use CCC to return to unsecure mode, which is faster. The default value is NO. This property is available only if the Connection type parameter is set to FTP with SSL (implicit) or FTP with SSL (explicit). |
Enable Tumbleweed mode |
Yes/No |
No |
No |
TUMBLEWEEDSERVER="YES" |
If set to YES, allows compatibility with Tumbleweed SecureTransport, a centrally managed client-server solution supporting a broad set of open standard file transfer protocols, including FTP, FTPS, HTTP, HTTPS, SSH (SFTP and SCP), and AS2. SecureTransport enables customers to safely exchange large files and transactions without proprietary software. Set to NO by default. This property is available only if the Connection type parameter is set to FTP with SSL (implicit) or FTP with SSL (explicit). |
Use compression |
Yes/No |
No |
No |
COMPRESSION="YES" |
If set to YES, data is compressed using a single algorithmto reduce the total amount of data that is transmitted. If transmission speeds are slow, transfers can be sped up significantly when using compression, particularly if text files are being transferred. Media files (e.g., JPEG and MPEG) are usually compressed already, thus, there will be little or no benefit in using compression. |
Enable FIPS mode |
Yes/No |
No |
No |
FIPS="YES" |
If set to YES, FIPS 140-2 validated cryptography mode is enabled (set to NO by default). The Federal Information Processing Standard (FIPS) Publication 140-2 specifies the security requirements of cryptographic modules used to protect sensitive information. Most government agencies such as the Department of Defense and companies in the public sector such as healthcare, financial and manufacturing require FIPS validation to protect the integrity of data traffic traveling across their networks. |
FTP option(s) |
Options |
No |
None |
FTPOPTIONS="DoNotSendSignals" |
Indicates any FTP advanced options required during transmission. Click the down arrow to display a list of available options to select from. To specify more than one option, use a comma as a delimiter (e.g., DoNotSendSignals,DoNotSendAbort). The default value is None . This property is available only if the Connection type parameter is set to FTP (standard), FTP with SSL (implicit) or FTP with SSL (explicit). |
SFTP version(s) |
Options |
No |
Sftp2 Sftp3 Sftp4 |
SFTPVERSIONS="Sftp5,Sftp6" |
Indicates the SFTP version(s) that the server supports. Click the down arrow to display a list of available versions to select from. To specify more than one version, use a comma as a delimiter (e.g., Sftp4,Sftp5,Sftp6). This property is available only if the Connection type parameter is set to SFTP (password) or SFTP (key). |
Authentication type |
Options |
No |
Auto |
SFTPAUTHTYPE="Password" |
Indicates the SFTP authentication type that the server supports. Click the down arrow to display a list of available authentication types to select from. To specify more than one type, use a comma as a delimiter (e.g., Password,Hostbased). This property is available only if the Connection type parameter is set to SFTP (password) or SFTP (key). |
Ignore/Validate SFTP server's host key |
Options |
No |
None |
SFTPHOSTKEY="validate" |
Indicates whether to ignore or validate the SFTP server's host key. This property is available only if the Connection type parameter is set to SFTP (password) or SFTP (key). |
If server host key is not found |
Options |
No |
Store it |
SFTPHOSTKEYNOTFOUND="throw_error" |
Indicates what action to perform if the server host key is not found. This property is available only if the Validate SFTP server's host key parameter is selected. The available options are:
|
Client certificate source |
Options |
No |
No Certificate |
|
FTP over SSL allows transmissions to be encrypted between an FTP client and server. This property is used to select the source of the certificate. A certificate is a digitally-signed statement that binds the value of a public key to the identity of the person, device, or service that holds the corresponding private key. One of the main benefits of certificates is that hosts no longer have to maintain a set of passwords for individual subjects who need to be authenticated as a prerequisite to access. Instead, the host merely establishes trust in a certificate issuer. This property is available only if the Connection type parameter is set to FTP with SSL (implicit) or FTP with SSL (explicit). The available options are:
|
Certificate issuer |
Text |
No |
(Empty) |
CERTIFICATEISSUERID="Name" |
The certification authority that issued the certificate. Click Select Certificate to show a list of available certificates to select from. This property is available only if the Client Certificate Source parameter is set to Certificate store. |
Certificate serial number |
Number |
No |
(Empty) |
CERTIFICATESERIAL= "c7 f5 fa f8 6d ab 77 87 43 4a 11 43 f1 cd 3c 0f" |
The unique serial number that the issuing certification authority assigns to the certificate. The serial number is unique for all certificates issued by a given certification authority. This property is available only if the Client Certificate Source parameter is set to Certificate store. |
Certificate file |
Text |
No |
(Empty) |
CERTIFICATE= "C:\Temp\Certificate.pfx" |
The path and filename of the certificate (.pfx or .p12) file. Click the folder icon and navigate to the desired certificate file. This property is available only if the Client Certificate Source parameter is set to File(s). |
Passphrase |
Text |
No |
(Empty) |
PASSPHRASE="encrypted" |
The passphrase used to authenticate connection. A passphrase is a password that comprises a whole phrase. This property is available only if the Client Certificate Source parameter is set to File(s). |
Certificate private key |
Text |
No |
(Empty) |
CERTIFICATEPRIVATEKEY= "C:\Temp\Private_Key" |
Specifies the path and filename of the Private key file. In public/private key encryption, different keys are used to encrypt and decrypt information. The first key is a private key (a key that is known only to its owner), while the second key (called the public key) can be made known and available to other entities on the network. The two keys are different but complementary in function. For example, a user’s public key can be published in a certificate in a directory so that it is accessible to other people in the organization. The sender of a message can retrieve the user’s certificate from Active Directory, obtain the public key from the certificate, and then encrypt the message by using the recipient's public key. Information that is encrypted with the public key can be decrypted only by using the corresponding private key of the set, which remains with its owner, the recipient of the message. This property is available only if the Client Certificate Source parameter is set to File(s). |
Log file |
Text |
No |
(Empty) |
LOGFILE="c:\temp\error.log" |
The location of a detailed FTP log (.log) file. This file contains comprehensive data regarding the FTP connection which can be useful in diagnosing particular errors or elusive problems. If this parameter is left blank, no log file will be created. |
Overwrite existing log file |
Yes/No |
No |
Yes |
OVERWRITELOG="NO" |
If set to YES, specifies that the log file should be overwritten with new data during each FTP logon attempt. If set to NO, existing data will remain intact and new data will append existing data during each logon attempt. The default value is YES. |
Timeout |
Number |
Yes |
30 Seconds |
TIMEOUT="60" |
Indicates a connection time out to customize how long will wait before aborting a connection attempt. If connection is not established within the time out value specified, it is automatically terminated and the event will be appropriately logged. The default value is 30 seconds. |
Measure |
Options |
Yes |
Seconds |
|
The time measurement to associate with the value entered under the Timeout parameter. The available options are:
|
Upload buffer size (bytes) |
Number |
Yes |
65536 Bytes |
UPLOADBUFFERSIZE="54443" |
The upload buffer size value (in bytes) for files being uploaded. In some cases changing the upload buffer size can make a difference; particularly in transfers over high loss or high speed connections where latency plays an important role. The default value is 65536 bytes, which is the maximum buffer size. NOTE: Setting the Upload buffer size value too high for slow connections might cause timeouts and the transfer speed calculation may become inaccurate. |
Proxy Type |
Options |
No |
None |
|
The proxy protocol that should be used. If you are unsure of the value to use in this parameter, contact your network administrator. The available options are:
|
Proxy server |
Text |
No |
(Empty) |
PROXYSERVER="proxy.host.com" |
The host name (e.g., server.domain.com) or IP address (e.g., xxx.xxx.xxx.xxx) of the proxy server. |
Use authentication |
|
|
|
|
If enabled, specifies that connection to the proxy server requires authentication (disabled by default). This is a visual mode parameter used interactively only duringdesign time, thus, contains no markups. |
Proxy port |
Text |
Yes |
21 |
PORT="1000" |
The port that should be used to connect to the proxy server. Most standard FTP servers operate on port 21 (the default port specified) however, this parameter can be customized in case the FTP server operates on other ports. NOTE: Other default ports may be assigned depending on the server connection type selected. |
Proxy username |
Text |
No |
(Empty) |
ROXYUSERNAME="username" |
The username that should be used to authenticate when connecting through the proxy server. |
Proxy password |
text |
No |
(Empty) |
PROXYPASSWORD="encrypted" |
The password that should be used to authenticate when connecting through the proxy server. |
File Parameters
Property |
Type |
Required |
Default |
Markup |
Description |
---|---|---|---|---|---|
Remote file(s) |
Text |
Yes |
(Empty) |
|
The file(s) to download. This can be a fully qualified UNIX style path and filename (preferred) or a single file (requires use of the FTP - Change folder activity). Wildcard characters (e.g., * or ?) may be used to download files matching a certain mask. Multiple files and/or file masks may be specified by separating the entries with the pipe symbol (e.g., *.txt|*.bak|*.log). |
Local file(s) |
Text |
Yes |
(Empty) |
|
The destination folder and (optionally) filename for the file(s) being downloaded. This can be a fully qualified path or a filename. Folders that do not exist will be automatically created at runtime. |
Create and populate dataset |
Text |
No |
(Empty) |
RESULTDATASET="theDataset" |
Specifies the name of a dataset to be populated with information regarding the files to download. Refer to Datasets below for more details about the dataset that this activity creates. |
File Parameters
Property |
Type |
Required |
Default |
Markup |
Description |
---|---|---|---|---|---|
Include subfolders |
Yes/No |
No |
No |
SUBFOLDERS="YES" |
If set to YES, specifies that, if present, sub-folders should be searched for files matching the mask specified in the Remote file(s) parameter. The default value is NO. |
Preserve folder structure |
Yes/No |
No |
No |
KEEPFOLDERSTRUCT="YES" |
If set to YES, specifies that sub-folders found in the source folder should be created in the destination folder and source files should be copied into their respective folders rather than directly into the root of the target folder specified in the Local file(s) parameter. The default value is NO. This option is available only if the Include subfolders parameter is set to YES. |
Only folder structure |
Yes/No |
No |
No |
ONLYFOLDERSTRUCT="YES" |
If set to YES, indicates that sub-folders found in the source folder should be created in the destination folder but no files will be copied. Enabling this option causes any file-specific parameters to be ignored. The default value is NO. This parameter is available only if the Include subfolders parameter is set to YES. |
Overwrite if exists |
Yes/No |
No |
No |
OVERWRITE="YES" |
If set to YES, specifies that, if files already exist in the destination, they should be overwritten. The default value is NO. |
Only if exists in destination |
Yes/No |
No |
No |
ONLYIFEXIST="YES" |
If set to YES, indicates that only files that already exist in the destination will be copied from the source. All other files, regardless of whether they match the mask or other parameter settings will be bypassed. The default value is NO. This parameter is only available if the Overwrite if exists parameter is set to YES. |
Resume download |
Yes/No |
No |
No |
RESUME="YES" |
If set to YES, specifies that downloads will resume on files that are partially downloaded (if the server supports resuming transfers). The default value is NO. |
Match case |
Yes/No |
No |
No |
MATCHCASE="YES" |
If set to YES, indicates that the properties set within this activity should be case sensitive in relation to the FTP server. The default value is NO. |
Transfer type |
Options |
Yes |
Binary |
|
Specifies what mode the transfer type should be set to. The available options are:
|
Validate checksum |
Yes/No |
No |
No |
VALIDATECHECKSUM="YES" |
If set to YES, Indicates that the integrity of data being transferred will be validated by calculating a checksum using the selected algorithm. The default value is NO. |
Checksum type |
Options |
No |
CRC |
|
Specifies the checksum algorithm to use. This parameter is available only if the Validate checksum parameter is set to YES. The available options are:
|
Exclude mask |
Text |
No |
(Empty) |
EXCLUDE="*.txt" |
Causes this activity to omit any files matching the mask(s) specified. Filenames or wildcard masks (e.g., * or ?) may be used. Multiple entries may be specified by separating them with the pipe ("|") symbol (e.g., *.txt|*.bak). |
Regular expression |
Yes/No |
No |
No |
RE="YES" |
If set to YES, specifies that the value entered in the Exclude Mask parameter is a regular expression, also referred to as regex or regexp, which provides a concise and flexible means for matching strings of text. The default value is NO. |
File Attributes Parameters
Property |
Type |
Required |
Default |
Markup |
Description |
---|---|---|---|---|---|
Attributes |
Text Options |
No |
(Empty) |
ATTRFILTER="+R+A-H" (compress read-only & archive files but not hidden files) |
This group of settings causes the activity to filter which files are transferred based on their attributes. In visual mode, a group of controls are provided to assist in the selection. In markup mode, a single text item is specified that contains the attributes of the files you wish to transfer. Available Options are:
|
Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.
Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)
On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)
Datasets
Using the Create and populate dataset parameter creates a fixed field dataset. A dataset is a multiple column, multiple row container object. The table below describes the set of columns that a dataset creates exclusive to this activity (assuming the dataset name assigned was theDataset).
Name |
Type |
Return Value |
---|---|---|
theDataset.DownloadResult |
Boolean |
The result of the download. If successful, 1 is returned. Otherwise, 0 is returned. |
theDataset.FTPFileDate |
Date |
The modified date/time of the transferred file. |
theDataset.FTPFileName |
Text |
The name of the transferred file. |
theDataset.FTPFileSize |
Number |
The size of the transferred file (in kb). |
Examples
The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.
Sample Task 1: This task will log onto an FTP site, download a single file and log off. Note that this example uses a file that is assumed to already exist. In order for this task to work in your environment, please make the appropriate modifications in the properties of each activity.
<AMFTP ACTIVITY="logon" SERVER="YourFTPHost" USERNAME="YourUsername" PASSWORD="AM1MoyAfpKHilpraHBIX6ei1E/2ZhM5egRHalje6g6YThM=aME" /> <AMFTP SOURCE="/home/ftp/filename.txt" DEST="C:\Temp\*.*" /> <AMFTP ACTIVITY="logoff" />
Sample Task 2: This task will demonstrate how can download a file via FTP that contains a date string in the name. creates a date variable and passes the variable into an FTP Download action to download a file by date. Note that this example uses a file that is assumed to already exist. In order for this task to work in your environment, please make the appropriate modifications in the properties of each activity.
<AMVARIABLE NAME="dtmdate">%Format(Now, "mmdd")%</AMVARIABLE> <AAMFTP ACTIVITY="logon" SERVER="YourFTPHost" SERNAME="YourUsername" PASSWORD="AM1MoyAfpKHilpraHBIX6ei1E/2ZhM5egRHalje6g6YThM=aME" /><AAMFTP SOURCE="test%dtmdate%" DEST="c:\temp\test%dtmdate%" /> <AAMFTP ACTIVITY="logoff" />