Using the File Management Tool

The File Management tool is a General tool which enables a user to carry out a number of automated actions on single or multiple files at task runtime. These actions allow you to move, copy, rename and delete files on your network, it is also possible to securely upload files to and download files from an FTP Server.

How a File Management Step Works

Single or multiple files can be processed by a File Management step during a single task run. The files must exist at a location on your network or FTP Server before they can be actioned. The tool is unable to consume a document that is dynamically generated during a task process, therefore the files must be saved to a location first.

For example, where a task that generates multiple HTML documents and then uploads them to an FTP Server.The files are first saved via a Save File step to give them a physical location before being selected and uploaded by the File Management step.

This process of selecting multiple files will be explained further down within the General Tab section.

Using the File Management Tool

The File Management Icon2 tool is dragged from the task browser under General tools and into the task design area. This will automatically open the tool for configuration. If you wish to use the upload and download features, please ensure that you have first created a global connection to your FTP server.

To learn about how to set up a connection please see the following article: File Management Tool Global Configuration

General Tab

The General tab is where a name and description can be entered for the step. It is also where you select a file(s) from a location on your network so that an action can be applied against it. Alternatively, files can be downloaded from your FTP server which will be covered further down in this section.

A file on your network is selected by specifying the file location in the Path field and the name of the file in the File Name field by using the associated Browse buttons. When specifying the File Name the file extension is also required so that a file can successfully be located at task runtime.

Ticking the box File Name and Path from previous step enables the use of a file name and path of a file being imported by an existing task step, such as an ‘Import XML Document’ or ‘Import Flat File’ step. This will save you from having to locate the file when you can simply specify an existing step that already knows the location.

1

Download file(s) with FTP or HTTP protocols (see figure 2 below) – Ticking this box will change the display menus and will allow you to select your FTP server for files to be downloaded from. This relies on having a connection to your FTP server setup first within the ‘File Management’ tool’s global configuration. The file transfer protocol used at runtime will be the one specified when the global connection was created, it can be any of the FTP, FTPS, SFTP or HTTP protocols.

Connection – Use the drop down menu to select your FTP Server.

Override global server directory setting – Tick this box if you wish to specify an alternative location on your FTP Server for where your files are stored. Leaving the tick box blank will use the directory for your stored files as specified in the tool global connection.

File Name – Provide the name of the file that you wish to download. Alternatively, a ‘wildcard’ character can be used to select multiple files from a location.

7

Selecting multiple files using a wildcard or recordset variable

Multiple files or file types alone can be selected and processed during a single task run. This can be via the use of wildcard characters or dynamic recordset variables when used in the File Name fields. This can be useful, for example, if you wish to move files in bulk to your FTP server or another location on your network.

Wildcard

A wildcard character such as an asterisk (*) is used in the file name in place of other text. Any file names with text that appears before or after the asterisk, depending on where it is placed, will be included for selection.

Example; ” order – *.xml ” where (*) would be an order number. This will select all xml files with the text ” order – ” in the file name for the scenario of having multiple files with order numbers in their file name.

Alternatively, by entering ” *.xml ” will select all files of an xml file type.

Recordset Variables

Recordset columns from a database query can also be used to dynamically produce the filename by dragging them from the task browser and into the File Name field. The file extension will also need to be included. The format will be as follows: [RECORDSETCOLUMN] . [FILEEXTENSION]

This would normally be used within a task that is generating multiple documents for output.

Note: The files must first be saved to a location using the same dynamic recordset variable before they can be selected.

Capture1

Example; A database query recordset is consumed by a Format as Text step which generates multiple CSV files, one file per customer.

The CSV files are saved to a location using a Save File step, the Customer Name recordset column from the database query is used to dynamically name the files.

When the same Customer Name recordset column is used in the File Name field of the File Management tool, it will be able to dynamically select every file that was previously saved for processing over a single task run. These files, for example, can then be uploaded all at once to your FTP server.

Main Tab

The Main tab is used to select an action to be performed on the selected file(s) at task runtime. The actions available are as follows:

In addition, the main tab has the ‘Memory’ feature available for use. This allows for task generated data to be stored at runtime to an internal repository or an external SQL database. For example, you may wish to log the data & time of when a particular file management process was fulfilled.

Move

The Move option enables you to move selected file(s) to a new location on your network.
2

Destination

Path – Use the Browse button to select a destination folder for the file(s) to be moved to. Alternatively, a recordset column or variable that holds data relating to a path on your network can be dragged from the task browser and placed in the field. This allows for the path to be dynamically generated at runtime.

Create destination folder if not found – Tick this box if you wish to create a new folder in the destination where the file is to be moved to. At task runtime the folder will be automatically created for the file to be placed in. If the folder does not exist and this box has not been ticked, the task will fail to execute correctly.

Note: The account used to run the task must have permission to create folders in the directory in order to succeed during runtime.

Overwrite file if it already exists – Tick this box to overwrite an existing file with the same file name.

File Read Only Attribute

Do not Change – This applies to the ‘Read Only’ attribute that can be set on a file.Selecting this option will not make any changes to this attribute when the file is moved.

Set Read Only Attribute – Selecting this option will set ‘Read Only’ ona file when it is moved at task runtime.

Clear Read Only Attribute – Selecting this option will remove ‘Read Only’ from a file when it is moved at task runtime.

Exception

Maximum file size – This allows you to prevent a file from being moved if it exceeds the maximum file size in megabytes specified here. You can enter any desired numeric value in MB.

Copy

The Copy option enables you to copy selected file(s) to another location on your network. Copy shares the same configurable options as Move. The descriptions for each option outlined above apply in a similar manner to Copy.

Rename

The Rename option enables you to rename the selected file(s) on your network.

3

New name

