Pagina 1/26
IBConnector Tutorial IBConnector Engine e IBConnector Manager Versione 3.2.0.7 Pagina 2/26
Indice generale Scopo del documento...4 Installazione IBConnector...5 Esecuzione...5 Messaggio di benvenuto...6 Path...7 Cartella...8 Log...9 Completamento...10 Installazione connettori...11 Architettura...12 Distribuzione integrazioni...12 Deploy...14 IBConnector Manager...16 Scelta connettore...17 Configurazione connessioni...18 Configurazione ETL...20 Gestione parametri...23 Importa...24 Ricarica...24 Parametrizzazione database...25 Pagina 3/26
Scopo del documento Il seguente documento si prefigge l'obbiettivo di documentare il prodotto della Zucchetti, IBConnector, in tutte le sue componenti e funzionalità. L'installazione, l'architettura, il deploy, la parametrizzazione e la configurazione saranno gli argomenti relativi all'ibconnector rivisitati e ristrutturati in questo tutorial. Pagina 4/26
Installazione IBConnector A partire dalla versione 3.1.0.2 di IBConnector, è stata introdotta una miglior gestione degli aggiornamenti e dei rilasci dell'ibconnector, tramite una nuova gestione di versioning. La versione di IBConnector, infatti, è formata da quattro numeri. I primi tre rappresentano la versione di PDI Kettle utilizzato per la creazione dell'etl. Quando questa versione cambia, il setup installerà una nuova istanza dell'ibconnector, non sovrascrivendo eventuali versioni già presenti con versioni di PDI Kettle differenti. L'ultimo numero nella versione di IBConnector invece, viene aumentato ogni volta che si effettuano degli aggiornamenti, senza modificare la versione di PDI Kettle. In questo caso, il setup aggiornerà IBConnector presente sulla macchina alla nuova versione, oppure, se non presente, installerà direttamente all'ultima release. Come già detto, questa nuova procedura partirà dalla versione 3.1.0.2. Ciò significa che la versione predente, ossia la 3.1.0.1, non gestisce tale configurazione e, se presente sulla macchina, è consigliabile disinstallarla prima di procedere con l'installazione della nuova release. Di seguito vengono esposti i passi per installare IBConnector dalla versione 3.1.0.2 e successive. Esecuzione Eseguire il file IBConnector-t.x.y.z-Setup.exe, dove t.x.y.z è la versione dell'applicativo. Al momento della stesura di questo documento la versione è 3.2.0.6. Se sulla macchina fosse installata la versione 3.1.0.1, e se l'utente volesse installare una 3.1.0.z, viene informato consigliando di disinstallare la vecchia versione (insieme ai connettori associati) prima di procedere: Se due IBConnector, hanno t, x e y (versione di Kettle) differenti, sono due istanze differenti e quindi le installazioni saranno distinte. In tutti i restanti casi, se la versione di Kettle è la stessa, l'istanza viene sovrascritta a quella esistente. Pagina 5/26
Messaggio di benvenuto Inizialmente, verrà aperta la finestra di benvenuto che guiderà l'utente nell'installazione. Premere Avanti : Pagina 6/26
Path Il prossimo passo permette all'utente di selezionare il percorso dove installare IBConnector: Pagina 7/26
Cartella A questo punto, è possibile specificare il collegamento a IBConnector dal menu start. Dopodiché, premendo il pulsante Installa, l'applicazione verrà installata secondo i parametri impostati. Se sulla macchina fosse presente la versione 3.1.0.1, il setup non permetterà di installare questa versione nello stesso percorso della 3.1.0.1. Anche i collegamenti dal menu di avvio (Windows) dovranno essere inseriti su una cartella diversa da quella impostata per la versione 3.1.0.1: Pagina 8/26
Log Completata l'installazione, verrà visualizzato il log delle operazioni svolte durante questa fase: Pagina 9/26
Completamento L'ultima finestra conferma l'avvenuta installazione di IBConnector: Per disinstallare IBConnector, invece, è sufficiente eseguire il file Uninstall IBConnector-t.x.y.z presente nel menù di avvio oppure dal pannello di controllo (Installazione / Applicazione). L'applicazione non verrà disinstallata se ad essa sono associati dei connettori. Quindi per procedere con la disinstallazione dell'ibconnector è necessario prima disinstallare tutti i connettori ad essa associati. L'installazione della versione Linux non hai il wizard della versione Windows appena descritto, è necessario solo effettuare l'unzip del pacchetto distribuito. Pagina 10/26
Installazione connettori I singoli progetti rilasciati vengono chiamati connettori. L'installazione di questi connettori è indipendente dall'installazione di IBConnector, ma richiedono la sua presenza. Ogni connettore è legato alla versione di IBConnector e, se la versione attualmente installata non è compatibile, non è possibile installare il connettore (a meno di un aggiornamento di IBConnector). Con il connettore viene inoltre distribuita la relativa documentazione di progetto e l'infomart per l'analisi dei dati tramite la suite InfoBusiness. Pagina 11/26
Architettura IBConnector è un pacchetto java preposto all'esecuzione di un job di un repository Kettle cifrato. Il connettore è un progetto di integrazione contenente un file xml che prende il nome di Repository. Al fine di proteggere il lavoro svolto il repository viene cifrato prima della distribuzione mediante un componente, denominato Crypter. L'output che si ottiene è un file con estensione.ibc, il Crypted Repository, che sarà utilizzabile da IBConnector. L'architettura vuole dare la possibilità a Zucchetti di proteggere il lavoro fatto dal gruppo InfoBusiness Progetti, dando la possibilità di distribuire un motore standard sincronizzato con il License Server di InfoBusiness. L'obiettivo è anche quello di non limitare il potenziale di quei clienti/rivenditori che hanno la necessità di implementare delle verticalizzazioni 'custom' dell'integrazione. I clienti/rivenditori potranno richiedere a Zucchetti i sorgenti del connettore, utilizzare il Crypter e utilizzare il nuovo repository cifrato mediante IBConnector. Per poter utilizzare IBConnector è necessario possedere la licenza InfoBusiness specifica per il connettore in questione. Distribuzione integrazioni L'architettura è presentata graficamente dallo schema seguente. L'architettura per la versione Linux non cambia, bisogna solo considerare i file bash di Linux (.sh) al posto dei file batch (.bat) di Windows. xetl Connector yetl Connector zetl Connector InfoBusiness Connector File Crypted properties Repository Data Warehouse Database Loader Repository Engine PDI Kettle Repository Decrypter Crypter Crypted Repository Repository Database Repository License Client License Server Pagina 12/26
Il progetto d'integrazione (connettore), dopo essere stato sviluppato, viene esportato in formato XML e prende il nome di Repository. Per proteggere il lavoro svolto, prima della distribuzione, si è pensato di utilizzare un applicativo centralizzato (Crypter) per la cifratura del codice. L'output sarà un repository protetto (Crypted Repository -.ibc) da dare in input al motore kettle 'esteso', che il cliente/rivenditore vedrà come una black-box (IBConnector). I componenti che fanno parte di IBConnector sono: License Client: Si occupa di comunicare con il LicenseServer di InfoBusiness per la verifica della licenza di utilizzo del connettore. Decrypter: Si occupa di prendere in input il repository distribuito e renderlo utilizzabile per il caricamento sul database (Database Repository). Loader Repository: Si occupa di caricare sul database (Database Repository), residente in memoria, il repository decifrato dal Decrypter. Engine PDI Kettle: Si occupa di eseguire l'etl. Può anche essere utilizzato (Spoon) per verticalizzare l'etl, dopo aver richiesto a Zucchetti i sorgenti decifrati. Al termine del processo, la memoria occupata da IBConnector verrà rilasciata. Il motore kettle (Engine PDI Kettle) è inglobato in IBConnector, che utilizzerà anche dei file properties per parametrizzare l'etl (ad esempio i valori di default) a seconda dell'integrazione (Connettore) che si sta lanciando, lasciando IBConnector standard per la distribuzione di tutti i progetti. I clienti/rivenditori che avranno la possibilità di fare editing sul repository, mediante Spoon (GUI PDI Kettle Spoon), devono poi cifrare il nuovo repository, per poter utilizzare l'ibconnector in maniera corretta. L'architettura, così come è stata studiata, vuole dare la possibilità a Zucchetti di proteggere il lavoro fatto dal gruppo InfoBusiness Progetti, dando la possibilità di distribuire un motore standard sincronizzato con il License Server di InfoBusiness. L'obiettivo è anche quello di non limitare il potenziale di quei clienti/rivenditori che hanno la necessità di implementare delle verticalizzazioni 'custom' dell'integrazione. Pagina 13/26
Deploy L'installazione di IBConnector crea la seguente struttura standard nel file system della macchina: File IBConnector.jar: motore del connettore. Decripta l'etl, lo carica in un DB residente in memoria e lo lancia. Finito il processo libera la memoria dal DB. File IBConsole.jar: GUI. File IBConnector.bat: batch file per il lancio del motore IBConnector.jar. File IBConsole.bat: batch file per il lancio della GUI IBConsole.jar. Cartella zibconfig di configurazione della console. ibconsole.ini: file di configurazione della GUI (versione e livello di log) wizard.properties: file di configurazione grafica della GUI. Cartella progettoetl (dove progetto è il nome del progetto realizzato). File progettoetl.ibc: repository ETL criptato. File progettoetl.con: è un file xml contenente i parametri di configurazione delle connessioni. Potrà essere configurato tramite l'utility IBConnector Manager. Viene creato durante la fase di installazione del progetto o eventualmente, se non presente, la prima volta che si lancia il processo ETL. File progettoetl_ modalita.bat: batch files con le varie modalita (init, run e setup) di lancio della IBConnector Manager e dell'ibconnector. File License.cfg: contiene i dati della licenza da utilizzare. File progettoetl.properties contiene i valori di default. File progettoetl_db.properties contiene i valori delle connessioni ai db. File progettoetl_job.properties contiene i valori di dei job da lanciare con la GUI ed i relativi parametri di input. Pagina 14/26
I parametri da passare al file IBConnector.bat sono i seguenti: 1) Nome del progetto (Connettore) 2) Percorso del file di licenza: 1.Se in locale bisogna inserire il path assoluto del file.lic 2.Se su server bisogna passare una stringa del tipo indirizzoserver:porta:ragione Sociale Cliente. L'Indirizzo del server, la porta, e la Ragione Sociale del Cliente sono informazioni che possono essere ricavate dal LicenceServer di Infobusiness. 3.Percorso assoluto del file license.cfg del progetto specificato al punto1) 3) Nome job da eseguire 4) Livello del log 5) Elenco di parametri opzionali da passare all'etl (possono essere massimo 5) Nella configurazione standard non è necessario modificare il file progettoetl.bat, ma solamente il file License.cfg utilizzato da tale batch. Pagina 15/26
IBConnector Manager IBConnector Manager è un'utility che agevola l'utente nell'utilizzo di IBConnector. Questo applicativo permette selezionare il connettore, di impostare le connessioni ai database, di lanciare l'etl e di gestire i parametri. Nell'installazione di IBConnector sono presenti nelle cartelle dei singoli connettori i files con estensione.con. Essi contengono le proprietà per le connessioni ai database utilizzati. Per permettere la modifica e la verifica delle connessioni presenti in questi file, viene utilizzata l'ibconnector Manager, rilasciata con l'ibconnector. La GUI è presente nella home directory di IBConnector. Per il lancio standalone bisogna utilizzare il batch IBConsole.bat. L'IBConnector Manager viene eseguito dai batch di lancio. Si rimanda ai manuali dei singoli connettori per il corretto utilizzo. La Console è nata con l'obbiettivo di rendere agevole la configurazione dell'ibconnector. E' possibile effettuare il lancio di JOB Kettle facendo in modo che possano prendere da GUI al massimo 5 parametri in input. Permette di interagire con tabelle dei parametri opportunamente create, gestendone per ogni tabella un'altra speculare di inizializzazione. Pagina 16/26
Scelta connettore Dopo l'installazione dell'ibconnector e dei connettori sarà possibile avviare la Console dal menu di avvio. Questa modalità è presente solo nella distribuzione Windows per la quale sono stati creati delle procedure di setup. Avviando la Console è possibile visualizzare la seguente schermata che chiameremo Step1. E' possibile avviare l'interfaccia manualmente anche con il file batch IBConsole (la distribuzione Linux utilizza solo questa modalità). Nel drill down dei connettori è possibile scegliere uno dei connettori installati (prendiamo il connettore AHRETL come esempio per questo documento). Lo Step1 prevede la verifica e la configurazione del file delle licenze (file License.cfg nella directory AHRETL). Con il tasto Test si effettua un'interrogazione al license server con le credenziali indicate. Il tasto.. effettua un binding della rete per individuare altri license server raggiungibili. Il tasto Next del Wizard salva automaticamente le impostazioni sulla licenza e passa nel pannello della Console dedicato alla configurazione delle connessioni (Step2). Pagina 17/26
Configurazione connessioni Le connessioni da configurare sono le connessioni dichiarate nell'etl mediante il Kettle e portate sul file xml generato dall'ibconnector AHRETL.con (prendiamo sempre il connettore AHRETL come riferimento per questo documento). Il campo Tipo DB permette di scegliere su quale motore DB ci si vuole connettere, l'elenco dei database disponibili è dato dalla compatibilità dell'etl, che viene dichiarata da InfoBusiness Progetti compilando il file AHRETL_db.properties. Quindi, nel file AHRETL_db.properties ci sono le connessioni che sono state rese disponibili per il connettore, ovvero le compatibilità degli ETL con i motori DB. In caso di una verticalizzazione, per rendere compatibile l'etl con un'altro motore DB, si dovrà modificare il file in questo modo: <Tipologia di motore DB> custom_type=custom_db <Compatibilità motore DB> custom_enable=1 <Classe JDBC> Pagina 18/26
custom_class=custom_jdbc <Porta motore DB> custom_port=custom_port <Script attributi SQL> custom_sql=custom_attribute_sql <Script attributi TST> custom_tst=creazione table space tabelle <Script attributi TSI> custom_tsi=creazione table space indici <Script attributi TTA> custom_tta=abilitazione table space tabelle <Script attributi TIA> custom_tia=abilitazione table space indici Tutti gli altri campi, non specificati nel file, indicano le credenziali di accesso per la comunicazione con il database. Il tasto Test verifica se la connessione ha successo. Il tasto Next del Wizard salva automaticamente le impostazioni delle connessioni e passa nel pannello della Console dedicato alla configurazione dell'etl (Step3). Pagina 19/26
Configurazione ETL L'ultimo passo del wizard, Step3, permette il lancio di job Kettle contenuti nell'etl. I job da inserire nell'elenco ed i relativi parametri da selezionare sono configurati nel file AHRETL_job.properties (considerando sempre AHRETL come connettore si esempio). Il file di configurazione è strutturato nel seguente modo: AHRETL_JB0=Z_ARCH_ETL/START_DWH_AdHoc AHRETL_JB1=Z_ARCH_ETL/START_Parametri AHRETL_JB2=Z_ARCH_ETL/START_Ricarica_Parametri AHRETL_JB0.parameters=param1:Azienda:false AHRETL_JB1.parameters=param1:Azienda:true Tramite il suffisso AHRETL_JBx si possono dichiarare i job che saranno contenuti nell'oggetto drill down del pannello. I parametri a seguire, massimo 5, sono indicati nella voce Pagina 20/26
AHRETL_JBx.parameters. Ogni parametro è composto da una terna di parametri in cui il primo identifica il nome del parametro, il secondo la label da visualizzare sul pannello (Azienda) e l'ultimo indica se il parametro è reso obbligatorio (true) o facoltativo (false). jobspanel.parametrsbtn.enabled=true Se abilitato (true) permette di abilitare il tasto Parametri, il quale attiverà la GUI per la gestione dei parametri. In questo caso, se il tasto Parametri dovesse riportare un popup di errore significa che le tabelle dei parametri non sono state correttamente configurate. Se un ETL non prevede i parametri si può evitare di riportare l'errore, che sarebbe incompleto, disabilitanndo (false) il parametro suddetto. jobspanel.parameters.connectionname=output Identifica il nome della connessione sulla quale vengono create e popolate le tabelle dei parametri tramite il job Z_ARCH_ETL/Start_Parametri. Di default la connessione sulla quali tali tabelle sono create è la connessione di OUTPUT. Il tasto Avvia Job permette di lanciare il job Kettle opportunamente selezionato e compilato, se l'esito del job sarà positivo verrà visualizzato un popup di coferma dell'avvenuta corretta esecuzione. Se la procedura di caricamento dati dovesse andare in errore, verrà visualizzata una finestra di dialogo in cui viene riportato il log dell'elaborazione per analizzare i motivi del malfunzionamento. Pagina 21/26
Nella cartella zibconfig, situata nella directory home dell'ibconnector, si trova il file di configurazione della Console: ibconsole.ini. Nel file è possibile specificare la granularità del livello di log che si vuole analizzare. NOTHING ERROR MINIMAL BASIC DETAILED DEBUG ROWLEVEL Il tasto Parametri permette di aprire la finestra per la gestione dei parametri utilizzati nelle procedure di ETL, da non confondere con i parametri di lancio dell'etl discussi in precedenza. Pagina 22/26
Gestione parametri La gestione dei parametri è necessaria per poter agevolare l'utente finale alla configurazione dei parametri necessari per la corretta configurazione dell'etl. Prendiamo sempre come esempio il connettore AHRETL. Per ogni parametro si possono definire uno o più tab (scelta pannelli in alto). Ogni tab rappresenta una coppia di tabelle, una contenente i parametri effettivi (pannello superiore), ed una contenente i possibili valori (pannello inferiore) da rendere effettivi. Pertanto è possibile effettuare una serie di operazioni di spostamento dal pannello inferiore a quello superiore (drag & drop). Ci sono anche i seguenti tasti che effettuano operazioni sulle tabelle rappresentate nei pannelli e che rispecchiano le tabelle presenti sul data warehouse: Cerca : effettua una ricerca su tutti i campi della tabella del pannello inferiore. + / - : crea / cancella nuovi record nella tabella del pannello superiore. Save : salva i dati della tabella del pannello superiore nella speculare tabella del database. L'elenco delle tabelle da mettere nella GUI per la gestione dei parametri è definito in una tabella del data warehouse: IBC_PAR_HELP. Attualmente una limitazione sulla locazione delle tabelle sta nel fatto che è obbligatorio definirle in una connessione Kettle chiamata OUTPUT. Tabella Alias Posizione ToolTip Pagina 23/26
IBC_PAR_AZIENDA Aziende 0 *** IBC_PAR_LISTINO Listini 1 *** IBC_PAR_MARGINALITA Marginalita 2 *** IBC_PAR_DOCUMENTI Documenti 3 *** Le tabelle specificate nel campo Tabella sono le tabelle rappresentate nei pannelli superiori di ogni tab, il campo Alias contiene il nome da assegnare al tab ed il campo Posizione indica la posizione del tab. Il campo ToolTip è stato pensato per poter generare un tool tip di spiegazione su ogni singolo tab ma attualmente non viene ancora gestito dalla Console. In seguito verranno descritti le funzionalità dei tasti Importa e Ricarica. Importa Lancia un job dell'etl che permette il flush dei parametri di inizializzazione, ovvero i dati presenti sulla tabella del pannello inferiore del tab selezionato. Quindi, utilizzando sempre il connettore AHRETL come esempio, supponiamo di aver selezionato il tab Azienda. Il tasto Importa effettuerà il lancio del seguente job: /PARAM/IM/IBC_PAR_INI_AZIENDA Ovviamente questo job si occuperà di popolare la tabella IBC_PAR_INI_AZIENDA in base ai criteri di popolamento del connettore. Ricarica Lancia un job dell'etl che permette il flush dei parametri, ovvere i dati presenti sulla tabella del pannello superiore del tab selezionato. Quindi, utilizzando sempre il connettore AHRETL come esempio, supponiamo di aver selezionato il tab Azienda. Il tasto Ricarica effettuerà il lancio del seguente job: /PARAM/RE/IBC_PAR_AZIENDA Ovviamente questo job si occuperà di popolare la tabella IBC_PAR_AZIENDA in base ai criteri di popolamento del connettore. La funzionalità di ripristino dati, può essere utilizzata anche come rollback dei parametri rispetto all'ultima esecuzione dell'etl, ovviamente sarà necessario prevedere nell'etl l'utilizzo di ulteriori tabelle di appoggio. Se si volesse seguire questa politica, attualmente non viene visualizzato un messaggio di Alert, quindi bisogna fare attenzione all'utilizzo in quanto si possono perdere le operazioni sui dati fin ora effettuate. Pagina 24/26
Parametrizzazione database Alcuni parametri di default dell'applicativo IBConnector Manager possono essere aggiornati modificando il file progettoetl_db.properties, che si trova dentro la cartella progettoetl di ogni singolo connettore. Questo file si presenta nel seguente modo: MSS_TYPE=MSSQL ORA_TYPE=ORACLE MYS_TYPE=MYSQL FIB_TYPE=FIREBIRD POS_TYPE=POSTGRESQL MSS_ENABLE=1 ORA_ENABLE=1 MYS_ENABLE=1 FIB_ENABLE=1 POS_ENABLE=0 MSS_CLASS=net.sourceforge.jtds.jdbc.Driver ORA_CLASS=oracle.jdbc.driver.OracleDriver MYS_CLASS=com.mysql.jdbc.Driver FIB_CLASS=org.firebirdsql.jdbc.FBDriver POS_CLASS=org.postgresql.Driver MSS_PORT=1433 ORA_PORT=1521 MYS_PORT=3306 FIB_PORT=3050 POS_PORT=5432 MSS_SQL=SET DATEFORMAT YMD; SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED; ORA_SQL=alter session set nls_date_format='yyyy/mm/dd' MYS_SQL=SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED; FIB_SQL= POS_SQL= MSS_TST= ORA_TST= MYS_TST= FIB_TST= POS_TST= MSS_TSI= ORA_TSI= MYS_TSI= FIB_TSI= POS_TSI= Pagina 25/26
MSS_TTA= ORA_TTA= MYS_TTA= FIB_TTA= POS_TTA= MSS_TIA= ORA_TIA= MYS_TIA= FIB_TIA= POS_TIA= Le voci con suffisso _TYPE indicano le tipologie di database attualmente supportate. Gli _ENABLE sono posti ad uno quando si desidera far visualizzare nell'utilty la tipologia di database indicata. I suffissi _CLASS e _PORT indicano, rispettivamente, le classi java utilizzate dai driver JDBC e le porte di connessioni ai database. Le voci _SQL permettono di impostare i parametri di connessione ai DBMS mediante script Sql. I parametri con suffissi _TST e _TSI, permettono di definire rispettivamente la frase sql per la creazione del table space delle tabelle e degli indici. Infine i parametri con suffissi _TTA e _TIA, permettono di abilitare rispettivamente i table space delle tabelle e degli indici. Pagina 26/26