Overblik
Dette dokument beskriver en migreringsvejledning for Organdonorregister-servicen. Projektet indeholder en migreringskomponent, hvis formål er at importere data fra det eksisterende register til dette nye register.
Ændringslog
Version | Dato | Ændring | Ansvarlig |
|---|---|---|---|
| 1.0.2 | 2018-08-31 | Ny release | Trifork |
| 1.0.4 | 2018-10-26 | Mindre rettelser | Trifork |
Installation
Se projektets installationsvejledning der også beskriver installation af migreringskomponenten odr-migration.
Funktionalitet
Komponenten udstiller en række endpoints, der kan anvendes til at styre funktionaliteten.
URL | HTTP metode | Funktionalitet |
|---|---|---|
<server>/odr-migration/isAlive | GET | Status-side for servicen. Viser om servicen fungerer korrekt. |
<server>/odr-migration/status | GET | Status-side for selve migreringsfunktionaliteten. Viser status før, under og efter kørsel af migrering. |
<server>/odr-migration/start | PUT | Starter migreringen. |
<server>/odr-migration/stop | PUT | Stopper migreringen. |
Til at kalde de forskellige endpoints kan man med fordel anvende curl.
Fx kan migreringen startes således: curl -sX PUT http://127.0.0.1:8080/odr-migration/start
Status kan eksempelvis ses således: curl -s http://127.0.0.1:8080/odr-migration/status
Status-siden kan løbende kaldes under kørslen for at holde øje med forløbet. Hvis det fx observeres at error count stiger højt, kan man afbryde migreringen vha. stop-funktionaliteten, i stedet for at køre hele datasættet igennem. Forventet throughput er ca. 500.000 rækker i minuttet, men det afhænger af mange faktorer.
Filformat
For migrering af Organdonorregistret er der påkrævet 2 filer, den ene indeholdende PersonData og den anden med data for eksisterende organdonorregistreringer.
Filformatet for begge filer skal være .csv med kommaseparerede værdier. Filerne skal indeholde en header med kolonnenavne i den første række, og dernæst data i alle øvrige rækker.
Der er herunder lavet eksempler på de 2 filer:
- Data for en personer: PersonData.csv
- Data for organdonorregistreringer: OrganDonorData.csv
Dataformater
Tabellerne nedenunder angiver hvilke kolonner, der er påkrævet for hver af de nødvendige filer, derudover format, et eksempel samt eventuelle bemærkninger.
Kolonnenavne er baseret på tabeldokumentation for de eksisterende registre.
Encoding skal være i UTF-8 format og da migreringskørslen formodes at køre på et Unix miljø, er det anbefalet, at der anvendes Unix linjeskift (\n), dog kan migreringskoden også godt håndtere Windows linjeskift.
PersonData:
Kolonne Navn | Format | Eksempel | Bemærkninger |
|---|---|---|---|
PersonID | String | 215 | Inkrementelt id |
CivilRegistrationNumber | String | 2201601234 | CPR-nummer, uden bindestreg |
Organdonordata:
Kolonne Navn | Format | Eksempel | Bemærkninger |
|---|---|---|---|
PersonID | String | 215 | Reference til PersonID i PersonData |
FullPermission | String (varchar(1)) | J | Kun J eller N |
Forbidden | String (varchar(1)) | N | Kun J eller N |
RelativeAccept | String (varchar(1)) | N | Kun J eller N |
PermissionForHeart | String (varchar(1)) | N | Kun J eller N |
PermissionForLung | String (varchar(1)) | J | Kun J eller N |
PermissionForLiver | String (varchar(1)) | J | Kun J eller N |
PermissionForPancreas | String (varchar(1)) | N | Kun J eller N |
PermissionForKidney | String (varchar(1)) | J | Kun J eller N |
PermissionForCornea | String (varchar(1)) | J | Kun J eller N |
PermissionForSmallIntestine | String (varchar(1)) | N | Kun J eller N |
PermissionForSkin | String (varchar(1)) | N | Kun J eller N |
ValidDate | Date, format: yyyy-MM-dd HH:mm:ss.SSS | 2018-05-03 18:51:51.776 | Dansk tid. Skal være mellemrum mellem dato og tidspunkt |
DontKnow | String (varchar(1)) | N | Kun J eller N |
| EditDate | Date, format: yyyy-MM-dd HH:mm:ss.SSS | 2018-05-03 18:51:51.776 | Dansk tid. Skal være mellemrum mellem dato og tidspunkt |
Overvågning
IsAlive
Servicen udstiller en status-side (isAlive). På denne side fremgår servicens version, opstartstidspunkt mm.
Eksempel på et response fra status-siden:
200 OK Title: odr-migration Deployed: 2018-10-26T08:14:44.085Z Build-Date: 2018-10-18T13:08:04Z Build-Version: 1.0.4-SNAPSHOT Builder: A robot Display time: 2018-10-26T09:27:43.627Z
HTTP statuskode
Status-siden returnerer følgende HTTP statuskoder afhængig af servicens status:
- 200: Applikationen kører i øjeblikket fint.
- 500: Der er opstået en fejl, der kræver indgriben.
Fejlfinding
Følgende årsager kan resultere i en statuskode 500:
- Hvis databasen ikke er tilgængelige. Der overvåges databaseadgang ved et simpelt "SELECT 1" statement. Denne query køres på alle datasources.
- Andre ukendte årsager.
Hvis status-siden giver HTTP 500 bør man checke den servicens log, som burde indeholde en detaljeret fejlmeddelelse med stacktrace.
Alle komponenter kan genstartes ved at opdatere war-filens last access time med Unix-kommandoen touch, hvilket automatisk detekteres af Wildfly's deploynent scanner. Alternativt kan Wildfly genstartes.
Migreringsstatus
Yderligere indeholder servicen en status-side for migreringsprocessen. På denne side fremgår hvornår migrering er påbegyndt, om migrering er under afvikling, antallet af fejl der har været mm.
Eksempel på response fra migreringsstatus-siden:
Display time: 2018-11-14T16:58:53.685Z Migration start time: 2018-11-14T16:49:14.403Z Is running: false Number of rows inserted in database: 187083 Error count: 136
Logning
Følgende beskrivelse af logning i servicen tager udgangspunkt i standard-opsætningen. Logning konfigureres vha. konfigurationsfilerne beskrevet i installationsvejledningen.
Alle logfiler placeres i standalone/log i Wildfly.
Alle logninger er konfigureret med en rolling file appender, der indsætter et postfix i filnavnet på historiske logfiler ud fra følgende pattern:
-%d{MM-dd-yyyy}-%i
Der oprettes således en logfil pr. dag, og desuden oprettes endnu en logfil, når en logfil er blevet 10 MB stor.
Følgende tabel over logfiler beskriver, hvilke komponenter der skriver til dem:
Logfilnavn | Indhold |
|---|---|
| odr_migration.log | Applikationslog for migrering, som indeholder de vigtigste systemhændelser. Yderligere indeholder denne alle fejl, der kan forekomme i selve migreringen. Dette inkluderer valideringsfejl, databasefejl, fejl ved læsning af csv-filerne, osv. Root: WARN |