OpenTele datamonitoreringsplatform

Transkript

1 OpenTele datamonitoreringsplatform Systemdokumentation for OpenTele servere- og klienter 09. marts 2015 Side 1 af 17

2 Indholdsfortegnelse Indholdsfortegnelse Indledning Systemoverblik OpenTele server - Installation og drift Forudsætninger før installation Klargøring af database mv. før installation Deployment til Apache Tomcat 7 Overblik over log-filer for OpenTele server Installation / opdatering af STS certifikat Konfiguration af hjælpebilleders placering Overvågning af OpenTele server OpenTele monitoreringssnitflade Backup og restore af OpenTele server Backup af Java EE web applikationer Backup af database Restore af OpenTele server OpenTele Android klient OpenTele HTML5 klient Dokumenthistorik Side 2 af 17

3 Indledning Dette dokument udgør den tekniske systemdokumentation for OpenTele-platformen. Systemdokumentationen indgår i den samlede OpenTele dokumentationspakke, hvis dele er beskrevet i OpenTele dokumentationsoverblik. Formålet med systemdokumentationen er at beskrive hvordan OpenTele platformen installeres, konfigureres og driftes. Dokumentet giver et overblik over konfigurationsfiler, log-filer og andre relevante objekter. Systemdokumentationen tager udgangspunkt i, at en række komponenter er tilgængelige. De væsentligste af disse er et operativsystem, en database og en eller flere Java EE servlet containere. Systemoverblik Dokumentet OpenTele Arkitektur og design beskriver den overordnede arkitektur for OpenTele platformen. I det følgende gengives dele af arkitekturbeskrivelsen, med fokus på de elementer der er relevante for systemdokumentationen. OpenTele platformen består overordnet af en Android baseret klient-app, der findes i en Java baseret- og en HTML5 baseret udgave, samt en web-applikation, der er splittet op i en klinikerog en borgerserver. Web applikationerne afvikles på serversiden i en eller flere Java EE web containere. OpenTele platformen kan konfigureres til at overføre modtagne CTG målinger til en Medexa Milou server. Det er også muligt at konfigurere platformen til at overføre målinger til den centrale nationale KIH database. Nedenfor er den overordnede principielle systemarkitektur illustreret. Side 3 af 17

4 I illustrationen vises en OpenTele klinikerserver (OpenTele Provider server) og en OpenTele borgerserver (OpenTele Citizen server) som tilsammen udgør OpenTele web applikationen. Klinikerserveren udstiller en webbaseret brugergrænseflade til klinikere, som de anvender via en browser. Patienter (/borgere) henter spørgeskemaer fra OpenTele borgerserveren og indsender måledata til den via OpenTele Android app en eller OpenTele HTML5 app en. De to apps kommunikerer med OpenTele borgerserveren via en JSON protokol over http(s). Når HTML5 app en startes henter den sin brugergrænsefladen fra en simpel webapp (OpenTele HTML5) dedikeret til udelukkende dette formål. Klinikerserveren har integrationer til en række eksterne systemer: opslag vedr. patient information til CPR service på NSP overførsel af CTG-målinger til Milou for visning der export af målinger til KIH-databasen Side 4 af 17

5 OpenTele borger- og klinikerserveren anvender i fællesskab en standard SQL database som datalager. Løsningen er testet med H2, MySQL 5 og Microsoft SQL Server I det følgende antages at en Tomcat 7 Java EE web-container anvendes på serversiden. OpenTele bør også fungere uden større problemer i følgende Java EE Containere som er supporteret af Grails Tomcat 7 Tomcat 6 SpringSource tc Server Eclipse Virgo GlassFish 3 GlassFish 2 Resin 4 Resin 3 JBoss 6 JBoss 5 Jetty 8 Jetty 7 Jetty 6 Oracle Weblogic 10.3 Oracle Weblogic 10 Oracle Weblogic 9 IBM WebSphere 8.5 IBM WebSphere 8.0 IBM WebSphere 7.0 IBM WebSphere Se Side 5 af 17

