EldoS | Feel safer!

Software components for data protection, secure storage and transfer

Customizing SFTP / FTPS connection flow with command scripts

When working in default configuration, BizCrypto transport components, such as SFTP and FTPS adapters, stick to standard pre-defined connection flows. A standard algorithm utilized by the receive components is to set up a connection to server, ask for a list of files, download those matching the mask, and then close the connection. Although this straightforward algorithm works like a charm in the majority of use cases, certain environments may need special handling. For instance, a server may require the clients to apply certain attributes to files after downloading or uploading them. Another common requirement is to move files to a different location after the download is complete. A "standard" automated algorithm can hardly anticipate and satisfy all the variety of requirements, and that's why we have introduced a flexible mechanism of customizing connection flows for "non-standard" environments.

Transport connections made by BizCrypto components can be viewed as a sequences of logical steps. Basically, the component (1) connects to the server, (2) authenticates, (3) optionally requests a directory listing, then (4) downloads or uploads files one-by-one, and finally (5) closes the connection. BizCrypto components allow the user to intrude to the default connection flow by supplying custom commands to be executed between the steps.

Custom commands can be supplied by the user with the means of so-called command scripts. Command script is an instruction to the component (e.g. adapter) that directs which commands and in what sequence should be executed. The components publish a number of On* properties (e.g. On Before Receive), allowing to supply different command scripts for different stages of the connection.

The below tables list the On* properties supported by each of the transport components:


Property

Stage of the connection

Number of stages per connection

SFTP receive adapter

On Before Transfer

Before downloading files

Once per connection

On After Transfer

After all files have been downloaded

Once per connection

On Before List

Before requesting a file listing from server

Once per remote directory

On After List

After the listing has been received

Once per remote directory

On Before Receive

Before downloading a file

Once per every downloaded file

On After Receive

After the file has been downloaded

Once per every downloaded file

SFTP transmit adapter

On Before Transfer

Before uploading files

Once per connection

On After Transfer

After all the files have been uploaded

Once per connection

On Before Send

Before uploading a file

Once per every uploaded file

On After Send

After the file has been uploaded

Once per every uploaded file

FTPS receive adapter

On After Open

After TCP connection to server has been opened

Once per connection

On After Login

After the user has been authorized on the server

Once per connection

On After CCC

After CCC command has been sent

Once per connection (optional)

On Before List

Before requesting a file listing from server

Once per remote directory

On After List

After the listing has been received

Once per remote directory

On Before Receive

Before downloading a file

Once per every downloaded file

On After Receive

After the file has been downloaded

Once per every downloaded file

On Before Close

Before closing the connection

Once per connection

FTPS transmit adapter

On After Open

After TCP connection to server has been opened

Once per connection

On After Login

After the user has been authorized on the server

Once per connection

On After CCC

After CCC command has been sent

Once per connection (optional)

On Before Send

Before uploading a file

Once per every uploaded file

On After Send

After the file has been uploaded

Once per every uploaded file

On Before Close

Before closing the connection

Once per connection

Writing command scripts: FTPS components

FTP components accept command scripts in two different formats: XML and simplified.

XML command scripts

The general syntax for XML command scripts accepted by FTPS components has the following look:

<commands>
<command type="ftp" value="command1" acceptCodes="code1;code2;..." stopOnFailure="yes|no" />
<command type="ftp" value="command2" acceptCodes="code1;code2;..." stopOnFailure="yes|no" />
...
</commands>

The main commands tag enumerates the commands, in order, to be sent to the server on particular connection stage. The below table explains the meaning of the parameters of the command tag:

type

Command type. The only value supported at the moment is "ftp", meaning that an FTP protocol command is supplied in the value parameter of the tag.

value

An FTP protocol command. The list of commands supported by FTP is available in RFC959. Only commands utilizing the control channel are supported at the moment.

acceptCodes

A list of comma- or semicolon-separated command execution codes that will be considered successful by the component. Command execution code is returned by the server in response to every command requested by the client.

stopOnFailure

Either "yes" or "no", stating whether the component should treat a command execution code not listed in acceptCodes as an erroneous situation.

Example: to rename a file after upload, assign the below command script to the On After Send property:

<commands>
<command type="ftp" value="RNFR %MessageID%.tmp" acceptCodes="350" stopOnFailure="yes" />
<command type="ftp" value="RNTO %MessageID%.xml" acceptCodes="250" stopOnFailure="yes" />
</commands>

Simplified command scripts

FTPS components also support simplified command scripts where the result of commands execution is not essential. A simplified command script is a basic enumeration of commands to execute separated by commas:

command1,command2,...

A script corresponding to the above example will have the following look:

RNFR %MessageID%.tmp,RNTO %MessageID%.xml

Please note that no error handling is available with simplified command scripts. All command execution codes (even those indicating an error!) are accepted by the adapter and do not affect further connection flow.

Writing command scripts: SFTP components

SFTP components only support command scripts in XML form. The general syntax for command scripts accepted by SFTP components is shown below:

<commands>
<command type="sftp" value="command 1" … params … />
<command type="sftp" value="command 2" … params … />
...
</commands>

Unlike FTP, SFTP specification does not envisage commands in human-readable form. This way, the SFTP components support a limited set of pre-defined commands that are translated to SFTP-compliant format before they are sent to the server.

Command

Description and parameters

copyremotefile

Copies a file remotely from one remote location to another. This functionality is only available in SFTP version 5 and above, and is not supported by the majority of servers.


Parameters:

source: path to the file to copy

dest: path to the destination location (including the name of the destination file)

createsymlink

Creates a symbolic link.


Parameters:

linkpath: path to new symbolic link

targetpath: path to the link's target

createhardlink

Creates a hard link.


Parameters:

linkpath: path to new hard link

targetpath: path to the link's target

makedir

Creates a directory on server.


Parameters:

dir: path to the directory to create

removedir

Removes a directory on the server.


Parameters:

dir: path to the directory to remove

recursive: (true | false) specifies if subdirectories are to be deleted as well

removefile

Removes a file on server.


Parameters:

file: path to the file to remove

renamefile

Renames or moves a remote file.


Parameters:

srcfile: path to the source file ("old name")

destfile: path to the destination file ("new name")

abspath

Obtains a canonical representation for a remote path. This command has been introduced mainly as a workaround for a set of known server-side issues and has little practical sense in other cases.


Parameters:

path: path to request a canonical representation for

touch

Creates an empty file with the specified remote path.


Parameters:

file: path to the file to create

Example. To rename a file after upload, assign the below command script to the On After Send property:

<commands>
<command type="sftp" value="renamefile" srcfile="./path/%MessageID%.tmp" destfile="./path/%MessageID%.xml" />
</commands>

Command scripts are a powerful instrument of customizing transport connection flows in "non-standard" environments. Haven't found the command you need in the above list? No problem – every environment is different and often there is no way to anticipate which command(s) will be demanded.

Feel free to contact us, and we will consider extending BizCrypto with support for the particular command you need to use in your business application.

Return to the list

|

Back to top

As of July 15, 2016 EldoS Corporation will operate as a division of /n software inc. For more information, please read the announcement.

Got it!