SFTP Client Begin Session Service

The SFTP Client Begin Session service starts an SFTP session with an external trading partner for exchanging business documents.

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

Category	Description
System name	SFTP Client Begin Session Service
Graphical Process Modeler (GPM) category	All Services, B2B Protocols > SFTP Client
Description	Starts an SFTP session with an external trading partner for the purpose of exchanging business documents. This service works through an instance of the SFTP Client adapter.
Business usage	Use this service to establish a session with a trading partner SFTP server.
Usage example	A business process executes to translate a document sent to a trading partner. The trading partner profile specifies SFTP as the transport protocol. Sterling B2B Integrator uses the SFTP Client Begin Session service to establish a session with the trading partner's SFTP server.
Preconfigured?	Yes. Uses 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 MKDIR service SFTP Client MOVE service SFTP Client PUT service SFTP Client PWD service SFTP Client RMDIR service To mask the values associated with the remote password parameter, use the Obscure Data - Process Data Values service with the SFTP Client Begin Session service. This service is presented in GPM as Obscure Parameter on the All Services stencil. Then, the password must be revealed with the revealObscured XPath function before sending it to the 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	The SFTP Client Begin Session service allows you to specify a remote password. To obscure this password in process data for the business process, use the Obscure Data - Process Data Values service within the same business process (GPM display name is Obscure Parameter). 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	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 SFTP Client adapter. To view debug information for this service: Operations > System > Logs > SFTP Client Adapter and Services.

Input from Business Process to Service

The values for many of the parameters for the Begin Session service can be specified from multiple sources. The source for each parameter is determined by answering the following questions:

Is the parameter specified in the business process?

Yes - Sterling B2B Integrator uses those values.
No - Is ProfileId specified?
- Yes - Sterling B2B Integrator uses values from the profile associated with that ProfileId.
- No - Parameters noted in the following table take their value from the configuration of the selected SFTP Client adapter.

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

