Gå till slutet av bannern
Gå till början av bannern

SKLTP Aggregeringsplattform - arkitekturbeskrivning (SAD)

Hoppa till slutet på meta-data
Gå till början av metadata

Du visar en gammal version av den här sidan. Visa nuvarande version.

Jämför med nuvarande Visa sidhistorik

« Föregående Version 20 Nästa »

Innehåll

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:

  1. Arkitekturella krav
    Beskriver de arkitekturella egenskaper som är gemensamma för aggregerande tjänster.

  2. Systemsamverkan
     Ger en översiktlig bild av vilka system som samverkar samt dess primära roller i denna samverkan

  3. Användningsfall
    Beskriver de användningsfall som har störst påverkan på designen.

  4. Logisk vy
    Beskriver designens logiska uppdelning.

  5. Deploymentvy
    Beskriver hur lösningen skall driftsättas i QA och produktionsmiljöer.

  6. Testvy
    Beskriver integrationstester som behövs för att säkerställa den totala lösningens funktionalitet.

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

Om anropet inte gick bra redovisas felorsak. Felorsaker anges som Timeout eller Serverfel (detaljer från servern rapporteras vid timeout).

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]:

  1. Tjänstekonsument anropar aggregerande tjänst
  2. Engagemangsindex notifierar aggregerande tjänst
  3. Automatisk rensning av cache
  4. 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.

Notera att SOAP headern "ProcessingStatus" inte beskrivs i de tjänsteinteraktioner (WSDL-filer) som en aggregerande tjänst följer, detta för att kunna använda samma tjänsteinteraktioner som de underliggande tjänsteproducenterna använder. Det innebär att SOAP headern "ProcessingStatus" behöver beskrivas vid sidan av tjänsteinteraktionerna, förslagsvis som ett appendix till gällande RIV-TA version.

 

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:

  • Cache-flöde, cache-flow
     Synkront Mule flöde som ansvarar för att exponera tidbokningstjänsten.Söker i cache efter information och returnerar den om den finns. Saknas information i cache anropas main-flow.
  • Cache
     Mule ESB EE komponent (v3.3 eller senare), delvis specialiserad för att möta specifika behov som den aggregerande tjänsten har. Lagrar bokningsinformation per patient då den efterfrågas första gången. Håller bokningsinformationen per patient i upp till 30 dagar sedan den senast uppdaterats eller efterfrågats.
  • Huvud flöde, main-flow
    Synkront Mule flöde som hämtar index-information från engagemangsindex och splitterkomponenten anropas varefter flödet ställer sig och väntar på svar från aggregeringskomponenten innan svar returneras till anropande konsument. Svar från aggregerings-komponenten måste komma inom en konfigurerbar timeout-tid annars returnerar flödet ett timeout-fel tillbaka till konsumenten.
  • Splitterkomponent, splitter-flow
    Asynkront Mule flöde som ansvarar för fördela anropen till källsystem på ett antal instanser av workerkomponenten som arbetar parallellt. Flödet ansvarar också för att märka meddelande till workerkomponenterna med ett och samma correlation-id så att aggregeringskomponenten kan gruppera inkommande svar till respektive väntande konsument (blir speciellt viktigt i de fall två eller fler konsumenter samtidigt söker efter patientinformation som inte finns i cachen). På meddelande till workerkomponenterna anges också antalet förväntade svar så att aggregeringskomponenten kan returnera ett svar så fort alla svar kommit in, dvs inte behöva vänta tills timeouten slår till.

  • Workerkomponent, worker-flow
    Asynkront Mule flöde som anropar ett källsystem, väntar på svar och förmedlar det vidare till aggregeringskomponenten. Flödet väntar på svar från källsystemet upp till en konfigurerbar timeout-tid. Kommer inget svar inom den tiden skickar den vidare ett timout-svar till aggregeringskomponenten. Uppstår det något fel i samband med anropet till källsystemet så skickar flödet vidare ett svar med felinformation till aggregeringskomponenten.
  • Aggregeringskomponent, aggregator-flow
     Samlar in svar från de olika worker-flow instanserna, gruppera svaren per correlationId (satt av splitterkomponenenten) och skickar ett aggregerat svar tillbaka till tidboknings- komponenten när alla svar kommit in eller en konfigurerbar timeout-tid uppnåtts.
  • Notifieringstjänst, process-notification-flow
     Synkront Mule flöde som ansvarar för att exponera processNotification-tjänsten och genom den ta emot uppdateringar från engagemangsindex enligt användningsfallet "Engagemangsindex uppdaterar aggregerande tjänst".
  • 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

