Differenze

Queste sono le differenze tra la revisione selezionata e la versione attuale della pagina.

--- gwusermanual:interface:interface:import_export_csv_shp [2025/07/23 17:02]
giorgio.scali [Shape: gestione dei dati Geometrici]
+++ gwusermanual:interface:interface:import_export_csv_shp [2026/07/07 16:17] (versione attuale)
andrea.bocconi [IMPORT SHP]
@@ Linea 211: / Linea 211: @@
 |String|itemId|false| chiave del record da cui si sta lanciando l'azione, data.itemDB.pk_column, Da usare quando si vogliono importare anche i dati nella tabella della classe figlia. I record sono caricati già collegati al record padre dal quale viene lanciata l'azione |
 |String|relationName|false| nome della gwRelation di classe, qualora si vuole importare i dati in una tabelle di una classe collegata a questa tramite widget childlist. I record sono caricati già collegati al record padre dal quale viene lanciata l'azione|
-|String|codColumn|false| singola colonna o colonne multiple separate da virgola ','|
+|String|codColumn|false| singola colonna o colonne multiple separate da virgola ','. Nome della o delle colonne per le quali, qualora si facesse un importazione tipo update, verrebbero usate come criterio di sovrascrittura. Le colonne se più di una devono essere separate da virgola|
 |Object|columnHeadersMap|false| HashMap per la mappatura degli header del file con quelle del database. Vanno inserite soltanto quelle dove il nome è diverso e le si voglia importare. La forma è la seguente, nameColumnCsv: 'nameColumnDatabase'|
 |Object|additionalMap|false| HashMap contenente la lista delle colonne non presenti nel file che si voglia comunque popolare durante l inserimento. La forma è nameColumnDatabase: 'valore', il valore può essere anche preso dinamicamente dalla sessione  |
@@ Linea 374: / Linea 374: @@
 === standardPrefilterdListSelectedExportToExcel() ===
