AMQP Profil

Innledning

Dette dokumentet inneholder spesifikasjon av meldingsutveksling med helsenorge.no basert på den internasjonale standarden AMQP. Dokumentet etablerer en profil for bruk av AMQP og spesifiserer krav til feilhåndtering.

Meldingsutveksling helsenorge.no

Helsenorge.no inneholder tjenester rettet mot alle innbyggere. Ambisjonen er å gjøre innbyggernes hverdag enklere med digitale tjenester tilpasset alle deler av helse- og omsorgsektoren.

For å sende meldinger benyttes den åpne, internasjonale standarden AMQP som transportprotokoll. Norsk Helsenett (NHN) har etablert en Tjenestebuss som er tilgjengelig for alle virksomheter tilknyttet Norsk Helsenett.

I noen tilfeller benyttes også meldingsutveksling for å tilby synkrone tjenester. I utgangspunktet bør dette løses av mekanismer for datadeling, men av sikkerhetsmessige og historiske grunner har integrasjon via meldingsutveksling vært mest hensiktsmessig.

Eksempel flyt meldingsutveksling

Sekvensdiagram for et eksempel av asynkron tjeneste er vist i figuren under:

Sekvensdiagram for et eksempel av synkron tjeneste er vist i figuren under.

AMQP Meldingsutveksling

Ved innføring av Digital Dialog fastlege, var det behov for en mekanisme for synkron meldingsutveksling. Synkrone meldinger er ikke godt støttet med standard for meldingsutveksling basert på SMTP og ebXML. Bruk av AMQP ble derfor pilotert, og benyttes som transportprotokoll mot http://helsenorge.no.

Meldingsutveksling via AMQP er vist på figuren under med lignende notasjon som i standard for meldingsutveksling:

Dette kapittelet beskriver AMQP profil som er utarbeidet og feilhåndtering som benyttes ved utveksling av meldinger.

AMQP Profil

En AMQP melding består av «Bare message» som er meldingen generert av avsender. Denne er «immutable», dvs. det verken kan eller vil ikke skje endring fra den er sendt til den er levert.

«Annotated message» inneholder tilleggsinformasjon for å transportere meldingen korrekt frem til mottaker.

«Bare message» består av:

  • Application data: Selve innholdet i meldingen, dvs. fagmeldingen

  • Properties: Liste over predefinerte nøkler og deres verdier (dersom de er satt). Eks. «reply-to» eller «subject».

  • Application properties: Egendefinerte nøkler og deres verdier. Eks. “cpa-id”. Alle er av typen String

De øvrige elementene er:

Videreføring av prinsipper og funksjonalitet i ebXML/ebMS

ebXML rammeverket benyttes i dag for håndtering av:

  • Trygghet for at meldingen kommer fram ved bruk av transportkvitteringer

  • Sikkerhet. SMTP som protokoll har svært lite innebygget sikkerhet

Med AMQP-protokollen eksisterer det en struktur som er egnet for å håndtere de standardiserte feltene og verdiene som benyttes i ebMS V2. Bruk av ebMS sammen med AMQP vurderes som lite hensiktsmessig og gir et ekstra lag med innkapsling som tilfører lite verdi.

ebXML-transportkvittering (ebXML Acknowledgment) er håndtert ved følgende funksjonalitet i AMQP og krav til kommunikasjonsparametre i Tjenestebussen:

  • Avsender kan kun skrive til Tjenestebuss som eksisterer og er tilgjengelig

  • Positiv bekreftelse på at skriving til Tjenestebuss er OK

  • Sendingsforsøket feiler dersom Tjenestebuss er utilgjengelig

  • Krav til bruk av kommunikasjonsparametre (CPP og CPA), mottager har aktivt valgt å støtte en kommunikasjonsprosess.

