FTP Client LIST Service

The FTP Client LIST service retrieves a list in a specified directory on the trading partner's system and returns the list to Sterling B2B Integrator when the FTP protocol is required as the transport mechanism.

The following table provides an overview of the FTP Client LIST service:

System name FTP Client LIST Service
Graphical Process Modeler (GPM) categories All Services, B2B Protocols > FTP Client
Description Use this service to retrieve a list of documents in a specified directory on the trading partner's FTP server.
Business usage Use this service to retrieve a list of files in a specified directory on the trading partner's system and return the list to Sterling B2B Integrator when the FTP protocol is required as the transport mechanism.
Usage example A Sterling B2B Integrator business process is executed that must retrieve a list of files from the external trading partner. Sterling B2B Integrator uses the FTP Client LIST service, working through the FTP Client adapter, to retrieve the list of files from a specified directory on the trading partner system.
Preconfigured? No
Requires third-party files? No
Platform availability All supported Sterling B2B Integrator platforms
Related services Related services:
  • FTP Client adapter
  • FTP Client Begin Session service
  • FTP Client CD service
  • FTP Client DELETE service
  • FTP Client End Session service
  • FTP Client GET service
  • FTP Client MOVE service
  • FTP Client PUT service
  • FTP Client PWD service
  • FTP Client SITE service
  • FTP Client QUOTE service
Application requirements An FTP server at the external trading partner location.
Initiates business processes? This service does not initiate business processes.
Invocation This service is invoked from a business process.
Business process context considerations None
Returned status values Returned status values:
  • 0 – Success
  • 1 – Error
Restrictions None
Persistence level Default
Testing considerations Test this service by running the FTPClientDemoAllServices business process provided with Sterling B2B Integrator. This business process tests the FTP Client adapter and all its related services. The FTPClientDemoAllServices business process uses the preconfigured instance of the FTP Server adapter, which is disabled by default, and must be enabled before running this test.

To verify that the preconfigured FTP Server adapter is enabled, perform the following steps from the Sterling B2B Integrator Admin Console:

1. Choose Business Processes > Deployment > Services > Configuration.

2. Find FTP Server Adapter.

3. If not already selected, select the Enabled check box.

To test this service, perform the following steps from the Sterling B2B Integrator Admin Console:

1. Choose Business Processes > Manager.

2. Find the FTPClientDemoAllServices business process.

3. Run the FTPClientDemoAllServices business process with the following settings:
  • Run As User = Admin
  • Server filename =
    install_dir/installed_data/
    psftpclient/FTPClientDemoImport.xml
4. Verify that the business process runs successfully.

Debug information for this service can be found in the FTP Client adapter and services log files.
Notes Every FTP Client service returns a response code from the server. If this code is an error code as defined by the FTP specification (4xx or 5xx) then the business process will produce a fault. If the error code is expected, use an OnFault service to continue interacting with the trading partner.

Implementing the FTP Client LIST Service

To implement the FTP Client LIST service:
  1. Create an FTP Client LIST service configuration (or enable the configuration installed with Sterling B2B Integrator and edit parameters as needed). For information, see Managing Services and Adapters.
  2. Configure the FTP Client LIST service. For information, see Configuring the FTP Client LIST Service.
  3. Use the FTP Client LIST service in a business process.

Configuring the FTP Client LIST Service

To configure the FTP Client LIST service, you must specify settings for the following fields in the GPM:

GPM Field Description
Config Name of the service configuration.
ConnectionType Value that describes which way the data connection will be made when the data is transferred. Optional. Valid values are:
  • ACTIVE - The server will make the connection. (Default)
  • PASSIVE - The adapter will make the connection.
NamesOnly Whether to include just names or all information to the server. Optional.
  • YES – Causes the FTP protocol command NLST to be sent to the server. The results will be a stream of names of files and no other information.
  • NO – Causes the FTP protocol command LIST to be sent to the server. The results will vary in form and information depending on the server. (Default)
RemoteFileName File name or pattern to do the listing for. If not included the listing will be for a *.* pattern (depending on server implementation). Optional.
RepresentationType
Representation used for transferring the file. Optional. Valid values are:
  • ASCII – Transfers the data in ASCII mode
  • BINARY – Transfers the data in binary mode (default)
