Tjänstegränssnitt för domänen kvalitetsregister PM om tjänstegränssnitt för de nationella kvalitetsregistren på den Nationella Tjänsteplattformen
Innehållsförteckning Introduktion... 2 Versionsinformation... 2 Licens... 2 Bakgrund... 2 Problemställning... 3 Lösningsförslag... 4 Interaktionsmönster... 4 Tillståndshantering och ID... 5 Sökningar... 5 Processer... 5 Kontrakt... 6 Metadata... 7 Registering... 10 Utformning av kliniskt innehåll... 11 Responderobjektet... 12 ErrorInformationType... 14 Felhantering... 14 Vidare information... 15 1
Introduktion Detta dokument är en PM gällande arbetet med att utforma generella tjänstegränssnitt för interaktioner med nationella kvalitetsregister. Arbetet genomförs av Uppsala Kliniska Forsknings Centrum med stöd av SKL genom Nationella Programmet för Data insamling NPDi. Målet med projektet är att utforma interaktionsmönster och konkreta enhetliga tjänster vilka exponeras i den Nationella TjänstePlattformen, NTjP. Tjänsterna ska kunna användas av samtliga vårdproducenter vilka har relevanta avtal med Inera samt uppfyller de tekniska kraven. För Nationella Kvalitetsregister ska tjänstedomänen kunna användas för att exponera grundläggande funktioner för rapportering. Projektet rapporterar till NPDi genom Arkitekturgruppen för kvalitetsregister, vilket är en grupp av arkitekter som representerar landets registercentra samt leverantörer av kvalitetsregistersystem. Pilottester för en första tjänst genomförs sannolikt snarast efter sommaren 2013 och givet ett gott utfall kommer förankringsarbete med Arkitekturledningen, CeHIS att bedrivas under hösten 2013. Versionsinformation Version Datum Författare Kommentar 1.0 Tomas Snäckerström, UCR Initial version Licens Denna PM publiceras under Creative Commons enligt Erkännande-DelaLika 2.5 vilket gör det fritt att kopiera och använda innehållet på villkor att ursprung deklareras och licens bibehålls 1. Bakgrund I Sverige finns på nationellt plan ett hundratal så kallade Nationella kvalitetsregister. Det är en verksamhet som byggts upp sedan ett trettiotal år men där utvecklingen och användningen av webbtekniker fått registren att både växa och etablera sig som självklara verktyg för uppföljning av flertalet sjukvårdsområden. Registren täcker normalt någon specifik process eller behandlingen av utvalda diagnoser och är innehållsligt förvaltade av expertgrupper för respektive vårdområde organiserade som sk. Registerhållare. Medel kan tilldelas registren centralt genom Beslutsgruppen för Kvalitetsregister, vid SKL såväl som genom deltagaravgifter från anslutna vårdgivare. Gemensamt för alla kvalitetsregister är att de ur legal bemärkelse har en Centralt Personuppgiftsansvarig, som i regel är en juridisk person vid ett landsting eller annan sjukvårdsmyndighet. Denne har det praktiska ansvaret för att registret drivs och förvaltas i enlighet 1 http://creativecommons.org/licenses/by-sa/2.5/se/ 2
med gällande lagar, framförallt då PDL och PUL. Normalt finns en grupp med klinisk expertkunskap formerade som en styrgrupp, vilken beslutar om registrets utformning, funktioner, budget m.m. De svenska kvalitetsregistrens historia har varit något av en framgångssaga. Från de enkla initiativ som startades av drivna läkare som utrustats med persondatorer på 80-talet, till nationellt, och även internationellt spännande register, vilka utgör världsunika instrument för säkring och utveckling av vårdens kvalitet, är en utveckling som måste beskrivas som häpnadsväckande. Denna framgång har dock inte kommit utan invändningar. Insamlingen av uppgifter för kvalitetsändamål är i allt väsentligt fråga om en tilläggsdokumentation som måste göras utöver den dokumentation som redan görs i journal. Målet att integrera dokumentationen för journal och kvalitetsanvändning genom tekniska system har därför under så lång tid varit så eftersträvat att det närmast är iögonfallande att resultatet utfallit så magert som det har. Det finns enskilda integrationer mellan vissa register och enskilda system, men dessa har inte kunnat generaliseras och de samordnade initiativ som tagits har funnit hinder i konflikten mellan kvalitetsregistren krav på struktur och journalens behov av generalitet samt snårigheten i vårdens informatiska terräng. Problemställning Utöver Beslutsgruppens inflytande vid tilldelning av medel finns i praktiken ingen central förvaltning för registrens innehåll eller funktion. Det är en styrka i så måtto att det ger registerhållaren, som har den kliniska kompetensen att utveckla registret, stor frihet då de arbetar med att utforma innehållet. Baksidan av det myntet är givetvis att det innebär att man bygger upp en helt ortogonal organisation som har styrande inverkan på dokumentationsrutiner i vårdens verksamhet. Detta inflytande har man, utan att på något sätt, vara del av den organisation som upphandlar och kravställer de dokumentationsverktyg som används i vården. Resultatet, är att befintliga dokumentationssystem i allt väsentligt saknar arbetsverktyg för att stödja personales arbete med rapportering till registren. Häri ligger den stora svårighet som medfört att integrationer mellan journalsystem visat sig svåra att utveckla, annat än med högst specifika mål och mellan enskillda system. Kvalitetsregistren har mycket precisa krav på inrapporterad data emedan den primärt ska användas kvantitativt. Dessa data ska samlas in från system som huvudsakligen byggts för dokumentation människor emellan och som därtill vårdar en och samma patient. Omvänt har utvecklare av journalsystem rimligen inte möjliget att utveckla sina system utifrån mer än en kravorganisation. Man kan inte samtidigt svara mot en köpare och ett, numera ganska stort, antal andra intressenter som har konkreta krav på hur just deras dokumentationsrutin ska utformas. Än svårare ter sig frågan om man även betänker in den förvaltningssituation som uppstår i och med att registren normalt uppdaterar sitt innehåll ungefär årsvis. 3
Lösningsförslag Strukturerade och utifrån definitionen korrekt data är ett ofrånkomligt krav från kvalitetsregistren. En lösning som inte garanterar att man får in korrekta uppgifter utifrån vad man försöker mäta, är en lösning som omintetgör kvalitetsregistrets uppgift. En lösning måste därför fortsatt medge att registret förfogar över möjligheten att kravställa innehållet i inrapporterade uppgifter (och i förlängningen till del vilken information användaren möter när denne rapporterar till registret) Däremot finns inget som motsätter att man utvecklar en gemensam infrastruktur, ett gemensamt API, för den tekniska interaktionen med registret. Om man kan utforma en arkitektur sådan att samtliga kvalitetsregister uppträder enligt samma mönster så kan systemleverantörer för dokumentationsverktygen utveckla en lösning för att kommunicera med samtliga register. Uppnår man detta finns möjlighet att lägga energin på att utforma lösningen för att fånga rätt kliniskt innehåll. En förutsättning är att lösningen ska följa avsikter och intentioner i Nationell Arkitektur i form av RIVmodellen och främst då följa dess tekniska anvisningar 2. Målet är att tjänsterna ska finnas tillgängliga på Nationell TjänstePlattform och då är detta givetvis ett ofrånkomligt krav. Givet att projektet stödjs av NPDi är det även därför ett självklart beslut. RIV-TA innehåller i första hand anvisningar om hur tjänster ska utformas dels utifrån syftet att samordna mönster och principer samt dels att tillämpa best-practice i syfte att garantera interoperabilitet mellan olika plattformar. Att lösningen sedan ska följa lagar och förordningar är givetvis en självklarhet. Givet dessa ramar har vi möjlighet att utforma lösningar som passar för att uppnå de prioriterade mål vi observerat. Målet formuleras som att genom tjänster skapa en infrastruktur för att transportera ett strukturerat innehåll vars utformning förvaltas av berörda kliniska expertgrupper. Interaktionsmönster Kvalitetsregister är först och främst register. De används för kvalitetsuppföljning, men i fråga om funktionssätt är termen register den relevanta egenskapen. Register är i tekniska termer en form av ett datalager, eller en databas om man så vill. Den mest etablerade synen på interaktionen med ett datalager formulerades redan 1983 av James Martin och brukar beskrivas med akronymet CRUD 3. CRUD står för Create, Retrive, Update och Delete och är de basala operationer man använder mot ett register. Det finns alternativ där man abstraherar bort skillnaden mellan Create, Update och Delete, men för transaktionssäkra system med flera samtidiga klienter är CRUD en vedertagen princip. Intressant nog finns stora likheter med hur PatientdataLagen beskriver interaktionen i de delar där man medges direktåtkomst till egna uppgifter, alltså uppgifter man själv skapat. 2 http://www.cehis.se/arkitektur_regelverk/teknisk_arkitektur/ 3 http://en.wikipedia.org/wiki/create,_read,_update_and_delete 4
Vi föreslår en arkitektur där CRUD är interaktionsprincipen och där objektet för operationerna är en registrering i registret. I praktiken kan man jämföra en registrering med vad som finns i ett formulär, oavsett om man nu tänker på papper eller webbformulär, och det är normalt så man interagerar med registret, när man trycker på formulärets spara -knapp (eller sänder in papperet). Tillståndshantering och ID Det är i den tekniska interaktionen ordnat så att registret kvitterar transaktionen genom att returnera en identifierare för själva instansen vid ett (lyckat)create-anrop. Denna identifierare förväntas vara universellt unik för registret och ska sedan kunna användas som referens vid de övriga operationerna. Det finns ingen begränsning i hur mycket en registrering hämtas eller uppdateras men en registrering för vilket man genomfört ett delete-anrop ska det normalt inte gå att anropa vare sig update, get eller delete igen. Explicit utformade felkoder kommer att användas för att meddela såväl lyckade som misslyckade operationer. Detta för att underlätta tillståndshanteringen mellan konsumenter och producenter av tjänsten. Sökningar CRUD brukar i allmänhet även utökas med ett sökgränssnitt (vilket då kallas SCRUD). I nuläget finns inte någon tydlig kravbild för hur en sådan söktjänst skulle byggas upp. En söktjänst förutsätter en relativt etablerad modell för sökbegreppen och därtill ett formulerat sätt att hantera nödvändig predikatlogik över sökbegreppen. Ett system, eller en syntax för logiska relationer är legio att formulera, men registren är alltför diversifierade för att i nuläget peka ut användbara sökbegrepp. Detta i kombination med att ingen egentligen undersökt hur sökningar skulle användas av klientsystem, som exempelvis journaler, gör att en implementation av sökningar skjuts till en senare version. Processer CRUD beskriver operationerna för ett formulär, men ett register kan givetvis dela upp sitt kliniska innehåll i flertalet registreringar vilka riktas mot olika delar av den totala vårdprocessen. Oftast finns en tidsfaktor inblandad. Man vill normalt samla in data så snart den är redo att rapporteras, vilket gör det opraktiskt att vänta tills man vet allt om innehåll och utfall av vårdprocesser som kan sträcka sig över lång tid. En insats kan pågå över tid eller följas upp flera år efter att en den genomförts i syfte att undersöka långtidseffekter av insatsen. Typiskt har ett register två eller tre registreringsformulär som ingångsparametrar (inskrivningsuppgifter och liknande), uppgifter om den utföra insatsen (vård eller insatsregistrering) samt en eller flera uppföljningar som görs efter en tid för att se utfallet av vården. Väsentligt mycket mer komplexa scenarier finns där multipla problem ska hanteras i ett flöde med flera aktörer men de utgör en klar minoritet. 5
Det finns i dagsläget ingen enhetligt definierad modell för hur processer modelleras och uttrycks i kvalitetsregister. Vanligast är att man ser de insatser som kopplas till ett visst hälsoärende för en patient som en process och det blir normalt utifrån patienten och eventuell tidsfaktor som man identifierar vad som tillhör en process. I dagens register med utvecklade användargränssnitt finns normalt ett visst stöd för att följa och arbeta med vårdproceser för en viss patient men förutsättningarna ändras dramatiskt om man tänker sig ett scenario där alla uppgifter samlas in ifrån journalen. Därtill stoppar Patientdatalagen effektivt alla möjligheter att bygga explorativa tjänstegränssnitt där man kan söka efter tidigare kända insatser för en patient annat än inom den egna vårdgivarens egna uppgifter. Utifrån givna förutsättningar finns därför inga meta-tjänster föreslagna i nuvarande skede. Det kommer säkerligen att utvecklas intressen och möjligheter för ytterligare tjänster gentemot kvalitetsregister, men sub-domänen reporting inskränks åtminstone i sin första version till de basala CRUD-operationerna. Det medför att tillståndsinformation i relation till processen hanteras genom information som bifogas registreringsoperationerna. I registrets tjänstebeskrivning förväntas dokumentation förklara hur processen uttrycks i termer av registreringar och hur dessa relaterar till varandra. Specifika meddelanden som returneras i kommunikationen kan indikera såväl allmän information såsom specifik felinformation. Exempel på processrelaterad felinformation kan ske då någon exempelvis försöker registrera någon typ av uppföljningsregistrering för en patient som inte har någon registrad vårdprocess, är avliden, eller där tidsserier är omöjliga. Specifika felkoder uttrycker klassen av fel och detaljerad information ska ges av registrets tjänst i returmeddelandet (mer om detta nedan under ErrorInformationType) Kontrakt Lösningsförslaget innebär att man skiljer ut det kliniska innehåll, som registerhållaren ska förfoga kontroll över, från det strukturerade innehåll som behövs för att säkert transportera rätt uppgifter till rätt system. Samtidigt läggs en odefinierad datamängd i meddelandet vilket innehåller kvalitetsregistrets efterfrågade uppgifter. Lite tillspetsat kan man se det som att tjänsteplattformen med dess tjänsteorienterade överbyggnad används som ett transportlager för ett datainnehåll det inte behöver veta något om. Likväl är poängen med tjänsteorienterad arkitektur och kontraktsbaserade tjänster att man ska strukturera kommunikationen så hårt att man kan skapa typsäkerhet redan utifrån gränssnittets definitioner. Det är alltså ett krav på arkitekturen från RIV, att tjänster ska exponeras kontraktsbaserat. Att binda tjänstegränssnitten till förvaltade kontrakt enligt RIV-TA och som definierar dataelement ner till lägsta nivå skulle även medföra en orimligt stor förvaltningsapparat då registren vidareutvecklar sitt kliniska innehåll. Att ett hundratal register går igenom hela processen 6
för att publicera nya versioner enligt RIV-TA är med nuvarande bemanning helt enkelt inte möjligt och även om den kan anpassas så är kravet på ledtider väl kort från registrens sida. Som alternativ mellanväg föreslår vi en bindning av typer i runtime som backas av ett system där registrens typer publiceras och versionshanteras vid sidan av tjänsten. Likt för övriga tjänstedomäner kommer det att finnas domänövergripande typer och kodverk som definieras på den gemensamma nivån i tjänstedomänen. Till skillnad från en vanlig tjänstedomän i RIV-TA så kommer det att finnas en uppsättning scheman som är organiserade som subdomäner för varje register men som innehåller scheman för typer som inte refereras direkt ifrån WSDL:ens responderobjekt. Respondern innehåller istället en kombination av två element där det första är av typen AnyURI och som ska innehålla en valid referens till det schema som används för att formatera meddelandet. Det andra elementet är en sträng som av tekniska skäl formateras om på talbasen 64 (base64), och som innehåller registreringen formaterad utifrån angivet schema. Det finns alltså dokumenterade och tekniskt strukturerade specifikationer för alla datatyper som ska kunna användas, skillnaden är bara att valet av datastruktur för innehållet görs i det ögonblick man anropar tjänsten. För såväl konsumenter som producenter blir det en hantering i två steg där man i ena steget hanterar data och metadata för själva överföringen och i ett annat steg paketerar det kliniska innehållet. Med denna princip blir det helt möjligt för registren att versionshantera sitt kontraktsinnehåll helt oberoende av den yttre tjänstens utformning. Att lägga till ett nytt formulär eller en ny version av ett befintligt är helt enkelt en fråga om att publicera ett xml-schema för transportstrukturen och implementera tjänsten för att hantera den nya strukturen. Detta innebär även att det i praktiken blir en tjänst med fyra gemensamma ändpunkter som kan användas för att nå samtliga register. Samma tjänst hos NTjP används för att nå samtliga kvalitetsregister rapporteringstjänster. För att understödja adresseringen i tjänsteplattformen kommer elementet logical address i soap-headern att användas för att tjänsteplattformen ska kunna adressera förfrågningar till den implementerande tjänsteproducenten. Dessa kommer att uttryckas som tjänstens HSA-id. Metadata Emedan soap-headern redan har definierats av tjänsteplattformen i RIV-TA, innebär det att det kommer att finnas en struktur i body-elementet som definierar meta-information, alltså en typisk header fast den skickas som en del av själva meddelandet. Utformningen av innehållet i metadata har baserats i utgångspunkten att den ska på första nivå innehålla allt som man behöver veta för att avgöra om det aktuellt att hantera själva registreringen. Detta för att kunna processa requests så effektivt som möjligt. I realiteten rör det sig om uppgifter för tre ändamål. För det första säkerhet och spårbarhet, det vill säga uppgifter avsändaren som används för åtkomstkontroll och loggning. För det andra uppgifter som behövs för att säkerställa att rätt schema används för den aktuella typen och versionen av 7
registrering. För det tredje en del uppgifter som är nödvändiga för att implementera CRUD arkitekturen. För att exemplifiera beskrivs de översta nivåerna i responder-objekten för ett create-anrop. De övriga operationerna har motsvarande innehåll definierat i specifika respondrar fast givetvis utifrån vilken metadata de behöver. Ett create-anrop syftar till att skapa en initial instans av en registrering och det responderobjekt som definierar anropet har följande definition <xs:complextype name='createregistrationtype'> <xs:sequence> <xs:element name="careunit" type="xs:hsaidtype" minoccurs="1" maxoccurs="1"/> <xs:element name="legalauthenticator" type="xs:hsaidtype" minoccurs="1" maxoccurs="1"/> <xs:element name="subjectofcare" type="xs:hsaidtype" minoccurs="1" maxoccurs="1"/> <xs:element name="dateofcare" type="tns:datetype" minoccurs="1" maxoccurs="1"/> <xs:element name="registration" type="tns:registrationtype"/> <xs:any namespace='##other' processcontents='lax' minoccurs='0' maxoccurs='unbounded' /> </xs:sequence> </xs:complextype> Det är som synes en förhållandevis liten uppsättning metadata. Följande stycken förklarar elementens syfte lite närmare. CareUnit CareUnit är den vårdenhet som rapporterar in registreringen. Idealt ska vi kunna identifiera alla vårdenheter utifrån HSA-id, men det är ännu inte säkerställt att i dagsläget fungerar för alla kvalitetsregister. Det kan därmed vara aktuellt att under en övergångstid generalisera identifieraren så att helt arbiträra identifierare kan överenskommas mellan tjänsteproducenter och konsumenter. CareUnit används dels för att associera uppgifterna med rätt organisation (vårdgivare) och är den primära ägaren av uppgiften och tillgång till uppgiften delas för alla som har behörighet att åtkomma registret med medarbetaruppdrag för vårdenheten i fråga. CareUnit blir även löv i registrets organisationsträd och den finaste granularitet med vilken man kan gruppera uppföljningen av vården. Om ett visst register har behov av att ytterligare förfina organisationsträdet är det möjligt genom att införa registerspecifika organisatoriska begrepp såsom avdelning i själva registreringen. Detta motsäger principen som delar upp metadata från annan, men i syfte att inte komplicera det generella kontraktet hanteras attribut som inte är helt gemensamma i den mer anpassade payloaden. LegalAuthenticator LegalAuthenticator är den person hos konsumerande system som utpekas som ansvarig för registreringen såväl ifråga om beslutet att överföra uppgiften till registret som dess faktiska innehåll. Det ska inte likställas med signering emedan det har en annan specifik betydelse, men det har 8
effektivt en liknande effekt. Det är det användar ID här som skrivs i loggar och som kommer att följas upp vid förekommande behov eller rutin. Värt att notera i denna lösning är att integrationens säkerhetlösning bygger på ett förtroende maskiner emellan. LegalAuthenticator är inte liktydigt med användare emedan det inte är strikt sätt nödvändigt att den person som initierar överföringen av en uppgift också är en användare av registret. Historiskt var det självklart så emedan användaren var tvungen att kunna logga in i webbsystemet för att kunna registrera. Med maskin till maskin certifikat delegeras ansvaret att åtkomstreglera funktionen som konsumerar tjänsterna till det integrerande systemet. Registret kan inte annat än lita på att uppgiften stämmer och det är verksamhetsansvarigs ansvar att klientsystemen fungerar enligt tänkta principer. Det är givetvis möjligt att ett visst register förbehåller sig rätten att själv hålla en katalog för åtkomstreglering. Detta kan betingas av exempelvis krav på specifik utbildning eller liknande. Om sådana restriktioner framgår ska dessa dokumenteras i registrets egna SAD samt i annan lämplig dokumentation. SubjectOfCare SubjectOfCare är identifierare för patienten (eller subjektet) som vårdats. Typen är konstruerad för att hantera svenska personnummer, samordningsnummer, reservnummer eller arbiträra pseudonymer vilket möjliggör utformningen av helt pseudonymiserade register där endast vårdgivaren själv känner till kopplingen till person. SubjectOfCare är strikt sett ett element som möjligen skulle kunna överföras i själva registreringen men dels är det ett element som finns i stort sett överallt och dels finns i flera fall processrelaterade regler som knyts till patienten varför det kan vara en processmässig fördel att uttrycka den explicit. DateOfCare DateOfCare uttrycker datum för vårdkontakten i fråga om öppenvård alternativt inskrivningsdatum i slutenvård. Detta attribut är i första hand till för att bestämma version för registreringsinnehållet. I praktiken styr denna uppgift vilken version av registreringens xsd som är tillämplig och information om såväl versionsstyrande datum som kopplingen till specifika versioner, skall tillhandahållas av registret. Registren är i allmänhet versionshanterade utifrån vårdens tider snarare än rapporteringstidpunkt. Rapporteringen kan i vården ofta göras i efterhand men eftersom statistiska sammanställningar oftast organiseras utifrån tiden då vården utfördes, måste det vara möjligt att efterregistrera vårdhändelser utan att det innebär att man får rapportera utifrån ändrade definitioner. 9
Det återstår ännu att säkerställa valet av denna term då det kan tänkas vara missvisande i vissa fall. En granskning kommer att göras av samtliga begrepp och denna är förhållandevis svår. Det finns inte något bra ord för det datum som styr versioner av registeringsdefinitioner i registret och oftast rör det sig om just vårdkontakttidpunkt, men inte alltid. Registering Requestobjektet ovan innehåller även ett objekt kallat Registration av typen RegistrationType. Det är en typ som är utvecklad för att innehålla det strukturerade men i förväg inte typsatta element som innehåller själva registeringen. Typen är definierad enligt följande: <xs:complextype name="registrationtype" > <xs:annotation> <xs:documentation> / / </xs:documentation> </xs:annotation> <xs:simplecontent> <xs:extension base="xs:base64binary"> <xs:attribute name="schemalocation" type="xs:anyuri" use="required" /> </xs:extension> </xs:simplecontent> </xs:complextype> Det rör sig i praktiken om en slags wrapper för en base64 kodad sträng som även försetts med ett attribut som pekar ut var man kan hitta schemat som strängen formaterats från. Tjänstekonsumenten får således utifrån dokumenterade anvisningar skapa sitt dataobjekt baserad på ett schema som registret publicerar. Resultatet av det kodas om på talbasen 64, vilket det finns stöd för i alla relevanta programmeringsramverk/miljöer, och läggs in i det objekt som genererats av det webbserviceramverk man använder för att nå tjänsten. I och med att tjänstekontraktet inte pekar ut det specifika schemat har registeringstypen ett obligatoriskt attribut som ska innehålla en aktiv referens till schemat. Man hade givetvis kunnat nöja sig med ett logiskt namn men då registern förväntas publicera sina scheman kan man lika gärna använda de skarpa referenserna. Det minskar risken för sammanblandning i och med att en URI är universellt unik. Registret får själv avgöra i vilken utsträckning det önskar validera att utpekat schema stämmer mot den tänkta versionen av den tänkta registreringen. Scheman publiceras i versionerade namnrymder precis enligt anvisningar från RIV-TA, men det blir en samvetssak att faktiskt välja det schema som registret önskar. Tjänstekontraktet kommer inte att kunna ifrågasätta valet av schema och det är rekommenderat att registret säkerställer att det följer vad som förväntas. Här lämnas öppet för en strategi för versionshantering som är väldigt öppen för registren. Det ska de kunna utnyttja, men det måste givetvis beskrivas i detalj i SAD:ar och användardokumentation. 10
Utformning av kliniskt innehåll I och med att det kliniska innehållet skickas som en komprimerad sträng så kan innehållet egentligen formateras efter vilken standard som helst. Det enda kravet som ställs är att det finns en schemaspecifikation publikt tillgänglig. Hur schemat byggs upp är registrets sak att avgöra och teoretiskt kan de även använda andra tekniker för representation som exempelvis YAML 4, JSON 5 eller vanliga nyckel-värde par. Vi rekommenderar dock att man tar utgångspunkt i RIV-TA och följer de tekniska anvisningar som ges för utformaning av XML-scheman i tjänster i allmänhet och att man följer den strategi för versioner som anges där. Därmed rekommenderar vi att man dels använder XML-scheman för att representera datastrukturen och dels att värdemängder och valalternativ är strikt typade. RIV-TA innehåller även anvisningar för utformning av scheman och givetvis är det rimligt att följa dessa även i utformningen av dessa scheman. Gällande värdelistor så är det något som i högsta grad är vanligt förekommande i registren och mycket av förvaltningen kommer att kretsa kring frågor om svarsalternativ för olika frågor. Konkret finns strategier för att bygga upp en förvaltning av kodverk baserat på unikt identifierade namnrymder. Den teknik som börjat tillämpas inom Nationell Arktiektur inspirearas av initiativet GrenCDA 6 som har sitt ursprung i framtagningen av protokoll för HL7. Principen är att varje schema ges en unik namnrymd som är reserverad för den specifika applikationen. Under den kan man inom domänen definiera undergrupperingar och till sist identifierare för både begrepp och kodverk. Varje unikt begrepp eller kodverk identifieras av en objektidentifierare och en definieras genom en enkel typ (xs:simpletype). Dessa komponeras sedan genom att man skapar en komplex typ, som har den simpla typens värdemängd och en fixerad referens som obligatoriska attribut. På så sätt skapas ett för XML jämförelsevis lättviktigt protokoll där minimalt med komplexa typer med element används och eftersom referenserna pekar ut värderymden och kodvärdena är resultatet lika rikt på information som en fullständig schemarepresentation. Man har bara tagit bort den strukturella overhead som xml-tekniken normalt skapar i transportens representation. 4 http://www.yaml.org/ 5 http://www.json.org/ 6 http://wiki.hl7.org/index.php?title=greencda_project 11
Responderobjektet Som svar på ett request returneras ett responseobjekt. Responderobjetet innehåller en datastruktur som ger information om transaktionens utfall samt antingen data och metadata från CRUD operationen eller ett felinformationsobjekt som innehåller en lista av uppkomna fel. Objektet definieras enligt nedan: <xs:complextype name='createregistrationresponsetype'> <xs:sequence> <xs:element name='resultcode' type='reporting:resultcodeenum' /> <xs:choice minoccurs="1" maxoccurs="1"> <xs:element name="createdresourceinformation" type="tns:createdregistrationinformationtype" maxoccurs="1"/> <xs:element name="errorinformation" type="reporting:errorinformationtype" maxoccurs="unbounded" /> </xs:choice> <xs:any namespace='##other' processcontents='lax' minoccurs='0' maxoccurs='unbounded' /> </xs:sequence> </xs:complextype> Det svar som returneras innehåller en information kallad ResultCode. Denna kommer från ramverken kring RIV-TA och är identisk med övriga tjänster på NTjP så när som på att vi valt att inte använda statuskoden INFO emedan den har tveksamt värde ur ett transaktivt perspektiv. Det primära intresset för svaret är att signalera hur tillståndet har förändrats och CRUD arkitekturen förutsätter att en operation antingen är lyckad (resultatkod OK ) eller misslyckad (resultatkod ERROR ). ResultCode är alltså ur ett transaktionsperspektiv en flagga som indikerar operationens resultat. Beroende på resultatkodens utfall finns antingen en CreatedRegistrationInformation eller en ErrorInformation. Dessa är i sin tur komplexa typer som anpassats för att returnera relevant information. CreatedRegistrationInformationType är bifogad där resultatet av anropet är avklarat alltså där resultcode är OK och är definierad enligt följande: <xs:complextype name="createdregistrationinformationtype"> <xs:sequence> <xs:element name="registrationid" type="xs:string" minoccurs="1" maxoccurs="1" /> <xs:element name="version" fixed="1" minoccurs="1" maxoccurs="1"/> <xs:element name="status" type="reporting:registrationstatetype" minoccurs="1" maxoccurs="1"/> <xs:element name="information" type="xs:string" minoccurs="0" maxoccurs="unbounded" /> <xs:any namespace='##other' processcontents='lax' minoccurs='0' maxoccurs='unbounded' /> </xs:sequence> </xs:complextype> 12
RegistrationID RegistrationID är det referenshantag till registreringen som transaktionen resulterar i. Det är ett arbiträrt ID som sätts helt enligt registrets egna önskemål. Detta ID används som referens i alla efterföljande operationer i CRUD-mönstret. Om klientsystemet av någon anledning önskar uppdatera registeringens innehåll finns referensen med i requestheadern för den operationen, likadant för get och delete. Version Version används för att hantera synkroniseringsförhållanden när multipla klienter opererar mot samma registrering. Varje update operation tickar upp versionsnumret före registreringen. I och med att exemplet kommer från Create-operationen är versionsnumret givet alltid 1. Status Status är en flagga som berättar var registreringen är i förhållande till sin livscykel. En registrering kan gå genom ett antal faser från en första inrapportering via validering till låsning eller för den delen borttagen som ett resultat av en delete-operation. Rymden för möjliga status för en registrering är ännu inte helt kartlagd och förankrad, men kommer att uttryckas som en given enumeration vid publicering i produktion. Det återstår således en del förankringsarbete innan kontraktet är klart, men det kommer att finnas en given rymd för status. Information Information är en godtycklig sträng som kan innehålla arbiträr information gällande den skapade registreringen. Den är tänkt att nå slutanvändaren som står bakom registreringen och kan användas för att uttrycka observationer. Vilka exakta krav som finns på hanteringen av denna informationsmängd är ännu ej formulerat, men det kommer att finnas behov av att bifoga information även i de fall transaktionen kunnat klaras av. 13
ErrorInformationType Felinformation bifogas requests som resulterat i en misslyckad transaktion. Detta kan ha multipla orsaker och det är därför möjligt att bifoga en eller flera instanser av objektet. Det definieras enligt följande: <xs:complextype name="errorinformationtype"> <xs:sequence> <xs:element name='id' type='erroridenum' /> <xs:element name='detail' type='xs:string' minoccurs='0' /> </xs:sequence> </xs:complextype> ID ID är en error-kod som I närmare detalj beskriver vilken typ av fel som uppstått. Felkoderna är precis som i http-fallet organiserade i klasser utifrån vilken typ av fel det är och var felet uppstått, och har en detaljeringsgrad som ska underlätta felsökning. Det finns även felkoder för generella fel och klassningar som indikerar om felet är temporärt eller persistent. Detaljer om felkoderna kommer att presenteras i tjänstens SAD och det finns anledning att fundera igenom dessa noggrant innan man låser sig. I nuvarande förslag finns rymder för fel i själva tjänsten, (motsvarande 5XX i http), klientrelaterade fel (motsvarande 4XX), fel relaterade till registreringens innehåll (ogiltiga alternativ, processfel et.c.). Detta kan dock komma att utvecklas innan tjänstedomänen är antagen. Detail Detail är en valfri text där tjänsteproducent har möjlighet att ytterligare specificera information om det uppkomna felet. Tanken är att medan felkoden är en statisk information som pekar ut typen av fel kan detail informationen användas för att beskriva specifika bakomliggande orsaker. Felhantering Den uppmärksamme kan reagera på att vi har en webbtjänst som returnerar ett korrekt svar som samtidigt upplyser om att operationen misslyckats. I webbtjänst-tekniken finns mekanismer för att representera det man kallar tekniska fel med ett soap-fault, vilket motsvarar ett exception i vanliga programmeringsspråk. Detta beslut bottnar i principer från befintliga tjänster i RIV-TA och blir dessutom nödvändigt i och med att vi enbart använder webbservice-tekniken för att transportera ett innehåll. Tekniken med soap-faults är mer utformad för att kommunicera problem kring själva webbservice lagret. Soap-faults kommer i princip endast att returneras då tjänsten har problem med den underliggande soap hanteringen, något som ska vara sällsynt ifall alla flöjer beprövade tekniker och verktyg. 14
Vidare information Denna PM kommer att uppdateras i takt med projektets utveckling och tillgängliggörs genom SKL:s projekt NPDi och UCR. För ytterligare information om projektet eller tjänstekontrakten kan författaren kontaktas på epost: tomas.snackerstrom@ucr.uu.se alternativt mobiltelefon 070-274 41 18. 15