Tekniske krav til bruk av tjenestebuss

Oppkobling til Tjenestebussen

• • En AMQP-Connection skal holdes åpen så lenge prosessen som har interaksjon med AMQP brokeren kjører. Dette er støttet ved at Helsenorge.Messaging cacher Connection. Dersom en aktør selv skriver integrasjonen mot AMQP-broker må man sørge for å cache AMQP-Connection og holde denne åpen igjennom livstiden til prosessen.
  • Polling-frekvens anbefales satt til 60 sekunder.

Bruk av AMQP protokoll

• • Tjenestebussen støtter både AMQP 0.9.1 og 1.0
  • Forretningsprosessen kan stille krav til å benytte kun AMQP 1.0, f.eks kommunikasjon med helsenorge.no som definert i Standard for AMQP. HITS 1216:2018
  • Kun TLS 1.2 og 1.3 støttes

Bruk av køer

• • Standard meldingsutveksling
    • Opprettelse av køer skjer automatisk ved at informasjon om aktuelle køer registreres i Adresseregister(AR), gjennom WebGUI eller API.
    • Server og adresse til køen bestemmes av den tilhørende kommunikasjonsparten i AR
    • Det skal ikke opprettes flere køer for en tjeneste enn de forretningsprosessen krever.
    • Det skal ikke opprettes køer for tjenester som ikke trenger køer.
    • Ved deaktivering i AR av virksomheter, tjenester eller personer så vil eventuelle køer også bli deaktivert for deretter å bli slettet. Klient/eier av køen må sørge for at de da ikke mister uleste meldinger.
    • Der det er mulig anbefales bruk av felles kø på virksomhetsnivå.
    • Viktig at man leser hyppig fra køene og holde dem tomme. Køene er designet for å bli konsumert raskt fra, og Tjenestebussen vil degradere hvis køene benyttes for lagring.
    • Kø kan bli sperret/deaktivert ved feil bruk (f.eks. ved «opphopning av meldinger») som ikke er hentet.
    • Køene er ikke designet for store vedlegg. Meldingene på kø skal være minst mulig og ikke større enn 1 Mb. Helsenorge er gitt unntak fra dette kravet og kan formidle noe større meldinger.

• • Abonnement på hendelser i Grunndata (Topic/Subscription)
    • Opprettelse og avslutning av abonnement gjøres gjennom API til Adresseregisteret i Grunndata
      • Aktør plikter å avslutte abonnementet dersom hendelser ikke lenger er ønsket
    • Også for abonnement er det sentralt at kø ikke brukes for lagring. Ha som mål at kø skal være tom.
    • Mottagende system må støtte at samme melding kan komme flere ganger. "atleast-one-delivery"
    • Meldinger kan bli fjernet fra Tjenestebuss ved opphopning.

Kryptering

• • Innholdskryptering:
    • Sensitiv informasjon (innhold) skal krypteres og signeres. Se krav i dokumentasjon til den underliggende forretningsprosessen.
    • Verdier i properties skal være ukryptert og skal derfor ikke inneholde sensitive data
  • Transportkryptering TLS er påkrevd
    Kun TLS 1.2 og 1.3 støttes

Feilhåndtering

• • En asynkron kø vil ha en tilhørende feilmeldingskø (deadletter) der meldinger kan havne om de ikke blir prosessert riktig av mottakeren. Det er opp til eieren av køen å sørge for å monitorere og håndtere feilmeldinger på riktig måte.
  • Dersom en melding feiler på grunn av feil oppsett ved publiseringen, så vil tjenestebussen prøve å sende disse til egen feilkø som avsender har ansvar for å følge opp.
  • Forretningsprosessen vil sikre pålitelig meldingsutveksling ved å stille krav til mekanismer for kvitteringer.

Anbefalt rutine for håndtering av dead-letter

• • Antall meldinger på dead-letter bør sjekkes jevnlig, for eksempel hver time
  • Man kan automatisk reprosessere meldingene som ligger der eller ha funksjonalitet for å manuelt starte reprosessering
  • De resterende meldingene som ikke går gjennom etter reprosessering må manuelt følges opp
  • Det må defineres hvem som har har ansvaret for oppfølging av dead-letter-køen
  • Den/de ansvarlige må tydeligvarsles om at det befinner seg meldinger på dead-letter