Wiki Generator Client 1.0 beta - Guida all'Uso

Pagina creata da Edoardo De Marco

Varie

Italiano

Piace
Condividi
Incorpora
Schermo intero
Diapositive
Scarica HTML
Scarica PDF
Abuso

←

CONTINUA A LEGGERE

→

Trascrizione del contenuto della pagina

Se il tuo browser non visualizza correttamente la pagina, ti preghiamo di leggere il contenuto della pagina quaggiù

Wiki Generator Client 1.0 beta
                     Guida all’Uso

     © Miriade S.p.A. 2012 | via Castelletto 11 36016 Thiene (VI) Italy |
     Tel. +39 0445 030111 | Fax. +39 0445 030100 | info@miriade.it | P.IVA 02811580246 | CAP.SOC.
     120.000 I.V. | R.E.A. N. 2777861 | REG. IMPR/COD.FISC. 02811580246

Indice della Guida
 Wiki Generator
     Funzionalità Analisi Database
     Funzionalità Analisi ETL
 Il Client
     Requisiti Funzionali
     Gestione Licenza
     Elenco Connessioni
     Gestione Connessioni
     Operazioni sulla Wiki
     Livelli di Log
 Supporto
 Licenze Wiki Generator Client

                  © Miriade S.p.A. 2012 | via Castelletto 11 36016 Thiene (VI) Italy |
                  Tel. +39 0445 030111 | Fax. +39 0445 030100 | info@miriade.it | P.IVA 02811580246 | CAP.SOC.
                  120.000 I.V. | R.E.A. N. 2777861 | REG. IMPR/COD.FISC. 02811580246

Wiki Generator
Wiki Generator è un software, sviluppato da Miriade S.p.A., in grado di generare automaticamente
documentazione riguardante:
● Un database e la sua struttura
● Un flusso ETL
La documentazione viene creata in formato Creole / HTML e pubblicata all’interno di un’installazione
di DokuWiki® gestita da Miriade stessa.
Ogni cliente, dal momento dell’acquisto della licenza, avrà a disposizione un’istanza personalizzata
di DokuWiki nella quale verranno caricati i dati delle sue analisi e che potrà utilizzare senza
restrizioni (tranne quelle espressamente indicate nella licenza d’uso) anche per altre
documentazioni.
Il portale contenente tutte le wiki sarà raggiungibile da tutto il web, tuttavia l’accesso alla singola wiki
sarà definito attraverso ACL appositamente gestite per permettere l’accesso ai dati sensibili
solamente agli utenti autorizzati.
Nello specifico, alla wiki del singolo cliente potranno accedere in lettura/scrittura solamente un
elenco di utenti autorizzati (e gestiti) dal cliente stesso.
In ogni wiki verrà creato inizialmente anche utente amministrativo utilizzato da Miriade per la
gestione e la manutenzione.
Una guida sull’utilizzo di DokuWiki e sulla creazione e gestione di contenuti, come pure alcune
pagine di esempio di documentazione saranno disponibili direttamente dalla Start Page della wiki.

Funzionalità Analisi Database
La funzionalità “Analisi di un Database” permette all’utente di generare automaticamente una serie
di pagine di documentazione riguardo la struttura di un database selezionato.
Le tipologie di database supportati sono:
● DB2
● Postgres
● Oracle (sia driver Thin che driver OCI)
● MySql
● MsSql 2000 / 2005 / 2008 (sia driver Microsoft che Jtds)
● AS400
● Hypersonic

Per ogni tabella del database il software è in grado di ricavare i seguenti dati:
● Nome della tabella
● Eventuali commenti
● Definizione delle singole colonne, nello specifico:
○ Nome Colonna
○ Tipo di dato
○ Metadati (descrizione o note)
○ Eventuale Chiave Primaria
○ Eventuale Chiave Esterna

○ Eventuale tabella referenziata dalla chiave esterna

Durante tutta l’analisi non verranno in alcuno modo analizzati i dati contenuti nelle tabelle, per
evitare di maneggiare dati sensibili che non devono in alcun modo essere resi pubblici.
Tutte le query vengono di fatto effettuate sui dizionari del database.

Il risultato dell’analisi viene elaborato dal software che, per ogni tabella, genera una pagina
all’interno della wiki.
Ogni pagina conterrà tutti i dati sopra elencati, schematizzati e riassunti in una tabella.
Inoltre le foreign key verranno gestite in modo da rendere possibile la navigazione tra tabelle
correlate attraverso dei link.

