SFTP uploads

Learn how to automate product data imports by uploading CSV files via SFTP to Axiom's managed server.

Overview​

SFTP (Secure File Transfer Protocol) uploads allow suppliers to automate product data imports by placing CSV files directly on an Axiom-managed SFTP server. Files uploaded via SFTP are automatically detected and processed, eliminating the need for manual uploads through the web interface or API calls.

This feature is ideal for suppliers who:

• Require scheduled or automated data synchronisation
• Have existing systems that export product data regularly
• Prefer file-based integration over API-based integration
• Need to update large catalogues on a regular basis

How SFTP uploads work​

When you upload a file to your SFTP account:

1. The file is placed in a specific directory based on the import type (for example, product-csv for product imports)
2. Axiom's monitoring system detects the new file within minutes
3. The system automatically validates and processes the file
4. You receive notifications about the import status (success or failure)
5. Any errors are logged and available in your File uploads history

Files are monitored continuously and processed automatically. There is no need to trigger imports manually.

Setting up an SFTP account​

Prerequisites​

Before using SFTP uploads, you need:

• An SFTP account created by your Axiom administrator or support team
• An SSH key pair (public and private keys)
• Your SFTP connection details (hostname and username)

Generating SSH keys​

If you do not already have an SSH key pair, you can generate one using the following commands:

On Linux or macOS:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

On Windows (using PowerShell):

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

This creates two files:

• ~/.ssh/id_rsa – your private key (keep this secure, do not share)
• ~/.ssh/id_rsa.pub – your public key (provide this to your Axiom administrator)

Requesting an SFTP account​

To set up SFTP access:

1. Generate your SSH key pair using the instructions above
2. Send your public key file (id_rsa.pub) to your Axiom administrator or support contact
3. Provide your preferred username for the SFTP account
4. Your administrator will create the account and provide you with the connection details:
   • Hostname – The SFTP server address
   • Username – Your SFTP account username
   • Port – Typically 22 (standard SFTP port)

Important notes:

• Never share your private key with anyone, including Axiom support
• Keep your private key file secure with appropriate permissions
• Your username must be unique within your organisation

Connecting to your SFTP account​

Once your SFTP account is created, you can connect using any SFTP client or command-line tool.

Using the command line​

sftp -i ~/.ssh/id_rsa your-username@your-sftp-hostname

Replace your-username and your-sftp-hostname with the details provided by your administrator.

Using FileZilla or other SFTP clients​

1. Open your SFTP client
2. Create a new connection with the following settings:
   • Protocol: SFTP (SSH File Transfer Protocol)
   • Host: Your SFTP hostname (provided by your administrator)
   • Port: 22
   • Username: Your SFTP username
   • Authentication method: Key file
   • Key file: Path to your private key file (for example, ~/.ssh/id_rsa)
3. Connect to the server

Supported import types and directory structure​

Files must be placed in specific directories based on the type of import. The system automatically detects the import type based on the directory name.

Supported directories​

Directory structure example​

When you connect to your SFTP account, you will see the following structure:

/
├── product-csv/
├── price-list-csv/
├── product-stock-csv/
├── recommendation-rule-csv/
├── restrict-product/
└── service-csv/

Uploading files​

File format requirements​

• Files must be in CSV format
• Files must include all required headers for the import type
• Files should use UTF-8 encoding
• File names can be anything (for example, products_2024_12_14.csv)

Upload process​

1. Connect to your SFTP account
2. Navigate to the appropriate directory for your import type
3. Upload your CSV file to that directory
4. The file will be automatically detected and processed within a few minutes

Example using command line:

# Connect to SFTP
sftp -i ~/.ssh/id_rsa your-username@hostname

# Navigate to the appropriate directory
cd product-csv

# Upload your file
put /path/to/your/products.csv

# Exit
bye

Example using FileZilla:

1. Connect to your SFTP account
2. Navigate to the appropriate directory in the remote site panel
3. Drag and drop your CSV file from your local computer to the remote directory

