Stamdatamodulets design og arkitektur KOMBIT

Stamdatamodulets design og arkitektur KOMBIT

1 Indholdsfortegnelse 1 Indholdsfortegnelse... 2 2 Historik... 3 3 Arkitekturoverblik... 4 3.1 Importer... 5 3.2 Replikeringstjenesten... 5 3.3 CPR-opslagskomponenten... 5 4 Benyttede komponenter... 5 5 Fysisk Datamodel... 5 6 Importer... 7 6.1 Arkitektur... 7 6.2 Funktionalitet... 9 6.3 Validering af input... 9 7 Replikeringstjenesten... 10 7.1 Arkitektur... 10 7.2 Funktionalitet... 11 8 CPR-opslagskomponent... 12 8.1 Arkitektur... 12 9 Teknologiarkitektur... 13 9.1 SSL-terminering... 14 9.2 Skalerbarhed... 14 10 Referencer... 14 11 Komponenter og licenser... 15 Design og arkitektur 2

2 Historik Dato Version Ændring Ansvarlig 4. maj 2011 1.0 OFO, AHJ 5. maj 2011 1.1 Tilføjede figur med skalering af OFO database og replikeringstjeneste. 19. maj 2011 1.2 Rettelser efter KOMBIT review SEF/AHJ 10. juni 2011 1.3 Rettelser efter 2. KOMBIT review AHJ/SEF 20. juni 2011 1.4 Tilføjelse af opslagskomponent OFO/FRJ Design og arkitektur 3

3 Arkitekturoverblik Stamdatamodulet består af følgende komponenter: Importer. Administrator-GUI. Replikeringstjeneste CPR-opslagskomponent Database. Administrator-GUI en ligger dog som en del af replikeringstjenesten, og er derfor også deployet i samme webcontainer. Importeren, replikeringstjenesten og opslagskomponenten integrerer via databasen, som illustreret i nedenstående diagram: Register X CPR Importer Stamdatamodul DB Replikeringstjeneste Anvendersystem 1 Anvendersystem 2 Opslagskomponent Anvendersystem 3 Ovenstående figur viser stamdatamodulets opbygning. Importeren importerer data fra CPR og evt. andre registre til databasen. Replikeringstjenesten og opslagskomponenten udstiller data for anvendersystemer. Design og arkitektur 4

