FTP Client PUT Service

The FTP Client PUT service places a document or documents in a specified directory on the trading partner's FTP server.

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

System name	FTP Client PUT Service
Graphical Process Modeler (GPM) categories	All Services, B2B Protocols > FTP Client
Description	Used to place a document or documents in a specified directory on the trading partner's FTP server.
Business usage	Use this service to transfer a document or documents from Sterling B2B Integrator to a trading partner when the FTP protocol is required as the transport.
Usage example	You run a business process that translates a document that must be sent to a trading partner. After the translation, Sterling B2B Integrator uses the FTP Client PUT service, working through the FTP Client adapter, to place the document in a specified directory on the trading partner system.
Preconfigured?	Yes
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 LIST service FTP Client MOVE service FTP Client PWD service FTP Client QUOTE service FTP Client SITE service FTP Client MKD service FTP Client RMD service FTP Client MODE service
Application requirements	An FTP server at the external trading partner location.
Initiates business processes?	No
Invocation	This service is invoked from a business process.
Business process context considerations	Business processes that use the FTP client services should not be marked as Auto Resume. These protocol services require an established session, which will no longer exist in a re-start situation. Business processes that use the FTP Client PUT service cannot be run in sync mode.
Returned status values	Returned status values: 0 – Success 1 – Error
Restrictions	None
Persistence level	Default
Testing considerations	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 error code is defined by the FTP specification (4xx or 5xx) then the business process produces a fault. If the error code is expected, use a BPML activity 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 PUT Client Service

To implement the FTP Client PUT service, complete the following tasks:

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

Configuring the FTP Client PUT Service

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

UI Field	GPM	Description
Name		Unique and meaningful name for the service configuration. Required.
Description		Meaningful description for the service configuration, for reference purposes. Required.
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.
	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. Note: This is the pre-defined value set by the manufacturer. If you create a new configuration, the default value (Passive) is used. PASSIVE - The adapter will make the connection. Default.
	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.
	DocumentId	Document ID to PUT to the remote server. A single DocumentId can appear directly in the message to the service or any number of DocumentIds can appear under the DocumentList element. Optional. Note: The FTP Client PUT service will use DocumentList if a list is provided. If no list is specified in DocumentList, the service will use DocumentId. The service will not use both DocumentList and DocumentId. If no values are specified for either DocumentList or DocumentId, the service will PUT the primary document to the remote server. If the DocumentId and DocumentList are not specified, and if the DocumentId appears anywhere in the ProcessData prior to the FTP Client Put service, that DocumentId value will be used in the FTP Client Put service. Example: The GetDocumentInfoService populates the DocumentId in the ProcessData. If this service is used before the use of the FTP Client Put service in the BP, the DocumentId that is populated by the GetDocumentInfoService is used by the FTP Client Put service.
	DocumentList	List of documents to PUT to the remote server. Each item must be a DocumentId. A list could look like the following example: `<DocumentList> <DocumentId>12345</DocumentId> <DocumentId>67890</DocumentId> </DocumentList>`
	RemoteFileName	Filename that Sterling B2B Integrator uses to place the document on the remote system. If not specified, the name of the document will be used. Do not use this parameter if putting multiple documents on a server. Optional.
	RepresentationType	Representation used for transferring the file. Optional. Valid values: ASCII – Transfers the data in ASCII mode BINARY – Transfers the data in binary mode (Default) EBCDIC – Transfers the data in EBCDIC mode L 8 – Transfers the data in Local Byte 8 mode that is implicitly Binary mode
	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. Minimum value is 1 second. Valid value is any numeric value of 1 or higher. The default is the value from the FTP Client Begin Session service ResponseTimeout parameter. If the value is less than 1 second, the FTP Client PUT service resets the value to 1 second.
	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)
	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.
	StoreAction	Specifies the type of store that must be done. Optional. Valid values are: Normal - Puts a new file with the specified name. Default. Append - Appends to the file if it already exists. Otherwise puts a new file with the specified name. `<assign to="StoreAction">APPE</assign>` Unique - Saves the file with a unique name if a file with the same name already exists. `<assign to="StoreAction">STOU</assign>`
	UseDocBodyName	Specifies whether to use document body name as the remote file name. This parameter is only use in MPUT operation. Valid values are: YES – Use document body name NO – Use document name Default is NO. Optional.

Parameters Passed from Business Process to Service

