INDHOLD
Beskrivelse
National Adviseringsservice er en service på NSP'en der hjælper med at distribuere adviseringer fra et afsender system til et eller flere modtager systemer via en standardiseret snitflade.
Et afsender systemer sender adviseringer på et givent topic. En advisering består af et topic, et eller flere ID'er der kan filteres på og så selve adviseringen. Afsendelse af adviseringer sker via NotificationBroker snitfladen. Før et system kan afsende adviseringer skal topic være oprettet i systemet.
Ønsker man hente adviseringer sker det ved at modtagersystemet først opretter en evt. IDliste, et pullpoint og til sidst et abonnement på et emne og en evt. IDListe. Herefter er anvendersystemet klar til at hente adviseringer via det pullpoint der blev oprettet.
Den første version af den Nationale Adviseringsservice blev implementeret i 2012, og kan sende adviseringer fra kildesystemer til modtagersystemer. Dette gør sig bl.a. gældende i forhold til det Fælles Medicin Kort (FMK), som sender adviseringer til en række modtagersystemer herunder f.eks. hjemmesygeplejen i tilfælde af medicinændringer.
Denne version 2 har samme interfaces som version 1. Version 1 lider under en række tekniske udfordringer, som beror på valg af underliggende teknologier, der ikke i tilstrækkelig grad har kunnet understøtte de driftsmæssige krav der i dag stilles på NSP platformen, og som har resultereret i at løsningen ikke har haft den tilsigtede grad af robusthed. Fremadrettet ønskes der en løsning, der er baseret Kafka, for at tilsikre det ønskede niveau af robusthed.
Support ansvarlig: Arosii
NSP, NAS2 leverancebeskrivelse: National Adviseringsservice 2 (NAS2) - Leverancebeskrivelse
Forretningsanvendelse
Relaterede registre og services
Applikationsbeskrivelse
Generelt gemmes ingen persondata i servicens register, dog undtaget eventuelle CPR-numre angivet i IdListcontent.
Den Nationale Adviseringsservice udstilles på NSP (både cNSP og dNSP), og det er derfor teknisk muligt at få adgang til servicen fra både regionale it-systemer (dNSP) og fra it-systemer, der gør brug af den centrale NSP-instans (cNSP).
Adviseringsservicens abonnent-snitflade anvender fødereret sikkerhed og kræver Den Gode Webservice 1.0.1-ID-kort på minimum niveau 3. Derfor skal EOJ-systemet indhente et ID-kort signereret af STS’en, der kan anvendes i kald af abonnent-snitfladens operationer
Der findes 5 endpoints med kald formelt specificeret i tilhørende WDSL: (Bemærk, de samme som for NAS (version 1))
++ http://[host]:[port]/decoupling/notificationbroker/service https://wsdl.nspop.dk/notificationbroker/service?wsdl
++ http://[host]:[port]/decoupling/pullpointfactory/service https://wsdl.nspop.dk/pullpointfactory/service?wsdl
++ http://[host]:[port]/decoupling/pullpoint/service https://wsdl.nspop.dk/pullpoint/service?wsdl
++ http://[host]:[port]/decoupling/subscriptionmanager/service https://wsdl.nspop.dk/subscriptionmanager/service?wsdl
++ http://[host]:[port]/decoupling/idlist/service https://wsdl.nspop.dk/idlist/service?wsdl
Adviseringsservicens abonnent-snitflade anvender fødereret sikkerhed og kræver Den Gode Webservice 1.0.1-ID-kort på minimum niveau 3. Derfor skal EOJ-systemet indhente et ID-kort signereret af STS’en, der kan anvendes i kald af abonnent-snitfladens operationer. (Afsender snitfladen med notify operationen er ikke beskyttet af DGWS og sikkerhed sker udelukkende på baggrund af IP whitelisting og det faktum at topic skal være oprettet i systemet for at det er muligt at afsende adviseringer).
Adviseringsservice er realiseret som 5 Java baserede webservices med tilhørende operationer:
1) NotificationBrokers ansvarsområder er at modtage adviseringer via det udbudte interface Notify og delegere disse videre til det rette topic på Kafka infrastrukturen.
NotificationBroker er inddelt i lag.
På ydersiden af NotificationBroker findes Service Interface: Dette lag er ansvarlig for at udbyde Notify SOAP servicen samt at foretage mapning ned i mod den model, der anvendes i forretningslaget i NotificationBroker.
Forretningslaget indeholder forretningslogikken: Dvs tjek på, om det indkommende topic er et lovligt NAS topic og publisering til den underliggende infrastruktur.
Selve oprettelse og orkestrering af NotificationBrokers komponenter varetages af en konfigurationskomponent. Denne konfigurationskomponent er også ansvarlig for at inkludere de relevante konfigurationer fra de delte komponenter, som NotificationBroker anvender. Det drejer sig om:
- DB: Topic-delen af databasekomponenten (TopicMapping anvendes til at validere det indkommende NAS topic og mapning ned til internt (kafka) topic)
- Kafka: Publisher-delen af kafkakomponenten.
Operation:
++ Notify: Publicerer en eller flere adviseringer på adviseringsservicen. Afsender snitfladen er ikke beskyttet af DGWS og sikkerhed sker udelukkende på baggrund af IP whitelisting og det faktum at topic skal være oprettet i systemet for at det er muligt at afsende adviseringer.
2) PullPointFactory-service: For at et anvendersystem kan indhente adviseringer skal der oprettes et pull point. Et pull point er en adresse hvor fra der kan afhentes adviseringer. I svaret returneres der en reference der skal anvendes når GetMessages skal kaldes.
DB: PullPoint
Operation:
++ CreatePullPoint: Et anvendersystem opretter et Pullpoint ved denne operation. Når der oprettes et pullpoint skabes et unikt pullpoint-id, der i WS-BASE-NOTIFICATION returneres i CreatePullPointResponse som en WS Addressing endpoint reference (EPR). Pullpointets unikke EPR indeholder en adresse indeholdende en URI bestående af schema-navn, authority-del, path-del og en nøgle-del.
3) IDList Servicen har som ansvarsområde at udstille et endpoint, som anvendere kan bruge til at administrere ID lister. En ID liste er en liste over positive ID'er der skal hentes adviseringer for.
IDList Servicen er inddelt i lag. Selve oprettelse og orkestrering af IDList Service komponenter varetages af en konfigurationskomponent. Denne konfigurationskomponent er også ansvarlig for at inkludere de relevante konfigurationer fra de delte komponenter, som IDList anvender:
- DB: IDList, IDListContent og Subscription delene af databasekomponenten.
IDList servicen udstiller to SOAP actions. En operation der hedder CreateIDList og en der hedder DestroyIDList. CreateIDList anvendes til både at oprette og opdatere en ID liste. Dette gøres ved at tjekke om en ID liste med det givne navn allerede findes:
++ CreateIDList - Opretter eller opdaterer en ID Liste til brug for et abonnement på adviseringer
Anvendersystemet kan opdatere sin id-liste løbende. Identifikation af ID listen er det navn som der er anvendt da listen blev oprettet. Er id-listen (som her) anvendt i et abonnement, betyder det, når adviseringer efterfølgende afhentes er det den nye id liste der evalueres op mod. Opdatering sker ved at alle eksisterende ID'er slettes og de nye indsættes. Opdatering sker med samme kald som ved oprettelse, men returnerer en indikation af, om listen eksisterede.
I autorisationen indgår desuden, at opdatering af ID-liste kun kan gennemføres af den organisation, der oprettede den
++ DestroyIDList - Nedlægger en eksisterende ID Liste
I autorisationen indgår desuden, at nedlæggelse af ID-liste kun kan gennemføres af den organisation, der oprettede den.
Det er en forudsætning, at ID-listen ikke anvendes i abonnement(er). Der returneres SOAP Fault, hvis ID-listen anvendes.
4) SubscriptionManager-servicen: Ved oprettelse af abonnement knyttes et pullpoint sammen med et topic. Dermed bliver der oprettet et abonnement på et givent topic til et givent pull point. Dette abonnement kan indeholde enten navnet på en eksisterende id liste, en liste af id'er eller ingen af disse to. Ved angivelse af enten en id liste eller en liste af ider filtreres adviseringer på det angivne topic i forhold til de id'er der er i listen. Hvis der hverken er angivet ID'er eller navnet på en ID liste så modtages alle adviseringer på det topic der oprettes abonnement på.
I svaret returneres der en endpoint reference der skal bruges når et abonnement skal nedlægges.
- DB: Subscription, PullPoint, IdList
Abonnementsnitfladen er beskyttet af DGWS og det er derfor krævet at man har optaget et token i STS'en inden man kalder nedenstående snitflader
Operationer:
++ Subscribe - Opretter abonnement på et emne med givet filter.
Som led i abonnement-oprettelse specificeres hvilket emne, der ønskes abonneret på. Bemærk, at oprettelse og erhvervelse af emner og deres identifikation sker out-of-band forud for oprettelse af abonnement. Emner og indhold i adviseringer defineres af organisationen bag kildesystemet. Abonnering på adviseringer for enkelt ID henholdsvis flere ID'ere understøttes ved anvendelse af et filter, der specificeres på abonneringstidspunktet sammen med emne. Abonnering på adviseringer for flere ID'er understøttes gennem navngivne lister, de såkaldte ID-lister.
I autorisationen indgår desuden, at såfremt der er anvendt ID-liste i abonnementet, da skal anvendersystemet være ejer af ID-listen
++ Unsubscribe - nedlægger et abonnement
I autorisationen indgår desuden, at anvendersystemet skal være ejer af abonnementet, dvs. fra samme organisation som den, der oprettede abonnementet
5) PullPoint Service har som ansvarsområde at udstille et endpoint, som anvendere kan bruge til at hente adviseringer fra NAS2 for et givent pullpoint. Som en del af dette, er det op til PullPoint Service at opretholde en status for hvert abonnement under et givent pull point, der fortæller, hvor langt anvenderen er kommet i afhentningen.
PullPoint Service er inddelt i lag. På ydersiden af PullPoint findes Service Interface: Dette lag er ansvarlig for at udbyde GetMessages SOAP servicen samt at foretage mapning ned i mod den model, der anvendes i forretningslaget i PullPointService.
Forretningslaget indeholder forretningslogikken: PullPoint Service henter notifikationer fra Kafka via Streamer interfacet, som stilles til rådighed via det fælles Kafka modul. Til at holde styr på tilstanden for hvert abonnement anvender PullPoint Service det fælles database modul, der holder styr på tilstand (offset) hvor hvert abonnement. Selve oprettelse og orkestrering af PullPoint Service komponenter varetages af en konfigurationskomponent. Denne konfigurationskomponent er også ansvarlig for at inkludere de relevante konfigurationer fra de delte komponenter, som PullPoint anvender:
- DB: PullPoint-delen af databasekomponenten (PullPoint, Subscriber, NasConsumer, IdList, IdListContent)
- Kafka: Streamer-delen af kafkakomponenten.
Abonnementsnitfladen er beskyttet af DGWS og det er derfor krævet at man har optaget et token i STS'en inden man kalder nedenstående snitflader
Operationer:
++ GetMessages - Et anvendersystem henter adviseringer, uanset emner, fra et PullPoint.
I autorisationen indgår desuden, at anvendersystemet skal være ejer af PullPointet, dvs. fra samme organisation som den, der oprettede PullPointet.
++ DestroyPullPoint - Et anvendersystem nedlægger et PullPoint.
I autorisationen indgår desuden, at anvendersystemet skal være ejer af PullPointet, dvs. fra samme organisation som den, der oprettede PullPointet.
Datastruktur, Sundhedsdataregister: National Adviseringsservice (NAS2)
Register properties:
National Adviserings Service (NAS2) registeret indeholder masterdata til understøttelse af afkoblet system-til-system advisering ved brug af NSP.
Løsningen giver alle med adgang til NSP mulighed for at aflevere adviseringer til øvrige parter i sundhedssektoren gennem NSP. Løsningen er en realisering af et ”publish-subscribe” kommunikationsmønster, hvor adviseringskilder ”skubber” adviseringsinformationer til modtagere, dog med mulighed for at etablere et ”push-pull” scenarie gennem etablering af såkaldte ”PullPoints”.
Kilder og modtagere er indbyrdes afkoblede, idet kilderne leverer adviseringer til adviseringsservicen, og modtagerne vedligeholder et abonnement hos adviseringsservicen på de typer af adviseringer (”Topics”), de ønsker at modtage fra de respektive kilder.
Entitetsbeskrivelser
IdList
IDlist indeholder information om de oprettet idlister og anvendes af IdList Manager (IM).
Inden et modtagersystem opretter et abonnement skal der oprettes en id-liste, der angiver hvilke entiteter der ønskes adviseringer omkring. Bemærk at begrebet id-liste er fastlagt og defineret af NAS i modsætning til f.eks. pullpoint og abonnement, som er generelle WS-Notification begreber.
IdList og tilhørende IdListContent er en representation af det eventuelle filter der er på en subscription. Det vil sige at det er en filtrering af beskeder til en given subscription
En id-liste har et navn, en enkelt type og et antal id'er. Navnet på id-listen skal bruges når denne skal anvendes i et abonnoment, vedligeholdes eller evt. senere nedlægges igen. Navnet bør være unikt nok til at undgå konflikter med andre modtagersystemer og bør være opbygget således at det er læseligt i.f.m. support og fejlsøgning. De enkelte id'er er strenge, hvis format beskrives af idTypen. Mulige idTyper bestemmes af det kildesystem der ønskes adviseringer fra.
En id-liste oprettes via den tilhørende Idlist service.
Objektet indeholder informationen:
--------------------------------------
`name` -- Idlistens navn. Hvis den bliver oprettet indirekte via operationen subscribe vil denne være en UUID
`id_type` -- Typen af id'er, listen indeholder. Typen er defineret på idlist fremfor idlistcontent da dette gør opslag hurtigere, men dette begrænser lister til kun at kunne indeholde én type id'er.
`owner_id` -- Id for ejeren af pullpointet. Dette id er taget fra "Den Gode WebService" header, en sammensætning af InvokerId og ITSystemName.
`auto_delete` --
`description` -- Ikke obligatorisk streng som beskriver idlisten
IdListContent
idlistcontent tabellen indeholder de konkrete id-værdier relateret en Idlist
Objektet indeholder informationen:
--------------------------------------
`id_value` -- Den konkrete id
`idlist_id` -- Foreign key til idlist tabellen. Dette er et many-to-one forhold, hvor en idlist indeholder mange idlistcontents
`hash` --
NasConsumer
NasConsumer indeholder de messages som er sendt til en subscription.
NasConsumer er en representation af hvor langt en consumer er nået samt identifikation af seneste kald. Identifikation af seneste kald er nødvendig for at overholde DGWS krav omkring at gensende seneste svar.
Hvor langt en consumer er nået er blot en tekststreng og så er det op til Kafka at fortolke denne tekststreng. Dette er med til at sikre en afkopling mellem det underliggende system til at gemme beskeder og forretningslogikken. NasConsumer er modelleret så der udelukkende læses og indsættes rækker i tabellen. Når seneste offset skal hentes, så er det blot nødvendigt at læse nyeste række for den subscription der er tale om. Der er ikke brug for at opdatere eksisterende rækker. Dette betyder også at der løbende skal være et oprydningsjob der fjerner gamle rækker. Hvis dette ikke laves vil data aldrig blive slettet.
Bemærk: Hver gang der indsættes en række pr. subscription, slettes den ældste nas_consumer, så der maksimalt er to rækker pr. subscription. Altså ingen opryd alligevel ..
Objektet indeholder informationen:
--------------------------------------
`subscription` -- Foreign key til Subsription tabellen. Dette er et many-to-one forhold, hvor en Subscription indeholder mange NasConsumer
`offsets` -- Når en klient henter beskeder/notifikationer på et pullpoint, skal der fortsættes fra der hvor klienten sidst slap. Det er nemlig ikke blot eet offset, men en samling af flere offsets, der gemmes. Dette skyldes den måde Kafka clusteret bedst muligt udnyttes på. Når en besked afleveres til Notification Broker, vil den blive givet videre til Kafka clusteret og blive gemt i en af de partitioner, der er konfigureret. Der er skal som minimum være opsat det antal partitioner for et topic, som der er noder i clusteret. Beskeder vil blive uniform fordelt til partitioner tilhørende et topic. Når beskeder skal hentes ud igen, skal en Kafka consumer, altså Pullpoint servicen, sættes op sådan, at den henter fra samtlige partitioner for et givet topic. Der skal hentes ud fra det offset, der er gemt for den pågældende subscription og partition. Når tilstrækkelige beskeder er hentet og der skal returneres til klient, gemmes nye offsets til den efterspurgte subscription i databasen igen. Måden offsets gemmes på er i en "liste" i offset i nasConsumer. Da dette dog kun er en streng, skal der vælges passende formattering. Dette simplificeres af at partitioner altid angives med tallene fra 0 og opefter. En komma-separeret liste vil derfor være tilstrækkelig. (ex: 0,0,0,0).
`message_id` --
`message_count` --
`created` timestamp -- timestamp for oprettelse
`previous_id` --
PullPoint
Et pullpoint modelleres til persistering af bla. ejerskab af et pullpoint. Pullpoint indeholder data om de eksisterende pullpoints.
Benyttes af Pullpoint (PP) og PullPointFactory (PF) services.
Objektet indeholder informationen:
--------------------------------------
`pull_point_id` -- Det unikke id genereret til pullpointet.
`owner_id` -- Id for ejeren af pullpointet. Dette id er taget fra "Den Gode WebService" header, en sammensætning af InvokerId og ITSystemName.
Subscription
Tabellen subscription indeholder information om subscriptions og anvendes af Subscription Manager (SM).
For at data kan leveres til et pull point skal der være et eller flere abonnementer (Subscription). En subscription relaterer sig til et PullPoint og en række offsets (NasConsumer) og en evt. id list (IdList)
Objektet indeholder informationen:
--------------------------------------
`subscription_id` -- Det unikke id genereret til subscription.
`pull_point` -- Endpoint reference til pullpointet. Dette er et many-to-one forhold, hvor et pullpoint indeholder mange Subscriptions
`topic` -- Topic som der skal filtreres på til denne subscription.
`owner_id` -- Id for ejeren af denne subscription. Dette id er taget fra "Den Gode WebService" header, en sammensætning af InvokerId og ITSystemName.
`idlist_id` -- Foreign key til idlist tabellen. Dette er et many-to-one forhold, hvor en idlist indeholder mange Subscriptions
TopicMapping
TopicMapping anvendes af NotificationBroker (NB) til at validere det indkommende NAS topic og mapning ned til internt (kafka) topic.
Der er en 1-til-1 mapping mellem topics indeholdt i notifikationer til interne Kafka topics.
Objektet indeholder informationen:
--------------------------------------
`topic` -- indkommende NAS topic
`internal_topic` -- internt (kafka) topic
`active` boolean --
`created` timestamp --
`metadata` -- Eventuelle metadata-informationer såsom f.eks. hvem der har oprettet topic kan tilføjes metadata kolonnen. Metadata kolonnen vil blive gemt som JSON og dermed kan den udvides med ekstra værdier efter behov. Disse felter vil som udgangspunkt ikke blive læse i servicen og dermed er servicen heller ikke afhængig af hvad der står i metadata kolonnen.
Tabelbeskrivelser
Tabel: id_list
CREATE TABLE `id_list` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`name` VARCHAR(128) NOT NULL ,
`id_type` VARCHAR(128) NOT NULL ,
`owner_id` VARCHAR(128) NOT NULL ,
`auto_delete` INT(1) NOT NULL ,
`description` VARCHAR(512) NULL,
constraint id_list_pk primary key (id)
);
--
-- Indexes
--
ALTER TABLE `id_list`
ADD UNIQUE KEY (`name`);
Tabel: id_list_content
CREATE TABLE `id_list_content` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`id_value` VARCHAR(255) NOT NULL ,
`idlist_id` int(11) NOT NULL,
`hash` bigint NOT NULL,
constraint id_list_content_pk primary key (id)
);
--
-- Indexes
--
ALTER TABLE `id_list_content`
ADD constraint id_list_content_id_uc UNIQUE KEY `id_UNIQUE` (`id` ASC);
create index `id_list_content_hash_idx` on id_list_content(hash, idlist_id);
CREATE INDEX `id_list_content_idlist_idx`
ON id_list_content (`idlist_id` ASC);
Alter table id_list_content
add constraint `id_list_content_idlist_fk` foreign key(idlist_id) references id_list(id) on delete restrict on update restrict;
Tabel: nas_consumer
CREATE TABLE `nas_consumer` (
`id` bigint unsigned NOT NULL AUTO_INCREMENT,
`subscription` int(11) NOT NULL,
`offsets` varchar(1024) NOT NULL,
`message_id` varchar(1024) NULL,
`message_count` int(11) NOT NULL,
`created` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
`previous_id` bigint unsigned NULL,
constraint nas_consumer_pk primary key (id)
);
--
-- Indexes for table `nas_consumer`
--
ALTER TABLE `nas_consumer`
ADD constraint nas_consumer_previous_id_uc UNIQUE KEY (`previous_id`);
Alter table nas_consumer
add constraint nas_consumer_subscription_fk foreign key(subscription) references subscription(id) on delete restrict on update restrict
Tabel: pull_point
CREATE TABLE `pull_point` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`pull_point_id` varchar(128) NOT NULL,
`owner_id` varchar(128) NOT NULL,
constraint pull_point_pk primary key (id)
);
--
-- Indexes for table `pull_point`
--
ALTER TABLE `pull_point`
ADD UNIQUE KEY `pull_point_id_uc` (`pull_point_id`);
Tabel: subscription
CREATE TABLE `subscription` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`subscription_id` VARCHAR(128) NOT NULL ,
`pull_point` int(11) NULL ,
`topic` VARCHAR(128) NOT NULL ,
`owner_id` VARCHAR(128) NOT NULL ,
`idlist_id` int(11) NULL DEFAULT NULL,
constraint subscription_pk primary key (id)
);
--
-- Indexes
--
ALTER TABLE `subscription`
ADD UNIQUE KEY subscription_subscription_id_uc (`subscription_id` ASC);
CREATE INDEX `subscription_idlist_idx`
ON subscription (`idlist_id` ASC);
CREATE INDEX `subscription_pull_point_idx`
ON subscription (`pull_point` ASC);
Alter table subscription
add constraint `subscription_idlist_fk` foreign key(idlist_id) references id_list(id) on delete restrict on update cascade;
Tabel: topic_mapping
CREATE TABLE `topic_mapping` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`topic` varchar(128) NOT NULL,
`internal_topic` varchar(128) NOT NULL,
`active` boolean NOT NULL DEFAULT 1,
`created` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
`metadata` longtext NULL,
constraint topic_mapping_pk primary key (id)
); --ENGINE=InnoDB DEFAULT CHARSET=latin1;
--
-- Indexes for table `topic_mapping`
--
ALTER TABLE `topic_mapping`
ADD UNIQUE KEY `topic_internal_topic_uc` (`topic`,`internal_topic`);
ALTER TABLE `topic_mapping`
ADD UNIQUE KEY `topic_uc` (`topic`);