Feilmelding (ebXML Error Signal) er håndtert ved følgende funksjonalitet i AMQP (avsnitt 2.2 i AMQP spesifikasjon)

  • Transaksjonsbasert lesing av køen med støtte for å bekrefte at lesing og behandling av melding har gått bra før den slettes fra køen.

  • Leseoperasjon der transaksjonen ikke avsluttes, vil resultere i at meldingen etter 10 forsøk havner på mottagers Deadletter kø

  • Bruk av Error-kø der mottager sender en feilmelding som inneholder feilkode og en feilstatus, samt referanse til den opprinnelige meldingen

  • Krav til prosesser og rutiner for håndtering av error og deadletterkø

Applikasjonskvittering benyttes for å kvittere positivt eller negativt på selve fagmeldingen.

Med AMQP som protokoll er det også full sporbarhet av meldinger, slik at NHN som driftsleverandør kan identifisere status for en melding, hvem som har skrevet melding og hvem som eventuelt har mottatt og tatt melding fra kø.

Ansvarsoverdragelse for behandling av melding

AMQP følger retningslinjer beskrevet i "Veiledning til riktig bruk av Applikasjonskvittering" (HISD 1168:2016)

Det er er definert at ansvaret for behandling av melding overføres ved mottak av positiv applikasjonskvittering:

«Applikasjonskvittering brukes for å bekrefte eller avkrefte om en fagmelding har kommet korrekt fram til fagsystemet. Når positiv applikasjonskvittering er mottatt, skal avsender av fagmeldingen kunne være sikker på at fagmeldingen er kommet frem, at innholdet er i rett format, og at meldingen er klar for behandling i mottakers fagsystem. Det betyr således at mottaker har overtatt ansvaret for den videre behandlingen av fagmeldingen. Applikasjonskvitteringen er derfor avgjørende for tilliten til den elektroniske samhandlingen.»

Dette betyr også at det er avsender sitt ansvar å følge opp en sendt melding helt til en får en positiv applikasjonskvittering.

For synkrone tjenester som ikke benytter applikasjonskvittering, overdras ikke ansvaret til mottager av meldingen.

AMQP attributter

AMQP versjon 1.0 (OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0) skal benyttes i henhold til profilen under.

Bokstavkodene for kolonnen Required/optional betyr følgende:

  • R = Feltet er påkrevd i alle sammenhenger når det sendes en AMQP-melding

  • R2 = Feltet er kun påkrevd når AMQP-meldingen brukes for å melde transportfeil

  • O = Feltet er valgfritt og skal kun brukes i henhold til beskrivelsen av feltet

  • O2 = Feltet er valgfritt og skal kun brukes når AMQP-meldingen brukes for å melde transportfeil og i henhold til beskrivelsen av feltet

Application properties er utvidet med attributter fra SOAP:Header i ebXML for å sikre at meldingsutveksling foregår på riktig måte og støtter bruk av kommunikasjonsparametre.

AMQP-blokk

Required/ Optional

Felt

Innhold

AMQP-blokk

Required/ Optional

Felt

Innhold

Properties

R

messageId

Unik id på UUID-format, overført som type String.

messageId identifiserer en AMQP melding unikt og er uavhengig av eventuell meldingsId for fagmeldingen som sendes.

R

To

Id for kø-en meldingen skal sendes til (f.eks. _sync).

Det skal oppgis full id slik den er registrert i Adresseregisteret.

R

Subject

Angir meldingsinnhold med kodeverdi fra kodeverk 8279 «Meldingens funksjon»: se Volven

R

replyTo

Id for kø-en returmelding skal sendes til (f.eks. _sync). Det skal oppgis full id slik den er registrert i Adresseregisteret.

R

correlationId

Unik id for et sett av transaksjoner som hører sammen. ID på UUID-format.

Attributtet benyttes for synkrone meldinger, for å knytte svarmelding til forespørsel. Overføres som type String.

R

contentType

Settes til verdien:

  • Signert og kryptert innehold: «application/pkcs7-mime; smimetype=signed-and-enveloped-data»

O

absoluteExpiryTime

Ikke angitt per melding. Kø har default time to live på 10 dager

Application Properties

R

cpaId

Id for CPA-avtale, overføres som type String.

R

applicationTimeStamp

Tidsstempel for generering av AMQPmeldingen. Formatet skal være i henhold til ISO 8601 (CCYY-MM-ddThh:mm:ssTZD).

