Consiglio Nazionale delle Ricerche Progetto ITB - Istituto Tecnologie Biomediche LUMIR http://www.itb.cnr.it CONVENZIONE CNR – REGIONE BASILICATA LUMIR LUCANIA – MEDICI IN RETE WP3 Realizzazione estesa AT33 Erogazione WRAPPER STANDARD - Manuale di Installazione e configurazione CONTROLLO DEL DOCUMENTO Dati del documento Codice: File: Stato: Approvato Versione: 1.0 04Dicembre 2009 Approvazione ed emissione versione finale Funzione Redatto da: Gruppo progetto LUMIR Data 04/12/2009 Controllato da: Luca Serbanati RQ 04/12/2009 Approvato da: Fabrizio Ricci RP 04/12/2009 Distribuzione Firma Copia controllata n. 01 Firma A. Q. ______________________________ Copia non controllata 1 ver. 1.0 04 Dicembre 2009 Pagina 1 di 25 Consiglio Nazionale delle Ricerche Progetto ITB - Istituto Tecnologie Biomediche LUMIR http://www.itb.cnr.it Abstract In questo documento viene descritta la procedura di installazione del Wrapper Standard su un computer dotato di cartella clinica per MMG. Gruppo del progetto LUMIR che ha collaborato alla redazione del documento: INTEMA-Sanità: Vittorio Arleo, R. Gianturco CNR: Luca Serbanati, Gregorio Mercurio 2 ver. 1.0 04 Dicembre 2009 Pagina 2 di 25 Progetto LuMIR Wrapper Standard – Manuale Installazione Sommario Introduzione ...................................................................................................................................................... 4 Requisiti minimi di sistema................................................................................................................................ 4 Prerequisiti Software ......................................................................................................................................... 4 Installazione ....................................................................................................................................................... 5 Installazione della Java Virtual Machine ....................................................................................................... 5 Installazione di Bouncy Castle Crypto API ..................................................................................................... 5 Installazione di Estensioni Crittografiche Java (JCE) ...................................................................................... 5 Installazione dei certificati............................................................................................................................. 6 Installazione del Microsoft .Net Framework 3.5 SP1 .................................................................................... 6 Installazione del dbms PostgreSQL................................................................................................................ 6 Installazione della base dati .......................................................................................................................... 6 Installazione di Apache Tomcat 6.0.16 .......................................................................................................... 6 Installazione del Wrapper Standard .............................................................................................................. 7 Configurazione................................................................................................................................................... 8 Impostazione dei file di configurazione......................................................................................................... 8 camel-context.xml ..................................................................................................................................... 8 hibernate.cfg.xml....................................................................................................................................... 8 octopod.properties .................................................................................................................................... 9 Filtri per i messaggi duplicati ................................................................................................................... 11 Sicurezza .................................................................................................................................................. 12 Configurazione con il manager di gestione ................................................................................................. 15 3 Progetto LuMIR Wrapper Standard – Manuale Installazione Introduzione Nel seguente manuale viene descritta la procedura di installazione del Wrapper Standard su un computer dotato di cartella clinica per MMG. Requisiti minimi di sistema Sistema Operativo: Windows XP Service Pack 2 o superiore Memoria Ram: 1GB o superiore Spazio su disco fisso: 100MB (per l’installazione del Wrapper) Connessione internet a banda larga (ADSL) Prerequisiti Software Java Virtual Machine: Versione 6, in dotazione con la distribuzione software e scaricabile da http://java.com/it/download/manual.jsp Microsoft .Net Framework: Versione 3.5 sp1, in dotazione con la distribuzione software e scaricabile da http://www.microsoft.com/downLoads/details.aspx?familyid=AB99342F-5D1A-413D8319-81DA479AB0D7&displaylang=en PostgreSQL: versione 8.4.x, in dotazione con la distribuzione software e scaricabile da http://www.postgresql.org/download/ Bouncy Castle Crypto API: in dotazione con la distribuzione software e scaricabili da http://www.bouncycastle.org/latest_releases.html Estensioni Crittografiche Java (JCE): in dotazione con la distribuzione software Apache Tomcat 6.0.16: Una versione custom per il Wrapper Standard è fornita in dotazione con la distribuzione software 4 Progetto LuMIR Wrapper Standard – Manuale Installazione Installazione Installazione della Java Virtual Machine Lanciare il pacchetto di installazione (jre-6u17-windows-i586-s.exe) della Java Virtual Machine e seguire il wizard passo dopo passo. Al termine dell’installazione sarà necessario specificare una variabile d’ambiente per la stessa. Es: (nome variabile: JRE_HOME valore: C:\Programmi\Java\jre1.6.0_07 [sostituire con il proprio percorso di installazione]) Installazione di Bouncy Castle Crypto API Copiare il jar "bcprov-jdk16-139.jar" fornito in dotazione all’interno della cartella “Installazione Wrapper Standard/Sicurezza/BouncyCastle" all'interno di "C:\Programmi\Java\jre1.6.0_07\lib\ext" * Modificare il file "java.security" situato nella cartella "C:\Programmi\Java\jre1.6.0_07\lib\security" * aggiungendo la stringa "security.provider.10=org.bouncycastle.jce.provider.BouncyCastleProvider" subito dopo "security.provider.9=sun.security.mscapi.SunMSCAPI" (Un file di esempio si trova nella cartella “Installazione Wrapper Standard/Sicurezza/BouncyCastle") * Sostituire "C:\Programmi\Java\jre1.6.0_07" con la propria directory di installazione. Installazione di Estensioni Crittografiche Java (JCE) Decomprimere l'archivio "jce_policy-6.zip" fornito in dotazione all’interno della cartella “Installazione Wrapper Standard/Sicurezza/jce"; copiare quindi i file "local_policy.jar" e "US_export_policy.jar", sostituendo quelli contenuti in "C:\Programmi\Java\jre1.6.0_07\lib\security"*, avendo cura di fare una copia di backup degli originali) * Sostituire "C:\Programmi\Java\jre1.6.0_07" con la propria directory di installazione. 5 Progetto LuMIR Wrapper Standard – Manuale Installazione Installazione dei certificati Creare la cartella "C:\jks" e copiare al suo interno i certificati (“cacerts.jks” e “keystore.jks”) forniti dalle autorità di competenza. Installazione del Microsoft .Net Framework 3.5 SP1 Lanciare il pacchetto di installazione del .Net Framework e seguire il wizard passo dopo passo. Installazione del dbms PostgreSQL Lanciare il pacchetto di installazione (postgresql-8.4.0-1-windows.exe) e seguire il wizard passo dopo passo. Al momento richiesto, settare le seguenti credenziali in fase di setup (user: postgres – password: admin). Nel caso in cui si avesse intenzione di cambiarle, sarà opportuno annotarle, perché necessarie nelle successive fasi di configurazione. Installazione della base dati Connettersi a PostgreSQL attraverso il manager PgAdmin (Start -> Tutti i Programmi -> PostgreSQL 8.4 -> PgAdmin III) Eseguire gli script forniti in dotazione all’interno della cartella “Installazione Wrapper Standard/Database/ScriptSQL” nell’ordine indicato: 1. Creazione database.sql 2. Creazione tabelle.sql 3. Riempimento tabelle di decodifica.sql Installazione di Apache Tomcat 6.0.16 Scompattare l'archivio "apache-tomcat-6.0.16.zip" fornito in dotazione all’interno della cartella “Installazione Wrapper Standard/WebApp”; copiare quindi la cartella appena estratta (“apache-tomcat6.0.16”) comprensiva di tutto il suo contenuto, all’interno della cartella “C:\Programmi” 6 Progetto LuMIR Wrapper Standard – Manuale Installazione Installazione del Wrapper Standard Scompattare l'archivio "octopod.zip" fornito in dotazione all’interno della cartella “Installazione Wrapper Standard/WebApp”; copiare quindi la cartella appena estratta (“octopod”) comprensiva di tutto il suo contenuto, all’interno della cartella “C:\Programmi\apache-tomcat-6.0.16”. Settare quindi CATALINA_HOME nelle variabili d’ambiente ed aggiungerla al PATH del computer. Es: CATALINA_HOME=C:\Programmi\apache-tomcat-6.0.16 -> ;%CATALINA_HOME%\bin PATH ->nel nelle variabili di d'ambiente; sistema. Recarsi nella cartella "C:\Programmi\apache-tomcat-6.0.16\bin" e creare un collegamento al file “Startup.bat”. Copiare tale collegamento in “Esecuzione automatica” se si desidera che tomcat parta all’avvio del computer. Modificare il file “host” situato in "C:\WINDOWS\system32\drivers\etc", "78.40.170.44 aggiungendo la riga x3650san.bas-net.int". 7 Progetto LuMIR Wrapper Standard – Manuale Installazione Configurazione Di seguito viene descritta la procedura di configurazione per il wrapper standard. Tale processo avviene in due fasi: la prima si effettua attraverso la modifica degli appositi file di configurazione; la seconda, attraverso il manager di gestione. Impostazione dei file di configurazione camel-context.xml All’interno del file “\WEB-INF\classes\camel-context.xml” vanno configurate le property che consentono l’accesso alla base dati all’engine del wrapper. Di seguito le proprietà interessate. <property name="url" value="jdbc:postgresql://localhost:5432/octopod_db"/> Rappresenta la stringa di connessione alla base dati; a meno che il nome e la porta del database non siano stati cambiati in fase di installazione, essa non deve essere modificata. <property name="username" value="postgres"/> Rappresenta lo il nome utente dell’account di accesso alla base dati; se non è stato cambiato in fase di installazione, questo non deve essere modificato. <property name="password" value="admin"/> Rappresenta la password dell’account di accesso alla base dati; se non è stato cambiato in fase di installazione, questo non deve essere modificato. hibernate.cfg.xml All’interno del file “\WEB-INF\classes\hibernate.cfg.xml” vanno configurate per le property che consentono l’accesso alla base dati all’engine del wrapper. Di seguito le proprietà interessate. <property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/octopod_db</property> Rappresenta la stringa di connessione alla base dati; a meno che il nome e la porta del database non siano stati cambiati in fase di installazione, essa non deve essere modificata. <property name="hibernate.connection.username">postgres</property> Rappresenta lo il nome utente dell’account di accesso alla base dati; se non è stato cambiato in fase di installazione, questo non deve essere modificato. <property name="hibernate.connection.password">admin</property> Rappresenta la password dell’account di accesso alla base dati; se non è stato cambiato in fase di installazione, questo non deve essere modificato. 8 Progetto LuMIR Wrapper Standard – Manuale Installazione octopod.properties All’interno del file “\WEB-INF\classes\conf\octopod.properties” vanno configurate i parametri globali che assicurano il corretto funzionamento del wrapper standard, consentendo di attivare o disattivare caratteristiche aggiuntive. Di seguito le proprietà interessate. ROOT_ASL_HL7_OID = 102 Rappresenta il codice della struttura di appartenenza del medico che utilizzerà il wrapper standard. MAX_PULL_M2_MESSAGES = 10 Rappresenta il numero massimo di messaggi di notifica da scaricare per ogni richiesta (il valore di default è 10). TIMER_m2PollingSeconds = 60 Rappresenta l’intervallo di tempo, espresso in secondi, che intercorre tra il download dei messaggi di notifica (il valore di default è 60 secondi). MAX_PULL_M1RESPONSE_MESSAGES = 10 Rappresenta il numero massimo di messaggi di risposta da scaricare per ogni richiesta (il valore di default è 10). TIMER_m1ResponsePollingSeconds = 60 Rappresenta l’intervallo di tempo, espresso in secondi, che intercorre tra il download dei messaggi di risposta (il valore di default è 60 secondi). TIMER-xmlPollingSeconds = 10 Rappresenta l’intervallo di tempo, espresso in secondi, che intercorre tra l’invio delle richieste (il valore di default è di 10 secondi). TIMER_xmlRetryPollingSeconds = 120 Rappresenta l’intervallo di tempo, espresso in secondi, che intercorre tra l’invio delle richieste la cui spedizione è fallita in precedenza (il valore di default è di 120 secondi). DUPLICATE_FILTER_ON = true Consente di abilitare il filtro dei messaggi duplicati. Tale filtro consente di scartare messaggi già inviati in precedenza. Il funzionamento di tale filtro sarà esplicato in un’apposita sezione (valori possibili: true/false). ROUTE_M2_NOTIFICATION_ON = true Consente di abilitare il download dei messaggi di notifica (valori possibili: true/false). ROUTE_M1_RESPONSE_ON = true Consente di abilitare il download dei messaggi di risposta (valori possibili: true/false). 9 Progetto LuMIR Wrapper Standard – Manuale Installazione ROUTE_NCE_RETRY_ON = true Consente di abilitare il reinvio dei messaggi non spediti per mancata connettività (valori possibili: true/false). ROUTE_AUTHEX_RETRY_ON = true Consente di abilitare il reinvio dei messaggi non spediti per autenticazione fallita (valori possibili: true/false). M1_HEADER_NAMESPACE = xmlns=http://m1headerdatatypes.services.lumir.intemaweb.com/ Spazio dei nomi dell’header dei messaggi M1 (questo valore NON deve essere modificato). M1_BODY_NAMESPACE = xmlns=http://m1bodydatatypes.services.lumir.intemaweb.com/ Spazio dei nomi del body dei messaggi M1 (questo valore NON deve essere modificato). M1_HEADER_SCHEMA_LOCATION = /schemas/M1Header.xsd Posizione dello schema dell’header M1 (questo valore NON deve essere modificato). M1_BODY_SCHEMA_LOCATION = /schemas/M1Body.xsd Posizione dello schema del body M1 (questo valore NON deve essere modificato). BROKER_ENDPOINT_URL = http://78.40.170.44:9081/casaService1/casaPort1?wsdl Endpoint del broker (questo valore, in condizioni di normale utilizzo, NON dovrà essere modificato). BROKER_NAMESPACE = CompositeApp1 Target namespace del broker (questo valore NON deve essere modificato). BROKER_SERVICE_NAME = casaService1 Nome del servizio esposto dal broker (questo valore NON deve essere modificato). BROKER_PORT_NAME = casaPort1 Nome della porta del servizio esposto dal broker (questo valore NON deve essere modificato). BROKER_SOAP_ACTION = provideM1Request Soap Action del servizio esposto dal broker (questo valore NON deve essere modificato). NOTIFICATION_BROKER_ENDPOINT_URL = http://78.40.170.44:9081/casaService3/casaPort3?wsdl Endpoint del notification broker (questo valore, in condizioni di normale utilizzo, NON dovrà essere modificato). NOTIFICATION_BROKER_NAMESPACE = CompositeApp1 Target namespace del notification broker (questo valore NON deve essere modificato). NOTIFICATION_BROKER_PORT_NAME = casaPort3 Nome della porta del servizio esposto dal notification broker (questo valore NON deve essere modificato). 10 Progetto LuMIR Wrapper Standard – Manuale Installazione NOTIFICATION_BROKER_SERVICE_NAME = casaService3 Nome del servizio esposto dal notification broker (questo valore NON deve essere modificato). #Parametri di accesso al database per l'esecuzione del filtro duplicati: o dbServerURI = jdbc:postgresql://localhost:5432/octopod_db Rappresenta la stringa di connessione alla base dati; a meno che il nome e la porta del database non siano stati cambiati in fase di installazione, essa non deve essere modificata. o dbDriver = org.postgresql.Driver Rappresenta il driver specifico per il database in uso (Questo parametro non deve essere modificato). o dbUsername = postgres Rappresenta lo il nome utente dell’account di accesso alla base dati; se non è stato cambiato in fase di installazione, questo non deve essere modificato. o dbPassword = admin Filtri per i messaggi duplicati All’interno della cartella “\WEB-INF\classes\filters\” sono presenti file xml che contengono espressioni XPATH che consentono di rilevare messaggi duplicati, evitando quindi un reinvio. Tali file di configurazione non devono essere editati, spostati o cancellati in alcun modo, per non compromettere il corretto funzionamento del wrapper standard. 11 Progetto LuMIR Wrapper Standard – Manuale Installazione Sicurezza All’interno della cartella “\WEB-INF\classes\META-INF\” sono presenti i file di configurazione che consentono al wrapper standard di dialogare in maniera trasparente con il sistema di sicurezza LuMIR. Di seguito, per ognuno dei file, vengono esplicitati i principali tag soggetti a modifica, con il loro significato. casaPort1.xml <wsp1:Policy wsu:Id="casaBinding1Policy"> <wsp1:ExactlyOne> <wsp1:All> <tc:PreconfiguredSTS wspp:visibility="private" endpoint="http://78.40.170.44:8080/IdentityProvider/STS2Service" wstVersion="http://docs.oasisopen.org/ws-sx/ws-trust/200512"/> <sc1:KeyStore wspp:visibility="private" storepass="changeit" type="JKS" location="c:\jks\keystore.jks"/> <sc1:TrustStore wspp:visibility="private" storepass="changeit" type="JKS" location="c:\jks\cacerts.jks"/> </wsp1:All> </wsp1:ExactlyOne> </wsp1:Policy> tc:PreconfiguredSTS: o L’attributo endpoint contiene l’indirizzo del servizio di sicurezza LuMIR (In condizioni normali, questo parametro non dovrebbe essere modificato). sc1:KeyStore: o Nell’attributo location va inserita la posizione su disco del file “keystore.jks” installato in precedenza al passo “Installazione dei certificati” (Es: “C:\jks”) sc1:TrustStore: o Nell’attributo location va inserita la posizione su disco del file “truststore.jks” installato in precedenza al passo “Installazione dei certificati” (Es: “C:\jks”) 12 Progetto LuMIR Wrapper Standard – Manuale Installazione casaPort3.xml <wsp1:Policy wsu:Id="casaBinding3Policy"> <wsp1:ExactlyOne> <wsp1:All> <tc:PreconfiguredSTS wspp:visibility="private" endpoint="http://78.40.170.44:8080/IdentityProvider/STS2Service" wstVersion="http://docs.oasisopen.org/ws-sx/ws-trust/200512"/> <sc1:KeyStore wspp:visibility="private" storepass="changeit" type="JKS" location="c:\jks\keystore.jks"/> <sc1:TrustStore wspp:visibility="private" storepass="changeit" type="JKS" location="c:\jks\cacerts.jks"/> </wsp1:All> </wsp1:ExactlyOne> </wsp1:Policy> tc:PreconfiguredSTS: o L’attributo endpoint contiene l’indirizzo del servizio di sicurezza LuMIR (In condizioni normali, questo parametro non dovrebbe essere modificato). sc1:KeyStore: o Nell’attributo location va inserita la posizione su disco del file “keystore.jks” installato in precedenza al passo “Installazione dei certificati” (Es: “C:\jks”) sc1:TrustStore: o Nell’attributo location va inserita la posizione su disco del file “truststore.jks” installato in precedenza al passo “Installazione dei certificati” (Es: “C:\jks”) 13 Progetto LuMIR Wrapper Standard – Manuale Installazione STS2Service.xml <wsdl:service name="STSService2"> <wsdl:port name="ISTSService_Port" binding="tns:ISTSService_Binding"> <soap:address location="http:// 78.40.170.44:8080/IdentityProvider/STS2Service" /> <jaxws:bindings> <jaxws:provider>true</jaxws:provider> </jaxws:bindings> </wsdl:port> </wsdl:service> <wsp:Policy wsu:Id="ISTSService_BindingPolicy"> <wsp:ExactlyOne> <wsp:All> <sc1:KeyStore wspp:visibility="private" alias="username" storepass="changeit" type="JKS" location="c:\jks\keystore.jks"/> <sc1:TrustStore wspp:visibility="private" peeralias="sts" storepass="changeit" type="JKS" location="c:\jks\cacerts.jks"/> </wsp:All> </wsp:ExactlyOne> </wsp:Policy> soap:address: o L’attributo location contiene l’indirizzo del servizio di sicurezza LuMIR (In condizioni normali, questo parametro non dovrebbe essere modificato). ss1:KeyStore: o Nell’attributo alias va inserito lo username che sarà comunicato dalle autorità competenti, alla consegna del certificato. o Nell’attributo location va inserita la posizione su disco del file “keystore.jks” installato in precedenza al passo “Installazione dei certificati” (Es: “C:\jks”). sc1:TrustStore: o Nell’attributo location va inserita la posizione su disco del file “truststore.jks” installato in precedenza al passo “Installazione dei certificati” (Es: “C:\jks”). 14 Progetto LuMIR Wrapper Standard – Manuale Installazione Configurazione con il manager di gestione Una volta eseguita correttamente la fase di installazione, il manager di gestione della configurazione sarà raggiungibile con il browser web all’indirizzo http://localhost:18080/octopod La prima operazione necessaria è quella della creazione di un proprio account utente per poter accedere al manager. Una volta creato, sarà possibile accedere direttamente alla configurazione, saltando questo passo. Cliccando sul link “Sign Up” presente nella pagina iniziale, si avrà accesso alla pagina di creazione del proprio account personale. 15 Progetto LuMIR Wrapper Standard – Manuale Installazione Una volta riempiti i campi necessari (cognome, nome, username, password, indirizzo email) sarà sufficiente cliccare sul pulsante “Save user” per portare a termine l’operazione. 16 Progetto LuMIR Wrapper Standard – Manuale Installazione A A questo punto sarà possibile effettuare l’accesso cliccando sul pulsante “Login” ed inserendo le credenziali precedentemente specificate. 17 Progetto LuMIR Wrapper Standard – Manuale Installazione Il primo passo da effettuare è quello di specificare il nome dell’applicazione (es. Basmed, Millewin, Perseo…) che si intende interfacciare con il sistema LuMIR. Una volta inserito, basterà cliccare sul pulsante “New application” per poter procedere. Si verrà quindi rediretti alla pagina principale di riepilogo. 18 Progetto LuMIR Wrapper Standard – Manuale Installazione Il passo successivo consiste nella creazione di un endpoint. L’endpoint è rappresentato dalla cartella sul disco nella quale verranno depositati, dal software dell’MMG, i messaggi da inviare al sistema LuMIR, memorizzati come file xml. Clicchiamo quindi su “Endpoint Manager”, successivamente selezioniamo “Filesystem” come tipo di endpoint dal menù a tendina, ed infine clicchiamo su “New file system endpoint”. 19 Progetto LuMIR Wrapper Standard – Manuale Installazione Arrivati a questo punto, selezioniamo dal menù a tendina il tipo di file XML e, successivamente, specifichiamo il percorso della cartella nella quale l’applicativo legacy deposita i file da inviare a LuMIR. Per salvare le impostazioni sarà sufficiente cliccare su “Save endpoint”. 20 Progetto LuMIR Wrapper Standard – Manuale Installazione Verremo rediretti quindi alla pagina di riepilogo dell’endpoint appena creato, attraverso la quale potremo associare allo stesso le regole di trasformazione da applicare ai messaggi in uscita verso il sistema LuMIR. 21 Progetto LuMIR Wrapper Standard – Manuale Installazione Clicchiamo quindi sul pulsante “Associate Transformation rule”; ci troveremo nella pagina in cui dovremo specificare, per ogni operazione selezionata dal menù a tendina, i file addetti alle regole di trasformazione: nel dettaglio, andrà inserito un file xslt per la trasformazione dell’header xml, un file xslt per la trasformazione del body xml, ed infine un file xsd per la validazione del messaggio legacy da trasformare. N.B. I file delle regole di trasformazione verranno forniti a corredo dell’intera distribuzione software del wrapper standard. Cliccando su “Save Rule” porteremo a termine l’operazione. Va ricordato che questa operazione andrà ripetuta per tutti i tipi di operazione presentati nel menù a tendina. 22 Progetto LuMIR Wrapper Standard – Manuale Installazione Se la configurazione è andata a buon fine, il risultato sarà il seguente: 23 Progetto LuMIR Wrapper Standard – Manuale Installazione Infine, nella maschera di riepilogo (raggiungibile cliccando sul pulsante “Home”), sarà possibile attivare il wrapper standard, cliccando sul pulsante posto in alto a destra. Lo stato dell’applicazione, visualizzato in alto a sinistra, cambierà quindi da a . 24 Progetto LuMIR Wrapper Standard – Manuale Installazione 25