SFTP Client GET Service

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

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

System name	SFTP Client GET Service
Graphical Process Modeler (GPM) category	All Services, B2B Protocols > SFTP Client
Description	This service is used to retrieve one or more documents from a specified directory on the trading partner's SFTP server.
Business usage	Use this service to retrieve one or more documents from a trading partner and move them into Sterling B2B Integrator when the SFTP protocol is required as the transport mechanism.
Usage example	A business process is executed to retrieve a specified file or files from the external trading partner. Sterling B2B Integrator uses the SFTP Client GET service, working through the SFTP Client adapter, to retrieve a file or files from a specified directory on the trading partner system.
Preconfigured?	Yes. To implement, use the preconfigured service in a business process.
Requires third-party files?	No
Platform availability	All Sterling B2B Integrator supported platforms
Related services	The following services are related. Configured in a business process, they initiate the SFTP Client adapter to perform their operations: SFTP Client Begin Session service SFTP Client CD service SFTP Client DELETE service SFTP Client End Session service SFTP Client GET service SFTP Client LIST service SFTP Client MOVE service SFTP Client PUT service SFTP Client PWD service
Application requirements	An SFTP Server at the external trading partner location
Initiates business processes?	No
Invocation	This service is invoked from a business process.
Business process context considerations	None
Returned status values	0 – Success, 1 – Error
Restrictions	None
Persistence level	System default
Testing considerations	To test this service, run the SFTPClientDemoAllServices business process and verify that it completes successfully. For more information about the SFTPClientDemoAllServices business process, see the SFTP Client adapter documentation. For further information, go to Operations > System > Logs > SFTP Client Adapter and Services

Input from Business Process to Service

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

Field	Description
RemoteFileName	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.
ResponseTimeout	Maximum number of seconds it can take for the trading partner system to respond before the session times out and terminates. If a number less than 30 is specified, 30 seconds will be used. Optional. Default is the ResponseTimeout value specified in the SFTP Client Begin Session service.
SessionToken	Returned SessionToken from the Begin Session service. Required.
RemoteFilePattern	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.
RetrieveErrorSetSuccess	SFTP Client Get service will succeed in case of any error when RetrieveErrorSetSuccess field is set to `YES`. Optional. Valid values are `YES` and `NO`.

Output from Service to Business Process

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

Parameter	Description
ServiceStartTime	Date/time stamp for when the service started
DocumentId	Provides information about the file(s) retrieved as a result of the GET service under the DocumentList element.
ServerResponse	SFTP server response, which may include a reply code and any text associated with the reply code. Valid values are: 0 - OK 1 - End of File 2 - No Such File 3 - Permission Denied 4 - General Failure 5 - Bad Message 6 - No Connection 7 - Connection Lost 8 - Operation Unsupported
ServiceEndTime	Date/time stamp for when the service ended
Primary Document	File retrieved as a result of the GET service. Note: The SFTP Get Service can generate multiple primary documents. When the SFTP Get service is retrieving multiple primary documents a primary document is created with the NodeUniqueId so the primary document elements will be unique. The appearance of the NodeUniqueId attribute is an example of a Business Process working as designed.

Business Process Example

The following business process excerpts illustrate using the SFTP Client GET service:

Process to get a file named FileNameToGet from the server

[[Insert begin session here]]
 
<operation name="SFTP Client GET Service">
  <participant name="SFTPClientGet">
  <output message="SFTPClientGetServiceTypeInputMessage">
<assign to="RemoteFileName" >FileNameToGet</assign>
  <assign to="SessionToken" from="SFTPClientBeginSessionServiceResults/
              SessionToken/text()"></assign>
  </output>
  <input message="inmsg">
  <assign to="SFTPClientGetServiceResults" from="*"></assign>
  </input>
</operation>

[[Insert end session here]]

Process invoking multiple get commands

[[Insert begin session here]]

<operation name="SFTP Client Multiple GET Service">
<participant name="SFTPClientGet"/>
<output message="SFTPClientGetServiceTypeInputMessage">
<assign to="RemoteFilePattern">*.txt</assign>
<assign to="SessionToken"
from="SFTPClientBeginSessionServiceResults/SessionToken/text()"></assign>
</output>
<input message="inmsg">
<assign to="SFTPClientGetServiceResults" from="*"></assign>
</input>
</operation>

[[Insert end session here]]

When using RemoteFileName only one DocumentId will be present. For example:

<DocumentList>
  <DocumentId>758:117753:137c2a60706:oxnard:node1</DocumentId>
</DocumentList>

Example output obtained from using RemoteFilePattern when multiple files exist on the server

<ServiceStartTime>2012-05-25 16:28:52.06</ServiceStartTime>
  <SFTP.EDI.streamed.txt SCIObjectID="090:11589:137842d3794:oxnard:node1"/>
  <SFTP.fa997.dat SCIObjectID="513:11590:137842d3794:oxnard:node1"/>
  <SFTP.Process.Data.txt SCIObjectID="370:11591:137842d3794:oxnard:node1"/>
  <SFTP_Consumer1.Test SCIObjectID="398:118901:137c2a60706:oxnard:node1"/>
  <Status>0</Status>
  <ServerResponse>
    <Code>0</Code>
    <Text>OK</Text>
  </ServerResponse>
  <ServiceStartTime>2012-05-25 16:28:52.06</ServiceStartTime>
  <ServiceEndTime>2012-05-25 16:28:52.38</ServiceEndTime>
  <DocumentList>
    <DocumentId>838:11530:137842d3794:oxnard:node1</DocumentId>
    <DocumentId>547:11545:137842d3794:oxnard:node1</DocumentId>
    <DocumentId>084:11555:137842d3794:oxnard:node1</DocumentId>
    <DocumentId>118:11565:137842d3794:oxnard:node1</DocumentId>
  </DocumentList>
</ProcessData>

Correlations and Document Tracking

The following table details the correlations available from the SFTP Client GET service for document tracking:

Key	Values
ACTION	Get, Put
Direction	Inbound, Outbound
Protocol	SFTP
RemoteHostAddress	remoteAddress
RemoteHostName	remoteHost
Username	username
RemoteFile	filename