I forbindelse med overgang fra den tidligere WSRM/Pull til Webservicebeskeder/Push har STAR udarbejdet dette dokument som sammenfatter hvordan en løsning omkring webservicebeskeder foreslås. Dokumentet skal betragtes som et samtaleudgangspunkt. Dermed forbehold for elementer som ikke bliver implementeret.
Da webservicebeskeder indfases gradvist er forhold omkring transitionsfasen også beskrevet.
Denne løsningsbeskrivelse bygger oven på informationer givet på “Dialogmøde om Moderniseringsprojektet” afholdt . Se præsentation herunder “WebServiceBeskeder_TO-BE.pptx“
Denne løsningsbeskrivelse er målrettet leverandører af systemer som modtager webservicebeskeder. Enkelte endnu uafklarede område er markeret med rødt.
Ekstern Kommunikation | Det forretningsdomæne i DFDG, hvorfra webservicebeskeder afsendes til aftagere heraf. |
Forretningsdomæne | Henviser til ét af de definerede forretningsdomæner i DFDG, som eksempelvis “Visitation og status”, “Kontaktforløb” m.fl. (se den fulde liste på Webservice-struktur (TO-BE på moderniserende DFDG webservice)). |
Tillslutningsaftale | En tilslutningsaftale med STAR består primært at manuel juridisk inspektion. I dette dokument betegner en tilslutningsaftale dog en teknisk oprettelse af et webservicebesked aftagersystem i DFDG. |
Abonnement | Et abonnement skal forstås som en aftagers abonnement på en webservicebeskedtype. |
Webhook | HTTPS endpoint, hvortil DFDG kan afsende webservicebeskeder. |
Nedenstående liste angiver tekniske krav til hver aftager af webservicebeskeder.
Udstilling af ét til flere webhooks (https), som DFDG kan kalde for at aflevere webservicebeskeder. Abonnementsmodellen for webservicebeskeder understøtter forskellige konfigurationsmuligheder hertil (se afsnittet om abonnements modellen).
Angive en liste med kontaktpersoner (telefon/email), som STAR kan kontakte ifm. med evt. drift problemer
Kommerciel kontakt (formel ansvarshavende hos aftager)
Teknisk kontakt (teknisk person som kan hjælpe med at afklare tekniske spørgsmål, f.eks. ved udfordringer med at afvikle udsendte beskeder. Kan være Fogbugz for Fogbugzaftagere)
Juridisk kontakt (kontakt ved. f.eks. GDPR relaterede spørgsmål)
Abonnementsmodellen for webservicebeskeder understøtter, at hver enkelt aftager af webservicebeskeder efter eget behov kan udstille ét eller flere Webhooks i kombinationen af:
aftagende system af webservicebeskeder, eksempelvis et givent sagsbehandlingssystem, et givent plannersystem m.fl.
webservicebeskedtype, den specifikke webservicebeskedtype, jeg som aftager af webservices ønsker at få tilsendt.
organisation (organisationstype og organisationskode), der angiver, hvilken organisation, jeg som aftager af webservicebeskeder lovmæssigt må få tilsendt webservicebeskeder for, eksempelvis et givent jobcenter, en given kommune eller en given a-kasse.
Abonnementsmodellen muliggør, at jeg som aftager af webservicebeskeder ville kunne:
udstille et og samme Webhook, hvorpå jeg får tilsendt alle webservicebeskeder uanset webservicebeskedtype (dem jeg abonnere på) gældende for alle de organisationer, som jeg lovmæssigt må få tilsendt webservicebeskeder for.
udstille et Webhook, hvorpå jeg får tilsendt alle webservicebeskeder af en given webservicebeskedtype, som jeg abonnere på gældende for alle de organisationer, som jeg lovmæssigt må få tilsendt webservicebeskeder for.
udstille et og samme Webhook, hvorpå jeg får tilsendt alle webservicebeskeder uanset webservicebeskedtype (dem jeg abonnere på) gældende for én af de organisationer, som jeg lovmæssigt må få tilsendt webservicebeskeder for.
udstille et Webhook, hvorpå jeg får tilsendt alle webservicebeskeder af en given webservicebeskedtype, som jeg abonnere på gældende for én af de organisationer, som jeg lovmæssigt må få tilsendt webservicebeskeder for.
DFDG går væk fra et benytte (hoved)køer og subkøer i den nye abonnementsmodel. I stedet sætter den nye abonnementsmodel fokus på de systemer, som skal aftage webservicebeskeder. Det er således til de enkelte aftagne systemer, at man konfigurerer abonnementer på organisationer (organisationstype + organisationskode) og webservicebeskedtyper.
[TBD]
Alle webservicebeskeder fremsendes som JSON i en struktur, der både indeholder forretningsmæssigt, indhold samt det tekniske indhold (f.eks. metadata)
Nedenstående tabel beskriver det tekniske indhold, som medsendes hver webservicebesked uanset typen på webservicebeskeden.
Element | Beskrivelse |
|---|---|
Oprindelse, registrerende myndighed | Angivelse af den myndighed, der oprindelig var årsagen til afsendelse af webservicebeskeden. Strukturen omfatter information om myndigheden i form af organisationstype og organisationskode. Strukturen udfyldes med følgende information:
|
Oprindelse, registrerende bruger | Angivelse af hvem, der oprindelig var årsagen til afsendelse af webservicebeskeden. Strukturen omfatter information om brugeren enten i form af en sagsbehandler, en borger ved borgerregistreringer eller et system ved system til systemkald. Ydermere indeholder strukturen information om den myndighed (organisation), hvorfra personen/systemet agerer. Strukturen udfyldes med følgende information:
|
Oprindelse, system (SystemId og Systemnavn) | Angivelse af hvilket system, der oprindelig var årsagen til afsendelse af webservicebeskeden. Det udfyldes med følgende information
|
Besked Identifier | Unik identifikation på selve webservicebeskeden. I forbindelse med genfremsendelser grundet eventuelle fejl, eller at man som aftager af webservicebeskeder ønsker en webservicebesked genfremsendt, forbliver den unikke identifikation af webservicebeskeden den sammen. |
Hændelsestidspunkt | Angivelse af hændelsestidspunktet for den hændelse, som har givet anledning til, at webservicebeskeden er blevet sendt. Det er DFDG, der sætter hændelsestidspunktet. |
Miljø | Angivelse af det STAR-miljø, hvorfra webservicebeskeden er sendt, eksempelvis PROD, PREPROD, T3 m.fl. |
Korrelationsidentifier | Unik korrelationsidentifier, som DFDGs forretningsdomæne har givet:
Korrelationsidentifier er med til at sikre sporbarhed og understøtte fejlsøgning. |
Entitet (EntitetId og Entitetnavn) | Angivelse i form af type og navn på, hvilket forretningsentitet, som webservicebeskeden omhandler (se EksternKommunikation.EntityTypeCodeList). |
Ekstern Identifier | Unik identifikation af den forretningsentitet, som webservicebeskeder omhandler, hvilket eksempelvis kan være:
Med den unikke identifikation af forretningsentitet, vil det i de fleste tilfælde være muligt at hente den akutelle information om forretningsentiteten. Dette ved at udføre et webservicekald til en metode (GET) i et af DFDGs forretningsdomæner. Entitetstypen vil kunne fortælle, hvilken metode, der skal kaldes i hvilket DFDG forretningsdomæne. |
Version Identifier | Unik versionsidentifikation af den forretningsentitet, som webservicebeskeden omhandler. Den unikke versionsidentifikation kan betragtes som et versionsnummer for forretningsentiteten og vil specifikke tilfælde kunne give adgang til at hente forretningsentiteten, som den så ud, da webservicebeskeden blev udsendt. Gældende for specifikke forretningsentiteter vil således det være muligt at udføre et webservicekald til en historikmetode (GET) i et af DFDGs forretningsdomæner for at få adgang til forretningsentiteten, som den så ud, da webservicebeskeden blev udsendt. Entitetstypen vil kunne fortælle, hvilken historikmetode, der skal kaldes i hvilket DFDG forretningsdomæne. |
Identifikation | En identifikation af enten den borger, den virksomhed eller den forretningsentitet, som webservicebeskeden omhandler. |
Identifikationstype (IdentifikationstypeId og Identifikationstypenavn) | Angivelse i form af type og navn på, hvad Identifikation feltet i Metadata er (se EksternKommunikation.IdentificationTypeCodeList). |
Ændringstype (AendringstypeId og Aendringstypenavn) | Angivelse i form af type og navn på, hvilken ændringstype, som har medført, at webservicebeskeden blev sendt (se EksternKommunikation.ChangeTypeCodeList). |
Dette json eksempel viser den tiltænkte struktur for metadata. Forbehold for mindre justeringer.
|
Den forretningsmæssige datastruktur for en webservicebesked aftales mellem STAR og webserviceaftagere.
Indhold i webservicebeskeder valideres altid af DFDG inden afsendelse. Fejler valideringen af en webservicebesked betragtes den som værende fejlet og vil herefter følge samme mønstre (f.eks genfremsendelsesregler, blokeringsregler m.m.), som de webservicebeskeder, der er ikke er afleveret grundet fejl hos aftagere af webservicebeskeder.
STAR tilstræber dataminimering ved udsendelse af webservicebeskeder.
STAR sletter afsendte webservicebeskeder efter gældende regler (pt. 6 måneder).
Webservicebeskeder versioneres efter samme mønster, som WSRM beskeder er blevet versioneret efter. Dette betyder, at der kan komme en ny version af samme webservicebeskedtype, når:
forretningen ændrer sig, og den eksisterende version af webservicebeskedtype ikke længere kan rumme de forretningsmæssige ændringer.
Ekstern Kommunikation sørger for, at webservicebeskeder afsendes til aftagere af webservicebeskeder i den rækkefølge, som hændelserne sker i de forretningsdomæner, som er årsagen til at webservicebeskeder bliver dannet.
Rækkefølgende af webservicebeskeder overholdes dermed i kombinationen af det enkelte forretningsdomæne og den enkelte borger.
[TBD]
Hvordan dokumenteres Webhooks og webservicebesked (kontrakter).
Hvordan laves der varslinger også til eksempelvis små private operatører? Light version af dokumentation og tilknytningsmuligheder?
Roadmap.
Teknisk dokumentation.
Referenceimplementation?
Forretningsdomænet Ekstern Kommunikation laver hændelseslogning på al afsendelse- og genfremsendelsesaktivitet, når webservicebeskeder forsøges afleveret til aftagere af webservicebeskeder.
I hændelsesloggen logges alle webservicebeskeder med:
webservicebeskedens indhold (payload)
en identifikation, som vil være:
borgerens CPR nummer, når webservicebeskeden omhandler en borger
unik identifikation af den dataentiteten, som webservicebeskeden omhandler, når der ikke er tale om borgerrettede webservicebeskeder, eksempelvis webservicebeskeder omhandlende stillingsbetegnelser
det Webhook (HTTPS endpoint), hvortil webservicebeskeden er fremsendt
den modtagne HTTP status kode fra Webhooket (aftagers svar)
den modtagne HTTP response body, når aftager melder fejl tilbage og denne er medsendt
Derudover logges brugen af selvbetjeningsmuligheder.
Forretningsdomænet Ekstern Kommunikation foretager revisionslogning på administration af abonnementer mv.
Aftagere af webservicebeskeder skal for hver enkelt webservicebesked, som modtages fra DFDG, returnerer en HTTP status kode, der indikerer, hvorvidt webservicebeskeden er modtaget og færdigbehandlet eller om webservicebeskeden er fejlet. Dette på grund af, at det forretningsdomæne, som fra DFDG afsender webservicebeskeder, agerer på HTTP status koder og sørger for, at genfremsendelsespolitikken træder i kraft for fejlende webservicebeskeder.
Som serviceaftager må jeg først forretningsmæssigt processere modtagene beskeder efter jeg har kvitteret overfor DFDG.
Som serviceaftager må jeg først forretningsmæssigt processere modtagene beskeder efter jeg har kvitteret overfor DFDG.
Aftagere af webservicebeskeder skal benytte nedenstående intervaller af HTTP status koder for at indikere, hvorvidt en given webservicebesked er succesfuldt modtaget og behandlet eller om den er fejlet:
Successful responses (200 – 299), der betragtes som værende, at den afsendte webservicebesked er succesfuldt modtaget hos aftager.
Client error responses (400 – 499), der betragtes som værende, at den afsendte webservicebesked er fejlet hos aftager grundet en formodet fejl i DFDG. Serviceaftager kan oprette en FogBugz-sag hos STAR/DFDG. Det anbefales at medsende beskrivende fejlbesked i HTTP response body (samt i FogBugz).
Server error responses (500 – 599), der betragtes som værende, at den afsendte webservicebesked er fejlet hos aftager grundet en fejl hos aftager selv. DFDG benytter sig efterfølgende af sin genfremsendelsespolitik ved fejlende webservicebeskeder (se nedenstående afsnit). Det anbefales ikke at medsende beskrivende fejlbesked i HTTP response body.
Øvrige returkoder vil ikke munde ud i genfremsendelse.
Timeout/manglende svar fra Webhook vil medføre, at DFDG benytter sig af sin genfremsendelsespolitik.
Når aftagere af webservicebeskeder ikke korrekt kan modtage og behandle en given webservicebesked, som modtages fra DFDG, enten på grund af forretningsmæssige årsager såvel som tekniske årsager, skal aftager returnerer en HTTP status kode, som indikerer fejl.
Når en aftager af webservicebeskeder med en HTTP status kode angiver, at en webservicebesked ikke kunne modtages og behandles, træder genfremsendelsespolitikken i kraft. Dette betyder, at:
den fejlende webservicebesked tilføjes til en genfremsendelseskø, hvor at den forsøges genfremsendt med en passende tidsforskydning, som bliver større gang for gang webservicebeskeden forsøges genfremsendt.
Tidsforskydningen stiger eksponentielt per besked for hver gang beskeden forsøges sendt igen, op til et maksimum af 3 timer mellem hvert forsøg. Tiden mellem hvert forsøg er baseret ud fra mængden af genforsøg, eksempelvis første gang så er næste forsøg om 1 sekund, så 3 sekunder, så 7, 15, 31... Dvs. at mængden af tid før næste forsøg fordobles, indtil at vi når til et punkt hvor at næste forsøg er over 3 timer (hvor at den så sættes til 3 timer hver gang).
tidsforskydningen er det samme for TEST og PROD miljøer på nuværende tidspunkt, dog er det sat op til nemt at kunne gøres konfigurerbart per miljø, hvis dette bliver nødvendigt.
der fremsendes ikke yderligere webservicebeskeder på samme borger fra det forretningsdomæne, som i DFDG var årsagen til, at den fejlende webservicebesked blev sendt. Disse webservicebeskeder ligges på kø til efterfølgende afsendelse.
der fremsendes ikke yderligere webservicebeskeder på samme dataentitet, som webservicebeskeden omhandler (eksempelvis samme stillingsbetegnelse), fra det forretningsdomæne, som i DFDG var årsagen til, at den fejlende webservicebesked blev sendt. Disse webservicebeskeder ligges på kø til efterfølgende afsendelse.
Når genfremsendelsespolitikken ligger webservicebeskeder på kø, er det for at sikre, at den forretningsmæssige rækkefølge af webservicebeskeder overholdes, eksempelvis pr. borger inden for et givent forretningsdomæne i DFDG. De webservicebeskeder, der ligger på kø, vil bliver afsendt fra DFDG, når aftager har modtaget og behandlet den oprindelig fejlende webservicebesked.
DFDG stiller krav om, at aftagere af webservicebeskeder stiller en teknisk kontakt (email/telefon), som kan kontaktes, når en og samme webservicebesked fejler vedvarende. Aftagere som benytter Topdesk bedes benytte Topdesk. |
Er Webhooks nede hos en aftager af webservicebeskeder, sørger DFDG for at ligge de webservicebeskeder, som skal afleveres til disse Webhooks, på kø til senere afsendelse.
DFDG vil løbende forsøge at genfremsende de webservicebeskeder, som ligger på kø. Dette vil være ensbetydende med, at aftagere af webservicebeskeder, vil begynde at modtage og behandle webservicebeskeder fra køen og derefter modtage og behandle nye webservicebeskeder, når aftagers Webhooks igen er oppe at køre.
DFDG sikrer, at rækkefølgende af webservicebeskeder overholdes pr. borger inden for et givent forretningsdomæne i DFDG.
I DFDG er det forretningsdomænet Ekstern Kommunikation, der afsender webservicebeskeder fra DFDG. Er dette forretningsdomæne nede i DFDG, afsendes der ikke webservicebeskeder, før forretningsdomænet igen er oppe at køre.
De i DFDG øvrige forretningsdomæner, som er oppe at køre, vil stadig kunne modtage og udføre forretningslogik ved webservicekald samt afvikle forretningsdomænernes Batchjobs. De enkelte forretningsdomæner, vil dermed stadig danne og aflevere interne hændelser (events) til Event Brokeren, som benyttes af DFDG. Når forretningsdomænet Ekstern Kommunikation igen kommer op at køre, vil forretningsdomænet begynde at aftage de ophobede interne hændelser (events) fra Event Brokeren og på baggrund af disse danne og afsende webservicebeskeder.
Er et andet forretningsdomæne, eksempelvis “Visitation og status”, nede i DFDG samtidig med, at forretningsdomænet Ekstern kommunikation er oppe at køre, vil aftagere af webservicebeskeder stadig kunne modtage webservicebeskeder. Dette fra de forretningsdomæner, som stadig er oppe og køre i DFDG.
Forretningsdomænet Ekstern Kommunikation danner og afsender webservicebeskeder på baggrund af interne hændelser (events), som sker i de øvrige forretningsdomæner i DFDG. De interne hændelser (events) publiceres til en Event Broker i forbindelse med servicekald og ved afvikling af Batchjobs. Ekstern Kommunikation agerer “næsten øjeblikkeligt” på disse interne hændelser (events), som kommer via Event Brokeren.
Dette er ensbetydende med, at aftagere af webservicebeskeder kan forvente at modtage webservicebeskeder fra DFDG i nærrealtid i en normal driftssituation.
Hver aftager af webservicebeskeder udstiller et eller flere Webhooks som HTTPS endpoints således at de er tilgængelige for DFDG.
DFDGs kald til aftagers webhook:
I forbindelse med tilslutning af en webservicebeskedaftager defineres et endpoint-prefix pr. miljø danner en “base-url“. F.eks. skal webservicen aftageren “MinAkasse“ angive at alle webservicebeskeder på f.eks. testmiljøet T3 skal sendes til en adresse startende med “https://test.minakasse.dk/webhooknavn”. Alle abonnementer skal således udelukkende opsættes ved den resterende url (hvis forskellig fra baseurl).
DFDG kalder aftagers webhook med et klientcertifikat (antageligvis ét for PROD og et andet for alle testmiljøer)
Aftagers kald imod DFDG (selvbetjening)
Når aftager skal opsætte abonnementer (se afsnit selvbetjening) kan dette gøres via GUI eller API. APIet sikres ‘udelukkende’ med en JWT Bearer token. Derved vil det ikke være muligt at benytte samme authenticationmodel som i det øvrige DFDG (certifikat).
[TBD]
Selve webservicebeskeder og deres indhold krypteres ikke. Dette begrundes med, at:
en kryptering vil gøre fejlsøgning på tværs af aftagere af webservicebeskeder og DFDG besværligt.
kryptering ikke er strengt nødvendigt, når STAR tilstræber tynde og semitykke webservicebeskeder uden al for megen forretningsmæssigt indhold af hensyn til GDPR.
der benyttes naturligvis TLS ved beskedoverførslen - jf. afsnit om sikkerhed.
STAR påtænker at oprette en selvbetjeningsløsning som aftagere af webservicebeskeder kan benytte. Løsningen kan bestå af:
En webapplikation som giver en bruger adgang til nedenstående funktionalitet
Et API som tillader programmatisk selvbetjening
Sikkerheden for webapplikationen forventes at integrere med den fælles brugerrettighedsstyringskomponent (FBRS) (https://digst.dk/it-loesninger/nemlog-in/om-loesningen/aendring-i-funktionaliteter/implementeringssite/infrastrukturbeskrivelse/nemlog-in3-projektet/ )
Sikkerhed for API følger standarden for STARs øvrige moderniserede applikationer og benytter OAUTH 2. Klientcertifikater tilbydes ikke.
Herfra er der muligt at se og genafspille webservicebeskeder. Dette er muligt for
fejlede
korrekt modtagerede beskeder (når der skiftes system eller et nyt system ibrugtages)
Beskeder er synlige indtil de slettes, jf. GDPR.
Her kan aftager se beskeder som af en eller anden grund endnu ikke er afsendt.
Her kan aftager se status på sin tilslutningsaftale samt ændre kontaktinformationer. Det er kun muligt for STAR at oprette og nedlægge tilslutningsaftaler.
Aftagere kan abonnere på webservicebeskedstyper. Herunder registrere hvilket Webhook Endpoint der skal kaldes.
Mulighed for at kunne afsende testbeskeder med fiktivt Payload. Hermed bliver det muligt for webservicebeskedaftageren at verificere at webhooket kan modtage det afsendte beskedformat.
STAR overvåger driften af webservicebeskeder, men det er aftagernes ansvar at webhooks er kørende og tilgængelige.
Skal vi skrive noget omkring for mange beskeder de skal kunne holde til?
Webservicebeskedaftagerne kan via STARs webservicebesked-selvbetjeningsløsning se status på driften for egne beskeder.
STAR/DFDG har en forventning om, at webservicebeskeder afsendes fra DFDG og modtages samt behandles hos aftagere af webservicebeskeder i nærrealtid under normale driftsforhold. Dette betyder, at der i forbindelse med en release kun vil ligge de webservicebeskeder, som aftagere ikke har kunnet modtage og behandle - altså de beskeder, som ligger til genfremsendelse i forhold til genfremsendelsespolitikken for webservicebeskeder.
STAR/DFDG ser ikke et behov for, at aftagere af webservicebeskeder behøver at have modtaget og behandlet eventuelle fejlende webservicebeskeder inden en release, idet sådanne webservicebeskeder forsøges genfremsendt, når releasen er idriftsat
Ovenstående er ensbetydende med, at aftagere af webservicebeskeder skal kunne håndtere de webservicebeskeder, som måtte ligge til genfremsendelse til aftager, efter en release er idriftsat. Dette vil også være gældende, når der til releasen er kommet og idriftsat en nye versioner af webservicebeskedtyper. Dette skal aftager af webservicebeskeder understøtte forretningsmæssigt såvel som teknisk, da DFDG genfremsender tidligere fejlende webservicebeskeder (som kan være i tidligere versioner) efter releasen er idriftsat. |
STAR/DFDG følger de normale regler for varsling af nye versioner af webservicebeskedtyper.
Under en release stopper DFDG med at fremsende webservicebeskeder indtil releasen er idriftsat.
Via selvbetjening afprøve, om man rent faktisk kan modtage beskeden med en 'test-knap'
En del af at oprette et abonnement mellem en given aftager af webservicebeskeder og en specifik webservicebeskedtype forudsætter en end-to-end test, der beviser, at aftageren af webservicebeskedtypen kan aftage og returnere en HTTP status kode OK, når STAR sender en webservicebesked indeholde fiktive data.
Hvad gør vi med versionering og nye versioner af samme webservicebesked?
Kan man overhovedet oprette et abonnement i PROD, eller skal test være gennemført på T-miljøer inden?
Mock af Webhooks til vores udviklingsmiljøer → så vi ikke ligger at fejler og forsøger at genfremsende endpoints.
KMD giver udtryk for at de foretrækker at afvente med omlægningen til alle WSRM-beskeder er omlagt |
[TBD]
STAR står for at oprette tilslutningsaftaler for alle eksisterende WSRM aftagere.
Eksisterende WSRM abonnementer migreres ikke automatisk. Når en aftager ønsker at overgå fra WSRM til webservicebeskeder:
afmeldes det nuværende WSRM abonnement (via eksisterende proces)
har aftager ansvaret for at oprette et webservicebesked-abonnement via selvbetjeningsløsningen på alle miljøer.
Alle nye beskeder bliver implementeret som webservicebeskeder. Der implementeres således ikke tilsvarende WSRM beskeder.
Hvornår kan jeg begynde af aftage Webservicebeskeder?
Hvornår jeg kan få WSRM og benytte mig af dobbelt drift?
Skal nye beskedtyper være på ny eller gammel model =>