1. Indhold

2. Introduktion

2.1. Formål

Formålet med dette dokument er at beskrive systemarkitekturen for LAR servicen.

2.2. Læsevejledning

Nærværende dokument er tiltænkt udviklere og IT-arkitekter med interesse i LAR Servicen og dens opbygning.

2.3. Dokument historik

Dato

Ansvarlig

Beskrivelse

26/2-2018KvalitetsITInitiel version

2.4. Definitioner og referencer

ReferenceBeskrivelse
NSPNational Service Platform
LARLægemiddelAllergiRegister
CAVELatin for vogt eller undgå. Fagudtryk for medicin som en patient bør undgå
FHIRFast Health Interoperability Resources
RESTRepresentational State Transfer
DGWSDen Gode WebService

3. Introduktion til LAR

3.1. 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).

Overblik

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 MinLog)
  • Mapning af kompleks FHIR model (i Cave Service) til enklere model mod anvenderne af LAR

3.2. Overblik over LAR

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:

  • 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.


LAR Arkitektur

  • SMB-Util: Utilities, der indeholder klientkode, der kan anvendes fra LAR til kald af de eksterne NSP services: MinSpærring, MinLog og behandlingsrelationsservice.

3.2.1. 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. Se afsnit 3.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 ved anvendelse af MSB-Util 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.

Registring af opslaget i MinLog samt behandlerrelationsservice. Se LAR - Driftsvejledning for opsætning af registering i MinLog 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).


read flow

3.2.2. 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. Se afsnit 3.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 MinLog. Se LAR - Driftsvejledning for opsætning af registering i MinLog for oprettelse.

3.3. 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. 

3.3.1. 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. 

flere snitflader

3.3.2. 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. 

docker versionering

4. Designmålsætninger og -beslutninger

4.1. 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) 

4.2. 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.

4.3. 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.

4.4. 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
  • requesterOrganization.code og requesterOrganization.type er udfyldt
  • requesterOrganization.code har en gyldig værdi (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)

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
  • 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)

4.5. 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.



  • No labels