FTP Get File activity

During run time, the FTP Get File activity connects to an FTP Server and attempts to get a single file at the specified location. You can configure the FTP Get File activity to return the contents of the file into a variable of the orchestration.  In addition, you can configure the FTP Get File activity to return the timestamp of the file returned by the FTP Server into a variable of the orchestration.

The FTP Get File activity differs from the FTP Poll Directory activity in the following ways:
  • The FTP Get File activity does not poll for a file or files in the specified directory. Instead the FTP Get File activity checks for the file a single time and if the file is not found, it throws an error and the orchestration job continues to processing.
  • The FTP Get File activity is not a starter activity, so it cannot be the first activity in an orchestration.
  • The FTP Get File activity does not move or delete files on the FTP server.

Symbolic link

The support for symbolic links by the FTP Get File activity during run time is dependant on the following factors:  
  • The types of symbolic links supported by operating system that hosts the FTP Server.
  • The types of symbolic links supported by the FTP Server itself.
  • The types of symbolic links supported by the FTP Get File activity, as listed in the following table:
    Table 1.
    Symbolic Links to... Hard Symbolic Links Soft Symbolic Links Notes®
    Files Not Supported Not Supported The FTP Get File activity does not interpret symbolic links to files as files and therefore symbolic links to files are not processed by the FTP Get File activity during run time.
    Directories Supported Supported  
To determine the specific symbolic link support for a specific FTP Server on a specific operating system, see your operating system and FTP Server documentation.

Adding an FTP Get File activity in the orchestration

  1. Create or open an orchestration. A graphical representation of the orchestration is displayed.
  2. Select the Activities tab and expand the FTP folder.
  3. Drag the Get File activity onto the orchestration.
  4. Select the activity. The Checklist is displayed.

Creating, selecting, or editing an FTP endpoint

  1. Click Pick Endpoint task from the Checklist and choose from one of the following actions:
    • Select an existing endpoint:
      1. Select Browse. The Project Explorer is displayed.
        Attention: Specifying a new FTP Endpoint with a different directory structure than the original FTP Endpoint can cause the orchestration job to fail during run time. You must either specify a new FTP Server that matches the directory structure of the originally specified FTP Server or change the configured directory of the In Directory field by clicking Browse as described in the Configuring the activity procedure.
      2. Select an existing endpoint and click OK. Skip to the "Configure the activity" procedure.
    • Select an existing endpoint and edit the endpoint:
      1. Select Browse. The Project Explorer is displayed.
      2. Select an existing endpoint and click OK.
        Attention: Specifying a new FTP Endpoint with a different directory structure than the original FTP Endpoint can cause the orchestration job to fail during run time. You must either specify a new FTP Server that matches the directory structure of the originally specified FTP Server or change the configured directory of the In Directory field by clicking Browse as described in the "Configure the activity" procedure.
      3. Click Edit. The Edit Endpoint pane is displayed.
    • Create a new endpoint: Select New. The Create Endpoint pane is displayed.
  2. Create or edit an FTP endpoint: Creating or Editing an FTP endpoint

Specifying the delivery rules

  1. Select the Delivery Rules task from the Checklist. The Delivery Rules pane is displayed. If security is not enabled for the FTP endpoint, the Transfer as Text (ASCII) and Transfer as Binary (BINARY) options are enabled. If security is enabled for the FTP endpoint, the file transfer type is always binary.
  2. Select the type of file transfer between the Integration Appliance and the FTP Server from one of the following options:
    • Transfer as Text (ASCII) - Only seven bits of each character in the file is transferred by the Integration Appliance to the FTP Server. This option is used for transferring ASCII files such as HTML and text files.
      CAUTION:
      Using this option with binary files can result in a loss of data.
    • Transfer as Binary (BINARY) - All eight bits of each byte in the file is transferred by the Integration Appliance to the FTP Server. This option is used for transferring binary files.
    Note: Setting the transfer mode in the Delivery Rules task is equivalent to setting the transfer mode via a command line session with an FTP Server using the following commands:
    • ascii
    • binary
Note: App Connect FTP connector SFTP endpoint supports only client side SFTP protocol version 3. Hence, the SFTP protocol does not support ASCII/text mode file transfer. Make sure to set the File Transfer Type to Transfer as Binary (BINARY) in the Checklist > Delivery Rules.

Configuring the activity

  1. Select the Configure task from the Checklist. The Configure pane is displayed.
  2. Configure all the fields in this pane as described in the following table:
    Table 2.
    Field Description
    File Named This field is not used for this activity. You specify the name of the output file using the filename input parameter of the Map Input task.
    From Directory Specifies the directory on the FTP server where the Integration Appliance places the file generated in this activity. You can specify a directory using one of the following options:
    • Directly enter directory path by clicking in the field and typing in one of the following directory paths:
      • Relative directory path, for example: /output.  (Assumes that FTP home has been configured for the user account that connects to the FTP Server. See "Note" for more information.)
      • Complete directory path, for example on a UNIX machine: /home/user/output.
    • Click Browse... to populate the drown-down list of available directories. Select the appropriate directory from the drop-down list.
    Note: UNIX: If you specify a relative directory path when connecting to an FTP Server on a UNIX machine, verify that the FTP home directory has been correctly specified in the /etc/password file for the user account connecting to the FTP Server.
    Of Type Specifies how to read in the contents of the file - either as binary data or encoded text. If the Text option is selected, set the encoding type using one of the following options:
    • From the encoded with drop-down list, select one of the default encoding types.  
    • Enter your encoding type directly by clicking in the encoded with field and typing in your encoding type.
     
    Attention: You must specify the Transfer as Text (ASCII) option for FTP activities when retrieving text files and placing text files on an FTP Server for Endpoints that manipulate text data while transferring data from/to the FTP Endpoint in ASCII mode. For example, mainframe and DOS FTP Endpoints manipulate ASCII data when passing data in ASCII mode.
    For example, if your orchestration retrieves ASCII files using the FTP Poll Directory activity and places ASCII files using the FTP Put File activity to a mainframe FTP Server, you must specify the options in the following tasks in Studio:
    • In the Configure task of an FTP Poll Directory activity, for the Of Type field select the Text option.
    • In the Delivery Rules task of an FTP Poll Directory activity, for the File Transfer Type field select the Transfer as Text (ASCII) option.
    • In the Configure task of an FTP Put File activity, for the Of Type field select the Text option.
    • In the Delivery Rules task of an FTP Put File activity, for the File Transfer Type field select the Transfer as Text (ASCII) option.