6 OpenTele server - Installation og drift Da installation af OpenTele kliniker- og borgerserverne foregår på præcis samme måde - på nær en enkelt konfigurationsfil - anvender vi begrebet OpenTele server når et skridt i installationen er ens for begge applikationer. OpenTele server er en Java EE web applikation, udviklet i Groovy frameworket Grails I det følgende beskrives hvordan en Java EE web-applikation (WAR-fil) bygges og installeres på en applikationsserver. Selve installationen af WAR-filen i Java EE applikationsserveren afhænger af hvilket operativsystem, samt hvilken applikationsserver og databaseteknologi, man vælger at anvende. I det følgende eksempel anvendes version 7 af Apache Tomcat Servlet Containeren som applikationsserver, MySQL 5 som datalager og OS X 10.7 som operativsystem. Forudsætninger før installation Før installation af OpenTele server forudsættes følgende: 1. Adgang til en, to eller flere fysiske eller virtuelle maskiner med operativsystem installeret. Det er op til en konkret designbeslutning i opsætningen af systemet, om man vil afvikle applikationsserver og database på separate maskiner. Samt om man vil afvikle kliniker-, borgerserver samt HTML5 brugergrænseflade-server server på samme maskine. I det følgende antages at alle tre web applikationer installeres i én applikationsserver på én maskine og at databasen er tilgængelig på en anden maskine. Vær opmærksom på at OpenTele klinker- og borgerserver skal anvende samme database. 2. På systemets applikationsserver skal en Java EE webcontainer være installeret. F.eks. JBoss eller Apache Tomcat 7. Applikationsserveren skal anvende Java På systemets database server skal f.eks. MySQL eller SQL Server være installeret. 4. En WAR-fil med OpenTele web-applikationerne, bygget til det konkrete miljø skal være tilgængelig. 5. Hvis OpenTele skal integrere til CPR opslag på NSP, samt KIH Databasen, skal et relevant certifikat i PKCS12 format være tilgængeligt. Side 6 af 17

7 Kompilering- og byg af WAR applikationer er beskrevet nærmere i dokumentet OpenTele Guide til videreudvikling. Kort beskrevet, skal et miljø (environment) defineres i web-applikationen (gøres af systemets udviklingsteam). Efterfølgende skal en WAR fil til det konkrete miljø bygges. Hvis et miljø med navnet osxtest f.eks. er defineret, kan war-filen bygges med kommandoen: grails Dgrails.env=osxtest war Klargøring af database mv. før installation I det følgende beskrives hvordan OpenTele installeres (deployes) til Apache Tomcat 7. For installation til andre Java EE web containere, f.eks. JBoss, henvises til den sektion i manualen for den konkrete web containere, som beskriver installation af web-arkiver (WAR-filer). Før installation af web-arkivet skal systemets database være installeret. Hvis MySQL anvendes kan dette f.eks. ske ved at installere MySQL, og efterfølgende oprette en database, og en OpenTele bruger, med kommandoerne nedenfor: create database opentele character set utf8; GRANT SELECT, INSERT, UPDATE, CREATE, DELETE, DROP, ALTER, INDEX on opentele.* TO 'opentele'@'localhost' IDENTIFIED BY 'opentele'; flush privileges; Husk at udskifte brugernavn og adgangskode i ovenstående. Når databasen er installeret skal der oprettes en konfigurationsfil, hvorfra web-applikationen henter sin konfiguration. På Windows placeres konfigurationsfilen i biblioteket: c:\kihdatamon\settings\datamon-config.properties for OpenTele klinikerserveren, og c:\kihdatamon\settings\datamon-citizen-config.properties for OpenTele borgerserveren. På Unix baserede systemer (f.eks. Linux eller OS X) placeres filen i biblioteket: ${userhome}/.kih/datamon-config.properties for OpenTele klinikerserveren, og ${userhome}/.kih/datamon-citizen-config.properties for OpenTele borgerserveren. Hvor ${UserHome} angiver home-biblioteket for den bruger som web-containeren kører under. Side 7 af 17

8 Hvis filen ønskes placeret andetsteds, skal dette ændres i systemets kildekode. Nedenfor ses to eksempler på OpenTele server konfigurationsfiler. Én hvor web-applikationen anvender en MySQL database som datalager, og én hvor web-applikationens datalager er en Microsoft SQL Server. Eksempel på OpenTele server konfigurationsfil med MySQL database: # Common settings #datasource.dbcreate = update datasource.pooled = true #datasource.logsql = false ## MYSQL DB datasource.dialect = org.opentele.server.core.util.mysqlinnodbdialect datasource.driverclassname = com.mysql.jdbc.driver datasource.username = opentele datasource.password = opentele datasource.url = jdbc:mysql:// :3306/opentele Eksempel på OpenTele server konfigurationsfil med SQL Server database (OBS: Hvis katalog ikke anvendes på SQL Server fjernes default_catalog linien): # Common settings #datasource.dbcreate = update datasource.pooled = true #datasource.logsql = false # SQL Server DB datasource.driverclassname = net.sourceforge.jtds.jdbc.driver datasource.username = opentele datasource.password = opentele datasource.url = jdbc:jtds:sqlserver:// :1433:opentele datasource.dialect = org.opentele.server.core.util.sqlserverdialect hibernate.default_schema = dbo hibernate.default_catalog = opentele Konfigurationsfil parameteren datasource.dbcreate, mapper til Grails standard databaseopsætningsparameter og kan antage værdierne i nedenstående tabel. I et produktionssetup, anbefales det at parameteren fjernes helt, eller at den sættes til værdien validate, da der ellers er risiko for, at systemet vil forsøge at overskrive dets database når det startes/genstartes. Hvis man i forbindelse med installationen af OpenTele server ønsker at oprette tabeller mv. i systemets database, kan det gøres ved at starte systemet med værdien sat til: Side 8 af 17

