SFTP Connect

SFTP Connect

Type: sftp-connect  ·  Package: SFTP Activities v1.1.0  ·  Output: ZoanSftpSession

Connects to an SFTP server and returns a session shared by the other activities. It is the starting point of any transfer: you authenticate once and run every operation over the same connection.

How it works

Connects to host:port (port 22 by default) with username and the chosen authentication:

• Private key: if privateKeyPath has a value, that key file is loaded (with privateKeyPassphrase if it is encrypted) and used to authenticate; password is ignored.
• Password: if there is no privateKeyPath, password is used.

Before authenticating it checks the server fingerprint (see Server fingerprint):

• With hostKeyFingerprint: if the fingerprint the server presents is not that one, the connection is refused and no credentials are sent.
• Without hostKeyFingerprint: the server is accepted and the log shows a warning with its fingerprint (SHA256:…) so you can copy it into the parameter.

Two modes:

• With body: the activities inside inherit the session; at the end it closes by itself, also when an activity in the body fails.
• Without body: returns the session as output; pass it as session to the activities and close it with SFTP Close.

Required parameters

Parameter	Type	Default	Description
host	string	—	SFTP server (name or IP).
username	string	—	SSH username.

Optional parameters

Parameter	Type	Default	Description
port	int	22	SSH port. A value that is not an integer is treated as 22.
password	credential	—	Password, for password authentication. Use credential("name")["password"]. Required if you do not set privateKeyPath.
privateKeyPath	string	—	Local path to the private key file (.pem / OpenSSH format), for key authentication.
privateKeyPassphrase	credential	—	Private key passphrase, only if the key is encrypted.
hostKeyFingerprint	string	—	Expected SHA256 fingerprint of the server, as ssh-keygen -lf shows it (e.g. "SHA256:jK3Qe7lY0b6n1tXrA9wFZ2hVcM5pD8uS4oGiE0yT1aQ"). The full ssh-keygen line or the value without SHA256: are also accepted. If it does not match, the connection is refused. Empty: the server is accepted and its fingerprint is written to the log. Since version 1.1.0.

Sub-flows

body

Optional. Activities run with this connection; they inherit it without setting session. On exit (success or error) the connection is closed. If the body is empty, the activity returns the session as output.

Output

• Without body: returns a ZoanSftpSession. Pass it as session to the other activities and close it with SFTP Close.
• With body: does not return a value (the session only exists inside the body).

Common errors

Message	Cause and fix
'host' is required. / 'username' is required.	The parameter is missing or the expression returned null.
Parameter 'password' is of type 'credential' but the value was null. Verify the credential exists in the configured store.	You set neither privateKeyPath nor a valid password (or the credential does not exist). Provide one of the two methods.
SSH authentication error (permission denied)	Wrong username, password or key, or the server does not accept that method. Confirm with the server administrator.
Error reading the key file	privateKeyPath does not exist, the format is not supported, or the key is encrypted and privateKeyPassphrase is missing (or wrong).
The fingerprint of server … does not match the expected one: expected … the server presented ….	The server presented another key. It may be a man in the middle: do not ignore it. If the administrator confirms the key changed, update hostKeyFingerprint.
'hostKeyFingerprint' is not a SHA256 fingerprint. …	The value is not SHA256: + 43 characters. Copy it as it appears in the log warning or in ssh-keygen -lf.
Connection error (unknown host, connection refused or timeout)	Wrong host or port, or a firewall blocks the port from the robot’s machine. Wrap it in a Retry if the server has occasional outages.

Example

With a password, downloading inside the body:

SFTP Connect   host = "sftp.vendor.com"   username = "zoan"   password = credential("sftp-vendor")["password"]
 └─ body:
      SFTP Download   remotePath = "/outbound/report.csv"   localPath = "C:/downloads/report.csv"   → output: file
      Read CSV   path = file   → output: data

With an encrypted private key, storing the session in a variable:

SFTP Connect   host = "sftp.bank.com"   port = 2222   username = "integration"
               privateKeyPath = "C:/keys/integration.pem"   privateKeyPassphrase = credential("sftp-key")["password"]
               hostKeyFingerprint = "SHA256:jK3Qe7lY0b6n1tXrA9wFZ2hVcM5pD8uS4oGiE0yT1aQ"
               → output: sftp
SFTP Upload    session = sftp   localPath = "C:/outbound/batch.csv"   remotePath = "/inbound/batch.csv"
SFTP Close     session = sftp

Related activities

• SFTP Close — close the connection (mode without body).
• SFTP Upload / SFTP Download — transfer files.