Tidspunkt skal oppgis i UTC. Dersom lokal tid benyttes skal tidssone angis.

Eksempel: 2014-02-26T12:45:32+02:00.

R

fromHerId

HER-id for avsender

R

toHerId

HER-id til mottaker

R2

originalMessageId

Feltet skal inneholde messageId fra den meldingen som AMQP-transportfeilmeldingen gjelder for. Overføres som type String

R2

receiverTimeStamp

Tidsstempel for når mottaker prøvde å behandle den meldingen som feilet.

R2

errorCondition

Lesbar og maskinlesbar kode som beskriver feilårsak

R2

errorDescription

Lesbar tekst som beskriver feilårsaken

Applicationdata

R

 

Den krypterte fagmeldingen (tilsvarende «Payload» i ebMS) plasseres direkte i «Application Data» uten noen form for MIMEencoding/konvertering. Dvs. at en skriver/leser de krypterte dataene til/fra AMQP-meldingen på samme måte som om en skriver til/fra en fil (dataene er en byte-array, byte[]).

AMQP Køoppsett

Køer administeres ved hjelp av funksjoner i Adresseregisteret. Behovene til den enkelte virksomhet og tjeneste, sammen med kravene i de aktuelle forretningsprosessene, bestemmer hvilke køer som trengs.

Følgende køer benyttes av helsenorge ved meldingsutveksling via AMQP

  • Async: Brukes ved asynkrone operasjoner. Time to Live (TTL) for async kø er satt til 10 dager

  • Sync: Brukes ved synkrone operasjoner. TTL er satt til 15 sekunder

  • Error: Brukes ved kjente feilsituasjoner, beskrevet i AMQP Feilhåndtering. TTL er satt til 10 dager

  • Deadletter: Innkommende meldinger rutes til deadletter-køen dersom mottaker forsøker å lese meldingen fra kø flere enn et definert antall ganger uten at transaksjonen avsluttes. TTL er satt til 10 dager

Det er etablert løsning for arving av køer fra virksomhet, for å redusere antall køer og forenkle drift og vedlikehold. Det er også mulig å sette opp en mal for nye tjenester, som gjør at disse automatisk får ønsket oppsett ved opprettelse.

Type køer og kønavn

Type kø

Kønavn

Kommentar

Type kø

Kønavn

Kommentar

Async

[her-id]_async

Asynkrone meldinger sendes over denne

Sync

[her-id]_sync

Synkrone forespørsler/meldinger sendes via denne køen

SyncReply

[her-id]_syncreply

Når man besvarer en synkron melding besvares denne til en SyncReply-kø. Denne skal denne alltid plukkes fra ReplyTo og ikke hardkodes

Error

[her-id]_error

Se utfyllende beskrivelse av error-køen i AMQP-spesifikasjonen

Deadletter

[her-id]_dl

Meldinger som deadletteres havner på denne køen. En melding deadletteres etter at den er forsøkt lest X antall ganger. X settes på brokeren-siden og er i dag satt til 10 forsøk.

Error-kø

Error-køen er en del av køoppsettet som er beskrevet i AMQP-spesfikasjonen for Helsenorge.no.

Formål

Formålet med error-køen er å varsle avsender om feil med meldingen på transportnivå.

Bruk

Error-køen skal kun benyttes for de feilsituasjoner beskrevet lenger ned i AMQP Feilhåndtering. Interne feil hos mottager, skal ikke rapporteres til avsender av melding.

Monitorering

Error-køen skal monitoreres slik at feilen kan rettes, og eventuelt gi sluttbruker beskjed om at en utgående melding har feilet hos motpart og at motparten derfor ikke kunne prosessere meldingen. Sluttbruker skal bli presentert med angitt årsak og mulighet til å resende meldingen etter at feilsituasjon er rettet.

Deadletter-kø

Alle køer har en sekundær sub-kø som kalles deadletter. Køen opprettes automatisk og kan ikke slettes eller på annen måte forvaltes uavhengig.

Formål

