Skip to content
Xferity

Tutorial: Your First SFTP Transfer

Tutorial: Your First SFTP Transfer

Section titled “Tutorial: Your First SFTP Transfer”

This tutorial walks you from zero to a running SFTP transfer with operator-visible confirmation.

Time to complete: 20–30 minutes
Prerequisites: an SFTP server you can connect to and test with

What you will build

Section titled “What you will build”

A single SFTP download flow that:

  • picks up files from a remote SFTP directory
  • lands them in a local path
  • tracks processed files to avoid duplicates
  • gives you logs, status, and audit trace after the first run

Step 1: Create the runtime directory layout

Section titled “Step 1: Create the runtime directory layout”

Create the directories Xferity needs:

Terminal window
mkdir -p config flows partners state logs audit storage/inbox keys

Step 2: Create a minimal global config

Section titled “Step 2: Create a minimal global config”

Create config/config.yaml:

flows_path: ./flows
partners_dir: ./partners


storage:
  base_path: ./storage


state:
  backend: file


logging:
  output: file
  file: ./logs/xferity.log
  level: info


audit:
  enabled: true
  path: ./audit/audit.jsonl

Step 3: Create the partner definition

Section titled “Step 3: Create the partner definition”

Create partners/supplier-sftp.yaml:

id: supplier-sftp
display_name: Supplier SFTP
protocol: sftp
sftp:
  host: sftp.supplier.example
  port: 22
  user: xferity-transfer
  remote_dir: /outgoing
  known_hosts: file:./keys/known_hosts
  key_path: file:./keys/supplier_id_rsa

Replace the host, user, and key paths with your actual values.

Generate the known_hosts entry:

Terminal window
ssh-keyscan -H sftp.supplier.example >> ./keys/known_hosts

Verify the fingerprint with your partner out-of-band.

Step 4: Create the flow definition

Section titled “Step 4: Create the flow definition”

Create flows/supplier-inbound.yaml:

flows:
  supplier-inbound:
    direction: download
    enabled: true
    source:
      partner: supplier-sftp
      path: /outgoing
    local:
      path: ./storage/inbox
    files:
      - pattern: "*.xml"
    idempotency_mode: hash

Step 5: Validate the configuration

Section titled “Step 5: Validate the configuration”
Terminal window
xferity validate

If validation passes, you should see no errors. If it fails, read the error message carefully — the YAML parser rejects unknown fields and missing required values explicitly.

Step 6: Run diagnostics

Section titled “Step 6: Run diagnostics”
Terminal window
xferity diag supplier-inbound

Diagnostics check:

  • SSH connectivity to the partner
  • Host key verification
  • Authentication
  • Remote path access

Fix any issues before running the flow.

Step 7: Run the flow once manually

Section titled “Step 7: Run the flow once manually”
Terminal window
xferity run supplier-inbound

Watch the log output. After the run:

Terminal window
# Check current status
xferity flow status


# View the run result
xferity flow history supplier-inbound


# View logs
xferity logs supplier-inbound

Step 8: Verify with audit trace

Section titled “Step 8: Verify with audit trace”

If files were processed, confirm with:

Terminal window
xferity trace invoice-2026-03-15.xml

This returns the lifecycle events for that file from the audit log.

What you have now

Section titled “What you have now”
  • a working SFTP download flow
  • validation and diagnostics passing
  • a confirmed first run in logs and history
  • audit trace for processed files

Next steps

Section titled “Next steps”
  • add scheduling with schedule_cron to poll automatically
  • add notifications.on_failure: true to get alerted on failures
  • add PGP decryption if files are encrypted (see Tutorial: Secure PGP File Delivery)
  • review the Protocols: SFTP page for all configuration options
Section titled “Related pages”