SFTP Activities

Version: 1.1.0  ·  ID: zoan-packages-sftp  ·  Author: Zoan Software

The SFTP package transfers files securely with a remote server through the SFTP protocol (SSH File Transfer Protocol). It is widely used in business-to-business integrations: uploading files to a server (a batch of invoices for a vendor), downloading files left there (bank reports), or managing remote folders. It needs no client installed on the robot’s machine, so it also works in unattended execution.

Concept 1: the session

All operations work on a session that you open with SFTP Connect and share with the other activities. A single connection serves every transfer, without signing in again for each file:

• With body: the activities inside inherit the session; at the end (also if something fails) the connection closes by itself.
• Without body: you store the session in a variable, pass it as session and close it with SFTP Close.

Unlike the mail packages, here the session is mandatory: an SFTP activity outside the Connect body and without session fails with 'session' must be a ZoanSftpSession.

SFTP Connect   host = "sftp.vendor.com"   username = "zoan"   password = credential("sftp-vendor")["password"]
 └─ body:
      SFTP Upload   localPath = localFile   remotePath = "/inbound/invoice.xml"

Concept 2: authentication

SFTP supports two ways to authenticate (choose one in SFTP Connect):

Method	How
Password	password parameter with a credential — credential("sftp-vendor")["password"].
Private key	privateKeyPath parameter with the path to your key (.pem / OpenSSH) on the robot’s machine, plus privateKeyPassphrase if it is encrypted. When privateKeyPath is set, the key is used and password is ignored.

Do not write the password in plain text

Use a Zoan Cloud credential for the password or the key passphrase. See Security.

Server fingerprint

The fingerprint (host key) identifies the server. Set it in the hostKeyFingerprint parameter of SFTP Connect and the robot only connects to that server: if another one impersonates it (a man in the middle), the connection is refused before the username or password are sent. Since version 1.1.0.

• How to get it: connect once without a fingerprint; the log shows a warning with the received fingerprint (SHA256:…), copy it into the parameter. The server administrator can also give it to you (ssh-keygen -lf on the server’s public key).
• Without a fingerprint: whatever server answers is accepted, as in earlier versions, and its fingerprint is written to the log.
• If the server changes its key legitimately, the connection fails with an error showing the expected and the received fingerprint: update the parameter.

Remote paths

Server paths use forward slashes /: /inbound/data.csv, /outbound/reports/. A path without a leading / is relative to the user’s home folder on the server. Do not confuse them with local paths (on the robot’s machine), which go in localPath.

Activities

Session

Activity	Type	Output	What it does
SFTP Connect	sftp-connect	ZoanSftpSession	Connects to the SFTP server
SFTP Close	sftp-close	—	Closes the connection

Transfer

Activity	Type	Output	What it does
SFTP Upload	sftp-upload	string	Uploads a local file to the server
SFTP Download	sftp-download	string	Downloads a file from the server

Manage files and folders

Activity	Type	Output	What it does
SFTP List Directory	sftp-list	List<object>	Lists remote files and folders
SFTP Exists	sftp-exists	bool	Does a file/folder exist?
SFTP Move / Rename	sftp-move	string	Moves or renames a remote file
SFTP Delete	sftp-delete	—	Deletes a remote file
SFTP Create Directory	sftp-mkdir	—	Creates a remote folder

Next steps

• SFTP Connect — connect to the server.
• SFTP Download / SFTP Upload — transfer files.
• Files — manage local files.