ResponseErrorSetSuccess If this parameter is set to YES in LIST, GET or MGET, a ResponseTimeOut will not occur between canAccept and Reply 226 in the MGET and LIST Services due to a race condition. This is a BPML parameter and is not available in the Graphical Process Modeler. Default value is NO. Optional.
ResponseTimeout Maximum number of seconds the FTP client waits for the server to respond before the session times out and terminates. Optional. Valid value is any numeric value. The default is the value from the FTP Client Begin Session service ResponseTimeout parameter. Minimum value you can specify is 1 second. If the value you specify is less than 1 second, the FTP Client LIST service resets the value to 1 second.
SessionToken Specifies the identifier for the session established between the FTP Client adapter and an FTP server. Required.
Note: The session token is returned from the FTP Client Begin Session service.
SaveTranscript Indicates how to handle the transcript. Optional. Valid values are:
  • erroronly – persists the transcript only when an error occurs
  • on – always persists the transcript (Default)

Output from Service to Business Process

The following table contains the parameters passed from the FTP Client LIST service to the business process:

Parameter Description
ServerResponse Indicates the FTP server response, which may include a reply code and any text associated with the reply code. Required.
TranscriptDocumentId Identifies the document that contains a transcript of the exact exchange with the FTP server. Required.
ListNames Provides information about the files included in the specified directory. Optional. Only returned if NamesOnly=YES.

Output from Business Process to Service

The following table contains the parameters passed from the business process to the FTP Client LIST service:

Parameter Description
ConnectionType Value that describes which way the data connection will be made when the data is transferred. Optional. Valid values are:
  • ACTIVE - The server will make the connection. (Default)
  • PASSIVE - The adapter will make the connection.
NamesOnly Whether to include just names or all information to the server. Optional.
  • YES – Causes the FTP protocol command NLST to be sent to the server. The results will be a stream of names of files and no other information.
  • NO – Causes the FTP protocol command LIST to be sent to the server. The results will vary in form and information depending on the server. (Default)
ListNamesErrorSetSuccess Ignore 550 error code when executing the NLST command. Optional. Valid values are:
  • YES
  • NO
RemoteFileName File name or pattern to do the listing for. If not included the listing will be for a *.* pattern (depending on server implementation). Optional.
ResponseTimeout Maximum number of seconds the FTP client waits for the server to respond before the session times out and terminates. Optional. Valid value is any numeric value. The default is the value from the FTP Client Begin Session service ResponseTimeout parameter. The minimum value you can specify is 1 second. If the value you specify is less than 1 second, the FTP Client LIST service resets the value to 1 second.
SessionToken Specifies the identifier for the session established between the FTP Client adapter and an FTP server. Required.
Note: The session token is returned from the FTP Client Begin Session service.
SaveTranscript Indicates how to handle the transcript. Optional. Valid values are:
  • erroronly – persists the transcript only when an error occurs
  • on – always persists the transcript (Default)

Business Process Example

The following example business processes illustrate the use of the FTP Client LIST service:

Example of a Names Only listing:

<sequence>
  [[ Insert FTP Client Begin Session ]] 
    <operation name="FTP LIST SERVICE NAME"> 
    <participant name="FTPClientList"/> 
    <output message="ListRequest"> 
      <assign to="SessionToken" 
         from="/ProcessData/FtpBeginSessionServiceResults/SessionToken/text()">
      </assign> 
      <assign to="NamesOnly">YES</assign> 
      <assign to="RemoteFileName">*.txt</assign> 
      <assign to="ConnectionType">PASSIVE</assign> 
    </output> 
    <input message="inmsg"> 
      <assign to="NameListResults" from="*"></assign> 
    </input> 
    </operation> 
  [[ Insert FTP Client End Session ]] 
</sequence>

Example of a Raw listing:

<sequence>
  [[ Insert FTP Client Begin Session ]] 
    <operation name="FTP LIST SERVICE RAW"> 
    <participant name="FTPClientList"/> 
    <output message="ListRequest"> 
      <assign to="SessionToken" 
         from="/ProcessData/FtpBeginSessionServiceResults/SessionToken/text()">
      </assign> 
      <assign to="NamesOnly">NO</assign> 
      <assign to="ConnectionType">PASSIVE</assign> 
    </output> 
    <input message="inmsg"> 
      <assign to="RawListResults" from="*"></assign> 
    </input> 
    </operation> 
  [[ Insert FTP Client End Session ]] 
</sequence>