-**CASO 2: Export per aggiornamento**
+**CASO 1: Export per consultazione**
 **@Deprecated** (usare [[gwusermanual:interface:interface:import_export_csv_shp#standardlistselectedallattributeexporttoexcel|standardListSelectedAllAttributeExportToExcel()]])
@@ Linea 471: / Linea 471: @@
 |Integer|exportType|true|E' un numero intero ed indica il tipo di esportazione. Valori ammessi: 1 (per aggiornamento), 2 (tutti gli attributi)|
 |function|callback|false|Permette di inserire la funzione di callback dopo l importazione|
-|String|codColumn|false| Nome della o delle colonne per qualora si facesse un importazione tipo update. Le colonne se più di una dovrebbero essere separate da virgola|
+|String|codColumn|false| singola colonna o colonne multiple separate da virgola ','. Nome della o delle colonne per le quali, qualora si facesse un importazione tipo update, verrebbero usate come criterio di sovrascrittura. Le colonne se più di una devono essere separate da virgola|
 |Object|columnHeadersMap|false| HashMap per la mappatura dell header dello shape con quelle del database. Vanno inserite soltanto quelle dove il nome è diverso e le si voglia importare. La forma è la seguente: {'nameColumnShp': 'nameColumnDatabase'}|
 |Object|additionalMap|false| HashMap contenente la lista delle colonne non presenti nel file che si voglia comunque popolare durante l inserimento. la forma è {'nameColumnDatabase': 'valore'}, il valore può essere anche preso dinamicamente dalla sessione  |
@@ Linea 507: / Linea 507: @@
 	}
 );
+</code>
+=== standardListSelectedAllAttributeExportToShp(queryParameter, grid) ===
+@Deprecated usa exportShape() per maggior controllo
+**Parametri**
+  * **queryParameter**: Object, required
+  * **grid**: Object, required
+Esportazione SHAPE di tutti gli attributi codificati (senza callback, columnHeadersMap, additionalMap e fileMapping)
+<code javascript>
+standardListSelectedAllAttributeExportToShp(queryParameter, grid);
 </code>
@@ Linea 523: / Linea 536: @@
 |String|itemId|false| chiave del record da cui si sta lanciando l azione, data.itemDB.pk_column, qualora si volesse importare i dati in una tabelle di una classe collegata a questa tramite childlist. I record verrebbero già caricati collegati al record padre dal quale viene lanciata l azione|
 |String|relationName|false| nome della relazione sulla classe, qualora si volesse importare i dati in una tabelle di una classe collegata a questa tramite childlist. I record verrebbero già|
-|String|codColumn|false| Nome della o delle colonne per qualora si facesse un importazione tipo update. Le colonne se più di una dovrebbero essere separate da virgola|
+|String|codColumn|false| singola colonna o colonne multiple separate da virgola ','. Nome della o delle colonne per le quali, qualora si facesse un importazione tipo update, verrebbero usate come criterio di sovrascrittura. Le colonne se più di una devono essere separate da virgola|
 |Object|columnHeadersMap|false| HashMap per la mappatura dell header dello shape con quelle del database. Vanno inserite soltanto quelle dove il nome è diverso e le si voglia importare. La forma è la seguente {'nameColumnShp': 'nameColumnDatabase'}|
 |Object|additionalMap|false| HashMap contenente la lista delle colonne non presenti nel file che si voglia comunque popolare durante l inserimento. La forma è {'nameColumnDatabase': 'valore'}. Il valore può essere anche preso dinamicamente dalla sessione  |
 |String|fileMapping|false| E' il nome del file di mapping se presente nei contenuti statici, deve risiedere nella cartellina SHAPE|
-|String|scriptName|false| Nome dello scripts groovy, senza estenzione che verrà lanciato al termine del caricamento. Lo script deve essere presente nella cartella dei contenuti statici sottocartella groovy|
+|String|scriptName|false| Nome dello scripts groovy, CON l'estensione che verrà lanciato al termine del caricamento. Lo script deve essere presente nella cartella dei contenuti statici sottocartella groovy|
 |Integer|handleErrorsType|false| Specifica il comportamento del sistema in presenza di un errore. Se 0,(default) il sistema va avanti segnalando alla fine i records non importati e l errore verificatosi, se 1 blocca l intera importazione se almeno un record non può essere importato|
 |Integer|idProcessImport|false| Se indicato non viene inserito un nuovo record nella tabella contenente l archivio storico delle importazioni bensì aggiorna il record con quel idProcess|
@@ Linea 650: / Linea 663: @@
 La mappatura può avvenire in 3 modalità (ma non tutte le tipologie di importazione/esportazione la supportano), ognuna mutualmente esclusiva con le altre.
+Il formato .xlsx, sia in import che in export, non supporta la rimappatura delle colonne.
 Matrice di supporto.
@@ Linea 660: / Linea 675: @@
   * **HashMap ** Si passa un parametro denominata 'columnHeadersMap' variabile hashmap contenente una lista di chiave\valore dove  in fase di esportazione la chiave è il campo nel database e valore il campo nel file e viceversa in fase di importazione.
 <code>
+//esportazione
 columnHeadersMap:{
-‘nome_campo_nel_database1’:'nome_campo_nel_file1',‘nome_campo_nel_database2’:'nome_campo_nel_file2',etc…}
+  'nome_campo_nel_database1': 'nome_campo_nel_file1',
+  'nome_campo_nel_database2': 'nome_campo_nel_file2',
+  etc…
+}
+//importazione
 columnHeadersMap:{
-‘nome_campo_nel_file1’:'nome_campo_nel_database1',‘nome_campo_nel_file2’:'nome_campo_nel_database2',etc…}
+  'nome_campo_nel_file1': 'nome_campo_nel_database1',
+  'nome_campo_nel_file2': 'nome_campo_nel_database2',
+  etc…
+}
 </code>
@@ Linea 986: / Linea 1009: @@
 ==== Supporto ai dati JSON ====
