Page History
Indhold
Table of Contents |
---|
Introduktion
Formål
Formålet med dette dokument er at beskrive systemarkitekturen for LAR servicen.
Læsevejledning
Nærværende dokument er tiltænkt udviklere og IT-arkitekter med interesse i LAR Servicen og dens opbygning.
Dokument historik
Dato | Ansvarlig | Beskrivelse |
---|---|---|
26/2-2018 | KvalitetsIT | Initiel version |
Definitioner og referencer
Reference | Beskrivelse |
---|---|
NSP | National Service Platform |
LAR | LægemiddelAllergiRegister |
CAVE | Latin for vogt eller undgå. Fagudtryk for medicin som en patient bør undgå |
FHIR | Fast Health Interoperability Resources |
REST | Representational State Transfer |
DGWS | Den Gode WebService |
Introduktion til LAR
Løsningens opbygning
Der etableres med løsningen en webservice, som giver mulighed for opslag af lægemiddeloverfølsomhedsoplysninger for sundhedspersoner.
LAR indeholder yderligere en webservice, som giver mulighed for sundhedspersoner at registrere og opdatere oplysninger vedr. lægemiddeloverfølsomhed for borgere.
Selve LAR Servicen ejer ikke data. Dette ansvar delegeres til den bagvedliggende CAVE Service (se i øvrigt CAVE - Design- og Arkitekturbeskrivelse).
Gliffy Diagram | ||||
---|---|---|---|---|
|
LAR Servicen fungerer således primært som en frontend for CAVE Servicen. LAR Servicens ansvarsområder er følgende:
- Implementation af sikkerhed (DGWS)
- Anvendelse af samtykkedata i MinSpærring i forhold til opslag af lægemiddeloverfølsomhed - herunder håntering af værdispring
- Kald af behandlingsrelationservice til tjek/opfølgning
- Logning af opslag og registreringer (auditloging og MinLog2)
- Mapning af kompleks FHIR model (i Cave Service) til enklere model mod anvenderne af LAR
HTML |
---|
<iframe src="https://archi.nspop.dk/NSP/570928ca/views/id-53393914-f2b1-4699-8003-8f6f7e488205.html" name="test" height="510" width="800">You need a Frames Capable browser to view this content.</iframe> |
* Hver kasse i ovenstående diagram har en kort forklaring, som kommer frem i et nyt browservindue, når der klikkes på kassen.
LAR er udviklet som en web applikation i henhold til Servlet specifikationen 2.5. Dette sikrer, at LAR kan afvikles på enhver Servlet Engine, der overholder denne specifikation - specielt på WildFly Application Server 8.2, der i øjeblikket anvendes på NSP.
Løsningen er opbygget af et antal (Maven) moduler, der hver dækker et overordnet ansvarsområde i LAR:
...
LAR:
...
- Larservice-types: Har til ansvar at generere Java kode for LAR udfra dennes snitfladebeskrivelse (WSDL).
- Larservice-cave: Ansvar for at kalde den bagvedliggende CAVE (FHIR) REST service samt mapning mellem de typer, der anvendes i LAR snitfladen og den domænemodel, der eksponeres af den bagvedliggende CAVE (FHIR) REST service.
- Larservice-app: Forretningslogik, implementation af sikkerhedsprotokolen (DGWS) samt mapning af sikkerhedsprotokollens model og requestmodellen anvendt internt i LAR.
- Larservice-web: Modul, der samler de forgående moduler i en sammenhængende og eksekverbar (i f.eks. WildFly) WAR fil.
- Larservice-integrationstest: Integrationstests, der kan afvikles mod en kørende LAR service.
Overblik over løsningen
Der etableres med løsningen en webservice, som giver mulighed for opslag af lægemiddeloverfølsomhedsoplysninger for sundhedspersoner.
LAR indeholder yderligere en webservice, som giver mulighed for sundhedspersoner at registrere oplysninger vedr. lægemiddeloverfølsomhed for borgere.
Gliffy Diagram | ||||
---|---|---|---|---|
|
- .
Gliffy Diagram | ||||||
---|---|---|---|---|---|---|
|
Opslag af oplysninger om lægemiddeloverfølsomhed for en borger
Opslag af oplysninger om lægemiddeloverfølsomhed for en borger sker på følgende måde:
Først foretages der en validering af det indkommende request. Valideringen foretages på to niveauer på vej ind i LAR Servicen:
- Sikkerheden håndhæves af modulet DGWS provider (se arkitekturtegning ovenfor). Kun kald, hvor sikkerhedskravene er overholdt sendes videre til LAR servicens forretningslogik (se i øvrigt afsnittet Sikkerhedskrav i forhold til kald af LAR).
- Valideringen af indholdet af requestet foretages i LAR forretningslogikken herunder kald til CprExist. Se afsnit 4.4 Validering af requests i LAR
For detaljer vedr. request- og responseformat for anvendere af LAR samt fejlkoder henvises til LAR - Guide til anvendere. Se i øvrigt også Beslutninger vedr LAR Snitfladen nedenfor.
LAR service transformerer i modulet til LAR-CAVE transformation (se tegning ovenfor) herefter requestet til FHIR og viderestiller forespørgselen til den bagvedliggende CAVE service, der står for selve dataopslaget.
Kommunikationen med CAVE service (herunder fejlhåndtering) håndteres af LAR Servicens modul larservice-cave.
Opslag i MinSpærring for at finde ud af, om der findes negative eller dataspecifikke samtykker for borgeren mod den opslående bruger eller organisationen, hvor opslaget foretages fra (en del af snitfladen for opslag). I tilfældet af negativt samtykke returnerer LAR uden videre en fejlkode til kalderen. NB! Der er i snitfladen mulighed for at angive, at man ønsker at foretage værdispring. Hvis kalderen angiver, at værdispring ønskes, så springes opslaget mod MinSpærring over.
Registrering af opslaget i MinLog2 samt behandlerrelationsservice. Se LAR - Driftsvejledning for opsætning af registering i MinLog2 for opslag.
LAR servicen transformerer herefter FHIR responset fra CAVE til den mere simple responsemodel for LAR. Da FHIR stukturen i den bagvedliggende CAVE Service er mere kompleks, end det, der tillades i LAR, har det været nødvendigt at foretage en række valg. Se afsnittet Mapning mellem LAR og CAVE for detaljer vedr. denne mapning.
Inden resultatet returneres sker der evt en filtrering af oplysningerne i henhold til MinSpærring (i tilfældet, hvor der findes dataspecifikt negativt samtykke).
De interne id'er for de returnerede CAVE oplysninger (og id'er for de frafiltrerede oplysninger) logges vha AuditAPI'et (se i øvrigt LAR - Driftsvejledning for detaljer vedr. indholdet af auditlogingsbeskeden).
Gliffy Diagram | ||||||
---|---|---|---|---|---|---|
|
Registrering og opdatering af oplysning
...
om lægemiddeloverfølsomhed for en borger
Registrering af
...
oplysninger om lægemiddeloverfølsomhed for en borger sker på følgende måde:
Først foretages der en validering af det indkommende request. Valideringen foretages på to niveauer på vej ind i LAR Servicen:
- Sikkerheden håndhæves af modulet DGWS provider (se arkitekturtegning ovenfor). Kun kald, hvor sikkerhedskravene er overholdt sendes videre til LAR servicens forretningslogik (se i øvrigt afsnittet Sikkerhedskrav i forhold til kald af LAR).
- Valideringen af indholdet af requestet foretages i LAR forretningslogikken herunder kald til CprExist. Se afsnit 4.4 Validering af requests i LAR.
For detaljer vedr. request- og responseformat for anvendere af LAR samt fejlkoder henvises til LAR - Guide til anvendere. Se i øvrigt også Beslutninger vedr LAR Snitfladen nedenfor.
LAR service transformerer i modulet til LAR-CAVE transformation (se tegning ovenfor) herefter requestet til FHIR og viderestiller registreringen til den bagvedliggende CAVE service, der står for selve dataregistreringen.
Kommunikationen med CAVE service (herunder fejlhåndtering) håndteres af LAR Servicens modul larservice-cave.
LAR servicen transformerer herefter FHIR responset fra CAVE til responemodellen for LAR i form af en status kode og en status tekst afhængigt at kommunikationens udfald.
Oprettelsen logges vha AuditAPI'et (se i øvrigt LAR - Driftsvejledning for detaljer vedr. indholdet af auditlogingsbeskeden).
Registreringen og opdateringen medfører også et kald til MinLog2. Se LAR - Driftsvejledning for opsætning af registering i MinLog2 for oprettelse.
HTML |
---|
<iframe src="https://archi.nspop.dk/NSP/570928ca/views/id-77b3df12-55b4-4270-890d-0f2b3e0c6241.html" name="test" height="170" width="800">You need a Frames Capable browser to view this content.</iframe> |
* Hver kasse i ovenstående diagram har en kort forklaring, som kommer frem i et nyt browservindue, når der klikkes på kassen.
Snitfladeversionering
Der findes to strategier for versionering af LAR sntifladen. En hvor der køres flere versioner af det docker image der leveres og en hvor det kørende docker image udstiller flere versioner af snitfladen.
Et docker image med flere snitflader
Ved denne strategi implementerer LAR servicen to WSDL definitioner. Implementationerne udstilles på hver sin endpoint. Dette gør at klienter skal vælge om de skal kalde den ene eller den anden snitflade ved blot at kalde to forskellige url'er. Det kan f.eks. være nedenstående.
- http://localhost:8065/larservice/MedicationAllergyService
- http://localhost:8065/larservice/MedicationAllergyServiceV1.1.0
Gliffy Diagram | ||||
---|---|---|---|---|
|
Flere version af docker imaget
I og med at LAR servicen den levereres som et docker image, så kan en anden strategi være at køre flere versioner af LAR servicen. Ved denne strategi lader man den eksisterende container køre og den nye version af LAR servicen startes i en anden container. Ved denne skal klienterne kalde enten den ene eller den anden container alt efter hvad for en version af servicen de ønsker at anvende.
Gliffy Diagram | ||||
---|---|---|---|---|
|
Designmålsætninger og -beslutninger
Sikkerhedskrav i forhold til kald af LAR
Det er besluttet, at der for både opslag af oplysninger og registrering af oplysninger i LAR kræves et niveau 4 SOSI Idkort (medarbejdercertifikat).
LAR servicen validerer sikkerheden på følgende måde:
- At der medsendes et gyldigt SOSI Idkort med niveau 4
- At der i SOSI Idkortet er et autorisationsid tilstede, der overholder det gældende format (Det kan være 5 tal, 5 konsonanter og/eller vokalen Y eller en kombination af tal og konsonanter og/eller vokalen Y.)
- At der i SOSI Idkortet er en uddannelseskode tilstede, der overholder det gældende format (numerisk og 4 cifre langt)
Beslutninger vedr. LAR Snitfladen
Begrundelsen for at gøre feltet med autorisations-ID tvunget på snitfladen for registrering af lægemiddeloplysninger er, at datakvaliteten på det indkommende data øges, og at parterne har vurderet denne oplysning til at være meget vigtig.
En konsekvens heraf bliver, at det bliver vanskelligt at lave masse-indlæsning af historiske data (som måske ikke indeholder denne oplysning). Der skal findes en løsning på dette, men det ligger for nuværende uden for CAVE projektet.
Mapning mellem LAR og CAVE
Udgangspunktet for LAR servicens snitflade og datamodel, er standarden FHIR - allergi resourcen. Efter en funktionel workshop er modellen blevet forsimplet ved at fjerne felter, der ikke skal gøres brug af. Samt reducere muligheden for flere værdier på en række af de felter, som er medtaget.
Som eksempler kan nævnes
- FHIR standarden giver mulighed for flere reaktioner per allergi. Altså en liste af reaktioner. LAR simplificeringen tillader kun een reaktion. Er der flere reaktioner for en given allergi, registreres de ved at kalde servicen flere gange med en reaktion per gang
- FHIR standarden giver mulighed for at angive flere koder per allergi type (substance.code/system). Altså en liste af koder/systemer. LAR simplificeringen tillader kun een type
At gå fra LAR format til FHIR format ved registrering af data er uden komplikationer; gå fra simpel format til mere kompleks format. Den modsatte vej, fra FHIR til LAR kan give udfordringer, i fald at data kommer ind af andre veje end LAR snitfladen, og dermed ikke overholder de simple strukturer.
Hvis der åbnes op for registrering af data på anden form en LAR format, vil man kunne komme i en situation, hvor man ved opslag fra LAR servicen kan stå med f.eks. 2 substance koder for den samme allergi. Og hvilken skal der så hentes?
For at fremtidssikre mod dette bedst muligt, er LAR servicen lavet sådan, at hvor FHIR standarden tillader lister (som f.eks. listen af substance koder) da tjekkes FHIR listen for en foretrukket værdi. Findes denne ikke, tages alternativ den mindste værdi alfabetisk. Den alfabetisk alternative udvælgelse er lavet, for at sikre at to kald efter hinanden altid vil returnere det samme svar.
FHIR til LAR simplificeringen foregår på følgende felter med angivne prioriteringer:
- identifer: mindste værdi alfabetisk
- clinicalStatus: active - alternativt mindste værdi alfabetisk
- verificationStatus: confirmed - alternativt mindste værdi alfabetisk
- category: medication - alternativt mindste værdi alfabetisk
- substance.code/system: foretrukket kodesystem - alternativt mindste kode værdi alfabetisk
- patient.code/system: foretrukket kodesystem - alternativt mindste kode værdi alfabetisk
- recorder.code/system: foretrukket kodesystem - alternativt mindste kode værdi alfabetisk
- recorderOrganization.code/system: foretrukket kodesystem - alternativt mindste kode værdi alfabetisk
- reaction.manifestation.code/system:
- hvis flere reactions: første foretrukket kodesystem på reaction.manifestation.coding - alternativt mindste kode værdi alfabetisk på coding
- hvis flere manifestation på reaction: foretrukket kodesystem på manifestation.coding - alternativt mindste kode værdi alfabetisk på coding
- hvis flere codings på manifestation: foretrukket kodesystem på coding - alternativt mindste kode værdi alfabetisk på coding
Den konkrete opsætning af foretrukne kodesystemer er beskrevet i LAR - Installationsvejledning.
Validering af requests i LAR
Der foretages validering for indkommende requests til både opslag og registreringer af lægemiddeloplysninger.
For opslag valideres det at:
- patient.code og patient.system er udfyldt. Hvis cpr-validering er enabled, bliver patient.code desuden valideret ved kald til CprExist service, som checker om cprnummeret findes.
- requesterOrganization.code og requesterOrganization.type er udfyldt
- requesterOrganization.code har en gyldig værdi (gyldige værdier fremgår af WSDL'en)
- Hvis requesterOrganization.type er Ydernummer, sikres det at requesterOrganization.code er på 6 tegn ved validering, og hvis ikke længden er korrekt, paddes code med 0'er.
- LAR Service validerer ikke på værdierne for de indkommende kode systemer (dette overlades til CAVE Servicen - se i øvrigt CAVE - Installationsvejledning)
For registreringer valideres det at:
- identifier er et gyldigt uuid, hvis udfyldt
- clinicalStatus er sat
- criticality har en gyldig værdi, hvis udfyldt (gyldige værdier fremgår af WSDL'en)
- substance.system og substance.code er udfyldt
- patient.system og patient.code er udfyldt. Hvis cpr-validering er enabled, bliver patient.code desuden valideret ved kald til CprExist service, som checker om cprnummeret findes.
- onsetDateTime er udfyldt
- recorder.system og recorder.code er udfyldt
- recorderOrganization.system og recorderOrganization.code er udfyldt
- reaction.manifestation.system og reaction.manifestation.code er udfyldt, alternativ reaction.manifestationDescription er udfyldt
- reaction.severity har en gyldig værdi, hvis udfyldt (gyldige værdier fremgår af WSDL'en)
- LAR Service validerer ikke på værdierne for de indkommende kode systemer (dette overlades til CAVE Servicen - se i øvrigt CAVE - Installationsvejledning)
- verificationStatus, type og category sættes af LAR servicen uafhængigt af, hvad der sendes ind i requestet
- onsetDateTime og reaction.onset format er bestemt af WSDL/XSD filen (Eksempel på gyldig format 2018-11-01T13:30:00.000+01:00)
Validering af patient.code
Gennem kald til CprExists Service foretages validering af CPR nummer. CPR valideringen kan køre i følgende tre modes:
- OFF: Der foretages ikke yderligere verifikation af CPRnummeret udover simpel validering af længde. CPRExists kaldes ikke
- WARNING: CPRExists service kaldes. Hvis denne service svarer, at CPR nummeret ikke findes, så audit logges denne information.
- REJECT: CPRExists service kaldes. Svaret fra denne er en hård validering dvs kaldet til LAR fejler, hvis CPRExist service ikke kender CPR nummeret.
Modellering af diverse identifiers i LAR
Der opereres flere steder i LAR snitfladen med eksterne identifiers f.eks. patientid, organisationsid og id for lægemiddel. For at lave den mest generelle snitfladet er der i LAR Servicen valgt en model, hvor disse identifiers skal angives som en struktur bestående af:
- Et kodesystem (OID)
- En kode (en streng, som antages at give mening i konteksten af det angivne kodesystem)
Som beskrevet i afsnittet vedr Validering af requests i LAR. så foretages der ikke i LAR en validering af de anvendte kodesystemer.