FTP BIC Automatic Activity - EnterWorks_Process_Exchange_(EPX) - 11.0

The FTP BIC provides the capability to send or receive files to or from an FTP server.

There are two flavors of this BIC, with the new one including support for SFTP servers. In the current installations, both BICs are provided and by default the old version (with no SFTP support) is active. Some manual installation/configuration steps must be followed in order to make use of the new version.

Settings tab:

1. In the Remote Directory field, type the path of the directory the activity should access on the remote host. For example:

   /private/hr/data/payroll/fy2001

   Note: For Get request, the remote directory is the location of the file or files that will be retrieved. The remote destination directory for the file transfer is used for Put request. An error occurs if the specified remote directory does not exist.

   In cases where a static directory path is not sufficient, use work item hash table keys enclosed in percent signs (%) to specify part or all of the remote directory path. This is not applicable to a activity not set as a starting point.

   For example, if a company's human resources department maintains individual directories for each employee, with the directories named using the format "Lastname_Firstname"; and if the work item hash table contains employee name keys called employee_first and employee_last; then the path typed in the Remote Directory box must be:

   /private/hr/employees/%employee_last%_%employee_first% 

   Note: Work item hash table keys cannot be used with Get requests if the FTP BIC activity is a starting point in the process flow.
2. In the Remote File field, specify the filename for the file(s) to be retrieved. This step is optional for Get action or when the activity is set to send files.

   If a new filename is not specified, the original will be used. The filename entered can contain the following types of name elements:

   • Standard legal filename characters. For example, if you type "holidayparty.doc", the activity will attempt to retrieve or send the file holidayparty.doc.
   • One or more asterisks (*) used as wildcards. For example, if you type "benefits_*", the activity will attempt to retrieve or send all files beginning with the string "benefits_". When a wildcard is used to retrieve files its behavior changes if used as a starting point or as non-starting point. If used as a starting point, a new work item will be started for each file that shows up. If used as a non-starting point, all of the files will be transferred and the results for all transfers will go into the single work item.
   • For non-starting point activities, enclosed one or more work item hash table keys in percent signs (%). For example, if you type "2001_%employeeNo%.xls" and the work item has a hash table key called employeeNo with a value of "210540", the activity will attempt to retrieve or send the file 2001_210540.xls.
   Note: When executing a Put request with an FTP BIC activity, the remote file will be overwritten if it has the same name as the file being sent.
3. In the Local Directory field, type the path of the directory the activity should access on the local host. You can also click the Browse... button and select the desired directory.
   Note: If the activity will perform a Put request, the local directory is the location of the file or files that will be sent. The local destination directory for the file transfer is used for Get request. An error occurs if the specified local directory does not exist.

   When the BIC is used in a clustered environment, make sure that the folders and/or files that will be indicated are existing in and pointing to where the BIC Manager server is installed. For non-starting point activities, work item hash table keys enclosed in percent signs (%) can be used to specify part or all of the local directory name, if necessary.

4. If the FTP BIC activity will be used to send files, type the name of the file to be sent in the Local File box. If instead the activity will retrieve files, then this step is optional and is only necessary if files need to be saved locally under different filenames than they had remotely. If a new filename is not specified, then the original filename is preserved. For a Get request, make sure that local file and the file being retrieved must have different filenames to avoid the local file from being overwritten. The filename entered can contain the following types of name elements:
   • Standard legal filename characters.
   • One or more asterisks (*) used as wildcards. When a wildcard is used to retrieve files its behavior changes if used as a starting point or a non-starting point. If used as a starting point, a new work item will be started for each file that shows up. If used as a non-starting point, all of the files will be transferred and the results for all transfers will go into the single work item.
   • For non-starting point activities, one or more work item hash table keys, enclosed in percent signs (%).
5. From the Transfer Type dropdown list, select the type of the file to be transferred (i.e., ASCII, Binary).
6. In the LIST Gaps field, specify the number of blank gaps. This step is optional for Put request.
   Note: Blank gaps are spaces between groups of characters when viewed in a directory listing on the remote FTP server. The Get operation will fail if the number entered in the LIST Gaps field is incorrect. A bic.log file will contain an error message identifying the file name can be retrieved .
7. The number of gaps can be determined by manually establishing an FTP connection to the FTP server and typing the command: dir <filename> where <filename> is the fully qualified file of interest. Then, count the number of blank areas between characters. For example, if the remote file were a purchase order form called po.doc located in the FTP directory, then the FTP command to be typed is:

   dir ftp/po.doc 

   Supposing that the output of the command appeared as follows:

   -rw-r--r-- 1 vdbeps eps 2490217 Dec 11 10:41 ftp/po.doc 

   For this example, the number of LIST gaps must be set to 8.

   If the directory listing on the remote FTP host contains more or fewer data fields than the example shown above, the number of gaps must be adjusted accordingly. For the example above, if the number in the LIST Gaps box entered was 6, then the file name will appear as "11 10:41 ftp/po.doc" in the error message. This indicates that the LIST Gaps value must be increased by 2, making the correct value 8.

8. In the Result Set field, type a result set name for the FTP BIC activity.

   When a file is successfully transferred, the transfer is logged as a key/value pair in the work item hash table, in the format:

   <Result_Set>_File<n>=<filename> 

   Where, <Result_Set> is the result set name entered in the Result Set box and File <n> identifies the position in the transfer order for the file. <n> is an incrementing number starting with 1. <filename> is the name of the file transferred, as it was saved in the destination file system. (That is, if the original filename has been changed due to a destination filename being specified, then it is the new destination filename that appears as the value.)

   For example, if an FTP BIC activity has a result set name of getPayroll, and the activity successfully transfers two files saved as "fy2001_210540.xls" and "fy2001_212031.xls", then the following key/value pairs are added to the work item hash table:

   getPayroll_File1=fy2001_210540.xls getPayroll_File2=fy2001_212031.xls 

9. By default, the option Generate error if 0 files match the criteria is selected to prompt the user with an error message when no files are found in the remote directory to match the search criteria in the Remote File text box. This scenario happens in a Get FTP action when a wildcard is used to search for a file in an empty directory or when the standard filename entry is non-existent in the remote directory.

   Note: If this option is not selected, no error messages will be generated upon execution.

10. To attach a copy of each transferred file to the work item, select the Attach to work item checkbox.

11. Click the Delete file from server checkbox to delete all retrieved files from the remote FTP server. This step is only applicable to Get requests. Selecting this option when executing a Put request will not delete sent files from the local file system.

12. Click the Include Subdirectories checkbox to send eligible files from multiple directories located beneath the selected local directory. This step is only applicable to Put requests.

    Note: When sending files, the FTP BIC activity will search all directories contained within the directory you entered in the Local Directory box and will send any files that match the filename you entered in the Local File field.

13. Save the data entered and proceed to another tab by clicking Apply. Clicking OK will also save the data entered and exit the FTP BIC editor. To cancel saving the data entered, click Cancel.