Field	Description
Name	Name this service will have in Sterling B2B Integrator
Description	Description of service
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 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.
PreferredAuthenticationMethod	Method used to authenticate users. Required. Valid values are: password, public key Note: The value entered for this parameter overrides the setting in the SSH Remote Profile configuration.
CompressionMethod	Specifies whether data is to be compressed, which reduces the amount of data transmitted as the file is copied from one node to another. The file will be automatically decompressed at the destination. Required. Valid values: None, ZLIB. Default is None. Note: The value entered for this parameter overrides the Compression setting in the SSH Remote Profile configuration.
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 from 1 to 50. Default is 1. Note: The value entered for this parameter overrides the Connection Retry Count setting in the SSH Remote Profile configuration. 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>`
KnownHostKeyId	Public key used to authenticate remote SFTP servers to the Sterling B2B Integrator SFTP Client. Internal value is GUID. Required. Note: The value entered for this parameter overrides the setting in the SSH Remote Profile configuration.
LocalPortRange	Any valid port number(s) not being used by another application running on the system. A port in the specified range will be used to establish an SSH channel to the remote SFTP server. Optional. Valid values are: (empty) - system selects an available port0 - system selects an available port `nnnn` - use specified port `nnnn`, for example 9012nn-yy - use a port in the range of nn to yy, for example 462-863 would use a port in the range of 462 to 863, inclusiveMultiples of the above values can be specified, separated by commas, for example 9012, 462-863, 4925. Note: The value entered for this parameter overrides the setting in the SSH Remote Profile configuration.
PreferredCipher	From v6.1.1.1 and later versions: Here is the list of supported ciphers: aes128-ctr aes192-ctr aes256-ctr aes128-cbc aes192-cbc aes256-cbc aes128-gcm@openssh.com aes256-gcm@openssh.com 3des-cbc (unsafe/deprecated ciphers) Blowfish-cbc (unsafe/deprecated ciphers) Note: You can include unsafe/deprecated ciphers (client/server) explicitly by adding it to the `security.properties` file by referring to the list below: `For SFTP Client Adapter 2.0 #SSHServerCipherList_SSHD=3des-cbc,blowfish-cbc,arcfour128,arcfour256 #SSHClientCipherList_SSHD=3des-cbc,blowfish-cbc,arcfour128,arcfour256` If you do not want to use CBC ciphers, you must set the `supportCBCCiphers` property in `security.properties` to false. The default value is true. To disable CBC ciphers: Stop Sterling B2B Integrator. Modify the `customer_overrides.properties` file to add the following line: `security.supportCBCCiphers=false`. Or, you can add the line `supportCBCCiphers=false` to the `security.properties` file. Start Sterling B2B Integrator. After the CBC ciphers are disabled, they will not be displayed in the Preferred Ciphers field in the SFTP Server Adapter, the SFTP Client Begin Session Service, or the SSH Remote Profile. Note: The value that is entered for this parameter overrides the setting in the SSH Remote Profile configuration. Note: You can also specify the SSH ciphers to be used by updating SSHClientCipherList in the security.properties file. For SFTP Client Adapter 2.0 : You can also specify the SSH ciphers to be used by updating `SSHClientCipherList_SSHD` in the security.properties file. Note: When running in FIPS mode, Sterling B2B Integrator supports SSH Ciphers AES128-CTR, AES192-CTR, and AES256-CTR, as well as SSL/TLS Ciphers AES128-GCM and AES256-GCM.
Important: You cannot configure the SSH Key Exchange algorithms to be used with SFTP in the Sterling B2B Integrator UI. To select strong SSH Key Exchange algorithms, specify the values to be used in SSHKeyExchangeAlgList in the security.properties file. For example, `SSHKeyExchangeAlgList=diffie-hellman-group-exchange-sha1,diffie-hellman-group1-sha1,diffie-hellman-group14-sha1`. You can verify the algorithm used in the SFTP Client Begin Session service status report. Sterling B2B Integrator also supports the following key exchange algorithms: ecdh-sha2-nistp256 ecdh-sha2-nistp384 ecdh-sha2-nistp521 You can set this in the security.properties file as shown below: `SSHKeyExchangeAlgList=ecdh-sha2-nistp256, ecdh-sha2-nistp384,ecdh-sha2-nistp521` The EDCSA keys specified are used only for the duration of the exchange. The host keys used to identify the server can be any of the supported public key types and need not be the ECDSA keys for this key exchange to work. Note: In v6.0, the file `SSHCipherList` is renamed to `SSHClientCipherList` and is present in the `security.properties` file. In v6.0, SFTP Maverick logs are moved to `maverick3sp.logs` instead of `common3splogger.log`. Now, `maverick3sp.logs` are not accessible through the Sterling B2B Integrator user interface, instead can be accessed using the file system. To enable or set the logs into debug mode, you must set the below properties in `logging_maverick.properties` or in `customer.overrides` file. `logging_maverick.log4j.category.com.maverick=DEBUG,serviceFileAppender` `logging_maverick.log4j.rootCategory=DEBUG` `logging_maverick.log4j.appender.serviceFileAppender.Threshold=DEBUG`
PreferredMAC	The MAC the client prefers to use for stream encryption. Required. The following MAC algorithms are supported: hmac-sha2-256 hmac-sha2-512,hmac-sha1 hmac-sha1-etm@openssh.com hmac-sha2-512-etm@openssh.com hmac-sha2-256-etm@openssh.com The following MAC algorithms are not supported: hmac-md5 hmac-sha1-96 hmac-md5-96 Note: The value entered for this parameter overrides the setting in the SSH Remote Profile configuration. Note: You can also specify the SSH MAC algorithms to be used by updating SSHMACAlgList in the security.properties file. For SFTP Client Adapter 2.0: You can also specify the SSH MAC algorithms to be used by updating `SSHMacAlgList_SSHD` in the security.properties file
ProfileId	SSH Remote profile identification. Optional. Valid value is any valid profile ID.
UsingRevealedPasswd (V5.2.5 or later)	Indicates whether the password sent to the service is unobscured. Valid value is True or False. Default is False. Optional.
RemoteHost	External Trading Partner host system (SFTP server IP Address or DNS name. Required if ProfileId is not specified. Use any valid IP Address or DNS name. Note: The value entered for this parameter overrides the setting in the SSH Remote Profile configuration.
RemotePasswd	SFTP remote login password. Either UserIdentityKeyId or RemotePasswd is required if ProfileId is not specified. Note: You can obscure the password using the Obscure service. To reveal the password for the service, use the XPath function 'revealObscured(element), where (element) contains a text value of the obscured password, obtained from the Obscure parameter service. Note: The value entered for this parameter overrides the setting in the SSH Remote Profile configuration.
RemotePort	External Trading Partner port number. Required if ProfileId is not specified. Note: The value entered for this parameter overrides the setting in the SSH Remote Profile configuration.
RemoteUserId	SFTP remote login username. Required if ProfileId is not specified. Note: The value entered for this parameter overrides the setting in the SSH Remote Profile configuration.
ResponseTimeout	The maximum time taken for the trading partner system to respond before the session times out and terminates. The value is specified in seconds. The default value is 30 seconds. Optional. Important: If an input/out error occurs when you run the SFTP Client Begin Session Service, increase the value of the `sshTransportTimeout`property in the `sftp.properties` file. Note: The value entered for this parameter overrides the setting in the SSH Remote Profile configuration.
RetryDelay	Number of seconds the adapter will wait before retrying. Optional. Valid value is any numeric value from 100 to 7200,000 seconds. Note: The value entered for this parameter overrides the Retry Delay setting in the SSH Remote Profile. The minimum value for RetryDelay is 100 seconds.
SFTPClientAdapter	Select the SFTP Client adapter or a group that includes an SFTP Client adapter for this service to use when beginning sessions with an SFTP server. Required.
UserIdentityKeyId	Key pair used to authenticate the remote user to the server. Either UserIdentityKeyId or RemotePasswd is required if ProfileId is not specified. Note: The value entered for this parameter overrides the User Identity Key setting in the SSH Remote Profile configuration.

Output from Service to Business Process

If you provided a ProfileId in the Input from Business Process to Service, the SFTP Client Begin Session service uses the profile information you configured in the SSH Remote Profile to output the profile information to the process data. The following example illustrates the elements of an SSH remote profile in an XML ProcessData:

<ProcessData> 
... 
<TPProfile>
   <ProfileName>...</ProfileName>
   <RemoteHost>...</RemoteHost>
    <RemotePort>...</RemotePort>
   <KnownHostKey>...</KnownHostKey>
   <RemoteUser>...</RemoteUser>
	<PreferredAuthenticationType>...</PreferredAuthenticationType>
   <UserIdentityKey>...</UserIdentityKey>
   <Compression>...</Compression >
   <ConnectionRetryCount >...</ConnectionRetryCount>
   <RetryDelay>...</RetryDelay>
    <ResponseTimeout>...</ResponseTimeout>
   <PreferredCipher>...</PreferredCipher>
   <PreferredMAC>...</PreferredMAC>
   <LocalPortRange>...</LocalPortRange>
   <Directory>...</Directory> 
</TPProfile> 
... 
<ProcessData>

A Business Process can also use the ProcessData element <Directory> in the SFTP Client CD Service to change the configured directory.

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

Parameter	Description
SessionToken	Specifies the identifier for the session established between the SFTP Client adapter and an SFTP server.
SessionStartTime	The date/time stamp for when the session started.
ServerResponse	The SFTP server response, which might include a reply code and any text associated with the reply code. Valid values are: OK - 0 General Failure - 4 Bad Message - 5 No Connection - 6 Connection Lost - 7 Operation Unsupported - 8
ServiceStartTime	The date/time stamp for when the service started.
ServiceEndTime	The date/time stamp for when the service ended.

Business Process Example

The following example business process excerpt illustrates by using the SFTP Client Begin Session service:

<operation name="Obscure Password">
      <participant name="FTPClientObscureParameter"/>
      <output message="outmsg">
        <assign to="." from="*"></assign>
      </output>
     <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
   </operation> 
<operation name="SFTP Client Begin Session Service">
      <participant name="SFTPClientBeginSession"/>
      <output message="SFTPClientBeginSessionServiceTypeInputMessage">
       <assign to="SFTPClientAdapter">SFTPClientAdapter</assign>
       <assign to="RemoteHost">myhost</assign>
		<!-- Using the revealObscured XPath function ‡
       <assign to="RemotePasswd" from="revealObscured(admin)"></assign>
			<assign to="PreferredAuthenticationMethod">password</assign>
       <assign to="RemotePort">21</assign>
       <assign to="RemoteUserId">myname</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="inmsg">
       <assign to="SFTPClientBeginSessionServiceResults" from="*"></assign>
     </input>
    </operation> 
[[Insert SFTP Client End Session]]