FTP Client Begin Session Service

The FTP Client Begin Session service establishes a session with a trading partner FTP server.

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

System name	FTP Client Begin Session Service
Graphical Process Modeler (GPM) categories	All Services, B2B Protocols > FTP Client
Description	This service is used to start an FTP session with an external trading partner to exchange business documents.
Business usage	Use this service to establish a session with a trading partner FTP server.
Usage example	A business process is executed that translates a document that must be sent to a trading partner. After the translation, Sterling B2B Integrator uses the FTP Client Begin Session service to establish a session with the trading partner's FTP server. The Begin Session service works through a configuration of the FTP Client adapter.
Preconfigured?	No
Requires third-party files?	No
Platform availability	All Sterling B2B Integrator supported platforms
Related services	Related services: FTP Client adapter FTP Client CD service FTP Client DELETE service FTP Client End Session service FTP Client LIST 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 To mask the values associated with the remote password parameter, use the Obscure Data - Process Data Values service in conjunction with the FTP Begin Session service. This service is presented in the GPM as Obscure Parameter on the All Services stencil.
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	The FTP Client Begin Session service allows you to specify a remote password. To obscure this password in process data for the business process, you must use the Obscure Data - Process Data Values service within the same business process. The Obscure Data - Process Data Values service masks the values associated with parameters.
Returned status values	Returned status values: 0 – Success 1 – Error
Restrictions	N/A
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 Begin Session Service

To implement the FTP Client Begin Session service, complete the following tasks:

Create an FTP Client Begin Session service configuration. For information, see Managing Services and Adapters.
Use the FTP Client Begin Session service in a business process.

Configuring the FTP Client Begin Session Service

You can set the following values in the trading partner profile and specify it in the ProfileId field, or you can set these values in an instance of the service to only apply for that instance. If specified in the FTP Client Begin Session service, the following values override those in the FTP trading partner profile:

CACertificateId
CipherStrength
ConnectionRetries
CharacterEncoding
ConnectionTimeout
RemoteHost
RemotePasswd
RemotePort
RemoteUserId
RetryDelay
SSL
SystemCertificateId

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

Field	Description
Name	Name this service will have in Sterling B2B Integrator. Required.
Description	Description of service. Required.
Select a Group	Select one of the options: None – You do not want to include this configuration in a group at this time. (default) 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 service 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. Select FTPClientBeginSession.
CACertificateId (trusted_root)	Select from the list of trusted Certificate Authority public certificates. In process data, this parameter is displayed as an object ID. Required if SSL = IMPLICIT or SSL = EXPLICIT. Check an SSL certificate into the application to make available from the list.
CipherStrength	The level of encryption to apply to the data that flows through the socket connection. Optional. Valid values are: ALL – WEAK or STRONG is accepted WEAK – 40 bit encryption is required STRONG – 40 bit or higher encryption is required (default)
ClearControlChannel	Indicates if information that travels across the control channel should be clear. Optional. Valid values are Yes and No.
ConnectionRetries	The number of times the service will try to connect to the trading partner system. Connection retries occur only with TCP/IP related issues. Optional. Valid value is any numeric value. While using the ConnectionRetries parameter, set the ResponseTimeout value to wait longer than the total time for RetryDelay and ConnectionRetires parameters. This setting allows the business process to remain active to perform the retries before the session times out and terminates. The following example illustrates the setting where the value of the ResponseTimeout (300) is greater than the total time taken by RetryDelay and ConnectionRetires parameters (30*5=150): `<assign to="ResponseTimeout"> 300 </assign> <assign to="RetryDelay"> 30 </assign> <assign to="ConnectionRetries"> 5 </assign>`
CharacterEncoding	The encoding format used to encode all outgoing commands and incoming data. If CharacterEncoding is not specified, the default system encoding will be used. Valid value is any valid encoding scheme supported by Java. Optional.
ResponseTimeout	Maximum number of seconds the FTP Client Begin Session service waits for the trading partner system to respond before the session times out and terminates. You can also set this parameter from a trading profile. The value you specify in the FTP Client Begin Session service overrides the value you specify in the trading partner profile. Optional. Valid value is any numeric value. Default value is 30 seconds. Minimum value you can specify is 1 second. If the value you specify is less than 1 second, the FTP Client Begin Session service resets the value to 1 second.
FTPClientAdapter	Select the FTP Client adapter for this service to use when beginning sessions with an FTP server. Required.
ProfileId	Trading partner profile identification. Optional. Valid value is any valid profile ID.
UsingRevealedPasswd	Indicates whether the password sent to the service is unobscured. Valid value is True or False. Default is False. Optional.
RemoteAccount	FTP remote login account. Valid value is valid login account. There is no default value. Optional.
RemoteHost	External trading partner host system (FTP server IP address or DNS name). Required. Valid value is a valid IP Address or DNS name.
RemotePasswd	FTP remote login password. Optional. Note: For the password to be masked in process data, the Obscure Data - Process Data Values service must also be used in the same business process. The name used to store the password must be the same as the specified RemoteUserId.
RemotePort	External trading partner port number. Required.
RemoteUserId	FTP remote login user name. Optional.
RetryDelay	The delay (in seconds) the adapter will wait before retrying. Optional. Valid values are numeric values between 1 and 7200. The default value is 1 second.
SSL	Determines SSL socket negotiation. Optional. Valid values are: SSL_IMPLICIT – FTP server expects and requires SSL to happen automatically at the time of connection. CACertificateId is required. SSL_EXPLICIT – FTP client requests SSL and a secure connection is negotiated. CACertificateId is required. SSL_NONE – Connection will not use SSL. (default)
SystemCertificateId	Select from the list of PrivateKeys/Public Certificates that are signed by the trading partner Trusted Certificate Authority. This certificate confirms the identity of the client to the server. Required if SSL = SSL_IMPLICIT or SSL_EXPLICIT and the server requires client authentication. Obtain the certificate from your trading partner. Check it into Sterling B2B Integrator from the Admin menu selecting Trading Partner > Digital Certificates > System to make it available in this list.
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.