9 datasource.dbcreate = create. Efterfølgende - når systemet er startet og tabelstruktur er oprettet - skal parameteren ændres til f.eks. datasource.dbcreate = validate. En bedre metode til oprettelse af tabeller er, at systemets udviklere danner et tabeloprettelsesscript (DDL). Og at systemet enten konfigureres med en tom datasource.dbcreate eller med datasource.dbcreate = validate. dbcreate værdi Betydning create Ved opstart af web-applikationen nyoprettes tabeller og andre databaseobjekter. update Ved opstart af web-applikationen oprettes tabeller og andre databaseobjekter som ikke i forvejen eksisterer i databasen. (OBS: Anbefales ikke! I stedet anbefales at systemets udviklere manuelt håndterer database migrering, eller alternativt anvender Grails Database Migration plugin til migrering af databasestruktur. Se OpenTele udviklerguiden for yderligere detaljer). validate Ved opstart af web-applikationen validerer applikationen om alle nødvendige databaseobjekter er til stede. Hvis de ikke er til stede kan applikationen ikke starte og logger i stedet en fejl til dens log-filer. Tom værdi. Systemet antager at alle nødvendige databaseobjekter er til stede, men gør ikke noget for at undersøge om det er tilfældet. Deployment til Apache Tomcat 7 Når database- og konfigurationsfiler er klargjort kan web-applikationerne (WAR-arkiver) installeres på systemets applikationsserver(e). På Apache Tomcat sker dette ved at kopiere war-filen/filerne (f.eks. opentele-server.war) til Tomcat-serverens webapps bibliotek. På OS X og Linux kan dette gøres i en shell med kommandoen: cp opentele-server.war ${TOMCAT_HOME}/webapps/ Afhængigt af hvordan Apache Tomcat serveren er konfigureret, vil ovenstående kommando installere opentele web-applikationen, så dens rod-kontekst er opentele-server, når man åbner den fra en webbrowser, d.v.s.: Side 9 af 17

10 Hvis man i stedet ønsker, at applikationen skal installeres så brugere ikke skal angive en rodkontekst kan det gøres ved at omdøbe war-filen til ROOT.war når den kopieres til webapps biblioteket: cp opentele-server.war ${TOMCAT_HOME}/webapps/ROOT.war Når applikationen deployes som ROOT.war, forstår Tomcat det sådan, at den skal udbyde applikationen uden en rod-kontekst. Dvs. på adressen: Bemærk: hvis OpenTele kliniker- og borgerserver deployes på samme server, kan kun én af dem have rod-kontekst. Efter installation verificeres om serveren er korrekt installeret ved f.eks. at: overvåge om applikationen skriver fejl til sine log-filer verificere at applikationen er tilgængelig via en web-browser Nedenfor er vist et eksempel på, hvordan OpenTele klinikerserverens log-ind side ser ud på miljøet hovedstaden-test, når den er deployet som ROOT.war. Side 10 af 17

11 Overblik over log-filer for OpenTele server OpenTele server er konfigureret til at sende sine logs til Tomcats standard-logbibliotek. Dvs.: <TOMCAT>/logs Hvis systemet skal skrive log-filer til en anden lokation, skal dette konfigureres af udviklingsorganisationen (i filen Config.groovy ). I standard-opsætningen logger OpenTele webapplikationen til filen opentele.log. Som standard er applikationen konfigureret til at danne en ny log-fil på dagsbasis. Dvs. nyeste log-fil er filen opentele.log. Ældre log-filer omdøbes, så de efter opentele.log tilføjes datoen for de logninger filen indeholder. F.eks.: Filnavn Beskrivelse opentele.log Seneste logninger fra OpenTele web-applikationen opentele.log Logninger fra 5. januar 2015 opentele.log Logninger fra 4. januar 2015 opentele.log Logninger fra 3. januar 2015 Side 11 af 17

