Flat File
La Source di tipo Flat File in Flowlyze consente di leggere e interpretare file strutturati in diversi formati (CSV, posizionale, XML, JSON) provenienti da una varietà di canali di acquisizione (FTP, HTTP, S3, Azure Blob Storage).
Ogni riga o unità logica del file viene trasformata in un messaggio indipendente e processata dalla piattaforma in modo asincrono, consentendo la massima scalabilità e flessibilità nei flussi di integrazione.
Canali di acquisizione
Flowlyze supporta diversi canali di acquisizione per recuperare i file sorgente:
| Canale | Descrizione |
|---|---|
| FTP / FTPS / SFTP | Connessione diretta a un server FTP per scaricare file in modo sicuro. È possibile autenticarsi tramite utente/password o chiave SSH e specificare percorsi di cartelle, pattern di file o regole di retention. |
| HTTP (TBD) | Download di un file remoto esposto via HTTP o HTTPS, con possibilità di autenticazione (API key, Basic Auth o Bearer token). |
| Amazon S3 (TBD) | Connessione a un bucket S3 per scaricare file JSON, CSV o XML. È possibile filtrare per prefisso o nome file. |
| Azure Blob Storage (TBD) | Accesso a un contenitore (container) Blob in Azure per il download e la lettura del file. Supporta autenticazione tramite connection string o service principal. |
| Azure Blob Storage RFE | Variante del connettore Azure Blob con funzionalità estese per flussi di elaborazione multipli o coordinati. (In sviluppo) |
Protocolli di lettura
Flowlyze supporta due modalità di accesso e gestione dei file, dette protocolli di lettura:
Coordinato
In questa modalità, Flowlyze opera su una cartella di lavoro a cui ha permessi di lettura e scrittura.
Il processo prevede:
- Copia del file dalla cartella sorgente in una cartella temporanea di elaborazione.
- Lettura e parsing dei contenuti.
- Spostamento del file in una cartella di completamento al termine dell’elaborazione.
Vantaggi:
- Visibilità sui file non ancora processati
- Possibilità di analizzare eventuali errori
- Tracciabilità completa del ciclo di vita dei file
La pulizia periodica delle cartelle e la gestione degli artefatti è a carico dell’utilizzatore.
Semplice (TBD)
Flowlyze scarica e processa direttamente il file dalla sorgente, senza generare copie locali.
In caso di errore, la piattaforma genera un messaggio di errore nel flusso con il dettaglio della causa, ma non conserva una copia del file originale.
Formati supportati
La Source Flat File è in grado di interpretare vari formati di dati strutturati:
| Formato | Stato | Descrizione |
|---|---|---|
| CSV | Implementato | File a valori separati da delimitatore, con opzioni di parsing avanzato (header, quote, cultura, delimitatori personalizzati). |
| JSON | Implementato | Parsing di file JSON complessi con supporto a JSONPath per selezionare le entità da elaborare. |
| Posizionale | TBD | File a larghezza fissa, con definizione esplicita della posizione di ogni campo. |
| XML | TBD | Lettura di file XML con selettori XPath e mapping automatico dei nodi. |
Configurazione CSV
Per il formato CSV, Flowlyze consente una configurazione dettagliata dei parametri di parsing:
| Parametro | Descrizione |
|---|---|
| Line Delimiter | Delimitatore di riga, di norma \n o \r\n. |
| Column Delimiter | Separatore tra colonne (default ,). Può essere modificato in ;, ` |
| Quote Character | Carattere di quotazione usato per i campi contenenti delimitatori o spazi (default "). |
| Culture | Imposta la cultura usata per interpretare numeri e date (es. it-IT, en-US). |
| Has Header | Indica se la prima riga del file contiene i nomi delle colonne (true/false). |
| Grouping Column | Specifica una colonna da utilizzare per raggruppare più righe in un unico messaggio. |
Funzionalità di Raggruppamento delle Righe
Flowlyze consente di raggruppare più righe di un file sorgente in un unico messaggio logico, utilizzando una colonna di raggruppamento.
Questo meccanismo è utile quando il file contiene dati che rappresentano relazioni gerarchiche o versioni multiple dello stesso record, e si desidera trattarli come un’unica entità nella pipeline.
Durante il parsing, Flowlyze analizza il valore della colonna di raggruppamento (ad esempio product_id, record_id, ecc.).
Tutte le righe che condividono lo stesso valore vengono aggregate in un unico oggetto JSON.
Ogni gruppo genera un singolo messaggio in uscita, contenente i dati comuni e l’elenco delle righe raggruppate in un array secondario.
Esempio 1 – Raggruppamento varianti per prodotto principale
Scenario: un file CSV contiene le varianti di prodotto (taglia, colore, prezzo) associate a un prodotto principale identificato da product_id.
File di origine
| product_id | variant_id | color | size | price |
|---|---|---|---|---|
| 1001 | 1 | red | M | 29.90 |
| 1001 | 2 | blue | L | 31.50 |
| 1002 | 3 | black | S | 28.00 |
Colonna di raggruppamento: product_id
Output aggregato
{
"product_id": 1001,
"variants": [
{ "variant_id": 1, "color": "red", "size": "M", "price": 29.90 },
{ "variant_id": 2, "color": "blue", "size": "L", "price": 31.50 }
]
},
{
"product_id": 1002,
"variants": [
{ "variant_id": 3, "color": "black", "size": "S", "price": 28.00 }
]
}
In questo caso, Flowlyze costruisce un messaggio per ogni prodotto principale, includendo tutte le varianti come array all’interno del campo variants.
Anche se la colonna di raggruppamento è una sola (product_id), il risultato è un oggetto gerarchico utile per successive fasi di mapping o invio a un sistema target (ad esempio un ERP o un sistema e-commerce).
Esempio 2 – Raggruppamento di salvataggi multipli (tabelle di journaling)
Scenario: un sistema sorgente registra più versioni o aggiornamenti dello stesso record in una tabella di journaling o audit.
Ogni riga rappresenta un salvataggio, ma nel flusso di integrazione può essere utile consolidare tutte le versioni in un unico messaggio logico.
File di origine
| record_id | update_time | field | old_value | new_value |
|---|---|---|---|---|
| 501 | 2025-10-01 10:30:00 | status | draft | pending |
| 501 | 2025-10-02 11:45:00 | status | pending | approved |
| 501 | 2025-10-03 09:20:00 | note | null | "OK" |
Colonna di raggruppamento: record_id
Output aggregato
{
"record_id": 501,
"data": [
{
"update_time": "2025-10-01T10:30:00Z",
"field": "status",
"old_value": "draft",
"new_value": "pending"
},
{
"update_time": "2025-10-02T11:45:00Z",
"field": "status",
"old_value": "pending",
"new_value": "approved"
},
{
"update_time": "2025-10-03T09:20:00Z",
"field": "note",
"old_value": null,
"new_value": "OK"
}
]
}
In questo esempio, Flowlyze genera un solo messaggio per ciascun record_id, contenente la storia completa delle modifiche in ordine cronologico. Questo consente di consolidare più versioni in un’unica rappresentazione coerente e pronta per l’invio verso sistemi di destinazione (ad esempio un data lake, un CRM o un servizio di auditing).
Configurazione JSON
Per il formato JSON, Flowlyze supporta la lettura di file JSON strutturati, semplici o complessi, con la possibilità di selezionare una porzione specifica del documento tramite JSONPath.
La configurazione JSON è volutamente minimale: il comportamento di parsing dipende principalmente dalla struttura del nodo selezionato (oggetto, array o valore singolo).
Parametri di configurazione
| Parametro | Descrizione |
|---|---|
| Json Path | Espressione JSONPath che identifica il nodo del documento JSON da cui leggere i dati. Se non specificata, vuota o impostata a "$", viene utilizzata la radice del documento. |
Comportamento di parsing
Una volta determinato il nodo di destinazione (radice o nodo selezionato tramite JSONPath), Flowlyze genera uno o più messaggi in base al tipo del nodo:
| Tipo di nodo | Risultato |
|---|---|
| Oggetto JSON | Viene generato un singolo messaggio contenente l’intero oggetto. |
| Array JSON | Viene generato un messaggio per ogni elemento dell’array. |
| Valore singolo (stringa, numero, booleano, ecc.) | Viene generato un singolo messaggio contenente il valore. |
Questo comportamento è identico sia quando si utilizza la radice del documento sia quando si usa un JSONPath.
Utilizzo senza Json Path
Se Json Path non è configurato oppure è impostato a "$":
- L’intero file JSON viene letto.
- La radice del documento viene usata come nodo di input.
- La generazione dei messaggi dipende dal tipo della radice:
- Oggetto → 1 messaggio
- Array → N messaggi (uno per elemento)
Utilizzo con Json Path
Quando Json Path è valorizzato:
- Il file viene analizzato come JSON.
- L’espressione JSONPath viene applicata per individuare un nodo specifico (ad esempio un array o un oggetto annidato).
- Se il percorso non corrisponde ad alcun nodo, viene generato un errore di configurazione.
- Il nodo individuato diventa l’input per la generazione dei messaggi, seguendo le stesse regole viste sopra.
Esempi di configurazione
Oggetto JSON come radice
{ "id": 1, "name": "Example" }
Configurazione:
- Json Path: (non impostato)
Risultato:
- Viene generato un singolo messaggio contenente l’oggetto JSON completo.
Array JSON come input
[
{ "id": 1 },
{ "id": 2 }
]
Configurazione:
- Json Path: (non impostato)
Risultato:
- Vengono generati due messaggi, uno per ciascun elemento dell’array.
Selezione tramite Json Path
{
"data": {
"items": [
{ "id": 1 },
{ "id": 2 }
]
}
}
Configurazione:
- Json Path:
$.data.items
Risultato:
- Vengono generati due messaggi, uno per ciascun elemento dell’array
items.
Json Path non valido
Configurazione:
- Json Path:
$.missing.path
Risultato:
- Errore di configurazione: il percorso JSONPath non individua alcun nodo nel documento.