Specifying the retry options

  1. Select the Retry task from the Checklist. The Retry pane is displayed.
  2. Configure the retry options for connecting to an FTP Server. The following table defines the retry options for a connection to an FTP Server:
    Table 3.
    Field Description
    Retry  
    1) Wait ___ second(s) between each retry. The number of seconds that the Integration Appliance waits before trying to establish a connection to the FTP Server.
    2) Try to connect ___ times before failing. Specifies the retry count - the maximum number of times the Integration Appliance attempts to establish a connection to the FTP Server before issuing an error and stopping the processing of the current orchestration job.

    If you deploy an orchestration that contains an FTP Get File activity and the Integration Appliance cannot connect to the specified FTP Server, the Integration Appliance logs the connections errors as warnings in the system and orchestration logs until the retry count value is reached. When the retry count is reached, the Integration Appliance logs an error in the system and orchestration logs and the stops processing the current orchestration job.

    For example, you set the retry count to 3. The first, second, and third connection errors appear in the system log as warnings. The Integration Appliance logs the fourth connection error as an error and stops processing the current orchestration job.

Mapping the input into the activity

  1. Select the Map Inputs task in the Checklist. The input parameters of the activity are displayed in the To Activity pane.
  2. The filename parameter is the only parameter you are required to provide an value in the activity. All other parameters are optional. The filename parameter specifies the name of the file to get from the FTP Server. You provide a value for the filename parameter by either by creating a link from the filename input parameter to a variable or by defining a default value for the filename input parameter.

    If the optional input parameter listed in the following table are not displayed in the To Activity pane of the Map Inputs pane, select Map > Show Optional Parameters from the toolbar menu or right-click in the To Activity pane and select the Show Optional Parameters option. If the Map > Show Optional Parameters option is not selectable in the toolbar menu, click on a node in the Map Inputs pane to make this option active.

    You can optionally override the settings you specified in the Configure and Pick Endpoint task of the Checklist dynamically during run time, using the input parameters defined in the following table.

    For example, the directory on the FTP Server where the Integration Appliance gets the file, could be set in the Configure task to the directory called input. During run time, the directory name: inputXML could be passed into the activity using the directory input parameter. The directory name specified dynamically during run time overrides the original setting specified in the Configure pane. In this example, the Integration Appliance attempts to get the file from the inputXML directory.

Table 4.
Input Parameter Name/Node Description Overrides the Setting in Task?
directory Specifies the directory on the FTP server where the Integration Appliance places the file generated in this activity. The directory input parameter overrides the From Directory field of the Configure task.
encoding Specifies how the outgoing data is written out to the file:
  • If no encoding is required, specify the string: binary .
  • If encoding is required, specify the encoding type that should be used to encode the outgoing data, for example: UTF-8, US-ASCII, ISO_8859-1, EBCDIC-US, or SHIFT-JIS.
The encoding input parameter overrides the encoding specified in  the Of Type field of the Configure task but if the Binary option is selected in the Of Type field of the Configure task, the encoding specified by the encoding input parameter is ignored.
connection/timeout Specifies the connection timeout — the number of seconds before a timeout occurs between the Integration Appliance attempting to establish a connection to the endpoint and the time it takes for the endpoint to respond to the connection request. For the FTP Get File activity, the amount of time the Integration Appliance attempts to establish a connection to the FTP Server before timing out.   The timeout node of the connection input parameter overrides the Connection Timeout -Time out after ___ second(s) when establishing a connection to the Endpoint field of the FTP endpoint.  
connection/host Specifies the Host Name or IP address for the FTP server. The host node of the connection input parameter overrides the Host Name field of the FTP endpoint.
connection/port Specifies the port number for the specified host name. The standard port for FTP traffic is 21. The default port for SFTP traffic is 22. The port node of the connection input parameter overrides the Port field of the FTP endpoint.
connection/username Specify a user name for the account used to connect to the FTP Server. The username node of the connection input parameter overrides the User Name field of the FTP endpoint.
connection/password Specify a password for the account used to connect to the FTP Server. The password node of the connection input parameter overrides the Password field of the FTP endpoint.

Mapping the output of the activity

  1. Select the Map Outputs task in the Checklist. The output parameters of the activity are displayed in the From Activity pane as described in the following table:
    Table 5.
    Output Parameter Name Description
    data Contains the contents of the file.
    timestamp Contains the timestamp for the file returned from the FTP Server, typically the creation date or last modified date of the file.  
  2. Map the desired output parameters to variables.



Feedback | Notices


Timestamp icon Last updated: Tuesday, 27 September 2016


http://pic.dhe.ibm.com/infocenter/wci/v7r0m0/topic/com.ibm.wci.doc/ftp_get_file_activity.html