Formålet med deadletter-køen er å holde på innkommende meldinger som ikke kan prosesseres av mottaker på det gitte tidspunktet. Årsaken til at meldingen havner på deadletter kan være flere, men i hovedsak skal det dreie det seg om at ett eller flere bakenforliggende system er nede, nettverksbrudd eller uhåndterte feil.

Bruk

Meldinger som havner på deadletter-køen må analyseres for feilkilde. I noen tilfeller kan det være tilstrekkelig å reprosessere melding, dette gjelder ved midlertidige feil. I andre tilfeller vil det kreves en retting i meldingstjener for å behandle melding korrekt. Melding kan reprosesseres ved å legge melding tilbake på kø spesifisert i «to»-feltet i AMQP properties.

Monitorering

Deadletter-køen skal overvåkes slik at det gis anledning til å identifisere feilen og reprosessere disse meldingene etter at feilsituasjon er rettet.

Sertifikathåndtering

Meldingstjener anbefales å holde en lokal cache av sertifikater for systemoptimalisering.

Følgende skal valideres for sertifikater ved inngående og utgående meldinger:

  • Er innenfor gyldighetsperioden

  • Har korrekt bruksområde

    • Benytt OID verdi 2.5.29.15 - Key Usage for å kvalitetsikre bruksområdet til sertifikatet

  • Ikke er tilbakekalt/revokert ved å gjøre en Online Revocation Check

  • Dersom validering-serveren til sertifikatutsteder er nede skal operasjonen avbrytes og det kan forsøkes på nytt etter et egendefinert tidsrom.

Dersom validering av offentlige sertifikat feiler, skal cache invalideres og nye sertifikater hentes fra adresseregisteret. Meldingen skal beholdes, og dekryptering eller validering skal gjøres på nytt med det nye sertifikatet når dette er lastet ned og installert.

For løsninger som støtter parallelle sertifikater skal nyeste sertifikat benyttes som default. Dette for å gjøre overgang fra gammelt til nytt sertifikat så smidig som mulig og minimere risiko for feil ved utløp av gammelt sertifikat.

For meldingsutveksling ved AMQP benyttes kommunikasjonsparametre, der CPA angir hvilket sertifikat som er benyttet for kryptering og signering. Denne mekanismen vil håndtere sertifikatbytter på en smidig måte, uten behov for manuelle steg.

Kryptering og signering av fagmelding

Den krypterte og signerte fagmeldingen («Payload» i ebMS) plasseres direkte i AMQP Application Data uten noen form for MIME-encoding/konvertering. Dvs. at en skriver/leser de krypterte dataene til/fra AMQP-meldingen på samme måte som om en skriver til/fra en fil (dataene er en byte-array, byte[]). For signering benyttes «encapsulated data». Ved bruk av både signering og kryptering skal fagmeldingen først signeres og deretter krypteres. Cryptographic Message Syntax benyttes for signering og kryptering, og prosessen for dette er:

  1. Signerer fagmeldingen (encapsulated, ikke detached)

    1. Input er komplett fagmelding + virksomhetssertifikat med Key Usage = «Non-Repudation»

    2. Output er signert fagmelding

  2. Deretter kryptereres den signerte fagmeldingen

    1. Input er signert fagmelding fra pkt. 1b + virksomhetssertifikat med Key Usage = «Key Encipherment»

    2. Output er kryptert fagmelding

  3. Til sist opprettes en AMQP Message:

    1. ContentType = “application/pkcs7-mime; smime-type=signed-andenveloped-data”

    2. Body = Output fra 2b

Signering og kryptering benytter virksomhetssertifikater registrert i Adresseregisteret

Synkronisering av klokke

For sending og mottak av meldinger er det viktig og påkrevd at klokken på klienten er synkronisert med en sentral tidsserver. Dette kreves blant annet for:

  • Sikre at synkrone meldinger håndteres korrekt

  • Sikre at tidsstempel i fagmelding er riktige, disse brukes i noen tilfeller for sortering av meldinger

For synkronisering av klokker er det flere tilgjengelige tidsservere på internett og disse kan velges fritt. NHN tilbyr en tidstjener for applikasjoner på helsenett. Denne er vist i tabellen under.

Server