Use input file names as part of output file name – Ticking this box allows the original file name to be kept, alternatively if the tick box is left blank you can enter a new name for the file within the File Name field. “Part of” means you may prefix or suffix additional definition to the original file name.

Prefix file name with – Ticking this box allows you to enter additional text which will appear at the beginning of the file name. For example, if you had a file called Example.txt and you enter the text “123“, the file name will appear as “123Example.txt“. Alternatively, you can click the option Date and Time Stamp which will prefix the file name with the current date and time at the time the task runs. For example, “20150401095332Example.txt“. The format is as follows; [yyyymmddhhmmss][File Name].[Ext]

Suffix file name with – Ticking this box allows you to enter additional text which will appear at the end of the file name. It shares the same configurable options as ‘Prefix’.

File name created – This is the preview pane which displays how the file name will appear. It displays changes in real time so as you configure the above options the file name will actively change. Handy for giving you an idea of what the final result will be!

File Read Only Attribute

Do not Change – This applies to the ‘Read Only’ attribute that can be set on a file. Selecting this option will not make any changes to this attribute at task runtime.

Set Read Only Attribute –Selecting this option will set ‘Read Only’ on a file at task runtime.

Clear Read Only Attribute – Selecting this option will remove ‘Read Only’ from a file at task runtime.

Delete

The Delete option enables you to delete a selected file(s) on your network.

4

Restrictions

Only delete file if last modified time is more than – Ticking this box enables a time period to be set which will restrict the deletion of a file if it has been modified within that time. A drop down list allows you to choose a time period of Years, Months, Weeks, Days, Hours and Minutes. A numeric value is entered to define the length of time. The time period will begin from the time at which the task runs.

For example, a time period of 1 week is set. At task runtime it is checked if the file has been modified between now and 7 days ago. If the file has not been modified during that time it will simply be deleted.

Note: The account used to run the task must have permission to delete files from that directory in order to succeed during runtime.

Upload

The Upload option enables you to upload a selected file(s) from your network to your FTP Server. It uses the connection that you setup in the ‘File Management’ tool’s global configuration and will use the transfer protocol that you specified.

5

Destination

Connection – Use the drop down menu to select the connection to your FTP Server, as first setup in the tool global configuration.

Override global server directory setting – Ticking this box enables you to specify an alternative directory on your FTP server to upload the file to. If the tick box is left blank the file will be uploaded to the directory specified in the global connection.

Create destination folder if not found – If uploading to an alternative destination, tick this box if the folder does not yet exist. At task runtime the folder will be automatically created for the file to be placed in. If the folder does not exist and this box has not been ticked, the task will fail to execute correctly.

Note: The account used to logon to the FTP site must have permission to create folders on the FTP on the sub-folder it’s associated with in order to succeed during runtime.

Overwrite file if it already exists – Tick this box to overwrite an existing file with the same file name.

Delete source file on completion – Tick this box if the original file in the source location is no longer required after it has been uploaded. At task runtime the original file will be deleted leaving a copy on your FTP server.If the box is left blank the source file will be left in it’s original location on your network.

File Read Only Attribute

Do not Change – This applies to the ‘Read Only’ attribute that can be set on a file. Selecting this option will not make any changes to this attribute when the file is uploaded.

Set Read Only Attribute –Selecting this option will set ‘Read Only’ on a file when it is uploaded at task runtime.

Clear Read Only Attribute –Selecting this option will remove ‘Read Only’ from a file when it is uploaded at task runtime.

Exception

Maximum file size – This allows you to prevent a file from being moved if it exceeds the maximum file size in megabytes specified here. You can enter any desired numeric value in MB.

Download

The Download option enables you to download selected file(s) from your FTP server to your network. This option is only available when the tick box Download file(s) with FTP or HTTP protocols is first selected within the General tab.

It uses the connection that you setup in the ‘File Management’ tool’s global configuration and will use the transfer protocol that you specified.

6

Destination

Override global download directory setting – Ticking this box enables you to specify an alternative directory on your network to download the file to. If the tick box is left blank the file will be downloaded to the directory specified in the global connection.

Create destination folder if not found – If downloading to an alternative destination, tick this box if the folder does not yet exist. At task runtime the folder will be automatically created for the file to be placed in. If the folder does not exist and this box has not been ticked, the task will fail to execute correctly.

Note: The account used to run the task must have permission to create folders in the respective directory in order to succeed during runtime.

Overwrite file if it already exists – Tick this box to overwrite an existing file with the same file name.

Delete source file on completion – Tick this box if the original file on your FTP Server is no longer required after it has been downloaded. At task runtime the original file will be deleted leaving a copy on your network.If the box is left blank the source file will be left in it’s original location.

Note: The account used to logon to the FTP site must have permission to delete files on the respective FTP folder(s) in order to succeed during runtime.

Move source file on completion – Tick this box if you wish to move the original file to another location on your FTP Server after it has been downloaded to your network. Use the Directory field to enter in the new location. If the tick box is left blank, the file will remain in it’s original location.

Note: The account used to logon to the FTP site must have permission to move files to the respective FTP folder(s) in order to succeed during runtime.

File Read Only Attribute

Do not Change – This applies to the ‘Read Only’ attribute that can be set on a file. Selecting this option will not make any changes to this attribute when the file is downloaded.

Set Read Only Attribute – Selecting this option will set ‘Read Only’ on a file when it is downloaded at task runtime.

Clear Read Only Attribute – Selecting this option will remove ‘Read Only’ from a file when it is downloaded at task runtime.

Options Tab

The Options tab is used to configure the step behaviour if an error occurs when the step is being processed at task runtime. The options dictate whether the current task should continue or abort in case of a processing failure, i.e. file transfer failure or file not found.

8

To read about tasks which make use of this tool see:

Building a task that uploads a file to an FTP server