Poichè la wiki è per sua natura uno strumento per la condivisione di informazioni, è possibile che, a
partire dalle pagine generate automaticamente, gli utenti aggiungano commenti o note.
Wiki Generator è in grado di eseguire anche l’analisi inversa delle pagine generate, e di salvare in
questo modo i commenti e le note aggiunte a mano.
Potrete trovare maggiori informazioni su quali sezioni possono essere modificate all’interno della
guida online.

Un’ulteriore funzionalità del software è la possibilità di assegnare ad ogni tabella un business name,
una label che verrà utilizzata al posto del nome reale della tabella (spesso poco espressivo).

Funzionalità Analisi ETL
La funzionalità “Analisi di un flusso ETL” permette di generare automaticamente una serie di pagine
di documentazione relative appunto ai vostri flussi ETL.
Al momento è supportata l’analisi dei soli flussi realizzati con PDI 4.1+ (Pendaho Data Integration,
noto anche come Kettle).

Il software è in grado di eseguire una scansione del repository di Kettle (memorizzato all’interno di
un database) e di ricostruire tutte le Trasformazioni e i Job memorizzati.
Vengono ricavate anche le informazioni principali riguardanti i singoli step, fornendo all’utente finale
praticamente tutti i dettagli e le opzioni definite durante lo sviluppo del flusso.

L’output in questo caso è, come nel caso precedente, una pagina per ogni job, trasformazione o
step, oltre ovviamente ad una pagina riassuntiva iniziale.

Per i job e le trasformazioni, Wiki Generator è il primo software in grado di generare anche il grafico
del flusso esattamente come viene rappresentato all’interno di Kettle.
Tale grafico è navigabile, permettendo all’utente di partire dal job principale e di spostarsi all’interno
dei vari step per visualizzarne i dettagli.

Non è prevista, al momento, la possibilità di aggiungere commenti alle pagine generate (al contrario
della funzionalità di analisi database), in quanto è già possibile inserire note e descrizioni
direttamente all’interno di Kettle.

Il Client
Wiki Generator Client è un componente software, sviluppato anch’esso da Miriade.
Si occupa in particolare di eseguire le analisi sui database e i repository dell’utente e di inviare al
server i dati grezzi per la generazione della documentazione.

Al momento dell’acquisto della prima licenza del software, verrà fornito all’utente un link dal quale
potrà scaricare l’ultima versione di questo client.
Una volta scaricato, il client non necessita di alcuna installazione, ma sarà sufficiente estrarre il
contentuto del file zippato ed eseguire il file eseguibile (start_client) predisposto per il vostro
sistema operativo (.bat per Windows, .sh per Linux).

