Exporta CSV

Introduzione

Introduzione

Presentazione

Il plugin è uno strumento avanzato per l'esportazione di dati in formato CSV, progettato per semplificare e automatizzare il processo di esportazione di informazioni da diverse tabelle del database. Questo plugin offre un'interfaccia intuitiva che permette di configurare facilmente le modalità di esportazione, personalizzare i formati dei dati e mappare i campi secondo le proprie esigenze.

image-1751528192127.png

Il sistema è dotato di un wizard guidato che accompagna l'utente attraverso tutti i passaggi necessari per configurare correttamente l'esportazione, garantendo un'esperienza d'uso fluida e professionale anche per utenti meno esperti.

Introduzione

Regole di utilizzo

Per poter utilizzare il modulo Esportazione CSV, è fondamentale che il plugin sia correttamente installato e attivato all’interno dell’ambiente vtenext. Al termine dell’installazione, è necessario verificare che non si siano verificati errori durante la procedura e che il plugin risulti attivo nella sezione dedicata ai moduli installati: un’installazione incompleta o un plugin disattivato compromettono il funzionamento dell’intero processo di esportazione.

È inoltre indispensabile assicurarsi che la cartella: "storage/CSVExporter/" disponga dei permessi di scrittura adeguati. In caso contrario, il sistema non sarà in grado di generare o salvare correttamente i file CSV esportati.

In ultimo, e non meno importante, sono richieste alcune competenze di base dell'operatore, in particolare su quattro ambiti:

  1. Conoscenza dei moduli CRM: comprendere la struttura dei moduli da esportare, i tipi di campo utilizzati, le relazioni tra le entità e le logiche di business.
  2. Familiarità con il formato CSV: conoscere i concetti di separatori di campo (`;`, `,`), delimitatori di testo (`"`), caratteri di fine riga e compatibilità con software come Excel, LibreOffice o Google Sheets.
  3. Gestione della codifica dei carattere: utilizzare la codifica UTF-8 per garantire la corretta visualizzazione di accenti, simboli e caratteri speciali nei file esportati.
  4. Organizzazione dei file: saper gestire strutture di cartelle, usare nomi coerenti per i file e implementare strategie di backup, per mantenere ordine e sicurezza nei dati generati.

Informazioni Base - HomePage

Fase 1 wizard

Informazioni Base - HomePage

Gestione dei Moduli dalla Homepage

La Homepage rappresenta il centro di controllo principale per la gestione di tutte le configurazioni di esportazione CSV. Questa interfaccia offre una panoramica completa di tutti i moduli configurati e fornisce accesso immediato alle funzionalità principali del plugin.

image-1751531190639.png

Visualizzazione Moduli Configurati

Nella homepage vengono visualizzati tutti i moduli di esportazione già configurati, organizzati in schede informative che mostrano:

Importante: Le modifiche vengono applicate definitivamente solo dopo aver completato tutto il processo del wizard e aver cliccato su "SALVA" nel passaggio finale. Fino a quel momento, è possibile annullare tutte le modifiche senza compromettere la configurazione esistente.

Informazioni Base - HomePage

Aggiunta di un Modulo

Creazione Nuove Configurazioni

Per creare una nuova configurazione di esportazione, la homepage mette a disposizione il pulsante "AGGIUNGI MODULO": 

image-1751532909635.png

  1. Clicca sul pulsante verde "AGGIUNGI MODULO"
  2. Il sistema apre automaticamente il wizard di configurazione in 5 passaggi
  3. Il wizard guida attraverso tutti gli aspetti della configurazione:
    - Selezione del modulo CRM da esportare
    - Definizione dei campi da includere
    - Configurazione di formati e separatori
    - Impostazione di filtri e opzioni avanzate
    - Salvataggio della configurazione per uso futuro
Informazioni Base - HomePage

Gestione Moduli Esistenti

Per ogni modulo configurato sono disponibili due azioni principali:

image-1751532837150.png

  1. Il pulsante "Modifica": consente di accedere al wizard di configurazione per apportare modifiche alla configurazione esistente.
    Questa funzione permette di: 
    - Aggiornare i campi da esportare
    - Modificare filtri e criteri di selezione
    - Cambiare le opzioni di formattazione
    - Aggiustare la logica di esportazione del modulo.

  2. Il pulsante "ELIMINA" : rimuove definitivamente la configurazione selezionata. Per garantire la sicurezza dei dati, il sistema implementa una procedura di conferma che: mostra un messaggio di avviso prima della cancellazione e  rchiede conferma esplicita dall'utente. In tal modo si previene eliminazioni accidentali ed informa che i file CSV già esportati verranno eliminati

    image-1751533048661.png

