FTP Client GET Service

The FTP Client GET service retrieves one or more documents from a specified directory on the trading partner's FTP server.

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

System name FTP Client GET Service
Graphical Process Modeler (GPM) categories All Services, B2B Protocols > FTP Client
Description This service is used to retrieve one or more documents from a specified directory on the trading partner's FTP server.
Business usage You would use this service to retrieve one or more documents from a trading partner and move them into 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 specified file from the external trading partner. Sterling B2B Integrator uses the FTP Client GET service, working through the FTP Client adapter, to retrieve the file 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 LIST service
  • FTP Client MOVE service
  • FTP Client PUT service
  • FTP Client PWD service
  • FTP Client QUOTE service
  • FTP Client SITE 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 initiated 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_directory>/installed_data/
    psftpclient/FTPClientDemoImport.xml.
4. Verify that the business process runs successfullyDebug 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 (that is, 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. There are two exceptions to this rule:
  • FTP Client GET service – If using the remoteFilePattern parameter and one of the files returns an error code indicating that the file could not be found, the GET command will continue without producing a fault. The error code will still be visible in the Transcript Document.
  • FTP Client QUOTE service – This service never produces a fault, because the service does not know what constitutes a valid response from the quoted command.

Implementing the FTP Client GET Service

To implement the FTP Client GET service, complete the following tasks:
  1. Create an FTP Client GET 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 GET service. For information, see Configuring the FTP Client GET Service.
  3. Use the FTP Client GET service in a business process.

Configuring the FTP Client GET Service

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

Field Description
Name Name this adapter will have in Sterling B2B Integrator
Description Description of adapter
Select a Group Select one of the options:
  • None – You do not want to include this configuration in a group at this time.
  • Create New Group – You can enter a name for a new group in this field, which will then be created along with this configuration.
  • Select Group – If you have already created one or more groups for this adapter type, they are displayed in the list. Select a group from the list.
Note: For more information about groups, see Managing Services and Adapters.
Config Name of the service configuration.
CheckFileSize Use to check that the file size is stable before downloading the file. Valid values are YES and NO. NO is the default value. When YES is specified, the FTP GET service checks the file size at 5-second intervals. The FTP GET service downloads the file only when the file size remains unchanged. Any change in the file size indicates that the file is still being transferred to the server and the service sends an error to the business process. Optional. You cannot use this parameter if RemoteFilePattern is specified.
Note: This parameter is supported with the following FTP servers:
  • Windows IIS FTP server
  • Standard UNIX FTP server – such as HP-UP, AIX
  • Standard LINUX FTP server – Redhat
  • War FTP Daemon 1.70/80 series (Windows)
ConnectionType Value that describes which way the data connection will be made when the data is transferred. Optional. Value values are:
  • ACTIVE — The server will make the connection. (Default)
  • PASSIVE — The adapter will make the connection.
ListNamesErrorSetSuccess Ignore 550 error code when executing the NLST command. Optional. Valid values are YES and NO.
RemoteFileName The name of the file to be retrieved from the remote trading partner. Optional. You cannot use this parameter if RemoteFilePattern is specified.
Note: Either RemoteFileName or RemoteFilePattern must be specified. Both cannot be left blank.
RemoteFilePattern The file filter pattern. Using this field activates multiple-get mode. Optional. You cannot use this parameter if RemoteFileName is specified.
Note: Either RemoteFileName or RemoteFilePattern must be specified. Both cannot be left blank.
RepresentationType The FTP representation type that will be used for the transfer. 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. Setting YES will also prevent the occurrence of zero byte files. This is a BPML parameter and is not available in the Graphical Process Modeler. Default value is NO. Optional.
ResponseTimeout Maximum number of seconds of inactivity during data transfer between the FTP Client and the FTP Server. The FTP Client waits during the data transfer, 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 GET service resets the value to 1 second.
RetrieveErrorSetSuccess Ignore 550 error code when executing the RETR command. Optional. Valid values are YES and NO.
SaveTranscript Indicates how to handle the transcript. Valid values are:
  • erroronly – persists the transcript only when an error occurs
  • on – always persists the transcript
Default is on. Optional.
DelayWaitingOnIO Specifies the number of seconds to wait for the data transfer to complete before going into WAITING_ON_IO state. If -1 is specified, the service operates in blocking mode. It will wait until the data transfer has completed. Valid value is any numerical value. Optional.
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.

Parameters Passed from Business Process to Service

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

Parameter Description
CheckFileSize Use to check that the file size is stable before downloading the file. Valid values are YES and NO. NO is the default value. When YES is specified, the FTP GET service checks the file size at 5-second intervals. The FTP GET service downloads the file only when the file size remains unchanged. Any change in the file size indicates that the file is still being transferred to the server and the service sends an error to the business process. Optional. You cannot use this parameter if RemoteFilePattern is specified.
Note: This parameter is supported with the following FTP servers:
  • Windows IIS FTP server
  • Standard UNIX FTP server – such as HP-UP, AIX
  • Standard LINUX FTP server – Redhat
  • War FTP Daemon 1.70/80 series (Windows)
ConnectionType Value that describes which way the data connection will be made when the data is transferred. Optional. Value values are:
  • ACTIVE — The server will make the connection. (Default)
  • PASSIVE — The adapter will make the connection.
ListNamesErrorSetSuccess Ignore 550 error code when executing the NLST command. Optional. Valid values are YES and NO.
RemoteFileName The name of the file to be retrieved from the remote trading partner. If a value is entered in this field, RemoteFilePattern cannot be used. Optional. You cannot use this parameter if RemoteFilePattern is specified.
Note: Either RemoteFileName or RemoteFilePattern must be specified. Both cannot be left blank.
RemoteFilePattern The file filter pattern. Using this field activates multiple-get mode. If a value is entered in this field, then RemoteFileName cannot be used. Optional. You cannot use this parameter if RemoteFileName is specified.
Note: Either RemoteFileName or RemoteFilePattern must be specified. Both cannot be left blank.
RepresentationType The FTP representation type that will be used for the transfer. Optional. Valid values are:
  • ASCII – transfers the data in ASCII mode
  • BINARY – transfers the data in binary mode (default)
ResponseTimeout Maximum number of seconds of inactivity during data transfer between the FTP Client and the FTP Server. The FTP Client waits during the data transfer, 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 GET service resets the value to 1 second.
RetrieveErrorSetSuccess Ignore 550 error code when executing the RETR command. Optional. Valid values are YES and NO.
SaveTranscript Indicates how to handle the transcript. Valid values are:
  • erroronly – persists the transcript only when an error occurs
  • on – always persists the transcript
Default is on. Optional.
DelayWaitingOnIO Specifies the number of seconds to wait for the data transfer to complete before going into WAITING_ON_IO state. If -1 is specified, the service operates in blocking mode. It will wait until the data transfer has completed. Valid value is any numerical value. Optional.
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.

Parameters Passed from Service to Business Process

The following table contains the parameters passed from the FTP Client GET 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.
DocumentList Provides a list of document IDs that were created for the files retrieved by the FTP Client GET service. Required.
Note: If a single document was retrieved, the service will place it as the primary document.

Business Process Examples

The following example business processes illustrate using commands supported by the FTP Client GET service.

This process gets a binary file named TestDoc using the passive connection type from the server:

 <sequence> 
  [[Insert FTP Client Begin Session here]] 
    <operation name="FTP GET SERVICE"> 
      <participant name="FTPClientGet"/> 
      <output message="GetRequest"> 
      <assign to="SessionToken" 
         from="/ProcessData/FtpBeginSessionServiceResults/SessionToken/text()">
      </assign> 
      <assign to="RemoteFileName">TestDoc</assign> 
      <assign to="ConnectionType">PASSIVE</assign> 
      <assign to="RepresentationType">BINARY</assign> 
    </output> 
    <input  message="inmsg"> 
       <assign to="FtpGetServiceResults" from="*"></assign> 
    </input> 
    </operation>  
  [[Insert FTP Client End Session here]] 
</sequence>

This process illustrates using a multiple GET command:

 <sequence> 
  [[Insert FTP Client Begin Session here]] 
    <operation name="FTP MULTIPLE GET SERVICE"> 
    <participant name="FTPClientGet"/> 
    <output message="GetRequest"> 
       <assign to="SessionToken" 
         from="/ProcessData/FtpBeginSessionServiceResults/SessionToken/text()">
      </assign> 
      <assign to="RepresentationType">BINARY</assign> 
    </output> 
    <input message="inmsg"> 
      <assign to="FtpGetServiceResults" from="*"></assign> 
    </input> 
  </operation>  
  [[Insert FTP Client End Session here]] 
</sequence>

The following example business process illustrates using an implicit assign to add a message from the FTP Client GET service to the process data:

<input message="inmsg">
   <assign to="." from="*"></assign> 
</input>

The following example business process illustrates using an explicit assign to add a message from the FTP Client GET service to the process data:

<input message="inmsg">
   <assign to="StatusReport" from="Status_Rpt(&apos;StatusReport&apos;)">
        </assign>
   <assign to="FTPGetResults" from="*"><assign>
</input>

Sterling B2B Integrator supports either implicit assign or explicit assign, but not both at the same time, for example:

<input message="inmsg">
   <assign to="StatusReport" from="Status_Rpt(&apos;StatusReport&apos;)">
       </assign>
   <assign to="." from="*"></assign> 
</input>