Side 1 af 9 FMK-online's brug af SmartFraming Version 1.1 2011-11-01
Side 2 af 9 Indholdsfortegnelse Indledning...3 Initialisering og login...3 Kontekst Properties...4 user.id.authorizationid...4 userorganization.id.number...4 userorganization.id.type... 4 userorganization.id.onbehalfof_authorizationid... 4 patient.id.idlist.n... 4 Events fra FMK-online... 5 AuthenticateUser event... 5 AuthenticateUser.in.ExpectedUserLogon.Oioidws-h...5 AuthenticateUser.out.Status... 5 AuthenticateUser.Ou.Logon.Oioidws-h... 5 AuthenticateUser.Ou.Name... 6 AuthenticateUser.Ou.Sosiid... 6 Journalnotat event... 6 Journalnotat.in.Type...6 Journalnotat.in.EntityId... 6 Journalnotat.in.EntityVersion... 7 Journalnotat.in.EventType... 7 Journalnotat.in.PatientPersonIdentifier... 7 Journalnotat.in.Timestamp... 7 Journalnotat.in.Text... 7 Journalnotat.in.Drugid... 8 Request af Medicinkort som PDF... 8 FMK_PDF_Request.in.PatientPersonIdentifier... 8 FMK_PDF_Response.in.PatientPersonIdentifier... 8 FMK_PDF_Response.in.PDF... 9
Side 3 af 9 Indledning Formålet med dette dokument er at beskrive FMK-online applikationens brug af SmartFraming. Hensigten er, at det komplette dokumentationsmateriale vil udgøres af følgende dokumenter: SmartFraming Specifikation FMK-online's brug af SmartFraming (dette dokument) Dokumentation af sikker browseropstart fra NSI Indholdet af dette dokument vil derfor fortrinsvis være specifikke beskrivelser af: hvordan SmartFraming komponenten initialiseres for at kunne sørge for login og kontekst deling hvilke kontekst properties som FMK-online er i stand til at udveksle og anvende hvilke operationer i FMK-online, der giver anledning til events, samt hvilke informationer, der inkluderes i disse hvilke actions FMK-online er i stand til at reagere på fra værtsapplikationen Initialisering og login Login på FMK-online med SmartFraming kræver denne sekvens af handlinger fra gæsteapplikationen: Gæsteapplikationen skaffer et login-token (en OIOIDWS-H ticket) fra SOSI STS'en Gæsteapplikationen instantierer SmartFraming komponenten, og initialiserer den med: en URL en række kontekst properties (se afsnittet Kontekst Properties ) en callback funktion (ContextAgent), som kaldes når der er behov for authentication med et login-token Gæsteapplikationen kalder navigate på SmartFraming komponenten SmartFraming komponenten initialiserer browserkomponenten og får den til at kalde den konfigurerede URL Ved behov for authentication skaffes et login-token via ContextAgenten, som anvendes til login. På serversiden validerer en custom Identity Provider login-tokenet og opretter login/brugersession Efter login skifter FMK-online til visning af medicinkort for den patient, hvis CPR-nr. er lagt ind i brugerkonteksten Dermed er sessionen startet. Hvis der ikke er et patient CPR-nr. i konteksten vises forsiden, hvor man kan oprette recepter til brug i praksis, eller recept uden CPR-nr. (men uden boksen, hvor man kan indtaste CPR-nr.). Hvis applikationens holdes åben indtil sessionen udløber, kan der opstå et event, som angiver at brugersessionen har fået timeout. For at genetablere login kaldes ContextAgenten til authentication igen og denne skaffer et nyt login-token fra SOSI STS'en.
Side 4 af 9 Kontekst Properties Dette afsnit beskriver de properties der kan eller skal anvendes i konteksten til FMK-online. user.id.authorizationid Format: XXXXX (5 karakterer, en kombination af bogstaver og tal, hvor bogstaverne er 'Y' eller konsonanter, bogstaverne skal skrives med upper case). Eksempel værdi: K1234 Beskrivelse: Et ID på en autorisation (med uddannelseskode), som er knyttet til brugerens CPR-nr. i autorisationsregisteret. Skal ikke udfyldes hvis brugeren logger ind på vegne af en anden bruger, dvs. hvis property'en userorganization.id.onbehalfof_authorizationid er udfyldt. Kan udelades, hvis bruger kun har ét autorisationsid (normal-tilfældet). userorganization.id.number Format: Integer Eksempel værdi: 7026 Beskrivelse: Et ID på den organisation, som brugeren aktuelt arbejder for. Property'en userorganization.id.type bestemmer i hvilken kontekst ID'et skal fortolkes, dvs. i hvilket register man kan slå organisationen op ud fra dette ID. userorganization.id.type Format: Yder Sygehus Afdeling Eksempel værdi: Yder Beskrivelse: I nuværende version understøttes to slags ID'er på organisationer: SKS koder, som anvendes til sygehuse og sygehusafdelinger, og ydernumre, som anvendes af praktiserende læger. userorganization.id.onbehalfof_authorizationid Format: XXXXX (5 karakterer, en kombination af bogstaver og tal, hvor bogstaverne er 'Y' eller konsonanter, bogstaverne skal skrives med upper case). Eksempel værdi: K1234 Beskrivelse: Denne property skal anvendes hvis og kun hvis brugeren logger ind på vegne af en anden bruger. I givet fald skal indholdet være denne anden brugers autorisationsid. Dvs. et ID på en autorisation (med uddannelseskode), som er knyttet til den anden brugers CPR-nr. i autorisations-registeret. patient.id.idlist.n ^^^CPR^^^^ (eller NNNNNNNNNN^^^^NI^CPR) ^^^CPR^^^^
Side 5 af 9 Beskrivelse: Angivelse af ID på patienten, i form af et CPR-nr. i et format, der er specificeret i den danske profil af HL7 CCOW. Det første format er det anbefalede format i den danske profil af HL7 CCOW (se evt. http://digitaliser.dk/resource/523901). Det andet format er medtaget af hensyn til bagud-kompatibilitet med en tidligere tolkning af den generelle HL7 CCOW specifikation. Events fra FMK-online AuthenticateUser event For at modtage AuthenticateUser events skal værtsapplikationen registrere en ContextAgent på et subject kaldet AuthenticateUser. Når disse events modtages forventes værtsapplikationen at fremfinde eller skaffe et OIOIDWS-H Identity Token (IdT) og returnere dette sammen med et par andre attributter. Som input fås en værdi og som output forventes værtsapplikationen at levere 4 værdier ved succesfuldt login (de 4 output værdier defineret nedenfor) eller en enkelt værdi i tilfælde af fejlet login (AuthenticateUser.ou.Status). AuthenticateUser.in.ExpectedUserLogon.Oioidws-h Beskrivelse: Når ContextAgenten kaldes skal der være en input-værdi med dette navn. Dens indhold er en tom streng, hvis brugeren endnu ikke har været logget ind i gæsteapplikationen i denne session, eller brugerens CPR-nr. hvis brugeren tidligere har været logget ind, og dette login ny skal fornys på grund af session timeout. Tilstedeværelsen af denne inputvariabel er samtidig en indikator på, at login-mekanismen er OIOIDWS-H Identity Tokens, så hvis ikke denne værdi er tilstede som input bør applikationen ikke fortsætte! Der kan på sigt blive indført flere/andre login-mekanismer. AuthenticateUser.out.Status Eksempel værdi: PASS FAIL Beskrivelse: Denne output værdi indikerer om login skal betragtes som succesfuldt eller fejlet. AuthenticateUser.Ou.Logon.Oioidws-h Beskrivelse: Denne output værdi indeholder CPR-nr. på den bruger som blev logget ind.
Side 6 af 9 AuthenticateUser.Ou.Name Eksempel værdi: Muhamad Danielsen Beskrivelse: Denne output værdi skal i forbindelse med succesfuldt login angive brugerens navn, som det er angivet i Identity Token eller id-kort. AuthenticateUser.Ou.Sosiid Eksempel værdi: (eksempel udeladt) Beskrivelse: Denne outputværdi indeholder en OIOIDWS-H Identity Token, som er komprimeret og encodet, så det kan indgå i en URL. Journalnotat event For at modtage journalnotat events skal værtsapplikationen registrere en ContextAgent på et subject kaldet journalnotat. Nedenstående tabel viser de operationer i FMK-online, som giver anledning til et journalnotat event, samt hvilke kombinationsmuligheder der er for entity type og event type. Entity type MEDICINECARD DRUG_MEDICATION DRUG_MEDICATION_EFFECTUATION PRESCRIPTION_MEDICATION Event type SUSPENDED, RESUSPENDED, ACTIVATED, REVIEWED CREATED, UPDATED, PAUSED, WITHDRAWN CREATED CREATED, ATTACHED, DETACHED I det følgende gennemgås de enkelte properties som inkluderes i hvert event. Journalnotat.in.Type Format: MEDICINECARD DRUG_MEDICATION DRUG_MEDICATION_EFFECTUATION PRESCRIPTION_MEDICATION Eksempel værdi: DRUG_MEDICATION Beskrivelse: Beskriver hvilken slags entitet som eventet relaterer sig til: medicinkort, lægemiddelordination, effektuering af lægemiddelordination, recept eller brugersessionen. Journalnotat.in.EntityId Format: Integer
Side 7 af 9 Eksempel værdi: 123456789 Beskrivelse: Et ID på den entitet som eventet omhandler. Bemærk at journalnotat.in.type angiver i hvilken kontekst ID'et hører hjemme, og journalnotat.in.eventtype angiver på hvilken måde entiteten er påvirket. Journalnotat.in.EntityVersion Format: Integer Eksempel værdi: 1 Beskrivelse: Et versions-id på den entitet som eventet omhandler, som kan bruges i samspil med entityid, hvis fx entiteten skal hentes via en webservice. Bemærk at journalnotat.in.type angiver i hvilken kontekst versions-id'et hører hjemme, og journalnotat.in.eventtype angiver på hvilken måde entiteten er påvirket. Journalnotat.in.EventType Eksempel værdi: CREATED Beskrivelse: En streng, som beskriver hvilken form for event, der er tale om. Tabellen ovenfor beskriver de mulige værdier for hver slags entitet (angivet i property'en journalnotat.in.type ). Journalnotat.in.PatientPersonIdentifier Beskrivelse: CPR-nr. for den patient hvis medicinkort skal vises / behandles. Journalnotat.in.Timestamp Format: YYYY-MM-DDThh:mm:ss Eksempel værdi: 2011-06-27T13:00:00 Beskrivelse: Tidspunkt for eventet, angivet i lokal tid. Journalnotat.in.Text Eksempel værdi: Oprettet lægemiddelordination på Cipramil tabletter, 10mg. Beskrivelse: Forslag til tekst, som kan gemmes som et journalnotat, der beskriver hvad der er foregået. Det skal understreges, at denne tekst ikke bør parses! Formattering og indhold vil kunne ændres i fremtiden uden varsel.
Side 8 af 9 Journalnotat.in.Drugid Format: Integer Eksempel værdi: 123456789 Beskrivelse: ID på lægemiddel fra Lægemiddelstyrelsens takst. Request af Medicinkort som PDF Der kan forekomme situationer, hvor lægen ønsker at kunne dokumentere hele sit beslutningsgrundlag som dokumentation for sin beslutning. En del af dette kan meget vel være det komplette medicinkort, som det ser ud på det tidspunkt beslutningen tages. Og det er IKKE nok at forlade sig på, at oplysningerne ligger gemt i FMK, og kan findes dér efter behov. I FMK gemmes oplysninger, som ikke længere er aktuelle, nemlig kun i 2 år. Som løsning på dette problem er der lavet en funktionalitet, så værtsapplikationen kan efterspørge en PDF fil med hele medicinkortet, og gemme denne som dokumentation. Der findes en webservice til det samme (som ikke dokumenteres yderligere her), men desuden er der mulighed for at skaffe PDF filen via SmartFraming events, som beskrives i det følgende. Det foregår ved at værtsapplikationen kalder ContextAction.perform() med en parameter: FMK_PDF_Request.in.PatientPersonIdentifier som indeholder patientens CPR-nr. og som dermed indikerer at vedkommendes medicinkort skal hentes som PDF. Det gør FMK-online, og returnerer svaret ikke direkte til kalderen fordi dette skal nemlig kunne foregå asynkront men svarer i stedet ved at kalde ContextAction.perform() den anden vej med to værdier: FMK_PDF_Response.in.PatientPersonIdentifier FMK_PDF_Response.in.PDF For at modtage response eventet skal værtsapplikationen have registreret en ContextAction på subject FMK_PDF_Response. I de kommende underafsnit beskrives hver af de tre input/output variabler nærmere. FMK_PDF_Request.in.PatientPersonIdentifier Beskrivelse: CPR-nr. for den patient hvis medicinkort skal hentes som PDF. FMK_PDF_Response.in.PatientPersonIdentifier Beskrivelse: CPR-nr. for den patient hvis medicinkort er blevet hentet som PDF.
Side 9 af 9 FMK_PDF_Response.in.PDF Eksempel værdi: (eksempel udeladt) Beskrivelse: Medicinkort som PDF, der er base64 encoded.