Skip to main content
This document covers SFTP-backed File Import triggers. This is not an on-demand agent tool: the trigger polls a selected remote folder and starts a new task when it claims a previously unseen file.

​
Connection setup

Create an SFTP integration with:
  • host and port (22 by default)
  • username
  • auth_method: password or private_key
  • the matching password, or PEM private key and optional passphrase
  • base_path: an absolute inbox path such as /incoming
The first successful connection validation captures the server’s SHA256 host-key fingerprint. Later browse and polling connections require that persisted fingerprint and reject a changed server key. Credentials are stored in the integration configuration and are never shown as a per-run input. SFTP operations emit host-only external_call audit events; remote paths and credentials are not included in those events.

​
Trigger setup

  1. Add a File Import trigger to the agent.
  2. Select the SFTP connection.
  3. Choose a folder at or beneath its configured base_path.
  4. Choose a polling interval. SFTP defaults to 60 seconds; the supported range is 10 seconds to 24 hours.
The folder picker cannot browse or create paths outside base_path.

​
Polling and deduplication

  • The first poll records files already present as the baseline; it does not start tasks for them.
  • Later polls list all regular files directly inside each watched folder. Subfolders are not traversed recursively—watch each required folder explicitly.
  • Deduplication uses the remote absolute path as the file’s external ID. Replacing a file at an already-imported path does not import it again; producers should use unique filenames when each delivery must start a task.
  • SFTP modification times are not used as a cursor. Backdated files uploaded after setup are still discovered.
  • At most 50 files are processed per poll; remaining files are picked up by later polls.

​
In-progress upload protection

Files modified within the previous 60 seconds are deferred so a producer writing directly to the final name can finish. Before and after download, the importer compares the remote size and modification time with the downloaded byte count. If the file changes during the read, it is retried instead of creating a task with partial content. For the strongest delivery contract, producers should upload to a temporary name and atomically rename it into the watched folder after the upload completes. Zero-byte or transiently unavailable files are retried for up to approximately 30 minutes. Files larger than 500 MB are skipped.

​
Task input

For each successfully claimed file, the trigger:
  • downloads the file through the pinned SFTP connection
  • stores it in platform file storage
  • creates a task with the uploaded file attached
  • records the remote path in the seen ledger so overlapping polls cannot create duplicate tasks

​
Common errors

  • Base path must be absolute: use /incoming, not incoming.
  • Host key fingerprint is missing or changed: reconnect and validate the integration; verify a changed key with the SFTP administrator before accepting it.
  • Permission denied: grant list/read permission for the configured base path and watched folders.
  • File is never imported again: the same remote path was already claimed; deliver the replacement under a unique filename.
  • File remains pending: ensure the producer closes the upload and that the file is stable for at least 60 seconds.