The following table contains the parameters passed from the business process to the FTP Client PUT 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.
DocumentId	Document ID to PUT to the remote server. A single DocumentId can appear directly in the message to the service or any number of DocumentIds can appear under the DocumentList element. Optional. Note: The FTP Client PUT service will use DocumentList if a list is provided. If no list is specified in DocumentList, the service will use DocumentId. The service will not use both DocumentList and DocumentId. If no values are specified for either DocumentList or DocumentId, the service will PUT the primary document to the remote server. If the DocumentId and DocumentList are not specified, and if the DocumentId appears anywhere in the ProcessData prior to the FTP Client Put service, that DocumentId value will be used in the FTP Client Put service. Example: The GetDocumentInfoService populates the DocumentId in the ProcessData. If this service is used before the use of the FTP Client Put service in the BP, the DocumentId that is populated by the GetDocumentInfoService is used by the FTP Client Put service.
DocumentList	List of documents to PUT to the remote server. Each item must be a DocumentId. A list could look like the following example: `<DocumentList> <DocumentId>12345</DocumentId> <DocumentId>67890</DocumentId> </DocumentList>`
RemoteFileName	Filename that Sterling B2B Integrator uses to place the document on the remote system. If not specified, the name of the document will be used. Do not use this parameter if putting multiple documents on a server. Optional.
RepresentationType	Representation used for transferring the file. Optional. Valid values: 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. Minimum value is 1 second. Valid value is any numeric value of 1 or higher. The default is the value from the FTP Client Begin Session service ResponseTimeout parameter. If the value is less than 1 second, the FTP Client PUT 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.
StoreAction	Specifies the type of store that must be done. Optional. Valid values are: Normal - Puts a new file with the specified name. Default. Append - Appends to the file if it already exists. Otherwise puts a new file with the specified name. `<assign to="StoreAction">APPE</assign>` Unique - Saves the file with a unique name if a file with the same name already exists. `<assign to="StoreAction">STOU</assign>`
UseDocBodyName	Specifies whether to use document body name as the remote file name. This parameter is only use in MPUT operation. Optional. Valid values are: YES – Use document body name NO – Use document name (Default)
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.
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)

Parameters Passed from Service to Business Process

The following table contains the parameters passed from the FTP Client PUT 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.
TranscriptDocumentId	Identifies the document that contains a transcript of the exact exchange with the FTP server.

Business Process Examples

Example 1

The following business process uses the FTP Client adapter to send the primary document from Sterling B2B Integrator to the remote FTP server:

<process name="FtpExample">
<sequence>
[[Insert Begin Session ]]
  <operation name="FTP PUT SERVICE">
  <participant name="FTPClientPut"/>
    <output message="PutRequest">
        <assign to="SessionToken"
from="/ProcessData/FtpBeginSessionServiceResults/SessionToken/text()"></assign>
        <assign to="RemoteFileName">TestDoc</assign>
        <assign to=”ConnectionType”>PASSIVE</assign>
        <assign to=”RepresentationType”>BINARY</assign>
        <assign to=”.” From=”PrimaryDocument”></assign>
    </output>
    <input message="inmsg">
        <assign to="FtpPutServiceResults" from="*"></assign>
    </input>
 </operation>
</sequence>
[[Insert end session here]]
</process>

Example 2

The following business process uses the FTP Client PUT service to send all documents received from a GET from Application to the remote FTP server.


<process name="FTP_PUT">
<sequence name="optional">
[[Insert begin session here?]]
     <operation name=”Get”>
       <participant name=”FTPClientGet”/>
       <output message=”GetRequest”>
            <assign to="SessionToken"
from="/ProcessData/BeginSessionResults/SessionToken/text()"></assign>
          <assign to=”RemoteFilePattern”>*.*</assign>
       </output>
       <input message=”GetResults”>
            <assign to=”GetResults” from=”DocumentList”/>
         </input>
    </operation>
       <operation name="Put">
         <participant name="FTPClientPut"/>
           <output message="PutRequest">
             <assign to="SessionToken"
from="/ProcessData/BeginSessionResults/SessionToken/text()"></assign>
              <assign to=”.” From=”/ProcessData/GetResults/DocumentList”/>
              <assign to="RepresentationType">ASCII</assign> </output>
            <input message="FtpPutResults">
              <assign to="PutResults" from="*"></assign>
           </input>
           </operation>
[[Insert End Session]]
     </sequence>
</process>

Example 3

The following business process uses the FTP Client PUT service to send all documents in a DocumentList from Application to the remote FTP server.

<process name="FTP_PUT">
  <sequence name="optional">
[[Insert begin session here?]]
   <operation name="Put">
      <participant name="FTPClientPut"/>
      <output message="PutRequest">
        <assign to="SessionToken"
from="/ProcessData/BeginSessionResults/SessionToken/text()"></assign>
        <assign to=”DocumentList/DocumentId” append=”true”>xxxxxxfffff</assign>
        <assign to=”DocumentList/DocumentId” append=”true”>yyyyyyfffff</assign>
        <assign to="RepresentationType">ASCII</assign>
      </output>
      <input message="FtpPutResults">
         <assign to="PutResults" from="*"></assign>
      </input>
   </operation>
[[Insert End Session]]
   </sequence>
</process>