FTP Integration Guide

Overview

The FTP integration allows your NINA workflows to connect with FTP and SFTP servers for file operations. This integration enables you to upload, download, list, delete, and rename files and folders using both standard FTP and secure SFTP protocols.

Status

The integration supports the following core functionalities:

• File Operations: Upload, download, delete, and rename files
• Directory Operations: List directory contents and manage folders
• Protocol Support: Both FTP and SFTP protocols
• Authentication Methods: Basic FTP authentication, SFTP password authentication, and SFTP private key authentication

Credential Configuration

Before using the FTP integration in your workflows, you need to configure credentials for authentication. The NINA platform supports three authentication methods for FTP/SFTP:

Authentication Methods

FTP Basic Authentication

Field	Description	Example
Host	FTP server hostname or IP address	ftp.example.com
Port	FTP server port	21
Username	FTP username	ftpuser
Password	FTP password	********

SFTP Password Authentication

Field	Description	Example
Host	SFTP server hostname or IP address	sftp.example.com
Port	SFTP server port	22
Username	SFTP username	sftpuser
Password	SFTP password	********

SFTP Private Key Authentication

Field	Description	Example
Host	SFTP server hostname or IP address	sftp.example.com
Port	SFTP server port	22
Username	SFTP username	sftpuser
Private Key	Private key in OpenSSH format	-----BEGIN OPENSSH PRIVATE KEY-----...
Passphrase	Passphrase for encrypted private key (optional)	********

Creating an FTP Credential

1. Navigate to the Credentials section in NINA
2. Click Add New Credential
3. Fill in the credential details:
   • Name: A descriptive name (e.g., "Production FTP Server")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "FTP"
   • Choose the authentication method (FTP Basic, SFTP Password, or SFTP Private Key)
   • Fill in the corresponding authentication fields
4. Click Test Connection to verify credentials
5. Click Save to store the credential

Supported Resources and Operations

The FTP integration supports the following resources and operations:

File

Operation	Description
Download	Downloads a file from the FTP/SFTP server
Upload	Uploads a file to the FTP/SFTP server
List	Lists contents of a directory
Delete	Deletes a file or folder
Rename	Renames or moves a file or folder

Parameter Details

Download Operation

Parameter	Type	Required	Description
protocol	string	Yes	File transfer protocol (ftp or sftp)
path	string	Yes	Full path of the file to download
binaryPropertyName	string	Yes	Name of the output binary field for the file

Upload Operation

Parameter	Type	Required	Description
protocol	string	Yes	File transfer protocol (ftp or sftp)
path	string	Yes	Full path where the file will be uploaded
binaryData	boolean	No	Whether to upload binary data or text content
binaryPropertyName	string	Yes	Name of the input binary field containing the file
fileContent	string	No	Text content to upload (if not using binary data)

List Operation

Parameter	Type	Required	Description
protocol	string	Yes	File transfer protocol (ftp or sftp)
path	string	Yes	Path of directory to list
recursive	boolean	Yes	Whether to list contents recursively

Delete Operation

Parameter	Type	Required	Description
protocol	string	Yes	File transfer protocol (ftp or sftp)
path	string	Yes	Full path of the file/folder to delete
options.folder	boolean	No	Whether folders can be deleted
options.recursive	boolean	No	Whether to remove all contents recursively

Rename Operation

Parameter	Type	Required	Description
protocol	string	Yes	File transfer protocol (ftp or sftp)
oldPath	string	Yes	Current path of the file/folder
newPath	string	Yes	New path for the file/folder
options.createDirectories	boolean	No	Whether to create destination directories

Example: File Operations

Downloading a File

Download a file from an FTP server:

{
  "resource": "file",
  "operation": "download",
  "parameters": {
    "protocol": "ftp",
    "path": "/public/documents/report.pdf",
    "binaryPropertyName": "data"
  }
}

Uploading a File

Upload a file to an SFTP server:

{
  "resource": "file",
  "operation": "upload",
  "parameters": {
    "protocol": "sftp",
    "path": "/uploads/document.pdf",
    "binaryData": true,
    "binaryPropertyName": "data"
  }
}

Listing Directory Contents

List contents of a directory:

{
  "resource": "file",
  "operation": "list",
  "parameters": {
    "protocol": "sftp",
    "path": "/public/documents",
    "recursive": false
  }
}

Deleting a File

Delete a file from the server:

{
  "resource": "file",
  "operation": "delete",
  "parameters": {
    "protocol": "ftp",
    "path": "/public/documents/old-file.txt",
    "options": {
      "folder": false,
      "recursive": false
    }
  }
}

Renaming a File

Rename or move a file:

{
  "resource": "file",
  "operation": "rename",
  "parameters": {
    "protocol": "sftp",
    "oldPath": "/public/documents/old-name.txt",
    "newPath": "/public/documents/new-name.txt",
    "options": {
      "createDirectories": true
    }
  }
}

Best Practices

1. Security:

   • Use SFTP instead of FTP when possible for secure file transfers
   • Use private key authentication for SFTP when available
   • Keep credentials secure and rotate them regularly

2. File Operations:

   • Always use absolute paths for file operations
   • Verify file permissions before operations
   • Handle large files with care, considering timeouts and memory usage

3. Error Handling:

   • Implement proper error handling for connection issues
   • Verify file existence before operations
   • Handle permission errors appropriately

4. Performance:

   • Use recursive listing only when necessary
   • Consider file size limits and transfer speeds
   • Implement appropriate timeouts for operations