FTP
Upload and download files via FTP, FTPS, or SFTP.
The FTP action can upload and download files via FTP, FTPS, or SFTP. The files to be uploaded are evaluated using file generators. Downloaded file data is available either as an UTF-8 string, or as a base64-encoded string, and can be used in followup task runs via mechanic/actions/perform.
A connecting service like Couchdrop can be used to relay these uploads on to other cloud locations, like Dropbox, Google Drive, and Amazon S3.
A single FTP action may download a maximum of 20MB of data, across all downloaded files.
Options
General options
Option | Type | Notes |
---|---|---|
|
| The protocol to use for connection; inferred if omitted |
| String, required | The hostname or IP address of the destination server |
| Number, optional | The server port to connect to |
| String, required | The username for authentication |
| String, optional | The password for authentication |
| Hash, optional | An object whose keys are file paths (relative or absolute), and whose values are file generators |
| Array, optional | File path strings (relative or absolute) to download |
FTP options
Option | Type | Notes |
---|---|---|
| String, optional | May be set to |
FTPS options
Option | Type | Notes |
---|---|---|
| Boolean, optional | May be set to |
SFTP options
Option | Type | Notes |
---|---|---|
| String, optional | A complete PEM-formatted private key for authentication |
| Boolean, optional | May be set to |
| String, optional | An sshd-compatible known_hosts file (docs, helpful article) |
User authentication
The user
option is always required.
When connecting to an FTP or FTPS server, authenticate with the password
option.
When connecting to an SFTP server, authenticate using either password
or private_key_pem
, or both. PEM certificates may be given directly in the task code:
Uploads and downloads
Both uploads
and downloads
allow the task author to define file paths. If only the filename is given (e.g. "sample.pdf"
), the file will be resolved in the home directory of the user. If a relative path (e.g. "subdirectory/sample.pdf"
) or absolute path (e.g. "/tmp/sample.pdf"
) is given, it will be respected accordingly.
Each individual file operation (i.e. each upload or download) will be attempted a maximum of 3 times within the FTP/FTPS/SFTP session, retrying if an error occurs during upload or download.
Example
This example action results in (a) an upload to an absolute path, starting from the server root, (b) an upload to a nested directory within the user's home folder, and (c) an upload to a nested directory in another user's home folder (which may fail, depending on filesystem permissions).
Result
In Mechanic, actions are performed after their originating task run concludes. Actions are not performed inline during the task's Liquid rendering.
To inspect and respond to the results of an HTTP action, add a task subscription to mechanic/actions/perform, allowing the action to re-invoke the task with the action result data.
Learn more: Responding to action results
An FTP action returns the following data structure, most useful in combination with mechanic/actions/perform (see Responding to action results):
Note that each uploaded and downloaded file is keyed by the path provided for that file in the action's options. Downloaded file data is available as a UTF-8 string; for binary data that cannot be represented in UTF-8, use the base64-encoded version, possibly in concert with the decode_base64 filter.
Testing
If a server is unavailable for testing, consider using Couchdrop, with their hosted storage service. This is a (nearly) configuration-free avenue for testing, using my.couchdrop.io for FTP, FTPS, or SFTP.
Alternatively, ngrok can be used to create a public tunnel to a local FTP or SSH server. By running ngrok tcp 22
(adjusting for the appropriate local port), ngrok will generate a temporary public host and port that's appropriate for use while testing.
Uploads are processed before downloads; it can be useful to test by uploading a file, and then immediately downloading it again:
Example
This task compiles all SKUs with their titles and prices, and uploads it as a CSV every night or on demand.
Last updated