De tre mappningarna testas av respektive unit-tester-klasser:

  1. se.skl.tp.at.tidbokning.engagemangsindex.FindContentRequestTransformerTest
  2. se.skl.tp.at.tidbokning.tidbokning.TidbokningRequestTransformerTest
  3. se.skl.tp.at.tidbokning.tidbokning.TidbokningResponseTransformerTest


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.

Not: I gällande version av aggregeringplatttformen, v1.0.0, är cache-funktionalitet inte implementerad. Dock är implementationen designad för att kunna införa cachning i en framtida version på ett kostnadseffektivt sätt.

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:

  1. Create Query Object
    Omvandlar inkommande tjänstespecifika anrop och skapar ett generiskt Query Object som resten av tjänsten använder sig av.

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

  3. 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:

# Default timeout for synchronous services
SERVICE_TIMEOUT_MS=4000
AGGREGATE_TIMEOUT_MS=4500
AGGREGATED_SERVICE_TIMEOUT_MS=5000

# Cache properties
CACHE_MAX_ENTRIES=1000
CACHE_TTL_MS=5000
CACHE_EXPIRATION_INTERVAL_MS=1000

 

Tjänstespecifika implementationer anges enligt:

# 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:

  1. Mappning AggregatedGetSubjectOfCareSchedule-request till FindContent-request
  2. Mappning FindContent-response till GetSubjectOfCareSchedule-request
  3. Mappning GetSubjectOfCareSchedule-response till AggregatedGetSubjectOfCareSchedule-response


De tre mappningarna implementeras av respektive transformeringklass:

  1. se.skl.tp.at.tidbokning.engagemangsindex.FindContentRequestTransformer
  2. se.skl.tp.at.tidbokning.tidbokning.TidbokningRequestTransformer
  3. se.skl.tp.at.tidbokning.tidbokning.TidbokningResponseTransformer


Variabler som används i mappningarna nedan är prefixade med id'n för tillhörande tjänst:

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

  • at.in.logicalAdress = hsa-id för aggr tjänst
  • at.in.actor = SUBJECT_OF_CARE eller SUBJECT_OF_CARE_AGENT
  • at.in.subject_of_care = personnummer för patienten i fråga

FindContent in-parametrar mappas enligt: 

  • ei.in.logicalAdress = hsa-id för nationellt EI
  • ei.in.registeredResidentIdentification = at.in.subject_of_care

  • ei.in.serviceDomain = "riv:crm:scheduling"

Not: Övriga element i FindContent requestet utelämnas och antas ge wildcard-funktionelitet, t ex Categorization och MostRecentChange

Kommentar av Johan Eltes:

Vi kanske skulle speca att en aggregerande tjänst kan parameteriseras (konfigureras) med ett datum för MostRecentChange och för antal dagar i cachen. Till exempel kanske tidbokningar i dåtid inte är intressant, mer än någon månad tillbaka...

 

Svar: Magnus Larsson:

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:

  • ei.ut.engagement-list, ett element i listan per logical-address som har tidbokningsinfo för patienten i fråga

    Not: Istället för att anropa GetBookingDetail en gång per bokning så anropas GetSubjectOfCareSchedule en gång per logical-address.

    Finns det två eller fler bokningar för en patient på en och samma logical-address så innebär det färre anrop till källsystemet, dvs en prestandavinst och lägre last på källsystemen.

GetSubjectOfCareSchedule in-parametrar mappas enligt:

  • 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, ett element in listan per bokning för avsedd logical-address för patienten i fråga

    Svaren från respektive logical-address läggs samman till ett aggregerat svar.

GetSubjectOfCareAggregatedSchedule ut-parametrar mappas enligt:

  • ks.ut.timeSlotDetail-list, summan av alla inkomna svar från källsystemen.

 

Engagemangsindex uppdaterar aggregerande tjänst

TBD

Rensning av cache

TBD

Referenser

  1. T-boken (REV B) - http://www.cehis.se/arkitektur_regelverk/teknisk_arkitektur/
  • Inga etiketter