Connettore File Format

Panoramica

I connettori File Format analizzano e serializzano formati di testo strutturati incorporati all’interno di campi del payload. Ogni connettore legge da inputKey e scrive il risultato in outputKey; tutti gli altri campi del payload vengono passati invariati.

Tipi Connettore: CsvProcessor, XmlProcessor

CSV

Modalità Parse

Legge una stringa CSV da inputKey e scrive un valore strutturato in outputKey.

{
  "type": "CsvProcessor",
  "config": {
    "direction": "parse",
    "delimiter": ",",
    "hasHeader": true,
    "inputKey": "raw_csv",
    "outputKey": "rows"
  }
}

Con hasHeader: true, l’output è un array di map[string]string chiavato dalla riga di intestazione. Con hasHeader: false, l’output è un array di array ([][]string).

Modalità Serialize

Legge un array di array da inputKey e scrive la stringa CSV in outputKey.

{
  "type": "CsvProcessor",
  "config": {
    "direction": "serialize",
    "delimiter": ";",
    "inputKey": "rows",
    "outputKey": "csv_text"
  }
}

Parametri di Configurazione

• direction (richiesto): parse o serialize
• inputKey (richiesto): Chiave del payload contenente il valore sorgente
• outputKey (richiesto): Chiave del payload in cui scrivere il risultato
• delimiter: Delimitatore di campo a singolo carattere (default ,)
• hasHeader: Quando true durante parse, tratta la prima riga come nomi di colonna

XML

Modalità Parse

Legge una stringa XML da inputKey e scrive una map annidata in outputKey. Il contenuto testuale è archiviato sotto la chiave _text quando gli elementi contengono figli misti.

{
  "type": "XmlProcessor",
  "config": {
    "direction": "parse",
    "inputKey": "raw_xml",
    "outputKey": "parsed"
  }
}

Modalità Serialize

Legge una map da inputKey e scrive una stringa XML in outputKey, avvolta in rootElement.

{
  "type": "XmlProcessor",
  "config": {
    "direction": "serialize",
    "inputKey": "data",
    "outputKey": "xml_text",
    "rootElement": "report"
  }
}

Parametri di Configurazione

• direction (richiesto): parse o serialize
• inputKey (richiesto): Chiave del payload contenente il valore sorgente
• outputKey (richiesto): Chiave del payload in cui scrivere il risultato
• rootElement: Tag root che avvolge l’output serializzato (default root)

Casi d’Uso

1. Ingestione di export CSV legacy da sistemi MES o SCADA
2. Bridge di protocolli industriali basati su XML a connettori a valle JSON-nativi
3. Emissione di file CSV verso S3 o storage locale per reportistica
4. Parsing inline di payload CSV/XML ricevuti su MQTT o HTTP

Esempio: Pipeline di Ingestione CSV

{
  "type": "CsvProcessor",
  "config": {
    "direction": "parse",
    "delimiter": ",",
    "hasHeader": true,
    "inputKey": "body",
    "outputKey": "records"
  }
}

Combinato con una sorgente HTTP, trasforma un upload CSV in ingresso in un array records strutturato che può essere alimentato in Transform, Validation o un sink di database.

Migliori Pratiche

• Per CSV con delimitatori non standard (;, \t, |), imposta delimiter esplicitamente
• Imposta sempre hasHeader: true quando i connettori a valle fanno riferimento alle colonne per nome
• Per XML profondamente annidato, segui il parser con Transform usando JSONPath per estrarre percorsi specifici
• Mantieni il testo raw in una chiave dedicata (es. raw_csv) in modo che l’originale sia preservato se uno stadio a valle fallisce

Connettori Correlati

• Transform - Estrai valori tramite JSONPath dopo il parsing
• Reshape - Rinomina o rimappa i campi analizzati
• Protocol Translator - Converti tra formati strutturati