Beskrivelse

Server

Beskrivelse

Time.windows.com

Standard tidsserver for Windows, krever tilgang til internett

ntp.nhn.no

Tidsserver tilgjengelig på Helsenett

AMQP Feilhåndtering

Meldingsutveksling benytter følgende mekanismer for å ivareta leveringssikkerhet og at avsender får beskjed om feil som oppstår når mottaker henter ned en melding fra kø og prosesserer meldingen:

  • AMQP-Error: benyttes ved feilsituasjoner på transportnivå. Dette er feil som oppstår i forbindelse ved validering av sertifikater i signerings- og krypteringssammenheng, feil encoding på Payload eller manglende påkrevde felter på AMQP-konvolutt.

  • Negativ AppRec: brukes dersom fagmelding ikke kan tolkes eller behandles av mottakers system.

  • Fagmelding: Dersom fagmeldingen har passert validering og positiv AppRec er sendt, men det oppstår en situasjon som skal rapporteres tilbake til avsender som en feil svares det med en fagmelding.

  • Håndtering av manglende AppRec: Dersom avsender ikke mottar en AppRec etter en definert tidsperiode skal meldingen tolkes som å ha fått en negativ AppRec.

Håndtering av de ulike mekanismene er ytterligere detaljert i underavsnitt.

Prosess asynkrone tjenester

For asynkron kommunikasjon er prosessen for sending av meldinger, inkludert feilhåndteringsprosessen vist i figuren under.

Stegene i prosessen er kortfattet beskrevet i tabellen under.

#

Steg

Beskrivelse

#

Steg

Beskrivelse

1

Send fagmelding

Fagsystem oppretter melding, sendes til meldingstjener.

2

Send AMQP melding

Meldingstjener sender melding, legges på mottagers Async kø.

3

Les melding fra kø

Mottager meldingstjener leser melding fra kø

4

Valider AMQP melding

Melding valideres i henhold til beskrivelse lenger ned i “Validering av meldinger og håndterng av feil”. Dersom validering feiles skal melding sendes til avsenders Error kø

5

Send AMQP Error

Feil oppstått som følge av validering av AMQP melding og definert i “Validering av meldinger og håndterng av feil” skal sendes til AMQP Error kø. Andre interne feil eller andre feilkilder skal ikke føre til melding på Error kø.

6

Valider fagmelding

Fagmelding valideres i henhold til beskrivelse lenger ned i “Validering av meldinger og håndterng av feil”.

7

Persister i fagsystem

Dersom melding validerer OK, persisteres melding i fagsystem for videre behandling.

8

Send negativ apprec

Dersom fagmelding ikke valideres OK, sendes en negativ apprec til avsenders async kø

9

Commit lest melding

Melding commites fra kø når en av følgende er oppfylt:

  • Melding persistert OK i fagsystem

  • AMQP Error sendt

Hvis melding forsøkes lest 10 ganger uten at den commites vil den legges på Dead letter kø.

10

Send positiv apprec

Positiv apprec til avsenders Async kø

11

Håndter Dead letter kø

Mottager må ha en prosess for å håndtere Dead letter kø. Alle meldinger som forsøkes lest 10 ganger uten å bli commited vil legges på Dead letter kø.

Årsak til feil rettes og melding kan legges tilbake på async kø for prosessering.

12

Håndter Error kø

Prosess for å håndtere og rette opp meldinger som ikke validerer OK i henhold til spesifikasjon

13

Håndter Aprec

Prosess for å håndtere positive og negative Apprec.

14

Håndter manglende respons

Dersom avsender har skrevet melding til kø, men ikke fått feilmelding på error kø eller applikasjonskvittering må dette håndteres. Hvordan dette løses, er implementasjonsavhengig og kan variere fra virksomhet til virksomhet

Prosess synkrone tjenester

For synkron kommunikasjon er prosessen for meldingsutveksling inkludert feilhåndteringsprosessen vist i figuren under. Den største ulikheten på den asynkrone prosessen er at

  • Applikasjonskvittering benyttes ikke: det forventes en synkron og når sanntid respons fra mottager. Dersom denne responsen ikke kommer vil transaksjonen time ut hos avsender

  • Dead letter kø benyttes ikke, meldingen er ikke persistent og vil time ut fra kø.