12 Logfilen bør ikke indeholde fejl-logninger. Disse er kendetegnet ved at ordet ERROR indgår i starten af en lognings-linie. Installation / opdatering af STS certifikat OpenTele anvender et OCES certifikat i forbindelse med autentifikation ved indsendelse af data til KIH Databasen samt CPR opslag mod den Nationale Serviceplatform (NSP). Konkret henter OpenTele billetter til adgang til de to services fra en identitetsservice (STS - Security Token Service) på NSP. Nedenfor beskrives hvordan OCES (VOCES) certifikat konfigureres i OpenTele. For at kunne hente en billet skal OpenTele via filsystemet, eller via en jar på CLASSPATH, have adgang til et certifikat installeret i en Java keystore. En Java keystore oprettes som følger: Fra f.eks. OpenTele driftsoperatøren modtages en pkcs12 fil med certifikat og privat nøgle. (Husk også at få password til pkcs12 filen og den private nøgle.) I pkcs12 filen er certifikatparret gemt under et alias. Hvis alias ikke er kendt i forvejen kan det findes med kommandoen: keytool -v -list -storetype pkcs12 -keystore <PKCS12_FIL> grep Alias Som f.eks. giver resultatet: Alias name: opentele - opentelekih-prod Dvs. alias er opentele - opentelekih-prod. PKCS12 filen konverteres til java keystore format med kommandoen: keytool -importkeystore -srckeystore <PKCS12_FIL> -srcstoretype pkcs12 -srcalias <ALIAS> -destkeystore <NY_KEYSTORE.jks> -deststoretype jks -deststorepass <KEYSTORE_PASS> -destalias sosi:alias_system Det er væsentligt at destalias sættes til sosi:alias_system. De andre parametre til kommandoen er: Parameter <PKCS12_FIL> <NY_KEYSTORE.jks> <KEYSTORE_PASS> Forklaring Filnavn (evt. inkl. sti) på pkcs12 filen Filnavn på den Java Keystore, som skal oprettes Password på den nye Java Keystore som bliver oprettet Side 12 af 17

13 <ALIAS> ALIAS certifikatet ligger under i pkcs12 filen. Se tidligere note om hvordan alias findes hvis det ikke er kendt. Når Java keystore er oprettet kan indholdet kontrolleres med: keytool -list -v -keystore <NY_KEYSTORE.jks> -storepass <KEYSTORE_PASS> Til sidst sikres, at aliaset har samme password som jks-keystore filen: keytool -keypasswd -alias sosi:alias_system -new <KEYSTORE_PASS> -keystore prod2.jks Når Java Keystore filen er oprettet skal den placeres i OpenTele serverens filsystem og OpenTele (kliniker-) serveren skal konfigureres til at anvende keystore-filen. Det sker ved at tilpasse OpenTele serverens konfigurationsfil ( datamon-config.properties ) hvor nedenstående skal udfyldes: seal.cvr = <CVR> seal.systemname = <SYSTEM_NAME> seal.federation.type = production seal.vault.type = file seal.vault.password=<keystore_pass> seal.vault.path = <PATH_TO_JKS_FILE, fx: c:/opentele/prod2.jks> seal.sts.url = Konfiguration af hjælpebilleders placering Det er muligt at angive hjælpebilleder, som kan vises på den borger-/patientrettede brugergrænseflade. Billederne uploades via den administrative brugergrænseflade. Stedet filerne uploades til angives som en sti i OpenTele serverens konfigurationsfil ( datamon-config.properties ) hvor nedenstående skal udfyldes: help.image.uploadpath = C:/billeder Det anbefales at folderen hvor billederne opbevares er omfattet af en passende backup løsning. Hvis OpenTele er distribueret på flere separate servere, skal de alle kunne nå den angivne folder, f.eks. kan folderen ligge på et netværksdrev. Side 13 af 17

