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