# SFTP Setup & Workflow

> SFTP connection parameters, directory topology, file pairing rules, and default descriptor options for Egon Batch address processing.

Automate high-volume batch address validation and enrichment over SFTP. Upload `<filename>.zip` and its `<filename>.trk` descriptor to `./input/`, and retrieve standardized `.gz` datasets from `./output/`.

## Connection Parameters

| Parameter          | Type        | Value / Description         | Example                    |
| ------------------ | ----------- | --------------------------- | -------------------------- |
| **Host**           | Hostname    | SFTP server endpoint        | Provided during onboarding |
| **Port**           | Integer     | SFTP server port            | Provided during onboarding |
| **Protocol**       | Protocol    | SSH File Transfer Protocol  | `SFTP`                     |
| **Username**       | String      | Customer account identifier | Provided during onboarding |
| **Authentication** | Credentials | Username and password       | Provided during onboarding |

---

## Directory Topology & Processing Lifecycle

### Directory Structure

Root directory: `/<CustomerName>/FTP/` (Username / Password). Dedicated SFTP home directory allocated during onboarding, with full control over `./input` and `./output`.

- **`./input/`** (Incoming Processing Mailbox): Deposit dataset archives (`.zip`) and matching descriptor files (`.trk`) into this directory.
  - Files must share the exact base filename (`<filename>.zip` + `<filename>.trk`), unless you use a default `.trk` agreed with Egon
  - The daemon polls this directory for new archives
  - The `.trk` stays here after processing, so later runs with the same name only need the new `.zip`
- **`./output/`** (Results Delivery Mailbox): Retrieve completed, normalized datasets packaged into compressed GZIP archives.
  - Engine deposits results named `<filename>_output_<timestamp>.gz`
  - Contains original input columns plus normalized postal attributes (geo attributes only with `GEO;`)
  - Client integration downloads archive and purges remote copy after sync

> **Processing Lifecycle**
>
> 1. **Deposit**: Upload `<filename>.zip` and `<filename>.trk` to `./input/`.
> 2. **Processing**: The daemon polls `./input/` and processes each `.zip` with the `.trk` of the same base name, or with your default `.trk`.
> 3. **Delivery**: The completed archive `<filename>_output_<timestamp>.gz` is placed into `./output/`, ready for download and cleanup.

---

## File Pairing

Each batch job needs an archive and a descriptor:

- **`<filename>.zip`**: Compressed archive containing exactly one delimited file named `<filename>.csv`. It must not contain subfolders or multiple files.
- **`<filename>.trk`**: Plain-text descriptor declaring input encoding, delimiter, and field-to-column mappings, with the same base name as the archive. It stays in `./input/` after processing, so later runs with the same name only need the new `<filename>.zip`.

The daemon processes an archive only when a `.trk` with the same base name is in `./input/`, or a default `.trk` is configured.

> **Default Descriptor**
>
> If your column layout is fixed, you can agree a default `.trk` with Egon. It
> applies to every archive you upload, even with a different base name, so you
> only upload the `.zip`.

> **No Error Notifications**
>
> The engine does not report processing errors. If no output appears in
> `./output/`, check that the `.trk` matches the archive and that both files
> share the same base name (or that a default `.trk` is configured).

---

## Next Steps

- Consult [Input Specifications & TRK Mapping](https://documentation.egon.com/docs/batch/input-specifications.md) for CSV delimiters, encodings, and column index directives.
- Consult [Output Schema & Codes](https://documentation.egon.com/docs/batch/output-specifications.md) for the complete dictionary of enriched postal fields and quality flags.