3.1 Importer Overordnet set er det importer-modulets opgave at importere data fra forskellige registre til databasen. Data leveres til importeren som filer på det lokale filsystem. Formatet af inputfilerne er registerspecifikke. Importeren er beskrevet i afsnit 6. 3.2 Replikeringstjenesten Replikeringstjenesten overordnede opgave er at udstille data i via REST. Data udstilles i form af feeds baseret på ATOM-standarden.Replikeringstjenesten er beskrevet i afsnit Fejl! Henvisningskilde ikke fundet.. 3.3 CPR-opslagskomponenten Opslagskomponenten udstiller cpr-data for enkeltpersoner via REST i Person(Part)-format. 4 Benyttede komponenter Alle benyttede komponenter og produkter (jf. afsnit 11) er baseret på open source-licenser. Løsningen er desuden selv open source. Som database benyttes MySQL. Løsningen benytter ikke MySQL-specifikke features, men databaseschemaet skal tilpasses hvis løsningen skal deployes på andre databaser. Applikationen deployes i JBoss, der er en J2EE-applikationsserver. Der anvendes dog ingen JBoss-specifik funktionalitet.applikationen bør derfor kunne deployes i en hvilken som helst Servlet container der understøtter minimum version 2.4 af servlet specifikationen. Løsningen erafprøvet på JBoss, Trifork T4, Tomcat og Jetty. Derudover anvendes en lang række open source-frameworks, såsom Log4J, Google Guice, Hibernate, Apache Commons, Freemarker og OOAPI. Disse bundles med WAR-filerne i korrekte versioner.. Som byggesystem anvendes Gradle (http://www.gradle.org). Filen libraries.groovy i config-biblioteket angiver præcis ID og version af de frameworks vi anvender. For afhængigheder for de enkelte moduler henvises til dependencies sektionen i byggefilen for modulet. 5 Fysisk Datamodel Integrationen mellem Importeren og replikeringstjenesten sker via den fysiske datamodel. Alle data i Stamdatamodulet er opdelt efter type. Alle typer data har tilknyttet et gyldighedsinterval, således at der opbygges en historik efterhånden som nye data, der erstatter gamle data, lægges i systemet. For cpr-data leverer cpr-kontoret et gyldighedsinterval for visse typer data. I disse tilfælde benyttes gyldighedsintervallet fra cpr-data. I de resterende tilfælde antages data at være gyldige fra udtrækstidspunktet. Der henvises til CPR-kontorets dokumentation for udtræk til det offentlige, hvoraf det fremgår hvilke record-typer der indeholder gyldighedsintervaller. Den delmængde af datamodellen der drejer sig om cpr, ser ud som følger. Design og arkitektur 5

Hver række i databasen indeholder: En PID: En databasegenereret primærnøgle. PID en anses for intern, replikeringsservicen sender ikke PID til klienterne. Design og arkitektur 6

CPR: CPR-nummeret på den person som rækken vedrører. For relationer mellem personer er der en person som ejer relationen. ValidFrom, ValidTo: Gyldighedsperiode for rækken. Der er tale om valid time, altså semantisk gyldighedsinterval, ikke transaction time. CreatedDate: Tidspunkt for hvornår rækken indsættes i databasen. ModifiedDate: Hvornår rækken sidst blev modificeret i databasen. ModifiedBy: Indeholder altid værdien SDM2. Eksisterer af legacy årsager. Der er ingen foreignkeys mellem de forskellige tabeller. Det kan ikke lade sig gøre, idet der er tale om temporale tabeller. Således er eksempelvis CPR-kolonnen ikke unik. Generelt er det tilstræbt at datamodellen i høj grad stemmer overens med hvordan data eksponeres via Replikeringstjenesten,og hvordan de leveres fra CPR. Det skaber størst muligt throughput ved at holde databasesøgningen så simpel som overhovedet mulig. Generelt er gyldighedsintervallerne dog omdøbt til ValidFrom og ValidTo uanset deres navne i CPRudtrækket. Endvidere er nogle recordtyper også samlet i Person-tabellen. Det drejser sig om Personoplysninger (recordtype 1) Navneoplysninger (recordtype 8) og Klarskriftsaddresse (recordtype 3). Det er primært af legacy-årsager, at Person-tabellen samler data fra flere record-typer. For dokumentation af de enkelte felter i datamodellen henvises til CPR-kontorets dokumentation for udtræk til det offentlige. For præcis dokumentation af SQL-typer, indexes m.v. henvises til db/schema.sql filen i kildekoden, som indeholder de DDL-statements som udgør databaseschemaet. 6 Importer 6.1 Arkitektur Importer-modulet består af en række uafhængige importere. En importer er en komponent, som er i stand til at importere data fra et register, eksempelvis CPR. Fælles for alle registre er, at data leveres i filer, som læses fra det lokale filsystem. Importerne instantieres og overvåges Design og arkitektur 7

af SpoolerManageren. Importere fungerer som plugins, der kan aktiveres og konfigureres uafhængigt af hinanden. SpoolerManageren kalder hvert 5. Sekund (konfigurerbart) Importerne som selv er ansvarlige for at undersøge om der er nye filer tilgængelige. Importerne parser input-filer og genererer instanser af nogle modelklasser, som samles i et datasæt, som returneres til SpoolerManageren. Denne sender datasættene genereret af importeren videre til Persisteren, som har ansvaret for at persistere de nye data i databasen. Hver importer har sine egne modelklasser, som har annotationer der fortæller Persisteren hvordan de pågældende modelklasser skal persisteres i databasen. Hver modelklasse korresponderer i udgangspunktet til en tabel i databasen, men der er mulighed for at flere modelklasser kan persisteres i den samme tabel.for CPR-importeren gælder, at der er en modelklasse for hver recordtype i CPR-udtrækket. Komponenterne i importeren anvender alle et sæt fælles komponenter, bl.a. til logning og konfiguration. 6.1.1 Komponenter Nedenfor gennemgås de forskellige delkomponenter af importeren. Hver enkelt java-pakke beskrives. 6.1.1.1 com.trifork.stamdata.config Komponent til indlæsning af konfiguration 6.1.1.2 com.trifork.stamdata.dao Fælleskomponent til persistering af data i databasen. Håndterer generering af SQLstatements, samt det temporale aspekt af data. 6.1.1.3 com.trifork.stamdata.spooler Importere kaldes af historiske årsager for Spoolere. Denne pakke indeholder klasser til registrering, eksekvering og overvågning af Spoolere. 6.1.1.4 com.trifork.stamdata.jobspooler Komponent til håndtering af batch jobs. Anvendes ikke af CPR-parseren. 6.1.1.5 com.trifork.stamdata.importer Fælles interface for importere. En importer skal implementere interfacet FileImporter, og implementationsklassen skal angives i konfigurationen. 6.1.1.6 com.trifork.stamdata.cpr CPR-importeren. Implementationsklassen er CPRImporter. CPRParser klassen indeholder kode til at parse hver enkelt record-type fra CPR. 6.1.1.7 com.trifork.stamdata.importer.cpr.model Model-klasser til at repræsentere til forskellige records fra CPR. Disse er beriget med annotationer, som angiver hvordan DAO-laget skal persistere den pågældende record-type i databasen. Design og arkitektur 8

6.1.1.8 com.trifork.stamdata.tools Indeholder værktøj til opsplitning af CPR input-filer. CPR input-filer kan opsplittes i mindre filer for at mindske hukommelsesbehovet for CPR-importeren. 6.1.1.9 com.trifork.stamdata.util Indeholder utility-klasse til konvertering af datoer. 6.1.1.10 com.trifork.stamdata.webinterface Komponent, som udstiller systemets aktuelle driftstilstand via en http status side til brug for overvågning. 6.2 Funktionalitet Importeren overvåger løbende bestemte mapper (konfigurerbart ift. den konkrete driftopsætning)i filsystemet, og når en fil dukker op, indlæses denne i systemet. Selve overførslen af filer til filsystemet håndteres således ikke af Stamdatamodulet, men sættes op af driftsoperatøren til fx at overføre cpr-data via FTP til den mappe som Stamdatamodulet overvåger for cpr-datafiler. Inden filen overføres til Stamdatamodulet bør der tages backup af de hentede filer jf. Installations- og Driftsvejledning. Import af en fil foregår i en selvstændig database-transaktion. Opstår der fejl under importen, rulles transaktionen tilbage. Dette bevirker at resten af systemet ikke er påvirket af fejlede eller halvfærdige import-forsøg. Importeren udstiller systemets drifts-tilstand som en web-service som driftsoperatøren overvåger. Ved fejl under import kan driftsoperatøren dermed alarmeres. Ved fejl under import af cpr-data blokeres import, og systemet afventer at problemet afhjælpes manuelt af driftsoperatøren (se Driftsvejledning). Løsningen sikrer at filer importeres i korrekt rækkefølge. I filnavnet for den enkelte fil indgår dato for udtræk. Denne dato benyttes til sortering så den yngste fil importeres først. Hver fil har desuden en startdato (gældende fra) og en dato for næste forventede udtræk. Hvis den næste fil der indlæses ikke har en startdato der matcher den forventede dato så afvisesfilen, og man kan via driftsovervågning se at der ligger filer. Afviste filer lægges i <stamdata-input-rod>/input/cpr/rejected i en mappe med tidsstempel. Heri lægges også en fil med navn RejectReason, som indeholder en fejlbesked og stacktrace. 6.3 Validering af input Vi udfører begrænset validering af input fra CPR. Validering af længden af inputfelterne valideres implicit af formatet for CPR-udtræk. Det sikrer, at ingen felter indeholder længere strenge end tilladt. Felter, hvor der forventes værdier fra en kodeliste valideres ikke op mod kodelisten. Årsagen til dette er at vi ønsker, at vores løsning kører videre selvom CPR vælger at udvide kodelisten. Design og arkitektur 9

Der tillades generelt manglende værdier for alle felter, eksempelvis kan navnet for en person godt være en tom streng. Der foretages validering af datoer og tidspunkter. Hvis en dato ikke kan parses, fejler afvises input-filen som beskrevet ovenfor. CPR leverer ikke altid korrekte datoer. Bl.a. er 1981-00- 00 en gyldig datoangivelse. Endvidere kan der optræde værdien 99 i minut- og timeangivelser. Vi fortolker dags- og månedsangivelser hvor værdien er 0 som 1, dvs. datoen 1981-00-00 ændres til 1981-01-01. Timeangivelser større eller lig 24 ændres til 0, og minutangivelser større eller lig 60 ændres til 0. Dernæst checkes om datoen efter denne transformation nu er en valid dato. Hvis datoen ikke er valid men kan parses af JAVAframeworket anses det for en ikke-kritisk fejl, som error-logges, men input-filen afvises ikke. Det checkes ikke om alle forventede recordsfor en person er modtaget fra CPR. En person kan altså mangle eksempelvis civilstand eller folkekirkeoplysninger, uden at systemet går ned. Der checkes, at startrecord og slutrecord er til stede i inputfilen, og at dato for det forrige udtræk angivet i startrecorden stemmer overens med det forventede. 7 Replikeringstjenesten 7.1 Arkitektur Admin GUI SecurityManager RegistryServlet AtomFeedWriter Dao-lag Database Den centrale komponent i replikeringstjenesten er RegistryServletten, som modtager http requests og returnerer svar. Den anvender SecurityManageren til at autorisere requests, og AtomFeedWriteren til at producere response. Dao-laget består af en RecordDao som kan hente view-records fra databasen, samt en UserDao og en ClientDao som kan hente administratorer og klienter fra databasen. Endvidere er der en administrations GUI, som tilgås af administratorer og anvendes til at oprette klienter og definere klienternes rettigheder. Design og arkitektur 10

Replikeringstjenesten er helt uafhængig af importeren, men integrationen mellem de to komponenter sker via databasen, så de to komponenter skal altså være enige om databaseformatet. 7.1.1 Views Et view er model for hvordan en bestemt record-type indlæses fra databasen og udstilles af replikeringsservicen. Hvert view er tilknyttet en bestemt URL, hvor records for det pågældende view kan udtrækkes i XML-format. For en beskrivelse af hvordan data er udstillet henvises til anvenderguiden. Implementationen anvender i meget høj grad annoteringer til at definere views. Der anvendes JAXB-annoteringer, JPA-annoteringer samt nogle selvudviklede annoteringer. Et view defineres af én annoteret Java-klasse. En instans af sådan en View-klasse repræsenterer en record i det pågældende view. Klassen skal være udstyret med JAXBannoteringer, som angiver hvordan den serialiseres til XML, samt med JPA-annoteringer, der angiver hvordan den læses fra databasen. Endvidere skal klassen have en @ViewPath annotering, som definerer view ets id (eksempelvis cpr/person/v1 ), og gør at klassen detekteres som et view. Navnekonventionen er <register>/<viewnavn>/<version> Det er hensigten at XML-repræsentationen for et view ikke ændres når det er kommet i produktion. I stedet laves et nyt view med samme viewnavn men ny versionsangivelse. Dermed kan bagudkompatibilitet bevares når systemet opgraderes. Da et view kun består af én annoteret java-klasse, er det meget nemt at definere nye views. 7.1.2 Komponenter 7.1.2.1 com.trifork.stamdata.replication.gui Administrationsgrænsefladen. 7.1.2.2 com.trifork.stamdata.replication.logging Håndterer audit-logging. 7.1.2.3 com.trifork.replication.security Håndterer sikkerhed i forbindelse med adgang til views. Der er underpakker til implementation af Den Gode Webservice og tovejs-ssl. 7.1.2.4 com.trifork.replication.replication Indeholder den centrale funktionalitet for replikeringsservicen. RegistryServlet klassen håndterer udstilling af views, AtomFeedWriter klassen håndterer generering af de ATOM feeds som udstilles, og RecordDao håndterer indlæsning af records fra databasen. 7.2 Funktionalitet Adgangen til data sker via en REST-grænseflade som replikeringstjenesten udstiller. For at tilgå denne REST-grænseflade benyttes 2-vejs-SSL med OCES-infrastruktur. Design og arkitektur 11

Data udstilles som en række views, der hver især er et Atom-feed. En klient kan anmode om alle data i et givet view, eller alle ændringer siden et givet tidsstempel. Som udgangspunkt eksponeres data som XML, men klienten kan anmode om data i FastInfoset for at nedbringe netværksomkostningerne. Dette gøres via HTTP accept headeren. Der anvendes standard HTTP fejlkoder. Der henvises til Anvenderguiden for mere information om hvordan data tilgås. 8 CPR-opslagskomponent 8.1 Arkitektur PersonResource SecurityFilter PersonPartConverter Dao-lag Database Den centrale komponent er PersonResource som udstiller personer som Person(Part) via REST over HTTP. Der benyttes en converter, PersonPartConverter, til at udfylde Person(Part)- strukturen på baggrund af data fra databasen, således som det hentes via DAO-laget. PersonResource ligger bag et sikkerhedsfilter som verificerer om anvendersystemet har adgang til servicen. Opslagskomponenten er helt uafhængig af importeren, men integrationen mellem de to komponenter sker via databasen, så de to komponenter skal altså være enige om databaseformatet. 8.1.1 Komponenter 8.1.1.1 com.trifork.stamdata.lookup.dao Indeholder en enkelt DAO, PersonDao, som sørger for at hente aktuelle cpr-records for en given person. Dette hentes fra mange forskellige databasetabeller. 8.1.1.2 com.trifork.stamdata.lookup.personpart Indeholder PersonPartConverter som kan tage output fra DAO en og konvertere det til Person(Part)-strukturen. Design og arkitektur 12

8.1.1.3 com.trifork.stamdata.lookup.rest Indeholder PersonResource der sørger for at udstille Person(Part)-data via REST, samt foretage XML-schema-valideringer på dette. Desuden indeholder modulet et eksempel på en JavaScript-klient. Denne udstilles via PersonClientResource. 8.1.1.4 com.trifork.stamdata.lookup.security HTTP-servlet-filter som checker om anvendersystemer har adgang til data. Listen af klienterne vedligeholdes i en opsætningsfil. 8.1.1.5 com.trifork.stamdata.lookup.validation Validerings-logik til XML-schema-valideringerne som ligger i rest-modulet. 9 Teknologiarkitektur Diagrammet nedenfor viser hvordan vi konkret har opsat løsningen: Maskinerne i diagrammet skal opfattes som virtuelle maskiner, ikke fysiske maskiner. Design og arkitektur 13

9.1 SSL-terminering Løsningen kan konfigureres således, at SSL-forbindelser til replikeringstjenesten og cpropslagskomponenten termineres af en Zeus Load Balancer, som medsender klientcertifikatet i en header. For en anvisning af hvordan dette gøres henvises til installationsvejledningen. Endvidere kan systemet konfigureres til at SSL termineres af servlet containeren, hvor servlet containeren skal opsættes til at indsætte klientcertifikatet i standard headeren javax.servlet.request.x509certificate. Der henvises til servlet containerens dokumentation for hvordan tovejs-ssl opsættes. Andre loadbalancere kan også anvendes til SSL-terminering, men dette vil kræve en mindre kodetilpasning, da de formentlig anvender en anden header og et andet format til videresendelse af klientcertifikatet end Zeus load balanceren gør. 9.2 Skalerbarhed Systemet baserer sig på infrastruktur, som i udgangspunktet er skalerbar. Database, Importeren, Replikeringstjenensten og Cpr-opslagskomponenten behøver ikke køre på samme maskine. Importeren, Replikeringstjenesten og Cpropslagskomponenten kan konfigureres til at anvende en ikke-lokal database. Det er muligt at koble flere replikeringstjenester eller cpr-opslagskomponenter til den samme database, og på denne måde skalere modulerne horisontalt. Modulerne er stateless. MySQL understøtter master-slave-replikering, som kan anvendes hvis man ønsker at skalere databasen horisontalt. Systemets arkitektur understøtter dette på en hensigtsmæssig måde, da replikeringstjenesten og cpr-opslagskomponenten kun læser data, og dermed kan nøjes med read-only-adgang til en MySQL-slave. Kun administrations-gui en kræver skrive-adgang til databasen og skal derfor være koblet på masteren. Der henvises til MySQL-dokumentationen for hvordan master-slavereplikering sættes op. Importeren er ikke umiddelbart horisontalt skalerbar. 10 Referencer Atom: http://en.wikipedia.org/wiki/atom_%28standard%29 Fast Infoset: http://en.wikipedia.org/wiki/fast_infoset REST (Representational State Transfer): http://en.wikipedia.org/wiki/representational_state_transfer OWSA Model T: http://www.itst.dk/it-arkitektur-og-standarder/standardisering/standarderfor-serviceorienteret-infrastruktur/standarder-for-webservices/oio-web-servicearkitekturen CPR-kontorets dokumentation for udtræk til det offentlige: http://cpr.dk/cpr/site.aspx?p=64&t=visartikel&articleid=4270 Design og arkitektur 14

Person(Part), høring: https://www.borger.dk/lovgivning/hoeringsportalen/sider/fakta.aspx?hpid=2146001788 11 Komponenter og licenser Følgende komponenter anvendes i løsningen: Person(Part), XML-schemaer: https://svn.softwareborsen.dk/sagogdokumentpoc/standarder/xmlskemaer%20(produktion)/ Gruppenavn (Maven groupid) Komponentnavn (Maven artifactid) Afhængigheder Licens com.trifork shared org.slf4j MIT org.reflections GPL 3 org.slf4j MIT com.google.collections 2.0 javassist MPL or LGPL dom4j BSD style license xml-apis com.google.code.gson javax.servlet CDDL 1.0 org.slf4j MIT org.hibernate.javapersistence J2EE CTS license org.slf4j MIT commonsconfiguration commons-configuration commons-lang commons-lang com.google.inject guice com.sun.jersey jersey-core com.sun.jersey jersey-server asm BSD License com.sun.jersey.contribs jersey-guice guice-servlet Design og arkitektur 15

guice javax.inject javax.inject javax.inject aopalliance aopalliance Public Domain com.google.inject guice-servlet com.google.inject guiceassistedinject dk.sosi seal LGPL 2.1 dk.itst.oiosaml oiosaml.java MOZILLA PUBLIC LICENSE 1.1 opensaml opensaml apache-velocity opensaml com.trifork rid2cprclient com.trifork xmlobject mysql mysql-connectorjava GPL 3 commons-io commons-io com.sun.xml.fastinfoset FastInfoset bouncycastle bcprov-jdk16 MIT X11 License org.freemarker freemarker BSD style license commons-codec commons-codec org.slf4j slf4j-api MIT org.reflections reflections GPL 3 org.slf4j MIT com.google.collections 2.0 javassist MPL or LGPL dom4j BSD style license xml-apis Design og arkitektur 16

com.google.code.gson javax.servlet CDDL 1.0 org.slf4j MIT org.slf4j MIT org.slf4j jcl-over-slf4j MIT xml-security xmlsec xalan xalan xalan xml-apis xerces xercesimpl xml-apis commons-httpclient Design og arkitektur 17