What happens after upload​

Once a file is uploaded:

1. Axiom's monitoring system detects the new file (typically within 1-5 minutes)
2. The file is validated against the required format
3. If validation passes, the import begins processing
4. You can monitor progress in the File uploads section of your supplier dashboard
5. Upon completion, you receive a notification with the import results

Monitoring import status​

You can monitor the status of your SFTP uploads through the Axiom supplier dashboard:

1. Navigate to the File uploads section in your supplier dashboard
2. View all import jobs, including those triggered via SFTP uploads
3. Each file upload shows:
   • Import status (pending, processing, completed, error)
   • Number of records processed
   • Number of successful imports
   • Number of errors
   • Option to download error details

Identifying SFTP-triggered imports​

SFTP-triggered imports are identified by:

• The import type shows the context (for example, "product import csv uploaded")
• The original filename matches the file you uploaded

Email notifications​

You will receive email notifications when:

• An import completes successfully
• An import fails due to validation errors
• An import encounters critical issues

Handling errors​

Common errors​

Downloading error reports​

If an import fails, you can download detailed error information from the File uploads section of your dashboard. The error report includes:

• Line number where the error occurred
• Field that caused the error
• Error message explaining what went wrong
• Suggested corrections for common issues

File cleanup​

Automatic cleanup​

Files that are placed in unsupported directories (directories that do not match the supported import types) are automatically deleted by Axiom's cleanup process. This prevents the accumulation of incorrectly placed files.

Supported files retention​

Files placed in supported directories remain on the server after processing. However, subsequent uploads of files with the same name will overwrite previous files.

Best practices​

1. Use descriptive filenames: Include dates or version numbers in your filenames (for example, products_2024_12_14.csv)
2. Test with small files first: When setting up SFTP uploads for the first time, test with a small sample file to ensure everything works correctly
3. Monitor the first few imports: Check the File uploads history to ensure your files are being processed as expected
4. Keep your SSH keys secure: Never share your private key. Store it in a secure location with appropriate file permissions
5. Validate files before upload: Run your own validation checks before uploading to catch errors early
6. Use consistent directory names: Always use the exact directory names listed in the supported directories table
7. Schedule uploads during off-peak hours: If uploading large files, consider scheduling uploads when system load is lower
8. Maintain file format consistency: Use the same CSV structure and headers across all uploads

Troubleshooting​

Cannot connect to SFTP server​

Check the following:

• Ensure you are using the correct hostname from the SFTP account details
• Verify your SSH private key matches the public key registered with Axiom
• Confirm the username is correct
• Check that port 22 is not blocked by your firewall

Files are not being processed​

Check the following:

• Ensure the file is placed in a supported directory
• Verify the file is a valid CSV with the correct headers
• Wait up to 5 minutes for the monitoring system to detect the file
• Check the File uploads section in your dashboard for any error messages

Import completed with errors​

What to do:

• Download the error report from the File uploads section of your dashboard
• Review the specific errors for each failed row
• Correct the data issues in your source file
• Re-upload the corrected file

Authentication issues​

If you receive authentication errors:

• Verify you are using the correct username and hostname
• Ensure your private key file has the correct permissions (typically chmod 600 ~/.ssh/id_rsa on Linux/macOS)
• If issues persist, regenerate your SSH key pair and send the new public key to your Axiom administrator
• Contact support if authentication continues to fail

Security considerations​

• Private keys: Never share your SSH private key with anyone, including Axiom support. Treat it like a password
• Key permissions: On Linux/macOS, ensure your private key file has restricted permissions (chmod 600 ~/.ssh/id_rsa)
• Key rotation: Periodically rotate your SSH keys by generating a new key pair and providing the new public key to your administrator
• Access control: Only authorised personnel should have access to SFTP credentials
• Secure storage: Store private keys in a secure location, such as a password manager or encrypted storage
• Connection security: Always connect using SFTP (port 22), never use insecure FTP