Data-Coupler/CSV_SCHEDULING_IMPLEMENTATION.md

Implementazione Schedulazione File CSV/Excel

Data

24 Gennaio 2026

Panoramica

Implementata la funzionalità completa di schedulazione per profili che utilizzano file CSV o Excel come sorgente dati. Precedentemente questa funzionalità era disattivata per motivi di sicurezza, ora è completamente funzionale con validazioni appropriate.

Modifiche Implementate

1. Validazione File CSV nel Salvataggio Profilo

File: Data_Coupler/Pages/DataCoupler.razor.cs

Modifica: Aggiunta validazione nel metodo OnProfileSaved per verificare che:

• Il file CSV/Excel specificato esista nel filesystem
• Il file sia leggibile dall'applicazione

Implementazione:

// Validazione specifica per file CSV
if (profile.SourceType == "file" && !string.IsNullOrEmpty(profile.SourceFilePath))
{
    // Verifica esistenza
    if (!System.IO.File.Exists(profile.SourceFilePath))
    {
        await JSRuntime.InvokeVoidAsync("alert", 
            "Errore: Il file non esiste o non è accessibile.");
        return;
    }

    // Verifica leggibilità
    try
    {
        using var fs = System.IO.File.OpenRead(profile.SourceFilePath);
        fs.Close();
    }
    catch (Exception fileEx)
    {
        await JSRuntime.InvokeVoidAsync("alert", 
            $"Errore: Il file non può essere letto. Dettagli: {fileEx.Message}");
        return;
    }
}

Benefici:

• Previene errori durante l'esecuzione schedulata
• Fornisce feedback immediato all'utente in fase di configurazione
• Verifica i permessi di lettura del file

---

2. Implementazione Lettura File per Schedulazioni

File: Data_Coupler/Services/ScheduledProfileExecutionService.cs

Modifica: Implementati i seguenti metodi per la lettura di file CSV e Excel:

Metodi Implementati:

1. GetAllRecordsFromFileAsync - Metodo principale

   • Determina il tipo di file (CSV, XLSX, XLS)
   • Verifica esistenza del file
   • Delega alla funzione appropriata

2. ReadCsvFileAsync - Lettura file CSV

   • Rilevamento automatico del separatore (,, ;, \t, |)
   • Parsing corretto con gestione virgolette
   • Supporto per file di grandi dimensioni

3. ReadExcelFileAsync - Lettura file Excel

   • Supporto per formati .xlsx e .xls
   • Utilizzo di ExcelDataReader library
   • Registrazione encoding provider (System.Text.CodePagesEncodingProvider)
   • Lettura del primo foglio Excel

4. Helper Methods:

   • DetectCsvSeparator: Rilevamento automatico separatore CSV
   • ParseCsvLine: Parsing linea CSV con gestione quote e escape

Esempio di utilizzo:

private async Task<IEnumerable<Dictionary<string, object>>> GetAllRecordsFromSourceAsync(
    DataCouplerProfile profile, IDatabaseManager? databaseManager)
{
    if (profile.SourceType.ToLower() == "file")
    {
        return await GetAllRecordsFromFileAsync(profile);
    }
    // ... altri tipi
}

Caratteristiche:

• Supporto completo per CSV con separatori multipli
• Gestione corretta di campi con virgolette e caratteri speciali
• Parsing robusto con logging dettagliato
• Compatibilità con file Excel legacy (.xls) e moderni (.xlsx)

---

3. Abilitazione Profili File nella Schedulazione

File: Data_Coupler/Pages/Scheduling.razor

Modifica: Rimosso il filtro Where(p => p.SourceType != "file") che escludeva i profili file dalla lista di schedulazione.

Prima:

@foreach (var profile in availableProfiles.Where(p => p.SourceType != "file"))
{
    <option value="@profile.Id">@profile.Name</option>
}

Dopo:

@foreach (var profile in availableProfiles)
{
    <option value="@profile.Id">@profile.Name @(profile.SourceType == "file" ? "(File)" : "")</option>
}

Miglioramenti UI:

• Etichetta (File) per identificare profili con file
• Messaggio informativo aggiornato:

  ℹ️ I profili con file CSV/Excel come sorgente sono ora supportati per le schedulazioni. Il file specificato nel profilo verrà letto ad ogni esecuzione.

---

4. Gestione Cancellazioni per File CSV

Implementazione: La gestione delle cancellazioni opzionali funziona automaticamente anche per i profili file grazie all'architettura esistente.

Flusso:

1. I record vengono letti dal file CSV/Excel
2. Vengono trasformati in Dictionary<string, object> come i record database
3. Il sistema di associazioni (KeyAssociationService) traccia i record
4. Se abilitato, il DeletionSyncService sincronizza le eliminazioni

