External transfer commands

SFTPPlus can run local executables or scripts before or after a transfer. It can also execute file management commands at the destination location.

This page describes both types of commands and their configuration options. For other transfer settings, see the transfers configuration reference.

Executing commands using pre/post transfer executables or scripts

Use the following options to run an executable or script on the computer running SFTPPlus:

• execute_before - Runs before processing a source file.

• execute_after_success - Runs after a successful transfer.

• execute_after_failure - Runs after a failed transfer.

Configure the path to the executable or script without command line arguments. Use a wrapper script when you need additional arguments or multiple commands.

In the following example, SFTPPlus copies files from a local source to a local destination. It checks for changes every 5 seconds and waits for 10 seconds without changes before transferring a file. The timestamp-always overwrite rule adds a timestamp to the destination file name. After each successful transfer, SFTPPlus runs the local after-success.bat script.

For example, the script can create a ZIP archive, add a date to its name, and move it to another directory:

[transfers/7db823d8-05f8-4481-be98-b87a826ded28]
enabled = Yes
name = inbox-transfer
description = Transfer Inbox files.
source_uuid = local-file-system-source-uuid
source_path = C:\acme\sftpplus\accounting\inbox
delete_source_on_success = No
destination_uuid = local-file-system-destination-uuid
destination_path = C:\acme\sftpplus\accounting\inbox-final
execute_after_success = C:\acme\sftpplus\transfer-jobs\after-success.bat
stable_interval = 10
changes_poll_interval = 5
overwrite_rule = timestamp-always
batch_interval = 0
retry_count = 0
retry_wait = 0

For individual transfers, commands run separately for each file. For batch transfers, commands run once for the batch. The option descriptions below explain which file path is passed to each local command.

Executing pre-/post- transfer destination commands

Use the following options to execute file management commands at the destination location:

• execute_on_destination_before - Runs before the transfer.

• execute_on_destination_after_success - Runs after a successful transfer.

• execute_on_destination_after_failure - Runs after a failed transfer.

These commands use the embedded SFTPPlus client-shell, which is already connected to the destination location. Use commands supported by the client-shell, such as rename and delete.

To list available commands, start the interactive client-shell and run:

> help

To find out more about a particular command, run:

> help COMMAND_NAME

Configure the commands in the transfer's Execute transfer commands section in Web Manager, or in the text configuration file. Separate multiple commands with semicolons or place each command on a separate indented line:

[transfers/99feb83f-a99d-42f1-a86c-1562c3281bb6]
name = transfer_sample
execute_on_destination_before =
    rename /path-to /path2
    delete /path3
execute_on_destination_after_success = rename /path1 /path4; delete /path5

For batch transfers, destination commands run once for the batch.

execute_timeout

Default value:

30

Optional:

Yes

From version:

4.11.0

Values:

• Number of seconds

Description:

This defines the time interval in seconds allowed for the execution of external commands. If the external command is still running after the configured duration, it's automatically terminated with an error.

When defined with a value less than or equal to zero, the default timeout value is used.

execute_before

Default value:

Empty

Optional:

Yes

From version:

2.7.0

Values:

• Path to a local script or executable to call before a file is transferred.

• Empty

Description:

The executable is called with the full path to the file that is about to be transferred.

This should be configured only with the path and without any other command line arguments. You can use a wrapping script/batch file to have the executable called with a set of default arguments or to call multiple executables.

The following environment variables are also set:

• SOURCE_PATH - is set to the source path of the processed file.

• DESTINATION_PATH - is set to the path on the destination for the file. (Since: 3.20.0)

For batch transfers, only the first file from the batch is sent as an argument.

The transfer continues only if the command's exit code is 0. When the exit code is not 0, the file is not transferred, and no other actions are performed for this transfer.

When the source location is remote and the destination is a local location, the command is called with a path that does not exist yet, as this is executed before the actual transfer takes place.

Note

On Windows, executables located in Unicode paths and monitored Unicode paths are not yet supported.

Note

Remote-to-remote transfers are not supported.

Leave it empty to disable command execution before a transfer.

execute_after_success

Default value:

Empty

Optional:

Yes

From version:

2.9.0

Values:

• Path to a local script or executable to call after a file is successfully transferred.

• Empty

Description:

Please see the description of the execute_before configuration option.

For batch transfers, the command is called with the path of the last file from the batch.

The command is not called when execute_before fails.

execute_after_failure

Default value:

Empty

Optional:

Yes

From version:

2.9.0

Values:

• Path to a local script or executable to call after a file fails to be transferred.

• Empty

Description:

Please see the description of the execute_before configuration option.

For batch transfers, the command is called with the path of the last file from the batch.

This is called once, after all retries have been executed. The command is not called if execute_before fails.

execute_on_destination_before

Default value:

Empty

Optional:

Yes

From version:

3.0.0

Values:

• List of commands to be executed in the destination location.

• Empty

Description:

Before starting the transfer of a file or a batch, execute in the destination location the list of configured commands.

Define each command on a separate line or separate commands with a semicolon (;).

You can use the following variables inside the commands:

• {source.path} - the full path on the source location

• {source.name} - the full file name on the source location

• {destination.path} - the full path on the destination location

• {destination.name} - the full file name on the destination location

The commands are executed using an embedded client-shell. The shell is already connected to the destination location. There is no need for an explicit open command. For the list of supported commands, please check the client-shell documentation.

The transfer continues only if the commands are successful. When one of the commands fails, the file is not transferred, and no other actions are completed for this transfer.

Note

If you need to execute more commands in the remote location, or you cannot implement your workflow using the available commands, contact us.

execute_on_destination_after_success

Default value:

Empty

Optional:

Yes

From version:

3.0.0

Values:

• List of commands to be executed in the destination location.

• Empty

Description:

See the description of the execute_on_destination_before configuration option.

The commands are executed if the file or the batch has been successfully transferred.

execute_on_destination_after_failure

Default value:

Empty

Optional:

Yes

From version:

3.0.0

Values:

• List of commands to call after a file fails to be transferred.

• Empty

Description:

See the description of the execute_on_destination_before configuration option.

The commands are executed if the file or the batch transfer has failed.