DownloadFiles and UploadFiles Tasks
DownloadFiles and UploadFiles Tasks are built to handle the downloading and uploading of one or multiple files via an SFTP connection. The Task takes source information including directory and file name, destination information outlining where to transfer the file and connection information which is used to make the connection to the source system. The Task also has options and info tabs which are optional. We will go through these one by one.
The Tasks are implemented firstly to list files which match the file mask given and then make the actual transfer. The transfer is done by firstly moving the files to the Agent's temporary directory by creating a temporary folder for that file after which the file is transferred to the actual destination directory. The Task will clean up the temporary folder which it created and the temporary file inside it.
Source properties
Tasks can transfer all or just specific files from a specific directory. This is done by specifying the source directory and a file name. You can also use a file mask in the same field to specify the files that needs to be transferred. When using a file mask every file that is recognized by that mask is transferred. You are also able to use regex and macros to specify the file you wish to transfer.
After you've specified the source directory and the file name, you can choose an action that the Task will implement when no files are found. Options for these actions are Error, Info and Ignore. When using the Task in a scheduled Process and you already know that the Task will not transfer files every run it is usually better to use either Info or Nothing. When the Task is supposed to transfer a file or files every run, Error is the correct choice. This way an exception is thrown if the Task does not find any files and support can be notified.
After that you can use the Operation field that determines what the Task will do to the original source file after the transfer is completed. Options for the Operation field are: Delete, Rename, Move and Nothing. These are quite self-explanatory but let's take a closer look at the options nevertheless.
The Delete Operation will delete the file from the source directory after the transfer is done. This makes the Task do a kind of move operation for the file so that there are no duplicate files anywhere else. This Operation is especially useful if the source directory will be used frequently as a base folder for files which are to be transferred even if the files are always named similarly.
Task can also handle file paths given directly. The file paths' attribute is mainly meant to be used with the File Trigger. The correct syntax for the input field is #trigger.data.filePaths. However, you can also create the filePaths array in your Process as well. The filePaths parameter expects a string array which can be created using C# Expression or C# Statement Element.
Destination Properties
Tasks will transfer the file to a given directory. The Destination directory is specified in the Destination tab. You can also specify a file name which the transferred file will be named after transfer. Note that if the Task is transferring multiple files, the file name cannot be static, but macros need to be used in the field, for example %SourceFileName%_%Date%%SourceFileExtension%.
You can assign used encoding for the file name which is used in the local machine. This encoding will not affect the encoding used in the files' content but only the name. In order to change the content's encoding, it is recommended to do that after the DownloadFiles Task's execution. The possible values for the file name encoding can be found in the Task's documentation.
Lastly, you can select an action that the Task will perform when a file already exists in the destination directory with the same name. You can then choose to throw an exception by selecting Error, overwrite the existing file or append the content to the existing file. If you choose to append there will be another option for the content's encoding. Similar to the file name encoding you can choose which encoding is used when the appending is executed.
Options Properties
Options properties gives a list of additional options that you can set for the Task. The first one is Throw error on fail. This one is quite self-explanatory but with this enabled the Task will throw an exception if any errors occur during the execution. By default, this is enabled but, in some cases, this can be disabled to let the Task give a different kind of error message.
You can enable the renaming of the source and destination files before and during transfer. These options will rename the transferred file during the transfer so that they are locked for use by other Processes. The source file will be renamed before the transfer has started and the destination file will be transferred as a renamed file. After the transfer is complete the destination file will be either renamed to the original name or to the name given to the destination properties directory parameter. You can also set the file extensions for those renamed files.
You can enable the Task to be able to create destination directories. This feature is great when you are not sure if the destination directory exists. The preserve last modified option enables the Task to preserve the file's last modified timestamp.
Lastly the operations log will give more information of the transfers. This is especially useful when debugging errors.
Info Properties
The info properties include options for the Task to use in the operations log in addition to an additional work directory. The transfer's name is only used in the operations log to specify what transfer is ongoing. This can be used for example when the operations logs are logged or archived in the Process. Work dir parameter is optional to specify the directory the Task will use where the files will first be moved before transferring them into the destination directory. This can usually be left empty because the Task will use the local machine's temp folder as a work directory.
Process Uri and Task execution ID are used to create a temp folder where the files are first moved during the transfer.
Return Properties
The Tasks return a Result object which includes boolean values for ActionSkipped and Success, string UserResultMessage, SuccessfulTransferCount, FailedTransferCount, list of transferred file names, dictionary of transfer errors, list of transferred file paths and operations log which can be disabled in the Tasks' options tab.
The next article is Introduction to ListFiles Task