Requisiti Funzionali
Per funzionare correttamente, il Client richiede:
● Java Virtual Machine 1.6+ correttamente installata
● Connessione di rete disponibile verso i database che si vogliono analizzare
● Connessione di rete verso il server centrale Wiki Generator (per la versione attuale
l’indirizzo completo è http://www.wikigenerator.com/ )

La connessione ai vari database avviene tramite driver jdbc che sono già forniti all’interno del
pacchetto fornito all’utente.

Gestione Licenza
La licenza d’uso viene inviata via email all’utente subito dopo l’acquisto del software, e rimane
invariata anche nel caso di successivi aggiornamenti.
Il file contenente la licenza (license.xml) dovrà essere copiato all’interno della directory principale
del programma per essere caricata automaticamente all’avvio.
In alternativa, se il sistema non trova il file, è possibile selezionare successivamente tale file tramite
l’iterfaccia grafica (Menu Impostazioni > Carica File Licenza), o addirittura inserire il solo codice di
licenza presente all’interno del file (Menu Impostazioni > Inserisci Codice Licenza).
Il client provvederà a verificare lo stato e la validità della licenza prima di attivare tutte le altre
funzionalità

Elenco Connessioni
Al momento dell’apertura del client (se la licenza è valida, o al momento dell’inserimento di una
licenza valida) verrà caricato l’elenco delle connessioni configurate.
Ogni connessione rappresenta una connessione jdbc ad un database (o un repository Kettle) che il
client può analizzare.
I dati sensibili relativi alle connessioni (username, password, ecc..) non vengono mai inviati al

server, ma vengono mantenuti in un file chiamato connectionsList.xml presente nella directory
principale del programma. Tale file dovrà essere copiato, come per il file di licenza, nel caso si
voglia spostare il client da una directory ad un’altra o da un computer ad un altro.
In ogni momento è possibile aggiungere, modificare o eliminare una connessione attraverso
l’interfaccia (vedi sezione successiva).
La modifica manuale del file connectionsList.xml potrebbe portare ad un errore di
sincronizzazione tra client e server e quindi all’impossibilità di eseguire correttamente
aggiornamenti successivi.
In particolare, in caso di mancato riconoscimento del codice identificativo della connessione, il
server non sarà in grado di eseguire correttamente l’analisi delle pagine della wiki, portando alla
probabile perdita dei commenti inseriti a mano in tali pagine.

Gestione Connessioni
L’utente ha la possibilità di aggiungere, modificare o rimuovere le connessioni configurate.
Per aggiungere una connessione è sufficiente cliccare sul tasto “Aggiungi Connessione” presente
nella finestra principale del client (sotto al menu).
Si aprirà una finestra secondaria nella quale dovranno essere inseriti i dati della connessione:
● Nome Connessione (non sarà possibile modificarlo in seguito)
● Tipo di database selezionato
● Hostname
● Nome Database (o Istanza, o SID)
● Schema (se rilevante)
● Porta di connessione (se diversa da quella di default del database)
● Username per la connessione
● Password
● Utilizzo della connessione (analisi database o analisi ETL)
● Tipo di output richiesto (Creole o HTML)

E’ possibile anche eseguire un test di connessione per verificare l’esattezza dei dati inseriti.

Nel caso la connessione venga utilizzata solo per l’analisi della struttura del database viene
eseguito un semplice tentativo di connessione.

Nel caso la connessione venga utilizzata per l’analisi dell’ETL il sistema verifica che nel database
selezionato sia effettivamente presente un repository valido.
L’analisi del repository tuttavia è più complessa rispetto alla semplice analisi della struttura, e
richiede la creazione di alcune viste e di alcune funzioni supplementari.
Il software genera in automatico uno script, oppurtunamente adattato al tipo di database
selezionato, che si occupa della creazione di queste viste e funzioni.
L’utente può decidere se eseguire direttamente lo script tramite il client o in alternativa di copiare lo
script per analizzarlo in dettaglio ed eseguirlo autonomamente.
In ogni caso l’analisi dell’ETL non potrà funzionare correttamente senza l’esecuzione di questo
script.

Una volta creata la connessione, questa apparirà nell’elenco delle connessioni all’interno della
schermata principale.
L’elenco mostrerà all’utente il nome della connessione, la tipologia (database o ETL), e lo stato
interno della connessione.
I possibili stati sono:
● Non Connessa: il client non è in grado di connettersi al database selezionato. E’ necessario
ricontrollare i parametri di connessione e le regole di networking / firewall verso il database.
● Non Analizzata: è stata effettuata la connessione al database, ma non è stata ancora
eseguita nessuna analisi
● Non Generata: La wiki è stata analizzata, ma non sono state create le relative pagine della
wiki. Generalmente questo indica un errore in fase di scrittura dell’output e si consiglia di
contattare il supporto Miriade.
● Completa: il database (o il repository) è stato analizzato e la documentazione automatica è
stata creata. Ora potete navigare all’interno della vostra wiki.

Il pulsante “Aggiorna Wiki” permette all’utente di eseguire operazioni sulla wiki selezionata (vedi
capitolo successivo), mentre il pulsante “Modifica Connessione” permette di modificare i parametri
della connessione.
La finestra di modifica della connessione è del tutto identica a quella di creazione.
Un pulsante in basso a sinistra (“Elimina”) permette inoltre di cancellare questa connessione
dall’elenco delle connessioni gestite.

Operazioni sulla Wiki
Come già accennato nel capitolo precedente il pulsante “Aggiorna Wiki”, presente in
corrispondenza di ogni connessione configurata, permette di eseguire operazioni di aggiornamento
della connessione relativa.
La finestra di dialogo che si aprirà contiene un elenco delle possibili operazioni (che può variare in
base allo stato e del tipo della connessione).
Al momento della selezione, prima della effettiva esecuzione, viene visualizzata una breve
descrizione delle azioni che stanno per essere eseguite.
Le possibili azioni sono:
● Aggiornamento dello Stato: il software esegue una verifica incrociata tra client e server per
determinare lo stato della connessione (tra quelli descritti precedentemente). Un eventuale
aggiornamento di stato può portare ad una modifica dell’elenco delle operazioni disponibili.
● Analisi Completa: (disponibile solo per le connessioni con stato superiore a “Non
Connessa”). In questo caso vengono eseguite operazioni diverse in base alla tipologia di
connessione:
○ Analisi Database: viene eseguita l’analisi della struttura del database, l’analisi delle
pagine già presenti nel server, viene unificato il risultato delle due operazioni
precedenti (merge) e vengono aggiornate le pagine della wiki con i nuovi dati.
○ Analisi Kettle: viene analizzato il repository e i dati vengono inviati al server. Il server
genera le nuove pagine in formato HTML o Creole, in base ai parametri selezionati
dall’utente.
● Aggiornamento delle Label: (disponibile solo per l’analisi database). In questo caso il

sistema apre una ulteriore finestra di dialogo, nella quale l’utente potrà, per ogni tabella,
inserire un business name ed una categoria. Questi dati verranno inviati al server che
provvederà ad aggiornare le pagine della wiki con la nuova nomenclatura.
La categoria andrà a modificare l’elenco delle connessioni creato nella home page del
progetto.

Al momento della conferma dell’operazione il sistema inizierà ad eseguire le operazioni previste
(nel caso delle analisi, questo può richiedere anche alcuni minuti, in relazione alla quantità di tabelle
/ job da analizzare ed alle prestazioni del database in analisi).
Al termine delle operazioni il sistema mostrerà un messaggio indicante l’esito dell’operazione ed
aggiornerà, se necessario, lo stato della connessione.
In caso di eventuali errori saranno visualizzati un codice di errore e, se il livello di log lo prevede, un
report dell’errore avvenuto (più precisamente lo stacktrace dell’eccezione java).
Il codice d’errore ed eventualmente il report potranno essere utilizzati per inviare segnalazioni al
servizio di supporto.

Livelli di Log
La prima release del Wiki Generator Client viene rilasciata in versione beta.
Questo, come noto, sottointende la possibilità che siano presenti nel codice bug o errori non
ancora riscontrati durante le fasi di test.
Per contribuire a migliorare l’applicazione, ogni utente può decidere di segnalare al servizio di
supporto eventuali problemi che fossero riscontrati durante l’utilizzo.
Per permettere di fornire segnalazioni il più accurate ed utili possibili, l’applicazione permette di
modificare il livello dei log forniti all’utente, da un livello base iniziale ad un livello molto dettagliato.
I messaggi di errore principale vengono visualizzati attraverso l’interfaccia grafica (solitamente
appare una finestra di dialogo con il riepilogo dell’errore).
Altri messaggi di errore secondari potrebbero essere invece visualizzati sulla console java che
viene aperta al momento del lancio del programma.

Per attivare o disattivare i log di livello piu dettagliato è sufficiente spuntare la voce “Debug Logging”
del menu “Impostazioni”

Supporto
Miriade si occupa di effettuare periodicamente operazioni di manutenzione e aggiornamento
dell’installazione web di DokuWiki.
E’ inoltre previsto il rilascio periodico di aggiornamenti del client, contenenti come prevedibile fix di
eventuali bug rilevati e nuove features.
Miriade invierà una comunicazione via email a tutti gli utenti attivi ad ogni nuovo rilascio, fornendo il
link per scaricare gratuitamente la nuova versione del software.
Per eventuali segnalazioni gli utenti possono inviare una mail a support@wikigenerator.com.

Licenze Wiki Generator Client
Le condizioni generali d’uso del software sono consultabili direttamente dall’interfaccia grafica,
selezionando la voce “Info > Info Licenza” del menu principale.
Una copia della licenza viene anche inclusa in formato testuale all’interno del file scaricato.

Oltre a queste condizioni d’uso, le licenze di Wiki Generator vengono suddivise in base alla
funzionalità richiesta.
Al momento esistono tre livelli di licenze:
● Analisi Database
● Analisi ETL Kettle
● Licenza Completa (comprende entrambe le precedenti)
Maggiori informazioni su queste fasce di licenze sono disponibili sul sito MixPlayer dove è possibile
acquistare tali licenze.
In ogni momento sarà possibile aggiornare la propria licenza, andando ad aumentare le funzionalità
disponibili.

Puoi anche leggere