====== DocWay3 - Modulo di import file Excel - XLS ======
 
GenericXlsImport (su docway3-cvs.3di.it)


===== Linguaggio =====

Java


===== Schema del modulo =====

{{:documentazione_3di:docway3:import_xls.jpg|}}


===== Breve descrizione del funzionamento =====

Il modulo legge dei file excel (__formato Microsoft xls__) e crea un nuovo documento partendo da un template xml (definito in un file di configurazione o passato dinamicamente dall'applicazione che usa il modulo) e riempiendolo con i dati di ogni riga (un documento per ogni riga di ogni foglio).
Un file excel deve riferirsi ad una sola tipologia documentale (es. doc, fascicoli...).
E' possibile configurare il modulo per importare differenti file xls riferiti ognuno ad una tipologia documentale diversa (es. uno per i doc, uno per i fascicoli...).
L'elaborazione delle righe dei fogli elettronici avviene tramite un insieme di regole definite in un file di configurazione.
L'operazione di import di uno stesso file excel può essere avviata più volte dato che, se viene fornita una ricerca per identificare in modo univoco i documenti da inserire, non salva un documento se è già presente nell'archivio.

L'accesso all'archivio in cui salvare i documenti avviene tramite una generica interfaccia in modo da essere indipendente dagli strumenti utilizzati per accedere all'archivio (es. common.jar, extraway WS...) e, volendo, anche dal tipo di archivio (extraway o altro).
Di questa interfaccia è stata realizzata un'implementazione che utilizza common.jar (classe //it.highwaytech.apps.generic.utils.excel_import.ArchiveManager4ExcelImport//).

Il modulo si basa su un meccanismo di notifica di eventi che consente all'applicazione di monitorare lo stato dell'import.
Tale meccanismo consente l'interfacciamento con un qualsiasi tipo di "barra di avanzamento" (es. stile docway o altro).

Per maggiori dettagli si veda il javadoc.

===== Breve descrizione del file di configurazione =====

File di configurazione xml:

    <?xml version="1.0" encoding="utf-8"?>
    <excel_import_rules>
      <excel_file start_row="..." id="...">
        <docs_template encoding="...">
            <![CDATA[...]]>
        </docs_template>
        <univocity_query>...</univocity_query>
        <row_rules empty_cell_skip_row="yes">
            <rule>    
                <parent_node_xpath>...</parent_node_xpath>
                <value type="...">...</value>
            </rule>
            ...
        </row_rules>
      </excel_file>
      ...
    </excel_import_rules>

Dettagli:

  * excel_import_rules: radice.
  * excel_file: (obbligatorio; 1 - N) blocco di regole per tipologie documentali omogenee.
    * @start_row: (opzionale) indica la riga (0-N) di ogni foglio da cui partire (per saltare eventuali header).
    * @id: (opzionale) identificatore univoco del blocco di regole.

  * docs_template: (opzionale) template xml dei documenti da inserire. Viene usato come base di partenza per creare i documenti da inserire (uno per ogni riga). Se omesso deve essere passato al modulo direttamente dall'applicazione. Esso deve contenere un solo elemento CDATA ( <![CDATA[...]]> ) contenente il template xml.         
    * @encoding: (obbligatorio) indica l'encoding del template xml.
                
  * univocity_query: (opzionale) query di univocità usata per verificare l'esistenza del documento da inserire prima del suo salvataggio. Se omessa non viene effettuato alcun controllo prima del salvataggio. La query può contenere dei tag "<xpath>...</xpath>" che consentono di recuperare dei valori dal documento xml da salvare ("..." rappresenta un generico xpath). Notare che i caratteri '<' e '>' devono essere codificati ("&lt;xpath&gt;...&lt;/xpath&gt;").
    
  * row_rules: (obbligatorio) raggruppa le regole che consentono di elaborare una riga del file xls.            
    * @empty_cell_skip_row: (opzionale) se vale "yes" (unico valore ammesso) comporta il salto di una riga se una delle celle indicate nelle regole è vuota.
    
  * rule: (obbligatorio; 1 - N) indica una regola xpath-valore.
    
  * parent_node_xpath: (obbligatorio) xpath di un nodo del documento che si sta costruendo (il nodo deve esistere).
        
  * value: (obbligatorio) valore da inserire nel percorso indicato da 'parent_node_xpath'. Esso può contenere dei tag [col:XX,function] che consentono di recuperare il valore di una cella (in posizione 0-N) e di effettuare eventuali elaborazioni su di esso mediante delle function. ",function" è opzionale. L'unica function attualmente supportata è "del_dec" che elimina (se presenti) i decimali (es. ".12", cioè la parte di stringa dopo l'ultimo '.').        
    * @type: (opzionale) indica il tipo del valore da inserire. 
      * Se assente/vuoto o "text": il testo del nodo individuato da 'parent_node_xpath' viene impostato con il contenuto di 'value'.
      * "attr:nome_attr": comporta la creazione di un attributo "nome_attr" nel nodo individuato da 'parent_node_xpath' contenente il testo di 'value'.
      * "el:nome_el": comporta la creazione di un elemento "nome_el" figlio del nodo individuato da 'parent_node_xpath' contenente il testo di 'value'.
      * "cdata": nel nodo individuato da 'parent_node_xpath' viene aggiunto un nodo CDATA con il contenuto di 'value'.

===== Applicazioni che usano il modulo =====

  * **Docway/Titulus** (documenti in arrivo, import fascicoli da file excel).