+=== Linee Guida Sviluppo ===
+Per integrare i flussi import export esistenti, con il supporto del tipo di dato JSON, sono state utilizzate le seguenti linee guida:
+  * Gestite solo le key di primo livello del JSON
+  * Per ogni key di primo livello è generata in export una specifica colonna dedicata
+  * La colonna del file è nominata con una convenzione che concatena il nome del campo JSON, un char separatore specifico (pipe: |), e la key del JSON
+  * È  sempre possibile il remap delle colonne (anche key di un JSON), al fine di integrarsi con sistemi terzi
+  * Sono supportati gli stessi tipo di dato gestiti dal JSON, come stringhe, numeri interi e decimali, date e boolean
+  * Si utilizzano, ove possibile, di tutti i vincoli imponibili dalle definizioni delle Famiglie Attributi
+  * Supporto multi-database: oracle, postgres e mssqlserver.
+  * Si supportano tutti i meccanismi e casi d’uso precedenti
+=== Key di primo livello del JSON===
+Ad essere gestite sono solo le key di primo livello. In fase di export, in presenza di un campo JSON, viene eseguita una specifica query (esiste una implementazione per ogni database) che recupera l’unione di tutte le key di primo livello presenti per un campo JSON.
+A tale proposito:
+  * Non è rilevante se sul campo JSON è collegata una Famiglia Attributi
+  * Viene applicato anche a questa query lo stesso filtro, dipendente dal contesto, con cui è stata lanciata l’esportazione
+  * Si tenta di recuperare il tipo di dato analizzando la prima occorrenza non nulla del valore della key (applicando sempre i filtri di contesto). Esiste una implementazione per ogni database.
+  * Dal momento che si possono esportare teoricamente record con JSON di struttura totalmente differente tra un record e l’altro (con o meno una Famiglia Attributi differente), c’è da notare che si possono creare inconsistenze non gestibili se con la stessa key in valori JSON differenti è utilizzata per ospitare tipo di dato differenti.
+  * Il codice è stato ottimizzato per generare al minimo eccezioni generate da inconsistenze. Per esempio una stessa key con valori integer e double su JSON differenti non crea problematiche. Analogamente una stessa key con valori string e boolean su JSON differenti non crea problematiche. Una key con primo valore date o double e successivi valori string potrebbe generare errori in fase di export
+=== Naming dell’intestazione della key ===
+L’header della colonna che si riferisce ad un key JSON,  è nominata con una convenzione che concatena il nome del campo JSON, un char separatore specifico (pipe: |) e la key del JSON. Così:
+<code>[json_field_name]+”|”+[key]</code>
+Esempio: se il campo JSON si chiama var_attr_jsonb e la key da recuperare è Power (HP) la notazione corretta è var_attr_jsonb|power (HP).
+In alcuni casi d’uso, dove il file esportato non è destinato ad essere reimportato, il nome del campo JSON è sostituito dalla label dell’attributo (come per tutti gli altri attributi non JSON).
+Il char “.” Come divisore nelle intestazioni di colonna è di esclusivo utilizzo del vecchio caso dell’importazione dei figli dal padre (lanciata dal dettaglio padre), che era già sviluppato ed è stato mantenuto.
+Da notare che in fase di export i nomi delle intestazioni vengono tutti trasformati in minuscolo.
+In fase del successivo import, se è possibile recuperare la Famiglia Attributi (in quanto è configurata sopra il JSON ed è effettivamente presente nel tracciato anche il codice della famiglia), essa viene utilizzata per ripristinare esattamente il caso di tutte le key del JSON.
+Nel caso di JSON semplice, al successivo import, le key del JSON saranno importate tutte come presenti nel file (quindi in minuscolo).
+Da questo si evince che in fase di implementazione, è possibile, anzi auspicabile, in caso di Famiglia Attributi utilizzare key ben formattate del tutto assimilabili a label (anche se l’utente GW ADMIN può impostare separatamente le key e le relative label).
+In caso di JSON semplice, per evitare conversioni non volute, è bene fina da subito utilizzare key semplici e minuscole. Si ricorda che comunque, nel caso il JSON semplice vada rappresentato tramite il widget LabelValueJSONVisualizer, è sempre possibile popolare nel JSON stesso la key _metadata, che permette di impostare anche label custom.
+===Rimappatura colonne con JSON key===
+Le modalità di mappatura dei campi sono rimaste le medesime.
+Esempio applicato ad una colonna JSON key:
+<code>
+columnHeadersMap:{
+‘json_field|key’: 'nome_rimappato_nel_file1',
+etc…
+}
+</code>
+===Tipi di dato nel JSON===
+Il JSON supporta i seguenti tipo di dato:
+  * String
+  * Integer
+  * Double
+  * Boolean
+  * Date (indirettamente)
+Il tipo di dato Date, non è direttamente supportato dal JSON, ma Geoweb lo supporta mediante stringhe formattate secondo i pattern:
+  * "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" ISO-8601 usato internamente a geoweb per salvare date nel JSON sul database
+  * "yyyy-MM-dd HH:mm:ss" usato per produrre e leggere i file .csv, .xlsx, .shp
+I pattern delle date nel JSON sono sempre completi e non hanno mai versioni ridotte come può accadere per i normali attributi di geoweb (che hanno "yyyy-MM-dd HH:mm:ss" o "yyyy-MM-dd").
+A seconda del formato d’esportazione i valori possono essere formattati in maniera differente:
+  * .csv e .shp
+    * Il separatore delle colonne è sempre il punto e virgola (;). Indipendentemente dal Locale dal locale della macchina server.
+    * Il separatore dei valori decimali è sempre il punto (.) e mai la virgola
+    * Non vengono applicate mai formattazioni particolari per separare le migliaia: spazio ( ) o punto (.)
+    * I boolean vengono esportati correttamente “true”, “false”
+    * I valori date vengono esportati e presentati come da pattern standard
+  * .xlsx e .csv convertiti a partire da .xlsx
+    * Dipendentemente dal locale della macchina server, Il separatore dei valori decimali può essere il punto (.), per le macchine con localizzazione US, o la virgola (,) per le macchine con localizzazione IT
+    * Non vengono applicate mai formattazioni particolari per separare le migliaia: spazio ( ) o punto (.)
+    * Dipendentemente dal locale della macchina server, i boolean vengono esportati correttamente maiuscoli e tradotti nella lingua locale: “VERO”/”FALSO” per le macchine con localizzazione IT e “TRUE”/”FALSE” per le macchine con localizzazione US.
+    * I valori date vengono esportati come da pattern standard (anche se in .xlsx possono essere formattate)
+Geoweb gestisce correttamente l’importazione dei valori a prescindere dal locale della macchina che ha prodotto (o convertito) il file, con alcune forzature:
+  * Per i boolean l’unico locale differente da US supportato è IT. Sono comunque sia validi tutti i locali che rendono i boolean come “TRUE”/”FALSE”
+===Policy di importazione===
+Di fronte ad un file di import che presenta nuove colonne che si riferiscono a key non esistenti in alcun JSON, geoweb attua la seguente regola:
+  * In caso di JSON con Famiglia Attributi (cioè sul quale c’è un PropertySetWidget verranno persistite SOLO le key per le quali esiste la definizione della relativa proprietà nella Famiglia Attributi.
+  * In caso di JSON semplice tutte le key e relativi valori sono salvati nel JSON del record importato.
+Quindi attualmente si delineano due casi d’uso ben distinti.
+Il primo è quello di esercizio, dove il SM (od il GW ADMIN) censiscono e definiscono preventivamente le Famiglie Attributi e le relative proprietà. La possibilità di introdurre dati corrotti tramite import da parte dell’utente è ridotta.
+Il secondo è quello in fase di popolamento dati iniziale o prototipazione del sistema, dove c’è totale libertà di import dei dati al fine di popolare il dato JSON. Nulla vieta che in una fase successiva su quel campo possa essere definita una Famiglia Attributi, magari costruita specificatamente in base ai valori effettivamente presenti.
+Trigger di classe .groovy
+Durante le importazioni naturalmente girano i trigger applicativi configurati per la classe.
+Per i tipi di dato JSON è predisposto un utilizzo map-like delle key nel groovy. I valori delle key sono quindi accessibili con notazione puntata.
+Esempi:
+<code>
+valuesMap.data_json_b.key_1 = “value one”;
+…
+valuesMap.data_json_b._metadata.groups.group_1.label = “Custom Label”;
+</code>