Stegene i prosessen er kortfattet beskrevet i tabellen under.

#

Steg

Beskrivelse

#

Steg

Beskrivelse

1

Send melding

Avsender sender melding, legges på mottagers Async kø

2

Les melding fra kø

Mottager leser melding fra kø

3

Valider AMQP melding

Melding valideres i henhold til beskrivelse lenger ned i “Validering av meldinger og håndterng av feil”. Dersom validering feiles skal melding sendes til avsenders Error kø.

4

Send AMQP Error

Error Feil oppstått som følge av validering av AMQP melding og definert lenger ned i “Validering av meldinger og håndterng av feil” skal sendes til AMQP Error kø. Andre interne feil eller andre feilkilder skal ikke føre til melding på Error kø.

5

Valider fagmelding

Fagmelding valideres i henhold til beskrivelse lenger ned i “Validering av meldinger og håndterng av feil”

6

Fagsystem behandler melding

Dersom melding validerer OK behandles forespørsel og svarmelding opprettes.

7

Commit melding

Melding commites fra kø når en av følgende er oppfylt:

  • Svarmelding sendt

  • AMQP Error sendt

Hvis melding forsøkes lest 10 ganger uten at den commites vil den leggges på Dead letter kø.

For synkrone meldinger er time to live 15 sekunder, så Dead letter kø vil i praksis ikke benyttes.

8

Send svarmelding

Svarmelding sendes til avsender av melding. Svar inneholder enten svar på forespørsel eller en feilkode dersom melding ikke kunne tolkes eller håndteres.

9

Håndter Error kø

Prosess for å håndtere og rette opp meldinger som ikke validerer OK i henhold til spesifikasjon

10

Håndter svarmelding

Prosess for å håndtere svarmeldinger.

Validering av meldinger og håndtering av feil

Både AMQP-meldingen og fagmeldingen skal valideres av avsender før den sendes, og av mottaker før den prosesseres. Avsnittet beskriver minstekravene for validering av en melding og hvordan feil i validering skal håndteres.

Type

Validering

Håndtering av feil

Type

Validering

Håndtering av feil

AMQP melding

Verifisere verdiene for påkrevde felter. For å sikre at AMQP-meldinger inneholder påkrevde felter og verdier må det programmatisk gjøres en validering

AMQP-melding på Error-kø med errorCondition «transport:invalid-fieldvalue»

Kommunikasjonsprosessen er støttet, hentes fra CPA.

AMQP-melding på Error-kø med errorCondition «transport:unsupportedmessage»

Dekryptering feiler

AMQP-melding på Error-kø med errorCondtion «transport:decryptionfailed»

Avsenders sertifikat er utgått

AMQP-melding på Error-kø med errorCondition «transport:expiredcertificate»

Avsenders sertifikat er tilbaketrukket

AMQP-melding på Error-kø med errorCondition «transport:revokedcerificate»

Avsenders signatur kan ikke verifiseres

AMQP-melding på Error-kø med errorCondition «transport:invalidsignature»

Duplikat AMQP MessageID. AMQP melding har blitt sendt tidligere.

Melding logges av mottager, ingen respons på error kø og ingen apprec. Opprinnelig sendt melding forventes å gi apprec og meldingen skal ikke behandles en gang til av fagsystem.

Fagmelding header validerer ikke eller kan ikke tolkes.

AMQP-melding på Error-kø med errorCondition "transport:not-well-formedxml"

Replyto kø fins ikke

AMQP-melding på avsenders Error-kø med errorCondition «transport:invalidfield-value»

Ikke samsvar AMQP Avsender HER-Id <- > fagmelding Avsender HER-Id

AMQP-melding på Error-kø med errorCondition «abuse:spoofing-attack»

Fagmelding

Ikke samsvar AMQP mottager HER-Id <-> fagmelding mottager HER-Id

Negativ AppRec med kode «E10 Ugyldig meldingsidentifikator» fra kodeverk 8221.

