Note: Denna funktion är under utveckling, följ utvecklingen i JIRA-26, JIRA-64 och JIRA-65!
Innehåll
| Innehållsförteckning | ||||||
|---|---|---|---|---|---|---|
|
Inledning
Aggregerande tjänster beskrivs i T-boken (REV B). Denna SAD syftar till att beskriva ett generellt realiseringsmönster för aggregerande tjänster, enligt T-bokens definition.
I nuvarande version är dokumentet inriktat mot realisering av en aggregerande tjänst för tidbokningar. Detta dokument har också ett långsiktigt syfte att vara grund för en design av ett generellt mönster för aggregerande tjänster, dvs. när designen är prövad för tidbokning i verkligheten kan designen generaliseras till att vara allmängiltig för alla aggregerande tjänster. Ett generellt möster för aggregerande tjänster kan relaiseras i en aggregeringsplattform (SKLTP AGP) på ett liknande sätt som SKLTP idag förenklar framtagning av virtuella tjänster (se T-boken) med sin virtualiseringsplattform, (SKLTP VP).
Figure 1, Översikt, informationssystemvy från T-boken (REV B)
Implementationsnära delar av detta designdokument är baserade på att Mule ESB CE (v3.3.1 eller senare) används samt att tjänsten driftsätts antingen i den nationella tjänsteplattformen (NTjP) eller i en regional tjänsteplattform (RTjP).
Översikt
Dokumentet är indelat i följande delar:
- Arkitekturella krav
Beskriver de arkitekturella egenskaper som är gemensamma för aggregerande tjänster. - Systemsamverkan
Ger en översiktlig bild av vilka system som samverkar samt dess primära roller i denna samverkan - Användningsfall
Beskriver de användningsfall som har störst påverkan på designen. - Logisk vy
Beskriver designens logiska uppdelning. - Deploymentvy
Beskriver hur lösningen skall driftsättas i QA och produktionsmiljöer. - Testvy
Beskriver integrationstester som behövs för att säkerställa den totala lösningens funktionalitet. - Implementationsvy
Beskriver centrala delar av implementationen.
Arkitekturella krav
Aggregerande tjänster delar en rad egenskaper:
Egenskap | Beskrivning |
1. En per tjänstedomän | Typfallet är att det finns en aggregerande tjänst per tjänstedomän och att den aggregande tjänstens payload är definierad av ett befintligt tjänstekontrakt i tjänstedomänen. Ett exempel kan vara tjänstedomänen för invånarens tidbokning. Den aggregerande tjänstens resultatmeddelande består av en lista av poster vars struktur definieras av tjänstekontraktet GetSubjectOfCareShedule. Det är också det tjänstekontrakt som den aggregerande tjänsten använder för att hämta data från källsystemen. |
2. Mellanlagrar sökresultat | Aggregerande tjänster ska skydda källsystemen från last och minimera svarstider genom att mellanlagra (t.ex. i primärminnet) sökresultat. Det gör att endast den första sökningen på ett patientid kommer att resultera i att data hämtas från källsystemet. Därefter ligger resultatet i minnet / mellanlager. Mellanlager hålls aktuellt genom att en aggregerande tjänst prenumererar på händelser från engagemangsindex. Vid notifiering från engagemangsindex aktualiseras data för patienter som redan finns i mellanlagret, från de logiska adressater som notifieringen refererade. När en patients data inte efterfrågats eller uppdaterats på 30 dagar tas patienten bort från mellanlagret (cache) i syfte att hålla nere mängden data som mellanlagras. Om en viss tjänsteproducent inte är tillgänglig när notifiering inkommer, bör den aggregerande tjänsten hantera omförsök periodiskt tills aktuella bokningar kunnat hämtas in till mellanlagret. Cachen måste hållas per tjänstekonsument eftersom olika tjänstekonsumenter har olika rättigheter som gör att tjänsteproducenten kan filtrera svaret olika beroende på vem anroparen är samt att TAK begränsar antalet logiska adressater per tjänstekonsument. |
3. Söker i Engagemangsindex | Aggregerande tjänster använder engagemangsindex för att veta vilka logiska adresser som håller data av aktuellt slag om patienten. När data om en patient/invånare efterfrågas och patienten inte finns i mellanlagret, konsulteras EI för information om vilka logiska adressater (vårdmottagningar) som håller information. |
4. Nationell omfattning | Aggregerande tjänster syftar till att sammanställa data från alla källsystemen i Sverige som stödjer tjänstedomänen (genom att ha tjänsteproducenter enligt domänens tjänstekontrakt). Att stödja en tjänstedomän som har en aggregerande tjänst omfattar oftast även krav på att uppdatera engagemangsindex. Det är sådana aggregerande tjänster som kravställs här, även om lösningen också ska kunna tillämpas regionalt (i en regional tjänsteplattform). |
5. Gemensamt tjänstekontrakt | Aggregerande tjänster stödjer samma tjänstekontrakt som en vanlig virtuell tjänst. Det gäller även tjänsteinteraktionen (WSDL:en). Skillnaden ur konsumentens perspektiv är hur man adresserar. Man adresserar med ineras eller regions HSA-id för att hitta nationell eller regional (för regionala konsumenter) aggregerande tjänst. För att “adressera sig förbi” aggregerande tjänst (dvs gå direkt mot en enskild tjänsteproducent) används som vanligt tjänstedomänens adresseringsvärde (ex. mottagningens HSA-id för tidbokningsdomänen). Dock finns en skillnad i payload för responsen: En aggregerande tjänst tillför en aggregeringsrapport i form av en header-struktur som redovisar utfallet av aggregeringen (metadata om aggregeringen). |
6. Patientidentitet är obligatorisk sökparameter | Aggregerande tjänster kan bara användas för att hämta information om en patient. Även om det finns en cache som täcker flera patienter, får tjänsten inte användas för sammanställningar av data för flera patienter. |
7. Samtidig hämtning av data | Aggregerande tjänster hämtar data från flera logiska adresser (beroende av patientens engagemang). För att ge så bra svarstider som möjligt, måste logiska adressater anropas parallellt. |
8. Redovisning av data om anropet | Tjänstekontraktet redovisar anropsstatus för varje logisk adressat. Anropsstatus anger om data kunnat levereras eller inte. Om anropet gått bra, redovisas om data kom från källan eller från cache. Om datat hämtades från mellanlager redovisas även tidpunkt då datat överfördes från källsystemet till mellanlagret. |
9. Behörighetskontroll | Den aggregerande tjänsten ingår i Tjänsteplattformen. Därför ska den inte ses som en tjänstekonsument med avseende på behörighetskontroll. När den aggregerande tjänsten anropar vitruella tjänster för att hämta data från källsystemen, är det därför HSA-id från den aggregerande tjänstens tjänstekonsument som den virtuella tjänsten ska använda vid behörighetskontroll mot tjänsteadresseringskatalogen. |
Systemsamverkan
De samverkande systemen beskrivs av följande komponentmodell samt tillhörande text:
- Tjänstekonsument
Frågar den aggregerande tjänsten efter tidbokningar för ett specifik patientid via tjänstekontraktet GetAggregatedSubjectOfCareSchedule. - Engagemangsindex
Förser via en prenumerationstjänst (tjänstekontrakt ProcessNotification) den aggregerande tjänsten med information om vilka vårdmottagningar som har tidbokningar för vilka patienter.
Tillhandahåller oxå en frågetjänst (tjänstekontrakt FindContent) som gör det möjligt för den aggregerande tjänsten att läsa upp index-information om en viss patients samtliga bokningar. - Tjänsteproducent (för källsystem)
Tillhandahåller en tjänst, GetSubjectOfCareSchedule, för åtkomst av tidbokningar i det specifika källsystemet. - NTjP - Virtualiseringsplattformen (VP)
Alla informationsutbyten mellan tjänstekonsumenter och tjänsteproducenter sker via virtuella tjänster i den nationella tjänsteplattformen. - NTjP - Aggregerande tjänst för Tidbokning
Tillhandahåller aggregerande tjänst för Tidbokning till konsumenter via tjänstekontraktet GetAggregatedSubjectOfCareSchedule.
Utgående från informationen tjänsten får från det nationella engagemangsindexet så kan tjänsten avgöra vilka vårdmottagningar som har tidbokningar för en patient.
Med hjälp av NTjP - Virtualiseringstjänst för Tidbokning kan den aggregerande tjänsten hämta patientens bokade tider och kallelser hos var och en av de vårdmottagningar som listats av engagemangsindex. Dessa kan sedan sättas samman till ett samlat svar från den aggregerande tjänsten. Svaret cachas internt i den aggregerande tjänsten under en begränsad tid (30 dagar) för att avlasta källsystemen om tidbokningar för samma patient efterfrågas inom denna tidsperiod. Patientinformation som finns i cachen hålls uppdaterad med hjälp av uppdateringar från prenumerationen i engagemangsindexet.
Användningsfall
Tjänsten uppfyller följande användningsfall för att möta de arkitekturella kraven i referens [1]:
- Tjänstekonsument anropar aggregerande tjänst
- Engagemangsindex notifierar aggregerande tjänst
- Automatisk rensning av cache
- Manuell rensning av cache
Tjänstekonsument anropar aggregerande tjänst
Användningsfallet beskrivs av följande löptext och tillhörande sekvensdiagram.
Då en tjänstekonsument anropar den aggregerande tjänsten för tidbokningar så söker den först i cachen på angivet patientId och returnerar informationen från cachen om sådan finns. Annars anropar tjänsten engagemangsindexet för att få redan på var nuvarande bokningar för angivet patientId finns, dvs hos vilka mottagningar. Därefter anropas respektive källsystem parallellt (för att minimera svarstiden) och ett aggregerat svars sätts samman. Det aggregerade svaret sparas i cachen samt returneras till tjänstekonsumenten. Cachen uppdateras också i de fall anrop misslyckats med relevant fel-information.
Respons SOAP headern "ProcessingStatus"
Teknisk information om bearbetningen sammanställs i svaret tillbaka till tjänstekonsumenten i en SOAP header med namnet "ProcessingStatus".
SOAP headern "ProcessingStatus" innehåller en lista med en rad per anropat källsystem och ger per källsystem information huruvida anropet gick bra, svaret kom dirket från cache, hur gammal den cachade informationen är. Se interoperability_headers_1.0.xsd för detaljer.
...
Not: I sekvensdiagrammet nedan är NTjP's Virtualiseringplattform bortabstraherad i syfte att öka diagrammets läsbarhet men den används i samtliga externa samband, dvs i anrop mellan den aggregerande tjänsten och konsumenter, engagemangsindex och källsystem.
Engagemangsindex notifierar aggregerande tjänst
Användningsfallet beskrivs av följande löptext och tillhörande sekvensdiagram.
Då engagemangsindex notifierar den aggregerande tjänsten om uppdaterad eller borttagen bokningsinformation så söker tjänsten först i cachen på angivet patientId. Finns ingen information i cachen för angivet patientId så ignoreras notifieringen. Finns information i cachen för angivet patientId så hämtas bokningar för de mottagningar som anges i notifieringen. För att nå respektive mottagnings källsystem används en virtuell tjänst i NTjP. Cachen uppdateras därefter med denna information eller med fel-information om anropet misslyckats.
Bokningar hämtas asynkront, dvs notifieringen från engagemangsindex bearbetas inte direkt under anropat från engagemangsindex utan läggs på en kö. För att undvika att notifieringar tappas bort pga tillfällig problem att nå källsystem osv så implementeras bearbetningen på ett robust sätt mha persistenta köer och omsändningslogik.
Tjänstekontraktet GetSubjectOfCareSchedule används istället för GetBookingDetails för att hämta bokningar från källsystemet både i fallet uppdaterad och borttagen bokningsinformation. Detta för att dels få en enklare logik för att hålla cachen i synk med källsystemet och dels för att minimera antalet anrop till källsystemet i de fall flera bokningar för en patient är uppdaterade.
Not: I sekvensdiagrammet nedan är NTjP's Virtualiseringplattform bortabstraherad i syfte att öka diagrammets läsbarhet men den används i samtliga externa samband, dvs i anrop mellan den aggregerande tjänsten, engagemangsindex och källsystem.
Automatisk rensning av cache
Användningsfallet beskrivs av följande löptext och tillhörande sekvensdiagram.
Då information om en patient varken uppdaterats eller lästs under de senaste 30 dagarna så skall tjänsten automatiskt ta bort all information om patienten ur cachen.
Manuell rensning av cache
Användningsfallet beskrivs av följande löptext och tillhörande sekvensdiagram.
Vid behov kan en administratör manuellt rensa hela eller delar av cachen. Partiell rensning kan göras för ett patientId eller en vårdmottagnings logicalAddress.
Logisk vy
Den aggregerande tjänsten är uppbyggd av ett antal logiska komponenter. De beskrivs av nedanstående komponentmodell samt efterföljande textuella beskrivning av respektive komponent.
Not: I komponentmodellen nedan är NTjP's Virtualiseringplattform bortabstraherad i syfte att öka bildens läsbarhet men den används i samtliga externa samband, dvs i anrop mellan den aggregerande tjänsten och konsumenter, engagemangsindex och källsystem.
Komponenter i den aggregerande tjänsten:
...
- Administrationsapplikation, admin-app
Gör det möjligt en administratör att rensa hela eller delar av cachen.
Deployment vy
Tjänsten skall driftsättas i befintlig infrastruktur för den nationella tjänsteplattformen, NTjP.Tjänsten paketeras och deployas som en standard Mule applikation på samma Mule instans som Virtualiseringsplattformen (VP) exekverar på.
Not: I dagsläget stöttar VP bara den gamla Mule 2 deploymodellen och inte Mule 3's nya Mule Applikations koncept, dvs utan möjlighet att deploya och omdeploya enskilda Mule applikationer (t ex nationella tjänster). Detta måste åtgärdas för att denna tjänst skall kunna driftsättas i NTjP's miljö.
Översiktbil av NTjP's QA och produktionsmiljö med aggregerande tjänst för tidbokning driftsatt:
Test vy
TODO: Uppdatera map införande av aggregeringsplattform
...
Integrationstester skall realiseras såväl som automatiska integrationstester som vara körbara i en test/qa miljö mot skarpa samverkande testsystem.
Följande integrationstester behövs för att säkerställa den totala lösningens funktionalitet.
TBD
Implementations vy
TODO: Uppdatera map införande av aggregeringsplattform
Mule flödena är implementerade mha Mule Studio och återges nedan som skärmdumpar från verktyget.
aggregating-service
aggregating-service är en generisk mönster-implementation av en aggregerande tjänst. Den kan anpassas för specifika aggregerande tjänsters behovs på tre ställen:
- Create Query Object
Omvandlar inkommande tjänstespecifika anrop och skapar ett generiskt Query Object som resten av tjänsten använder sig av. - Request List Transformer
Filtrerar och omvandlar svar från sökning i Engagemangs Index (via tjänsten findContent()) till anrop till underliggande källsystem via för tjänsten specifika tjänstekontrakt - Response List Transformer
Sätter samman ett tjänstespecifikt aggregerat svar baserat på delsvaren som returnerats från källsystemen.
process-notification-service
Mekanismer
TODO: Beskriv hantering timeouter och cachning samt konfigurerbara parametrer för detta:
...
| Kodblock |
|---|
# POJO implementations of the agp-api QUERY_OBJECT_FACTORY_IMPL=se.skltp.aggregatingservices.riv.crm.requeststatus.getrequestactivities.QueryObjectFactoryImpl REQUEST_LIST_FACTORY_IMPL=se.skltp.aggregatingservices.riv.crm.requeststatus.getrequestactivities.RequestListFactoryImpl RESPONSE_LIST_FACTORY_IMPL=se.skltp.aggregatingservices.riv.crm.requeststatus.getrequestactivities.ResponseListFactoryImpl |
Meddelandemappningar
I detta kapitel beskrivs de mappningar som behöver göras mellan meddelanden i respektive användningsfall.
TODO: Rensa upp och beskriv utgående från aggregeringsplattformen!
Konsument anropar aggregerande tjänst
Tre mappningar behövar göras för detta användningsfall, se tillhörande sekvensdiagram för överblick:
...
- at: Variabel för aggregeringstjänsten GetSubjectOfCareAggregatedSchedule
- ei: Variebel för engagemangsindex tjänsten FindContent
- ks: Variable för källsystemens tjänst GetSubjectOfCareSchedule
Mappning AggregatedGetSubjectOfCareSchedule-request till FindContent-request
GetSubjectOfCareAggregatedSchedule in-parametrar:
...
Låter rimligt, låter kommentaren stå kvar så får vi se var den kommer in....
Mappning FindContent-response till GetSubjectOfCareSchedule-request
FindContent ut-parametrar:
...
- ks.in.logicalAdress = ei.ut.engagement-list.row.logicalAddress
- ks.in.actor = at.in.actor
- ks.in.healthcare_facility = ei.ut.engagement-list.row.logicalAddress
- ks.in.subject_of_care = ei.ut.engagement-list.row.registeredResidentIdentification
Mappning GetSubjectOfCareSchedule-response till AggregatedGetSubjectOfCareSchedule-response
GetSubjectOfCareSchedule ut-parametrar:
...
- ks.ut.timeSlotDetail-list, summan av alla inkomna svar från källsystemen.
Engagemangsindex uppdaterar aggregerande tjänst
TBD
Rensning av cache
TBD
Referenser
- T-boken (REV B) - http://www.cehis.se/arkitektur_regelverk/teknisk_arkitektur/