Informazioni Base - HomePage

Modifica Configurazioni Esistenti

Per modificare una configurazione già creata, il processo è altrettanto intuitivo:

Procedura di Modifica:

  1. Individua il modulo da modificare nell'elenco della homepage
  2. Clicca sul pulsante "MODIFICA" corrispondente al modulo desiderato
  3. Il sistema caricherà automaticamente la configurazione attuale nel wizard
  4. Il wizard permette di modificare tutti gli aspetti della configurazione:
    - Aggiungere o rimuovere campi dall'esportazione
    - Cambiare separatori, formati di data e opzioni numeriche
    - Modificare nome del file, descrizione o cartella di destinazione
    - Aggiustare filtri e criteri di selezione

Configurazione del file di esportazione

Fase 2 wizard

Configurazione del file di esportazione

Impostazioni di Esportazione

Il secondo passaggio del wizard rappresenta il cuore della configurazione tecnica, dove vengono definiti tutti i parametri che determinano come i dati verranno estratti, formattati e salvati nel file CSV finale. Questa sezione è suddivisa in diverse aree tematiche che consentono un controllo granulare su ogni aspetto dell'esportazione:

  1. Tipologia Formato Dati
  2. Codifica dei Caratteri
  3. Formato Data
  4. Precisione Numerica
  5. Modalità di scrittura
  6. Delimitatore di Testo
  7. Configurazioni di Separazione
  8. Gestione File/Cartella di Output

image-1751543530592.png

Configurazione del file di esportazione

Tipologia Formato DatiPagina

Il campo Tipo di Esportazione offre due modalità distinte per l'estrazione e la formattazione dei dati dal database: 

image-1751544231981.png

La scelta tra queste due modalità dipende dall'utilizzo finale del file CSV: utilizzare "raw" per elaborazioni tecniche e "pretty" per report e analisi destinate alla consultazione diretta.

Configurazione del file di esportazione

Codifica dei Caratteri

Il campo "Codifica" determina il set di caratteri utilizzato per salvare il file CSV, influenzando direttamente la compatibilità e la leggibilità dei dati esportati. Il sistema offre quattro opzioni principali:image-1751544799132.png

Raccomandazione: Per la maggior parte degli utilizzi, specialmente in contesto italiano, si consiglia UTF-8 per la sua universalità e compatibilità con i software moderni. Utilizzare codifiche alternative solo in casi specifici di compatibilità con sistemi legacy.

Configurazione del file di esportazione

Formato Data

Il campo "Formato Data" definisce come le date verranno rappresentate nel file CSV esportato. Il sistema offre cinque formati distinti per adattarsi a diverse esigenze geografiche e di compatibilità software.

image-1751545226298.png


Il formato "d-m-Y" (giorno-mese-anno) standardizza la rappresentazione delle date secondo il formato europeo. Questa impostazione assicura coerenza nella visualizzazione delle date e facilita l'elaborazione dei dati da parte di software di analisi o fogli di calcolo configurati per il formato italiano.

Configurazione del file di esportazione

Precisione Numerica

Il campo "Numeri Decimali" controlla la precisione numerica di tutti i valori decimali presenti nel file CSV esportato. Il sistema offre cinque livelli di precisione, da 1 a 5 cifre decimali:

image-1751545679176.png

Le 2 cifre decimali rappresentano il compromesso ideale per la maggior parte delle esportazioni CSV in ambito aziendale, garantendo dati precisi senza appesantire inutilmente il file o compromettere la leggibilità.

Configurazione del file di esportazione

Modalità di scrittura

Il campo "Modalità di Scrittura" determina il comportamento del sistema quando un file CSV con lo stesso nome esiste già nella cartella di destinazione. Il sistema offre due approcci distinti:

image-1751545910546.png

Configurazione del file di esportazione

Delimitatore di Testo

Il campo "Delimitatore di Testo" definisce il carattere utilizzato per racchiudere i campi di testo nel file CSV, garantendo la corretta interpretazione dei dati anche quando contengono caratteri speciali. 
Il sistema offre tre opzioni principali:

image-1751546338401.png