Compatibilità:

• ✅ Supporto completo per EnableDeletionSync flag
• ✅ Tracking chiavi sorgente (SourceKeyField)
• ✅ Sistema di associazioni record
• ✅ Pre-discovery di record esistenti

---

Gestione File per Schedulazioni

Due Modalità di Caricamento

1. Caricamento Browser (per Preview)

• Scopo: Configurare mapping e vedere anteprima dati
• Funzionamento:
  • File caricato tramite browser (InputFile component)
  • Processato in memoria
  • Non salvato sul server
• Uso: Solo per configurazione iniziale del profilo

2. Percorso Manuale (per Schedulazione) ⭐

• Scopo: Specificare posizione file per schedulazioni
• Funzionamento:
  • Utente inserisce percorso completo (es: C:\Data\products.csv)
  • Sistema valida esistenza e leggibilità
  • Percorso salvato nel profilo
• Uso: Obbligatorio per profili che devono essere schedulati

Esempi di Percorsi Validi

Windows:

C:\Data\products.csv
\\server\share\customers.xlsx
D:\ImportFiles\orders.csv

Linux/Container:

/data/products.csv
/mnt/share/customers.xlsx
/app/import/orders.csv

Workflow Completo

1. Configurazione Iniziale:

   • Carica file da browser per preview
   • Configura mapping campi vedendo i dati reali
   • Importante: Questo file è solo temporaneo

2. Preparazione Schedulazione:

   • Posiziona il file nella location definitiva sul server
   • Inserisci il percorso completo nel campo "Percorso File sul Server"
   • Clicca "Valida e Carica" per verificare
   • Salva il profilo

3. Esecuzione Schedulata:

   • Il sistema legge il file dal percorso salvato
   • Il file deve esistere e essere accessibile
   • Aggiornamenti al file vengono letti automaticamente

Considerazioni Importanti

Sicurezza:

• Il file deve essere accessibile dal processo dell'applicazione
• Verificare permessi di lettura sulla directory
• Per ambienti multi-utente, considerare ACL appropriati

Percorsi Relativi vs Assoluti:

• Consigliato: Percorsi assoluti per chiarezza
• Se si usano percorsi relativi, sono relativi alla working directory dell'applicazione

Aggiornamento File:

• Il sistema legge sempre il file corrente dal percorso
• Per aggiornare i dati, basta sovrascrivere il file nella stessa posizione
• Non serve modificare il profilo se il percorso rimane invariato

Deployment Container:

• Montare volumi per directory contenenti i file
• Esempio docker-compose:

  volumes:
    - /host/data:/data  # Monta directory host in /data nel container
  

• Nel profilo usare: /data/products.csv

Best Practices:

• ✅ Usare una directory dedicata per file di import (es: /data/imports/)
• ✅ Nominare i file in modo descrittivo
• ✅ Implementare rotazione/backup dei file
• ✅ Monitorare spazio disco
• ❌ Non usare directory temporanee che vengono pulite
• ❌ Non usare percorsi di rete senza verifica connessione

---

Funzionamento Completo

Creazione Profilo con File CSV

1. L'utente seleziona "File" come tipo sorgente

2. Opzione A - Caricamento Browser (per preview):

   • Carica un file CSV/Excel tramite browser
   • Il file viene processato in memoria per preview
   • Permette di configurare il mapping vedendo i dati reali
   • Non viene salvato sul server - solo per anteprima

3. Opzione B - Percorso Manuale (richiesto per schedulazione):

   • Inserisce il percorso completo del file sul server (es: C:\Data\products.csv)
   • Clicca "Valida e Carica" per:
     • Verificare che il file esista
     • Verificare che sia leggibile
     • Caricare preview per configurare mapping
   • Il percorso viene salvato nel profilo

4. L'utente configura il mapping campi

5. Salvataggio: Il sistema valida che il file sia accessibile e leggibile

6. Il percorso completo originale del file viene salvato in SourceFilePath

Nota Importante: Per le schedulazioni è necessario specificare il percorso file manualmente. Il file deve essere accessibile dal server nella posizione specificata.

Schedulazione Profilo File

1. L'utente crea una nuova schedulazione
2. Seleziona un profilo con SourceType = "file"
3. Configura la frequenza (giornaliera, settimanale, intervallo, ecc.)
4. Abilita opzionalmente EnableDeletionSync per sincronizzare eliminazioni

Esecuzione Schedulata

1. Il background service avvia l'esecuzione alla schedulazione prevista
2. ScheduledProfileExecutionService.ExecuteProfileAsync viene chiamato
3. Il servizio legge il file dal percorso salvato usando GetAllRecordsFromFileAsync
4. I record vengono trasformati e inviati alla destinazione REST
5. Il sistema di associazioni traccia i record per evitare duplicati
6. Se configurato, vengono sincronizzate le eliminazioni

