Source content conversion#

When performing a transfer, SFTPPlus can convert the content of the source file and write the transformed content to the destination while keeping the source file unchanged.

The conversion happens as the file is transferred, without loading the whole file into memory.

Configuring content conversion#

Use the destination_content_actions configuration option to define conversion rules. Each rule is a comma-separated list with a path-matching expression, an action, and an optional parameter. Define each rule on a separate line.

Rules are checked in order against the source path relative to source_path. The first matching rule is applied. When no rules are configured, files are transferred without changing their content. When rules are configured but none matches a file, its transfer fails. Add *, no-action as the final rule to transfer all other files unchanged.

The supported actions are:

  • encoding - Changes the character encoding of a text file. Its parameter selects one of the conversions listed below.

  • no-action - Keeps the original content. This action has no parameter.

For details on path matching, see the matching expression documentation.

Supported encoding conversions#

The following values are supported as the parameter for the encoding action:

  • utf-16-to-ascii - Converts UTF-16 to ASCII. The transfer fails if the source contains characters outside ASCII.

  • ascii-to-utf-16 - Converts ASCII to UTF-16 with a little-endian byte order mark (BOM).

  • utf-16-to-utf-8 - Converts UTF-16 to UTF-8 without a BOM.

  • utf-16-to-utf-8-bom - Converts UTF-16 to UTF-8 with a BOM. Available from version 6.2.0.

  • utf-8-to-utf-16 - Converts UTF-8 to UTF-16 with a little-endian BOM.

  • utf-8-to-iso-8859-15 - Converts UTF-8 to ISO-8859-15, also known as Latin-9. The transfer fails if a character cannot be represented in ISO-8859-15.

  • iso-8859-15-to-utf-8 - Converts ISO-8859-15 to UTF-8 without a BOM.

  • iso-8859-15-to-utf-8-bom - Converts ISO-8859-15 to UTF-8 with a BOM. Available from version 6.2.0.

UTF-16 source files can use either little-endian or big-endian byte order when a BOM is present. If the source has no BOM, SFTPPlus assumes little-endian byte order. Get in touch with us if you need to handle big-endian UTF-16 as the default encoding.

Invalid or incomplete source characters cause the transfer to fail. ISO-8859-15 accepts every byte value, so SFTPPlus cannot detect whether a file declared as ISO-8859-15 actually uses another encoding.

UTF-8 output with a BOM starts with the three bytes EF BB BF. The BOM is written once at the beginning of each destination file, including an empty source file.

Converting UTF-16 to ASCII#

Below is an example for configuring a transfer to upload a source file with UTF-16 encoding by writing the content on the remote location using ASCII encoding:

[transfers/313a9679-bc15-42e9-80ef-e2305959a3d1]
enabled: yes
name: copy-utf16-remote-ascii

recursive: no
source_path: /out/sales
source_filter: *
delete_source_on_success: No

destination_uuid: 5f304286-8d56-41f9-ba57-420a2303e90c
destination_path: /Outbox/

destination_content_actions:
  *.txt, encoding, utf-16-to-ascii
  *, no-action

With the above configuration, a file named /out/sales/Report.txt that is stored on the source disk as UTF-16 is transferred to /Outbox/Report.txt as ASCII content, while the source file is kept as UTF-16.

A file named /out/sales/Report.pdf is transferred to the destination, having the exact content as the source file:

/out/sales/Report.pdf          -> /Outbox/Report.pdf with unmodified content.
/out/sales/Report.txt          -> /Outbox/Report.txt with ASCII encoding.

Converting to UTF-8 with a BOM#

Some applications require a BOM to recognize UTF-8 text. For example, to convert UTF-16 .txt files and ISO-8859-15 .csv files to UTF-8 with a BOM, while keeping all other files unchanged:

destination_content_actions:
  *.txt, encoding, utf-16-to-utf-8-bom
  *.csv, encoding, iso-8859-15-to-utf-8-bom
  *, no-action