Mottatt XML kan ikke tolkes

Negativ AppRec med kode «T01 – Ikke XML / ikke 'well formed' / uleselig» fra kodeverk 8221.

Krever at header i melding validerer og kan tolkes

XSD-validering

Negativ AppRec med kode «T02 – XML validerer ikke» fra kodeverk 8221.

Krever at header i melding validerer.

Validering av verdier for påkrevde felter feiler

Negativ Applikasjonskvittering med kode «T02 – XML validerer ikke» fra kodeverk 8221

Feilsituasjoner og håndtering av disse

Tabellen under viser noen mulige feilkilder og beskrivelse av hvordan de skal håndteres

Feilsituasjon

Håndtering av feilsituasjon

Feilsituasjon

Håndtering av feilsituasjon

Avsender mottar negativ AppRec

Avsender må manuelt følge opp mottatte feilkoder i AppRec og genere ny (feilfri) fagmelding og sende den. Resending av samme fagmelding skal ikke skje da dette forventes å føre til ny negativ AppRec.

Mottaker får ikke sendt AppRec i forbindelse med feil i sentral infrastruktur

Mottakers system sender automatisk AppRec på nytt etter et egendefinert tidsrom, eller gjør brukeren oppmerksom på feilsituasjonen med sentral infrastruktur slik at brukeren kan forsøke å generere/sende meldingen på nytt.

Avsender får ikke sendt melding i forbindelse med feil i sentral infrastruktur

Avsender sender melding på nytt automatisk etter et egendefinert tidsrom eller gjør brukeren oppmerksom på feilsituasjonen med sentral kø slik at brukeren kan forsøke å generere/sende meldingen på nytt.

Mottaker mottar samme fagmelding to ganger

Forkaste duplikat meldingen og sørge for at AppRec sendes kun én gang for forespørselen med tilsvarende fagmelding sin MsgId. En duplikat melding er en melding med samme verdi i MsgHead/MsgInfo/MsgId som en tidligere mottatt melding.

Avsender av fagmelding mottar ikke AppRec innen forventet tid

Forventet tid for mottak av apprec vil variere avhengig av bruken og hvilke aktører meldingen utveksles med. Helsenorge.no kan forventes å sende applikasjonskvittering innen et fåtall timer og normalt innen et fåtall minutter.

Avsender bør manuelt sjekke at melding er ok og kan sende melding på nytt. Ikke mottatt AppRec kan være feil hos mottaker og bør følges opp med mottaker for verifisering. Identisk fagmelding bør ikke resendes mer enn én gang.

NHN har sporbarhet på meldinger og overvåkning av køer og meldinger.

Helsenorge vil sende et varsel til innbygger om manglende kvittering etter et definert tidsrom. Denne funksjonen er nærmere beskrevet her:

Resending og id-er

Følgende retningslinjer gjelder for resending av meldinger og bruk av messageId på AMQP-nivå og MsgID fagmeldingen:

Situasjon

amqp:messageId

MsgHead/MsgInfo/MsgID

Situasjon

amqp:messageId

MsgHead/MsgInfo/MsgID

Systemet resender meldingen på nytt etter å ha mottatt en feil på AMQP Error-kø og rettet feil.

Ny

OriginalId

Systemet resender en melding etter å ha mottatt negativ AppRec og rettet feil.

Ny

Ny

Systemet resender en melding pga. at man ikke fikk lagt meldingen på køen (og derfor aldri har blitt behandlet av mottaker)

OriginalId

OriginalId

ebXML rammeverket beskriver resending av melding på grunn av manglende AppRec innen 96 timer. For synkrone meldinger benyttes ikke Apprec, men en svarmelding sendes med en gang. For asynkrone meldinger er heller ikke resending benyttet på AMQP av følgende årsaker:

  • Meldingsutveksling over AMQP forutsetter bruk av kommunikasjonsparametre (CPP/CPA). Avsender vet at melding støttes av mottager.

  • Meldingen er skrevet til Tjenestebuss. Avsender vet at melding er håndtert

  • Asynkrone meldinger blir håndtert på Tjenestebussen gjennom følgende mulige scenarier:

    • meldingen tas i mot og applikasjonskvittering vil sendes avsender

    • meldingen havner på avsenders Error kø, for oppfølging/håndtering der

    • meldingen havner på mottagers dead letter kø for oppfølging/håndtering der

  • Asynkron melding skal ikke fjernes fra aktuell kø før den er behandlet og applikasjonskvittering er sendt.

  • Avsender skal overvåke sin error kø og mottager skal overvåke sin dead letter kø.

