# Input Specifications & TRK Mapping > CSV formatting rules, ZIP archive packaging, and the complete .trk column mapping reference for Egon Batch input files sent via SFTP. CSV formatting rules, ZIP archive packaging, and complete `.trk` column mapping reference. Inbound packages require paired `.zip` (containing a single root `.csv`) and `.trk` files sharing the same base name (unless a default `.trk` is agreed with Egon), with zero-based column indexing and the column delimiter declared in `[IN_SEP]`. ## Packaging Schema ### Input Package Structure - **Compressed Data Archive**: `.zip`, containing `.csv`. Single delimited table (pipe or semicolon separated) - **Configuration Descriptor** (`.trk`): - **[IN_ISO]**: Fixed ISO (ITA) or column index - **[IN_SEP]**: Column delimiter - **[IN_FUN]**: Function: NOR / GEO (includes NOR) - **[IN_...]**: 0-based index (-1 if unmapped) #### Packaging Rules - **Identical Base Names**: The archive `.zip`, the internal `.csv`, and the descriptor `.trk` must share the exact case-sensitive base name, unless you use a default `.trk` agreed with Egon. - **Single CSV per ZIP**: The `.zip` archive must contain exactly one delimited text file. Nested folders or multiple files inside the zip are rejected. - **Zero-Based Column Indexing**: Field positions declared in the `.trk` file start from index 0 for the first column, 1 for the second column, and so on. - **Matching Character Encoding**: Ensure the text encoding configured via `[IN_ENC]` (e.g. `UTF8` or `cp1252`) strictly matches your source CSV byte encoding. | Component | File Name | Location | Requirements | | ---------------- | ---------------- | -------------- | -------------------------------------------------------------------------- | | **Data Archive** | `.zip` | `./input/` | Standard ZIP archive containing only `.csv`. | | **Data File** | `.csv` | Root of `.zip` | Delimited text file. Header row optional (`[IN_INT]`). | | **Descriptor** | `.trk` | `./input/` | Plain text directive file defining country, delimiter, and column mapping. | > **Recurring Ingestion Jobs** > > The `.trk` stays in `./input/` after processing, so later runs with the same name only need the new `.zip`. If your CSV column layout is fixed, you can also agree a default `.trk` with Egon: it applies to every archive you upload, even with a different base name. --- ## TRK Directives Reference Directives are declared on individual lines using an uppercase bracketed identifier, whitespace padding, and the parameter value terminated by a semicolon (`;`). All column mapping directives use a zero-based column index, or `-1;` when the corresponding column is absent from your input file: ```ini [DIRECTIVE] value; ``` | Directive | Parameter / Component | Allowed Values / Format | Description & CSV Formatting Rules | Example | | ---------- | --------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------- | | `[IN_ISO]` | Country | 3-letter ISO (`ITA;`) or column index (`1;`) | Destination country. Alphabetical ISO in single-country runs; 0-based column index in multi-country batches. | `ITA;` or `1;` | | `[IN_FUN]` | Operations | `NOR;`, `GEO;` | `NOR;` normalizes addresses. `GEO;` normalizes and also geocodes. | `GEO;` | | `[IN_SEP]` | CSV Delimiter | `\|;` (Pipe), `$;` (Semicolon) | Column separator character. Recommended: `\|;`. Note: use `$` to declare a semicolon in `.trk`. | `\|;` | | `[IN_ENC]` | Character Encoding | `UTF8;`, `cp1252;`, `cp1250;` | Source file byte encoding. Must match the input CSV encoding. Recommended: `UTF8;`. | `UTF8;` | | `[IN_INT]` | Header Row | `S;` (Present), `N;` (No header row) | When `S;`, row 1 is skipped as column headers. When `N;`, processing starts from row 1. | `S;` | | `[IN_IDN]` | Record Unique ID | Column index or `-1;` | Database primary key, preserved verbatim in its original column. Set to `-1;` if absent. | `0;` | | `[IN_STA]` | Country Name | Column index or `-1;` | Source country name string (e.g. `Italia`). Set to `-1;` when unmapped. | `1;` | | `[IN_REG]` | Region / State | Column index or `-1;` | Administrative territory / region. Set to `-1;` when unmapped. | `2;` | | `[IN_DPT]` | Province Code | Column index or `-1;` | Two-letter official province abbreviation (_Sigla_). Set to `-1;` when unmapped. | `3;` | | `[IN_CNL]` | Municipality / City | Column index or `-1;` | Official municipality name (_Comune_). Set to `-1;` when unmapped, for example when the full address is in `[IN_STR]`. | `4;` | | `[IN_DS1]` | Locality / Hamlet | Column index or `-1;` | Sub-district or hamlet (_Frazione_). Set to `-1;` when unmapped. | `5;` | | `[IN_ZIP]` | Postal Code | Column index or `-1;` | Postal routing code (CAP / ZIP). Set to `-1;` when unmapped. | `6;` | | `[IN_DUG]` | Street Type | Column index or `-1;` | Urban qualifier (_Via, Corso, Viale, Rue, etc._). Set to `-1;` if unmapped. | `7;` | | `[IN_STR]` | Street Name / Address | Column index or `-1;` | Street name. You can also map the full address here, including house number, postal code, and municipality. | `8;` | | `[IN_CIV]` | House Number | Column index or `-1;` | Street building / house number (_Civico_). Set to `-1;` if unmapped. | `9;` | | `[IN_ESP]` | Number Exponent | Column index or `-1;` | House number exponent or suffix (_Esponente / Barrato_). Set to `-1;` if unmapped. | `10;` | | `[IN_PRE]` | Care Of / Interior | Column index or `-1;` | Building interior, care-of, or additional delivery info. Set to `-1;` if unmapped. | `11;` | > **Country Configuration Precedence & ISO Behavior** > > The declared country configuration in your batch job is authoritative and strictly dictates how `[IN_ISO]` is processed. > > **Single-Country Batches (Fixed ISO):** When a specific destination country is declared (e.g. `ITA`, `DEU`, `USA`), `[IN_ISO]` in `.trk` is **always alphabetical** (`[IN_ISO] ITA;`) and applies to all rows uniformly. No CSV column is mapped to `[IN_ISO]`. Even if the input CSV contains an `ISO` or `COD_ISO` column, the batch strictly honors the declared configuration and leaves that column unmapped. > > **Multi-Country Batches (Multi-ISO Column):** When the dataset contains records from multiple nations, `[IN_ISO]` is **numeric** (e.g. `[IN_ISO] 1;`), pointing to the 0-based column index where each row supplies its 3-letter ISO code. In this mode, `[IN_ISO]` cannot be `-1;` (a column mapping is mandatory). --- ## Concrete Examples ### Example 1: Sample CSV Records (`customers_202610.csv`) ```text ID|COUNTRY|REGION|PROVINCE|CITY|LOCALITY|ZIP|STREET_TYPE|STREET_NAME|NUMBER|EXPONENT|CARE_OF 1001|Italia|Lombardia|MI|Milano||20121|Via|Monte Napoleone|8|A|Studio Rossi 1002|Italia|Lazio|RM|Rom|||P.zza|di Spagana|1|| 1003|Italia|Veneto|VR|Verona|San Massimo|37139|Corso|Milano|45|B| ``` ### Example 2: Single-Country Descriptor File (`customers_202610.trk`) In single-country batches, `[IN_ISO]` is alphabetical (`ITA;`), and all 12 column directives are defined: ```ini [IN_ISO] ITA; [IN_FUN] GEO; [IN_SEP] |; [IN_ENC] UTF8; [IN_INT] S; [IN_IDN] 0; [IN_STA] 1; [IN_REG] 2; [IN_DPT] 3; [IN_CNL] 4; [IN_DS1] 5; [IN_ZIP] 6; [IN_DUG] 7; [IN_STR] 8; [IN_CIV] 9; [IN_ESP] 10; [IN_PRE] 11; ``` ### Example 3: Multi-Country Batch with Unmapped Directives (`shipments_eu.trk`) In cross-border datasets, `[IN_ISO]` is numeric (`1;`), pointing to the 0-based column index where the country code is located. Directives for columns not present in the CSV are explicitly configured as `-1;`: ```text ID|ISO|CITY|ZIP|ADDRESS|CIVIC 501|FRA|Paris|75004|rue de Rivoli|45 502|DEU|Berlin|10117|Friedrichstraße|100 503|ESP|Madrid|28013|Calle Gran Vía|28 ``` ```ini [IN_ISO] 1; [IN_FUN] GEO; [IN_SEP] |; [IN_ENC] UTF8; [IN_INT] S; [IN_IDN] 0; [IN_STA] -1; [IN_REG] -1; [IN_DPT] -1; [IN_CNL] 2; [IN_DS1] -1; [IN_ZIP] 3; [IN_DUG] -1; [IN_STR] 4; [IN_CIV] 5; [IN_ESP] -1; [IN_PRE] -1; ``` > **Unmapped Directives Rule** > > Keep all 12 column directives in the `.trk` file. When your input dataset does > not provide a field (such as an ID, province, hamlet, or care-of), set its > directive to `-1;` instead of removing it. > **Try in Playground** > > Want to test your own CSV dataset layout, auto-detect column directives, and > generate validated `.trk` descriptor files interactively? Use the [Batch > Processing Playground](https://documentation.egon.com/docs/batch/playground.md). --- ## Next Steps - Inspect the [Output Schema & Codes](https://documentation.egon.com/docs/batch/output-specifications.md) for the full dictionary of returned fields and coordinates. - Explore the [Quality Indicators Reference](https://documentation.egon.com/docs/quality-indicators.md) for complete diagnostic code definitions. - Upload your files with [SFTP Setup & Workflow](https://documentation.egon.com/docs/batch/sftp-workflow.md).