14 Overvågning af OpenTele server I dette afsnit beskrives den snitflade OpenTele serveren stiller til rådighed for anvendelse i en driftsmæssig overvågning af platformen. En samlet overvågning af systemet bør også omfatte overvågning af systemets processer samt databaseserver og diskplads m.v. Hvilke processer der skal være kørende på systemet afhænger af hvilken Databaseteknologi og hvilken Java EE webcontainer systemet anvender. Der henvises derfor til dokumentationen for de konkrete produkter. OpenTele monitoreringssnitflade OpenTele serveren udstiller en simpel web-side, som kan anvendes til overvågning af serverens tilstand fra enten et overvågningssystem eller f.eks. en browser. Web-siden udstilles på adressen: http(s)://<opentele-url>/<rod-kontekst>/isalive Når siden kaldes, undersøger systemet om det er korrekt kørende og om det har mulighed for at skabe forbindelse til dets database. I nedenstående skærmbillede vises et eksempel på siden, som den ser ud når alt er fungerende: Der er fem værdier på siden, som beskrives i følgende tabel: Tekst responsetext runningversion environment isdatabasealive Beskrivelse Svarer I m alive! hvis systemets applikationsserver er fungerende. Angiver hvilken version af OpenTele serverapplikationen der er installeret på serveren. Angiver hvilket miljø serveren er konfigureret som (eksempelvis test, devel eller production) Angiver om applikationsserveren (f.eks. Tomcat) kan oprette en forbindelse til systemets SQL database. Mulige svar er: Yes. eller No.. Side 14 af 17

15 concurrentusers Angiver hvor mange aktive brugersessioner der er på serveren. For at have et fuldt fungerende system, skal responsetext være I m alive! og isdatabasealive være Yes.. Backup og restore af OpenTele server I det følgende angives anbefalinger for backup/restore strategier for OpenTele server (borgerog kliniker). Den konkrete strategi og fremgangsmåde afhænger af hvilke teknologier en konkret installation anvender. Backup af Java EE web applikationer OpenTele server applikationen gemmer alle data i sin database. Det bør derfor ikke være nødvendigt at lave løbende backup af applikationsserverens filsystem - bortset fra stedet hvor hjælpebilleder placeres. Det anbefales derfor, at der efter installation laves en initiel backup af den maskine serveren er installeret på, og at der løbende tages backup af serverens hjælpebilleder og konfigurationsfil (beskrevet i tidligere afsnit). Hvorvidt der udføres backup af web applikationens log-filer, besluttes i forbindelse med den konkrete installation. Backup af database Det anbefales at der etableres løbende backup af systemets database, således data ikke kan gå tabt ved evt. systemnedbrud. Restore af OpenTele server Hvis der er sket en hændelse, som medfører at det er nødvendigt at lave restore af hele eller dele af OpenTele installationen, anbefales følgende overordnede fremgangsmåde: 1) Kontrollér, at alle systemets applikationsservere, og andre systemer som skriver til systemets database, er standsede 2) Gendan systemets database 3) Start databaseserveren 4) Lav restore af systemets applikationsservere (eller start dem igen). OpenTele Android klient OpenTele Android klienten er en Android app, udviklet til Android Side 15 af 17

16 Klienten er testet på Samsung Galaxy Tab 10.1 og Samsung Galaxy Tab , begge med Android Klienten anvender Bluetooth Health Device Profile (HDP) til kommunikation med måleudstyr. HDP er først understøttet fra Android version 4. I stor-skala drift anbefales det at etablere en enterprise model for installation af klienter, således klienten fra centralt hold automatisk kan installeres på organisationens mobile enheder uden involvering fra slutbrugeren. Installation- og opdatering af OpenTele Android klienten er beskrevet i dokumentet, OpenTele klient installations- og opdateringsguide. Der henvises derfor til dette for yderligere information vedrørende klientinstallation. OpenTele HTML5 klient OpenTele HTML5 klienten er en HTML5 app pakket ind i en Android wrapper. Klienten er testet på Google Nexus 7, med Android 4.4.4, og kræver en tablet med Android 4.3 eller højere. HTML5 klienten er delt op i en web applikation (webserver) der returnerer selve HTML5 applikationen og en Android wrapper der viser den i en Android kontekst. Webserver-delen af HTML5 klienten kan bygges som en WAR-fil der deployes på samme måde som OpenTele serveren, beskrevet i afsnittet Deployment til Apache Tomcat 7. HTML5 klienten understøtter på nuværende tidspunkt ikke kommunikation med måleudstyr. Som for OpenTele Android klienten anbefales det i stor-skala at etablere en enterprise model for installation af klienter, således klienten fra centralt hold automatisk kan installeres på organisationens mobile enheder uden involvering fra slutbrugeren. Installation- og opdatering af OpenTele HTML5 klienten er beskrevet i dokumentet, OpenTele klient installations- og opdateringsguide. Der henvises derfor til dette for yderligere vedr. klientinstallation. Dokumenthistorik Version Dato Initialer Ændring Side 16 af 17

17 Initiel version Opdateret dokumentet til at afspejle opsplitning, grails 2.4 og html5 klient HRA Tlføjet tekst vedr. konfiguration af hjælpebilleder HRA Mindre rettelser i forbindelse med review af dokumentationspakke. Side 17 af 17