---

Sicurezza e Validazioni

Validazioni Implementate:

• ✅ Verifica esistenza file prima del salvataggio profilo
• ✅ Verifica permessi di lettura file
• ✅ Gestione eccezioni durante la lettura file
• ✅ Logging dettagliato per troubleshooting
• ✅ Validazione formato file (CSV, XLSX, XLS)

Considerazioni di Sicurezza:

• Il file deve essere accessibile dal processo dell'applicazione
• Percorsi assoluti sono salvati nel database
• Per ambienti containerizzati, montare volumi con i file
• Permessi filesystem devono consentire lettura

---

Formati File Supportati

CSV

• Separatori: , (virgola), ; (punto e virgola), \t (tab), | (pipe)
• Rilevamento automatico: Sì
• Gestione quote: Supporto completo per campi tra virgolette
• Escape caratteri: Supporto per "" (double quote escape)
• Dimensione massima: 50 MB (configurabile)

Excel

• Formati: .xlsx (Office Open XML), .xls (Binary Format)
• Fogli multipli: Legge il primo foglio per default
• Header: Prima riga utilizzata come intestazione
• Dimensione massima: 50 MB (configurabile)

---

Esempi di Utilizzo

Esempio 1: Schedulazione Giornaliera CSV

Profilo: "Import Prodotti da CSV"
- Sorgente: File CSV (products.csv)
- Destinazione: REST API (Salesforce)
- SourceKeyField: "ProductCode"
- UseRecordAssociations: true

Schedulazione: "Import Prodotti Quotidiano"
- Tipo: Daily (Giornaliera)
- Ora: 08:00
- EnableDeletionSync: false

Comportamento: Ogni giorno alle 08:00, il sistema legge products.csv, trasforma i dati secondo il mapping configurato, e li invia a Salesforce. I record esistenti vengono aggiornati, i nuovi creati.

Esempio 2: Sincronizzazione con Eliminazioni

Profilo: "Sincronizza Clienti Excel"
- Sorgente: File Excel (customers.xlsx)
- Destinazione: REST API (SAP Business One)
- SourceKeyField: "CustomerID"
- UseRecordAssociations: true

Schedulazione: "Sync Clienti Settimanale"
- Tipo: Weekly (Settimanale)
- Giorno: Lunedì
- Ora: 06:00
- EnableDeletionSync: true

Comportamento: Ogni lunedì alle 06:00, il sistema:

1. Legge customers.xlsx
2. Sincronizza i clienti con SAP Business One
3. Identifica clienti eliminati dal file
4. Elimina i corrispondenti record in SAP B1

---

Testing e Validazione

Test Consigliati:

1. Test file CSV con separatori diversi

   • Comma-separated
   • Semicolon-separated
   • Tab-separated

2. Test file Excel

   • Formato .xlsx moderno
   • Formato .xls legacy
   • Fogli con molte colonne/righe

3. Test errori

   • File non esistente
   • File senza permessi di lettura
   • File corrotto
   • File troppo grande

4. Test schedulazione

   • Esecuzione immediata manuale
   • Esecuzione automatica schedulata
   • Verifica storico esecuzioni
   • Test con EnableDeletionSync attivo

---

Limitazioni Note

1. Fogli Excel: Attualmente viene letto solo il primo foglio del file Excel
2. Dimensione file: Limite di 50 MB per sicurezza (configurabile in codice)
3. Percorsi assoluti: I file devono essere accessibili tramite percorso assoluto
4. Encoding: Supporto per encoding standard (UTF-8, Windows-1252)

---

Prossimi Sviluppi Potenziali

• Supporto per lettura di fogli Excel multipli
• Configurazione dinamica del foglio Excel da leggere
• Supporto per file remoti (HTTP, FTP, Azure Blob)
• Cache intelligente per file grandi non modificati
• Validazione schema file prima dell'esecuzione
• Notifiche in caso di file non trovato durante schedulazione

---

Conclusioni

L'implementazione della schedulazione per file CSV/Excel è ora completa e robusta. La funzionalità include:

✅ Validazione completa del file in fase di configurazione
✅ Lettura affidabile di CSV con separatori multipli
✅ Supporto per file Excel moderni e legacy
✅ Integrazione completa con sistema di associazioni
✅ Supporto per sincronizzazione eliminazioni opzionale
✅ Logging dettagliato per troubleshooting
✅ Error handling robusto

Gli utenti possono ora schedulare trasferimenti dati da file CSV/Excel esattamente come farebbero con sorgenti database, con le stesse funzionalità avanzate di tracking record e sincronizzazione.