Output from Service to Business Process

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

Parameter	Description
SessionToken	Specifies the identifier for the session established between the FTP Client adapter and an FTP server.
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.

Output from Business Process to Service

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

Parameter	Description
CACertificateId(trusted_root)	List of trusted Certificate Authority public certificates. In process data, this parameter is displayed as an object ID.
CipherStrength	The level of encryption to apply to the data that flows through the socket connection. Valid values are: ALL – WEAK or STRONG is accepted WEAK – 40 bit encryption is required STRONG – 40 bit or higher encryption is required
ClearControlChannel	Indicates if information that travels across the control channel should be clear. Valid values are Yes and No.
ConnectionRetries	The number of times the service will try to connect to the trading partner system. Valid value is any numeric value. While using the ConnectionRetries parameter, set the ResponseTimeout value to wait longer than the total time for RetryDelay and ConnectionRetires parameters. This setting allows the business process to remain active to perform the retries before the session times out and terminates. The following example illustrates the setting where the value of the ResponseTimeout (300) is greater than the total time taken by RetryDelay and ConnectionRetires parameters (30*5=150): `<assign to="ResponseTimeout"> 300 </assign> <assign to="RetryDelay"> 30 </assign> <assign to="ConnectionRetries"> 5 </assign>`
ResponseTimeout	Maximum number of seconds the FTP Client Begin Session service waits for the trading partner system to respond before the session times out and terminates. You can also set this parameter from a trading profile. The value you specify in the FTP Client Begin Session service overrides the value you specify in the trading partner profile. Optional. Valid value is any numeric value. Default value is 30 seconds. Minimum value you can specify is 1 second. If the value you specify is less than 1 second, the FTP Client Begin Session service resets the value to 1 second.
FTPClientAdapter	Select the FTP Client adapter for this service to use when beginning sessions with an FTP server.
ProfileId	Trading partner profile identification. Valid value is any valid profile ID.
RemoteHost	External trading partner host system (FTP server IP address or DNS name). Valid value is a valid IP Address or DNS name.
RemotePasswd	FTP remote login password.
RemotePort	External trading partner port number.
RemoteUserId	FTP remote login user name.
RetryDelay	The delay (in seconds) the adapter will wait before retrying. Valid values are numeric values between 1 and 7200. The default value is 1 second.
SSL	The SSL flag that determines SSL socket negotiation. Valid values are: SSL_IMPLICIT – FTP server expects and requires SSL to happen automatically at the time of connection. SSL_EXPLICIT – FTP client requests SSL and a secure connection is negotiated. SSL_NONE – Connection will not use SSL.
SystemCertificateId	Select from the list of PrivateKeys/Public Certificates that are signed by the trading partner Trusted Certificate Authority. Valid value is any alphanumeric string.
SaveTranscript	Indicates how to handle the transcript. Valid values are: erroronly – persists the transcript only when an error occurs on – always persists the transcript

Business Process Example

The following example business process illustrates using the FTP Client Begin Session service:

 <process name="FtpExample">
  <sequence>
    <operation name="Obscure Password">
      <!-- insert obscured password into process data -->
      <participant name="FTPClientObscureParameter"/>
      <output message="outmsg">
      <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
      <assign to="." from="*"></assign>
      </input>
    </operation>
    <operation name="FTP Client Begin Session Service">
      <participant name="FTPClientBeginSession"/>
      <output message="FTPClientBeginSessionServiceTypeInputMessage">
        <assign to="FTPClientAdapter">FTPClientAdapter</assign>
        <assign to="RemoteHost">hostb</assign>
        <assign to="RemoteUserId">admin</assign>
        <!-- copy obscured password from process data to service -->
        <assign to="RemotePasswd" from="admin/text()"></assign>
        <assign to="RemotePort">30651</assign>
        <assign to="CipherStrength>STRONG</assign>
        <assign to="SSL">SSL_MUST</assign>
        <assign to="CACertificateId">FTP Server CA Cert</assign>
        <assign to="SystemCertificateId">FtpClientSystemCert</assign>
        <assign to="RemoteUserId">admin</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="FTPClientBeginSessionServiceResults" from="*"></assign>
      </input>
    </operation> 
[[end session here]] 
</process>

The following example shows how to use the revealObscured function when the user ID contains domain or special characters. First, create a name in the Obscure Service without any special characters and assign the appropriate password to it. In the following example, the name created in the Obscure Service is "abcd" while the userid is sgp-abcd\abcd.

The parameter to the revealObscured() function is the node containing the obscured password. The function uses the node name as the key and the node value as the obscured password when unobscuring.

<operation name="Obscure FTP client password">
      <participant name="FTPClientObscureParameter"/>
      <output message="outmsg">
	<assign to="." from="*"/>
      </output>
      <input message="inmsg">
	<assign to="ObscureResult" from="*"/>
      </input> 
</operation> 
<operation name="PS FTP BEGIN SESSION SERVICE">
     <participant name="FTPClientBeginSession"/>
     <output message="BeginSessionRequest">
           ............
          <assign to="RemoteUserId">sgp-abcd\abcd</assign>
          <assign to="UsingRevealedPasswd">true</assign>   
          <assign to="RemotePasswd" from="revealObscured(ObscureResult/abcd)"/> 
          ..........
      </output>
      <input message="inmsg">
         <assign to="FtpBeginSessionServiceResults" from="*"/>
      </input> 
</operation>