FTP - Synchronize folder(s)

Declaration

<AMFTP ACTIVITY="synchronize_folder" REMOTEFOLDER="text" LOCALFOLDER="text" RESULTDATASET="text" SYNCHRONIZATION="remote_to_local" SYNCOVERWRITE="text (options)" SUBFOLDERS="YES/NO" MATCHCASE="YES/NO" CHECKSUM="YES/NO" VALIDATECHECKSUM="YES/NO" EXCLUDE="text" RE="YES/NO" INCLUDE="text" SESSION="text" />

Related Topics

Description

Synchronizes folders located on the FTP server with folders located on the local machine. Folders can be synchronized either uni-directionally (one-way) or bi-directionally (both ways). Other options include the ability to ignore or overwrite existing files, include/exclude masks, and checksum validation.

NOTE: An FTP session is required to run this activity. Use the FTP Logon activity to create a session.

Practical Usage

Usually used to replicate folders between an FTP server and a local machine or to backup specific folders.

Parameters

Connection

Property Type Required Default Markup Description
Session Text Yes FTPSession1 SESSION="SessionName" Specifies the session name (created by a previous FTP - Logon step) that this activity should originate from. This permits several FTP activities to be linked to a specific session, thus, allowing multiple simultaneous FTP transfers to take place within a single task.  

Folder

Property Type Required Default Markup Description
Remote folder

 

 Text

 

 Yes

 

 (Empty)

 

 REMOTEFOLDER="/Home/FTP_folder Specifies the FTP server folder that should be synchronized. Enter a fully qualified UNIX style path manually in the provided text box or click the folder icon to open the FTP Browser which allows connection to the server in order to browse available files and folders

If synchronization is set to Remote --> Local (Unidirectional) then files from the FTP server that do not exist locally will be transferred to the folder specified in the Local Folder parameter.

If synchronization is set to Local --> Remote (Unidirectional) then local files that do not exist in the FTP server will be transferred to the folder specified in the Remote Folder parameter.

If synchronization is set to Remote <-->Local (Bidirectional) then files from the FTP server that do not exist locally will be transferred to the folder specified in the Local Folder parameter and local files that do not exist in the FTP server will be transferred to the folder specified in the Remote Folder parameter.
Local folder Text Yes (Empty) LOCALFOLDER="c:\foldername\"  Specifies the destination folder that resides locally.
Create and populate dataset Text No (Empty) RESULTDATASET="theDataset" The name of a dataset to be populated with information regarding the folder/files to be synchronized. Refer to the Notes section below for more details about created datasets.
Synchronization Options Yes Bidirectional SYNCHRONIZATION="remote_to_local" Specifies the method by which the files should be synchronized. The available options are:
  • Remote <--> Local (Bidirectional) - The files will be synchronized both ways, from the remote folder to the local folder and from the local folder to the remote folder. files from the FTP server that do not exist locally will be transferred to the folder specified in the Local Folder parameter and local files that do not exist in the FTP server will be transferred to the folder specified in the Remote Folder parameter.
  • Remote --> Local (Unidirectional) - The files will be synchronized one way, from remote folder to the local folder. Files from the FTP server that do not exist locally will be transferred to the folder specified in the Local Folder parameter.
  • Local --> Remote (Unidirectional) - The files will be synchronized one way, from local folder to the remote folder. Local files that do not exist in the FTP server will be transferred to the folder specified in the Remote Folder parameter.
Exact copy in remote/local folder Yes/No No No EXACTCOPY="YES" When selected, an exact copy of files in the source folder will be created in the destination folder. Files and folders that exist in the destination folder but do not exist in the source folder are removed. If a newer version of a file or folder exists in the source, it will be copied to the destination. The default value is NO.

This parameter is available only if Remote --> Local (Unidirectional) or Local --> Remote (Unidirectional) is selected by way of the Synchronization parameter.
If file exists at both locations  Options  No  Newer Overwrites Older SYNCHOVERWRITE="ignore"

 

 Specifies what should be done if a file with the same name exists in both source and destination folders. The available options are:
  • Newer Overwrites Older (Default) - The file with the newer modified date will overwrite the matching file with an older modified date.
  • Ignore - The file with the same name that exists in the source folder will be ignored. No actions will be performed in regards to this file whether it is newer or older than its counterpart.
  • Overwrite - The file with the same name that exists in the source folder will overwrite its counterpart that resides in the destination folder, whether it is newer or older.
