Page History
...
Numbered Headings | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
FormålFormålet med dette dokument er at hjælpe udviklere, der skal i gang med at implementere import af en ny datakilde til NSP-platformen. IntroduktionNSP-platformen tilbyder adgang til en række webservices og data med relevans for sundhedsvæsenet – sikret af en ensartet sikkerhedsmekanisme. Yderligere beskrivelse kan finder her: https://www.nspop.dk/display/web/Platformsintroduktion.
Forløb Det overordnede program flow der gennemføres i SDM er følgende:
Relaterede komponenterEn importer står ikke alene, men indgår som del af NSP-infrastrukturen - i samarbejde med en række andre elementer. De vigtigste "samarbejdspartnere" er nævnt nedenfor: SDM4-core framework sdm4-core styrer det overordnede kontrolflow i import processen og stiller et API til rådighed for parseren (primært til persistering). Dette API skal benyttes, med mindre der kan angives gode grunde til andet (som i givet fald bør fremgå af dokumentation). Bemærk at spring frameworket benyttes, så et beskedent kendskab til dette, kan være nyttigt.
SDM4-parent Alle importere skal bygges ved hjælp af maven. Importerens pom-fil arver fra sdm4-parent, som hjælper med afhængighedsstyring og stiller diverse build-relaterede features til rådighed, f.eks. licens check og code coverage. Parent-projektet håndterer endvidere muligheden for i forbindelse med idriftsætning at overskrive importerens konfiguration med værdier relevante for det konkrete miljø. Endelig tilbyder parent projektet mulighed for deployment og afvikling af integrationstests op mod et lokalt virtuelt miljø - implementeret ved hjælp af Vagrant, som er en scriptet konfiguration af en Virtual-Box VM. sdm4-parent vedligeholdes pt. af Trifork. Nyeste version kan findes under https://svn.nspop.dk/svn/public/components/sdm4-parent/ (benyt nyeste navngivne version).
NSP-util Dette er et hjælpe modul til SLA logning. ReplikeringDe persisterede data replikeres af MySql rundt til de forskellige centrale og decentrale NSP-instanser. Herved sikres at de samme data er tilgængelige overalt (efter en beskeden forsinkelse), uanset om der kaldes fra et lægepraksissystem (benytter typisk central NSP), eller fra et EPJ på et hospital (benytter typisk en decentral, regional NSP). SKRS (Stamdata kopi register service)SKRS står for " Stamdata Kopi Register Service". Denne service giver mulighed for at hente komplette kopier af stamdata-registre. Dette giver anvendere mulighed for at ajourføre en lokal kopi af et stamdata-register. Adgangen er begrænset af den aftale der indgås med NSP-operatøren. SKRS anvendes som et feed, der giver anvender mulighed for at hente opdaterede værdier. Husregler På siden https://www.nspop.dk/display/web/Husregler findes en liste af krav/regler som generelt skal overholdes ved udvikling af moduler til NSI SDS platformen. Krav beskrevet i dette dokument kan overstyre eller udvide krav beskrevet i husreglerne. Opsætning af importer projektTemplate importerDer findes et lille template importer projekt, som illustrerer væsentlige aspekter ved konstruktion af en ny importer og kan findes under https://svn.nspop.dk/svn/nsp/trunk/tools/templateimporter/. Ved oprettelse af en ny importer kan dette projekt kopieres og tilrettes. Projektet illustrerer dels opsætning af maven, samt illustrerer typisk konfiguration og kode. Maven opsætningEn importer bygges ved hjælp af Maven. Projektets pom.xml vil typisk have nedenstående form:
Bemærk at projektet arver fra sdm-parent og benytter sdm-core mm. Opsætning af parserStamdata importer frameworket er implementeret som en spring-container og deployet som en web-applikation.
hvor MyImporterParser er den konkrete implementation af parser logikken. Denne har til formål at parse input filerne og så vidt muligt persistere dem i MySql.
Der findes kun 2 håndtag på interfacet, metoden "process" skal udføre konvertering af data og gemme resultatet i databasen, metoden "getHome" returnerer en tekst streng der angiver et sigende navn for import komponenten. Navnet anvendes af frameworket til eks. logning, opdatere status, m.m.
Opsætning af overvågning Udover konfiguration af parseren er det nødvendigt at opsætte overvågning, så det er muligt for driften at monitorere om importeren fungerer.
Spring sørger nu for at klassen svarer på forespørgsler på denne adresse: http://<ip:8080>/<myimporter>/status/ Såfremt status-siden fortæller at noget er galt, kan SLA-loggen og applikationsloggen efterfølgende benyttes til fejlsøgning.
Deployment som web applikation. Importeren deployes som en webapplikation. Den typiske web.xml vil have nedenstående udseende:
Hvor dk.nsi.sdm4.myimporter.config er den pakke som indeholder MyImporterConfig og WebConfig. Implementation af parserSDM flowImporteren kører skeduleret med korte mellemrum (pt hvert sekund).
Opstår der fejl fra import modulet (dvs parseren smider en exception) låses import modulet (en fil med navnet LOCKED oprettes) således at fejlen kan analyseres og udbedres. Låsen skal manuelt fjernes (filen LOCKED slettes) igen før import genoptages. Validering af kildedataImport modulet skal sikre at kildedata er korrekt. Det kan f.eks. omfatte validering af filnavne og indholdet af filerne. Hvis kildedata modtages opdelt skal det sikres at de kan importeres i den korrekte rækkefølge. Valideringen bør endvidere sikre at enkelte felters data har det korrekte format, så de kan mappes korrekt - f.eks. som en dato. Såfremt kildedata ikke kan valideres, skal dette fremgå af SLA loggen. Persistering af dataModulet sdm4-core indeholder bla. hjælpe klasser til at gemme importerede værdier pr. række, og hjælper samtidig med håndterering af nogle af de SKRS specifikke felter. Se afsnit for definition af SKRS felter. RecordPersister Klassen "RecordPersister" sikrer at data bliver valideret og gemt. UpdateExistingRecordPersisterDenne klasse sørger for at eksisterende rækker efterlades som historik, i stedet for at data overskrives. RecordFetcherDenne klasse sørger for henting af eksisterende records og giver dermed mulighed for at afgøre om nye records skal indsættes, eller eksisterende opdateres. Record/Field specificationVed persistering angives en Record (et map af data) der skal persisteres, samt en RecordSpecification som er en tabelbeskrivelse af data.
hvor RecordFieldType er en af typerne ALPHANUMERICAL (tekst), NUMERICAL (heltal), DECIMAL10_3 (decimaltal), DATETIME (dato og tid), DATE (kun dato). Her et eksempel hvor 4 felter udgør en record.
KonfigurationUdover opsætning af parser, SLA logning og overvågning, vil det være nødvendigt at konfigurere importer-frameworket – og muligt at konfigurere parseren.
Dette sker ved at placere dem i en property-fil ved navn default-config.properties, som skal være placeret i web-applikationens classpath (f.eks. WEB-INF/classes). Samme property-fil kan af parseren anvendes til diverse konfigurationsstyring. Disses værdier injectes automatisk i parseren ved f.eks. at benytte
som sikrer at den tilsvarende værdi fra property-filen anvendes (standard feature i spring-framework). sdm-parent projektet sikrer, at disse properties på deployment tidspunktet kan overskrives af andre værdier. Dette sker ved at hooke importer-komponenten sammen med et JBoss-modul indeholdende filer det kan være relevant for driften at modificere. Disse omfatter
Det anbefales at vedlægge flest muligt af disse filer til komponenten - man skal dog være opmærksom på at disse betragtes som "eksempler" der i en driftsituation kan blive overskrevet. De vedlagte filer skal ikke pakkes med i war-filen.
Operationelle aspekter Transaktions styringDet skal sikres at data altid er komplette, så der i fejlsituationer stadigvæk hentes konsistente data ved forespørgsler.
Historiske data Hvis data historik er understøttet skal det sikres at en genindlæsning af data kan håndteres uden at ødelægge historikken, uanset om det er en fuld genindlæsning eller en delvis indlæsning. Håndtering af genindlæsningen kan f.eks. være fuldstændig eller delvis oprydning af data. Her skal det specielt bemærkes at anvendere af kopiregisterservicen benytter ModifiedDate til at identificere ændrede records. ModifiedData bør derfor så vidt muligt være uændret, da det ellers potentielt kan føre til duplikater i anvendernes system. Overvågning / StatusDet er et krav at import modulet skal markere om importering af data gik godt eller skidt. Det sker automatisk af importer-frameworket, der fanger en eventuel exception og registrerer den som en fejl i SLA loggen. Kører parseren igennem uden exceptions gemmes blot en success markering i SLA loggen. SLA loggen kommer således kun til at indeholde en markering af om kaldet til metoden "process" gik godt eller skidt.
Alarmering SDM aktiverer kun importer modulet når dette er inaktivt og der er nye kildedata klar. UnreliableImport af data bør så vidt muligt håndtere mangelfulde data således at det kun er uhåndterbare fejl der forhindrer indlæsningen af kildedata, eller gemning af data i databasen. Det anbefales kraftigt at benytte unreliable-metoden til dette. Det betyder at hver datatabel bør have en ekstra kolonne "unreliable". Såfremt enkelte felter indeholder en ugyldig værdi, angives dette i unreliable-kolonnen, idet denne indeholder en komma-separeret liste af felter med ugyldige værdier. Et eksempel på dette kan ses i kildekoden til cpr2 importeren https://svn.nspop.dk/svn/public/components/sdm4-cpr2importer/latest/code/. Hvis et felt markeres som "unreliable" skal det fremgå tydeligt af applikationsloggen med en advarsel. Feltnavn og den ugyldige værdi skal også fremgå. Såfremt felter markeres som unreliable bør dette fremgå af SLA loggen - f.eks. ved angivelse af antal indlæste records med unreliable data.
Database design Alle data persisteres i tabeller i MySql. Angives der ikke andet bliver tabeller oprettet med default sortering (latin1_swedish_ci) og tegnsæt (latin1) jf. husreglerne. Er der behov for understøttelse af flere tegn kan tabellen oprettes med utf8 tegnsæt. Der skal som minimum oprettes 2 tabeller som import modulet skal vedligeholde. En tabel med angivelse af om import af data gik godt eller fejlede og en tabel til at holde data der importeres inklusiv "system" felter som SKRS skal anvende. Data tabel inkl. SKRS standard felterUdover de felter der skal holde de importerede data, skal der oprettes yderligere 5 felter som SKRS bruger til replikering af data.
Udover SKRS standard felterne skal tabellen indeholde de importer-specifikke felter med forretningsdata. Status for importeringUdover SLA loggen til at holde status på importering, skal der også oprettes en tabel til at holde status for importering. Tabelnavnet sammensættes ved at kalde 'getHome' metoden på Parser interfacet og tilføje teksten "ImportStatus".
Her er et eksempel på oprettelse af tabellen ImportStatus.
Importer frameworket sørger selv for at vedligeholde status af importeringen og der skal ikke yderligere gøres noget. Opsætning af SKRS viewmappingData tabeller skal registreres så SKRS kan finde ud af at kopiere dataene.
Ovenstående mapning sikrer, at SKRS servicen kan kopiere (udsnit af) de importerede data (et hypotetisk register over placeringer i tidligere X-Faktor konkurrencer). En beskrivelse af formatet kan ses i https://svn.nspop.dk/svn/public/components/sdm/latest/doc/Dynamisk%20SKRS.odt. Mapningen angiver dels hvilken tabel datatypen 'result' fra registeret 'xfaktor' skal hente data fra (nemlig tabellen Xfaktor). Men også hvorledes de enkelte kolonner udvælges (ud fra den kolonne der er markeret som pid-kolonne, samt de krævede data-felter) og præsenteres. Her angives dels navn (feedColumName) og rækkefølge (feedPosiition) i feedet, dels datatype. Datatypen referer til værdier af java.sql.Type, f.eks. 93 = http://docs.oracle.com/javase/7/docs/api/constant-values.html#java.sql.Types.TIMESTAMP. DatabasemigreringOpgradering af databasen sker automatisk ved serverstart, og fungerer på den måde at sql scripts med navne formatet "Vyyyymmdd_hhmm_description.sql" afvikles på databasen. Script filerne placeres under "resources\db\migration" og inkluderes dermed automatisk i den deployede applikation.
Testability Dette dokument beskriver hvordan modulet deployes til Jboss: https://svn.nspop.dk/svn/public/components/sdm4-core/latest/doc/Installationsvejledning.docx (afsnit 3.1.3). NIAB (NSP in abox) bør anvendes til aftestning af modulets funktionalitet. Vejledning til opstilling af Virtuel maskine kan findes her: https://www.nspop.dk/display/web/NSP+In+A+Box . Herved sikres at testen kommer tæt på produktions konfigurationen. Da importerne i drift kører på Jboss 7, bør man anvende den NIAB der hedder NIAB m. Jboss 7. Der skal leveres datafiler, eller et utility der generer datafiler, til aftestning af modulet. Så vidt det er muligt skal der være mange små datafiler, så det er hurtigt at genteste en specifik kombination. Der skal oprettes unittests, så code coverage procenten opnås (jf. husreglerne 80%), unittest omfatter også "Hul igennem" test på status url.
Release Relevante filer skal afleveres i NSP projektets SVN repository og NSP Leverandøren informeres.
Se husreglerne på denne side for yderligere uddybning: https://www.nspop.dk/display/web/NSP+SVN+anvendelse#NSPSVNanvendelse-2Komponentleverancer
|
...