Raccomandazione: Utilizzare sempre le virgolette doppie (") per garantire massima compatibilità e protezione dei dati, specialmente in presenza di testi complessi o indirizzi contenenti virgole.

Configurazione del file di esportazione

Configurazioni di Separazione

Questa sezione controlla i caratteri utilizzati per strutturare e organizzare i dati nel file CSV, definendo come vengono separati campi, righe e valori multipli.

image-1751547253575.png

"Separatore di Campo": definisce il carattere che divide le colonne nel file CSV:

Separatore di Riga: determina il carattere che indica la fine di ogni record:

Separatore Picklist Multiselezione: gestisce campi che possono contenere valori multipli:

Esempi Pratici di Utilizzo

Campo multiselezione "Categorie Prodotto":
- Con ||: "Elettronica||Computer||Gaming"
- Con ;: "Elettronica;Computer;Gaming"
- Con ,: "Elettronica,Computer,Gaming" (problematico se , è separatore di campo)

Raccomandazione: Utilizzare virgola (,) come separatore di campo, LF (\n) come separatore di riga, e doppio pipe (||) per le multiselezioni per garantire massima compatibilità e chiarezza nella struttura dati.

Configurazione del file di esportazione

Gestione File/Cartella di Output

Questa sezione definisce le impostazioni per la gestione del file di output, inclusa la destinazione, le notifiche e la denominazione del file CSV finale.

image-1751547880558.png

Mappatura dei campi

Fase 3 wizard

Mappatura dei campi

Mapping - Introduzione

Il terzo passaggio definisce la corrispondenza tra i campi del modulo VTE e le colonne che appariranno nel file CSV finale.
Questa fase è cruciale per determinare quali informazioni verranno esportate e come saranno strutturate.

image-1751549152050.png

L'interfaccia di mappatura è organizzata in due colonne principali che lavorano insieme in modo coordinato:

Colonna Sinistra - Campo VTE
Questa sezione mostra i campi disponibili nel modulo selezionato, con caratteristiche specifiche:
- Checkbox di selezione: Permette di includere o escludere ciascun campo dall'esportazione
- Nome del campo: Etichetta descrittiva del campo nel sistema VTE
- Tipo di campo: Identificazione automatica tra campi dinamici e valori fissi

Colonna Destra - Campo CSV
Questa sezione definisce come i campi appariranno nel file di output:
- Nome colonna: Etichetta che apparirà come intestazione nel CSV
- Campo editabile: Possibilità di personalizzare completamente il nome della colonna
- Controllo rimozione: Pulsante X per eliminare singole mappature

Mappatura dei campi

Tipologie di Mappatura

Il sistema supporta diverse tipologie di mappatura per adattarsi a esigenze specifiche:

Campi Dinamici
I campi dinamici rappresentano dati reali estratti dal database:
- Esempio: "Soggetto" → "soggetto"
- Funzione: Trasferisce il valore effettivo del campo dal record VTE
- Personalizzazione: Il nome della colonna CSV può essere modificato mantenendo il collegamento ai dati

Valori Fissi
I valori fissi permettono di inserire informazioni statiche in ogni riga:
- Esempio: "Valore}" → "Valore11"
- Funzione: Inserisce lo stesso valore predefinito in tutte le righe esportate
- Utilizzo: Ideale per identificatori, categorie o metadati comuni

Mappatura dei campi

Gestione delle Mappature

La mappattura dei campi viene gestita dalla:

Selezione di Campi:
- Checkbox attivo: Il campo viene incluso nell'esportazione
- Checkbox disattivo: Il campo viene escluso dall'esportazione
Controllo granulare: Possibilità di selezionare solo i campi necessari

Personalizzazione Nomi Colonne
- Modifica diretta: Click sul campo per editare il nome della colonna CSV
- Convenzioni: Possibilità di adottare standard di denominazione specifici
Chiarezza: Utilizzo di nomi descrittivi per facilitare l'interpretazione dei dati

Rimozione Mappature
-Pulsante X rosso: Elimina completamente la mappatura
- Azione immediata: Rimozione istantanea senza conferma
Flessibilità: Possibilità di riorganizzare l'elenco dei campi

Esempi Pratici di Mappatura

Scenario 1 - Esportazione Contatti
- Campo VTE: "Nome Azienda" → Campo CSV: "company_name"
- Campo VTE: "Email Principale" → Campo CSV: "email"
Valore Fisso: "Tipo" → Campo CSV: "customer_type" (valore: "Cliente")

Suggerimento: Iniziare con una mappatura essenziale includendo solo i campi indispensabili, quindi espandere gradualmente aggiungendo campi aggiuntivi in base alle necessità specifiche del progetto.

Mappatura dei campi

Gestione dinamica dei campi di mapping

Il sistema offre la possibilità di espandere dinamicamente la configurazione attraverso il pulsante "+ AGGIUNGI CAMPO", che rappresenta uno strumento fondamentale per la personalizzazione avanzata dell'esportazione. Quando si clicca su questo pulsante, il sistema aggiunge immediatamente una nuova riga di mappatura vuota alla fine dell'elenco esistente, permettendo di includere campi aggiuntivi che potrebbero non essere stati considerati nella configurazione iniziale.

image-1751549702702.png

Blocco Prodotti - Configurazione Speciale

Fase 4 wizard

Blocco Prodotti - Configurazione Speciale

Attivazione Blocco Prodotti

Il quarto passaggio del wizard si attiva esclusivamente quando nella mappatura dei campi (Passaggio 3) è stato selezionato il campo "Blocco Prodotti". Questo passaggio rappresenta una configurazione specializzata che gestisce la complessità dei dati prodotto, richiedendo impostazioni aggiuntive per definire come strutturare le informazioni dei prodotti associati nel file CSV finale.

Se il campo "Blocco Prodotti" non è stato incluso nella mappatura, il wizard procede direttamente dal Passaggio 3 al Passaggio 5 (Salvataggio Configurazione), saltando completamente questa fase.

image-1751553341046.png

image-1751553354302.png

Blocco Prodotti - Configurazione Speciale

Configurazione Avanzata Blocco Prodotti

La schermata mantiene la stessa struttura di mappatura del Passaggio 3, ma si concentra esclusivamente sui campi relativi ai prodotti. Il sistema presenta tutti i campi disponibili per i prodotti del modulo selezionato, permettendo una selezione mirata delle informazioni da esportare.

image-1751554545069.png


L'interfaccia presenta nuovamente le due colonne principali che lavorano in coordinazione :

image-1751554479411.png

Colonna Campo VTE: Mostra i campi specifici del blocco prodotti disponibili nel sistema, come "Soggetto", "Blocco Prodotti", "Tipo", "Intestazione" e altri attributi specifici dei prodotti.

Colonna Campo CSV: Permette di definire come questi campi prodotto appariranno nel file CSV finale, con la possibilità di personalizzare completamente i nomi delle colonne.

Il sistema implementa un meccanismo di ereditarietà dei campi che funziona in modo intelligente: quando viene selezionato un campo principale contenente sotto-strutture, il sistema eredita automaticamente tutti i campi collegati, presentandoli nella configurazione per permettere una mappatura completa e dettagliata.

La vera potenza di questa configurazione emerge quindi quando si selezionano campi complessi come "Sconto Suddiviso". In questo caso, il sistema riconosce automaticamente che questo campo contiene una struttura dati articolata e presenta all'utente tutti i sotto-campi associati. Per tanto con  "Sconto Suddiviso", il sistema espande automaticamente la mappatura mostrando tutti i componenti specifici:

Questo approccio garantisce che nessun dato importante venga perso durante l'esportazione e che l'utente abbia sempre il controllo completo sulla struttura finale del CSV, potendo decidere quali specifici sotto-campi includere o escludere dall'esportazione.

image-1751553766906.png

Salvataggio Mappatura

Fase 5 wizard

Salvataggio Mappatura

Completamento Esportazione

Il quinto e ultimo passaggio del wizard conclude il processo di configurazione del modulo. In questa fase, il sistema conferma che tutte le impostazioni sono state salvate correttamente e fornisce le opzioni per tornare alla gestione operativa.

image-1751550482041.png

In questa fase il sistema ha quindi completato tre operazioni fondamentali:

  1. Validazione delle impostazioni
    Controlla che la configurazione sia coerente e corretta (es. mappatura dei campi valida, formato CSV compatibile, ecc.).
  2. Salvataggio permanente
    Tutti i dati sono archiviati in modo sicuro per un uso futuro. La configurazione può essere modificata o riutilizzata in qualsiasi momento.
  3. Attivazione del modulo
    Il modulo configurato viene reso immediatamente disponibile nella **homepage del plugin**, pronto per l’esportazione.


NOTA IMPORTANTE: Il completamento del wizard "non è solo la fine della configurazione", ma l’inizio di un utilizzo pratico, veloce e personalizzato del sistema di esportazione CSV all'interno del modulo scelto.
Una volta salvata, ogni configurazione diventa uno strumento pronto all’uso, ottimizzato per rendere l’esportazione dei dati semplice ed efficiente.

image-1751550810856.png