Prosess for manglende respons beskrevet lenger opp under “Prosess asynkrone tjenester” benyttes i dette tilfellet.

Feilrapportering på AMQP Error-kø

Feilrapporteringen fra mottakers vil skje ved at det genereres en AMQP-melding (feilmelding) som kun består av properties og application properties med referanse til den mottatte meldingen og en oversikt eller liste som angir hvilke feil som er oppdaget. En slik melding vil ikke inneholde et forretningsdokument i form av en application data.

Ved feilrapportering skal AMQP-felter settes slik beskrevet i tabellen under:

Application Property

Beskrivelse

Application Property

Beskrivelse

amqp:messageId

Ny unik verdi

originalMessageId

Settes til opprinnelige amqp:messageId

receiverTimeStamp

Tidspunkt da meldingen ble forsøkt behandlet av mottaker

errorCondition

Lesbar og maskinlesbar kode som beskriver feilårsak. Se tabell under for detaljering.

errorDescription

Lesbar tekst som beskriver feilårsaken. Se tabell under for detaljering.

errorConditionData

Inneholder tilleggsdata i forbindelse med feilmelding. F.eks. i forbindelse med manglende påkrevde felter kan man gjengi manglende felter på en maskinlesbar måte.

Feilkoder og beskrivelser av disse er definert i tabellen under:

errorCondition

errorDescription

errorConditionData

errorCondition

errorDescription

errorConditionData

transport:invalid-cmspkcs

Could not decrypt message because of invalid format to CMS/PKCS.

 

transport:invalidcertificate

Could not decrypt message because of unknown/incorrect certificate

{ "thumbprint" : { "expected": "streng", "actual": "streng" } Thumbprint til sertifikater, for å lette feilsøking

transport:expiredcertificate

Could not decrypt message because of certificate expired.

Thumbprint til sertifikat, for å lette feilsøking

transport:revokedcertificate

Could not decrypt message because of certificate added to CRL (Certificate Revocation List).

Thumbprint til sertifikat, for å lette feilsøking

transport:decryptionfailed

Could not decrypt message because of unknown reason.

Thumbprint til sertifikat, for å lette feilsøking

transport:invalidsignature

Digital signature could not be verified.

Thumbprint til sertifikat, for å lette feilsøking

transport:requiredfield-missing

Missing or invalid value in field: 'AnyField'.

Array med navn på felter som mangler

transport:invalid-fieldvalue

Invalid value in field: 'AnyField'.

Array med navn på felter hvor verdier mangler eller ikke er satt riktig

transport:invalidencoding

Error occurred during decoding message. Expecting message encoded as ‘Unicode’.

En streng med IANA/MIME-navnet på encoding forventet http://www.iana.org/assignments/charactersets/character-sets.xhtml

abuse:spoofing-attack

Possible spoofing attack detected.

Array med to elementer { amqp:[herId], application:[herId] }

transport:xml-notinterpretable

XML cannot be interpreted

 

PKI-sjekkliste

Nedenfor er det vist sjekklister som kan brukes for PKI- og sertifikathåndtering ved sending og mottak for synkrone og asynkrone tjenester.

Asynkron, send melding

Asynkron, motta melding

Synkron, sende og motta melding

Synkron, hent og send melding

Henting av meldinger fra AMQP-kø

Som en generell retningslinje bør mottaker av en melding la meldinger være på AMQPkøen til den er behandlet og respons sendt (enten som apprec eller til error kø). Dette for å forhindre at meldinger «forsvinner» dersom en fjerner meldingen fra AMQP-køen og så skjer det en feil før meldingen er levert.