Praktisk information

Løsningsbeskrivelse

1 Praktisk information
2 Løsningsbeskrivelse
- 2.1 Baggrund
- 2.2 Læsevejledning
  - 2.2.1 Definitioner
- 2.3 Teknisk arkitektur
  - 2.3.1 Tekniske krav til aftagere af webservicebeskeder
  - 2.3.2 Abonnementsmodel
    - 2.3.2.1 Datamodel
  - 2.3.3 Indhold i webservicebeskeder
    - 2.3.3.1 Forretningsmæssigt indhold
    - 2.3.3.2 Teknisk indhold
  - 2.3.4 Metadata eksempel
  - 2.3.5 Skema og validering
  - 2.3.6 GDPR
  - 2.3.7 Versionering af webservicebeskeder
  - 2.3.8 Rækkefølge af webservicebeskeder
  - 2.3.9 Dokumentation
- 2.4 Drift
  - 2.4.1 Logning
    - 2.4.1.1 Hændelseslog
    - 2.4.1.2 Revisionslogning
  - 2.4.2 Returkoder og fejlhåndtering (link til permanent forretningsside)
    - 2.4.2.1 Genfremsendelsespolitik for fejlende webservicebeskeder
  - 2.4.3 Reliability
    - 2.4.3.1 Webhooks hos aftagere af webservicebeskeder er nede
    - 2.4.3.2 Forretningsdomænet Ekstern Kommunikation er nede
    - 2.4.3.3 Et andet forretningsdomæne i DFDG er nede
  - 2.4.4 Forventning til datakonsistens
  - 2.4.5 Sikkerhed
    - 2.4.5.1 Kryptering
    - 2.4.5.2 Netværkssikkerhed
  - 2.4.6 Selvbetjening
    - 2.4.6.1 Sikkerhed ifb. med selvbetjeningsmuligheder
    - 2.4.6.2 Se og genafspilning af allerede fejlende webservicebeskeder
    - 2.4.6.3 Se de webservicebeskeder, som p.t. ligger til afsendelse
    - 2.4.6.4 Administration af tilslutningsaftale
    - 2.4.6.5 Administration af abonnementer på webservicebeskeder
    - 2.4.6.6 Afsendelse af test webservicebeskeder
  - 2.4.7 Overvågning
  - 2.4.8 Opgaver i forbindelse med en release
    - 2.4.8.1 Serviceaftagere har ansvaret for at oprette abn. på alle miljøer (dvs. inkl. release aftenen)
    - 2.4.8.2 Tømning af køer ved releases
  - 2.4.9 Test
    - 2.4.9.1 Mock af Webhooks til intern test
- 2.5 Transition

Baggrund

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 Oct 26, 2022. Se præsentation herunder “WebServiceBeskeder_TO-BE.pptx“

Læsevejledning

Denne løsningsbeskrivelse er målrettet leverandører af systemer som modtager webservicebeskeder. Enkelte endnu uafklarede område er markeret med rødt.

Definitioner


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å https://starwiki.atlassian.net/wiki/spaces/KON/pages/356286533).
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.

Teknisk arkitektur

Tekniske krav til aftagere af 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)

Abonnementsmodel

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.

Datamodel

Indhold i webservicebeskeder

Forretningsmæssigt indhold

[TBD]

Teknisk indhold

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

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: den specifikke myndighed (eksempelvis et specifikt jobcenter, en specifik a-kasse eller et specifik STAR system såsom Jobnet) hvormed webserviceaftageren har kaldt en webservice i DFDG, der gav anledning til, at webservicebeskeden blev sendt. Dette værende sig også gældende, hvis webservicebeskeden blev sendt som en afledt handling fra et andet forretningsdomæne end dét, hvor webservicekaldet blev modtaget. den specifikke STAR forretningsdomæne, der har udført et batchjob, som var årsagen til at webservicebeskeden blev sendt, også selv om webservicebeskeden blev sendt som en afledt handling fra et andet forretningsdomæne end dér, hvor STAR Batchjobbet kører.
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: den bruger (eksempelvis en sagsbehandler i et jobcenter, en sagsbehandler i en a-kasse, en borger på Jobnet eller et system til systemkald) hvormed webserviceaftageren har kaldt en webservice i DFDG, der gav anledning til, at webservicebeskeden blev sendt. Dette værende sig også gældende, hvis webservicebeskeden blev sendt som en afledt handling fra et andet forretningsdomæne end dét, hvor webservicekaldet blev modtaget. det STAR Batchjob, som var årsagen til at webservicebeskeden blev sendt, også selv om webservicebeskeden blev sendt som en afledt handling fra et andet forretningsdomæne end dér, hvor STAR Batchjobbet kører.
Oprindelse, system (SystemId og Systemnavn)	Angivelse af hvilket system, der oprindelig var årsagen til afsendelse af webservicebeskeden. Det udfyldes med følgende information det eksterne system (eksempelvis et specifikt sagsbehandlingssystem, et specifikt plannersystem, et specifikt STAR system såsom Jobnet), der har kaldt en webservice, som gav anledning til, at webservicebeskeden blev sendt. Dette er også gældende, hvis webservicebeskeden blev sendt som en afledt handling fra et andet forretningsdomæne end dét, hvor webservicekaldet blev modtaget. det specifikke forretningsdomæne hvorfra et STAR Batchjob kører og som var årsagen til, at webservicebeskeden blev sendt, også selv om webservicebeskeden blev sendt som en afledt handling i et andet forretningsdomæne end dér, hvor STAR Batchjobbet kører.
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: det webservicekald, som var årsagen til, at webservicebeskeden blev sendt, også selv om webservicebeskeden blev sendt som en afledt handling fra et andet forretningsdomæne end dét, hvor webservicekaldet blev modtaget. det STAR Batchjob, som var årsagen til, at webservicebeskeden blev sendt, også selv om webservicebeskeden blev sendt som en afledt handling fra et andet forretningsdomæne end dét, hvor STAR Batchjobbet kører. 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 https://starwiki.atlassian.net/wiki/spaces/UDV/pages/4003628224).
Ekstern Identifier	Unik identifikation af den forretningsentitet, som webservicebeskeder omhandler, hvilket eksempelvis kan være: Unik identifikation af kontaktgruppen (KontaktgruppeIdentifier) Unik identifikation af ESCO STAR stillingsbetegnelsen (ConceptUriDa) … 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 https://starwiki.atlassian.net/wiki/spaces/UDV/pages/4004708631).
Ændringstype (AendringstypeId og Aendringstypenavn)	Angivelse i form af type og navn på, hvilken ændringstype, som har medført, at webservicebeskeden blev sendt (se https://starwiki.atlassian.net/wiki/spaces/UDV/pages/4005200134).

Den gode WSB/webservicebesked