FTP Server Timezone Options No (GMT) Coordinated Universal Time [UTC] FTPSERVERTIMEZONE="Fiji [Fiji Standard Time]" Indicates the timezone to set for the FTP server. This is useful if file date/time specifications are set for this activity and the FTP server is in a different timezone than that of the local machine. This property converts the local time into the server timezone selected.   

File Options

Property Type Required Default Markup Description
Include Mask Text No *.* INCLUDE="*.jpg" Specifies a wildcard mask (for example, *.txt?) representing the files that should be synchronized. The default value is *.* which specifies all files.
Regular Expression Yes/No No No RE="YES" If selected, specifies that the value entered in the Include 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. If disabled (default) the value is plain, readable text.
Exclude Mask Text No (Empty) EXCLUDE="*.txt" Causes this activity to omit any files matching the masks specified. Filenames or wildcard (for example, * or ?) masks may be used, multiple entries may be specified by separating them with a pipe character (|) (for example, *.txt|*.bak).
Regular Expression Yes/No No No RE="YES" If selected, 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. If disabled (default) the value is plain, readable text.
Transfer type Options Yes Binary TRANSFERTYPE="ascii" Specifies whether the transfer type should be set to binary or ASCII mode. The default is binary.

Binary mode refers to transferring files as a binary stream of data. Where ASCII mode may use special control characters to format data, binary mode transmits the raw bytes of the file being transferred. In this way, the file is transferred in its exact original form.

When files are transferred in ASCII mode, the transferred data is considered to contain only ASCII formatted text. The party that is receiving the transferred data is responsible for translating the format of the received text to one that is compatible with their operating system.
Validate checksum Yes/No No No VALIDATECHECKSUM="YES" Indicates whether to validate the integrity of data being transferred by calculating a checksum using the selected algorithm. The default value is NO.
Checksum type Options No CRC CHECKSUMTYPE="sha1" Specifies the checksum algorithm to use. The available options are:
  • CRC (default) - Stands for "cyclic redundancy check", so called because the check (data verification) value is a redundancy and the algorithm is based on cyclic codes.  
  • MD5 - A message-digest algorithm that's a widely used cryptographic hash function producing a 128-bit hash value, typically expressed in text format as a 32 digit hexadecimal number.
  • SHA1 - Stands for "secure hash algorithm" and produces a 160-bit hash value. A SHA-1 hash value is typically rendered as a hexadecimal number, 40 digits long.

This parameter is valid only if the Validate Checksum parameter is selected.
Include Subfolders Yes/No No No SUBFOLDERS="YES" If selected, indicates that, if present, subfolders will be searched for files matching the mask specified in the Remote Files parameter. The default value is NO.
Match Case Yes/No No No MATCHCASE="YES" Indicates whether the properties set within this activity should be case sensitive in relation to the FTP server. The default value is NO.

Description

Error Causes

On Error

Notes

Datasets

The table below describes the set of columns that a dataset creates exclusive to this activity (assuming the dataset name assigned was theDataset).

Name Data 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 and time of the file to download.
theDataset.FTPFileName Text The name of the file to download.
theDataset.FTPFileSize Number The size of the file to download (in kb).
theDataset.LocalFileName Text The local file name of the file.

Example

NOTE:
  • The sample AML code below can be copied and pasted directly into the Steps Panel of the Task Builder.
  • Parameters containing user credentials, files, file paths, and/or other information specific to the task must be customized before the sample code can run successfully.

Description

This sample task logs onto an FTP site, synchronizes a remote folder with a local folder and then logs off.

Copy 
<AMFTP ACTIVITY="logon" SESSION="YourFTPSession" SERVER="YourFTPHost" USERNAME="YourUsername" PASSWORD="AM2Ykm5dOYX3LA=aME" />
<AMFTP ACTIVITY="synchronize_folder" REMOTEFOLDER="/home/myFolders/FTPFolder1" LOCALFOLDER="C:\myFolders\Folder1" RESULTDATASET="theDataset" FTPSERVERTIMEZONE="(UTC-11:00) Coordinated Universal Time-11 [UTC-11]" SUBFOLDERS="YES" SESSION="YourFTPSession" />
<AMFTP ACTIVITY="logoff" SESSION="YourFTPSession" />