Krav på anropsresultat och felhantering


Detta krav beskriver hu anropsresultat och felhantering ska hanteras av anslutande system till Nationella läkemedelslistan.






Kravområden

Kravområde 1 – Returnera status och resultat på ett anrop

Variant 1.1 Ta emot meddelande om status på anrop

KRAV Krav-id: TK 1

Anslutande system ska ta emot HTTP-status och förmedla resultatet till klienten momentant, se även presentationskrav P17.

Möjliga statuskoder delas in i tre grupper i enlighet med HTTP-standarden:

  • 2xx Lyckad förfrågan. Förfrågan togs emot, förstods och accepterades.
  • 4xx Misslyckad förfrågan – Applikationsfel. Förfrågan har en felaktig syntax eller kan inte utföras/fullföljas.
  • 5xx Misslyckad förfrågan – Systemfel eller annat tekniskt fel. Servern misslyckades med att slutföra en till synes giltig förfrågan.

 Beroende på om anropet har accepterats eller avvisats, samt vilken information om anropets resultat som har efterfrågats (se variant 1.2)  returneras information enligt tabell 1 nedan.

Tabell 1.  HTTP attribut i anropsresultat

Attribut

Kommentar

HTTP-status

Status på anropet eller transaktionen. SSimplifier – ErrorHandling för mer information och lista över samtliga statuskoder.

HTTP response header

Består bland annat av X-Request-ID och en Location som returnerar adressen till skapad resurs (URL). För mer information om FHIR and REST, se Simplifier – FHIR and REST

HTTP body

Returnerad resurs (information) som svar på ett anrop. Innehåller olika mängd information beroende på vad som efterfrågats vid anropet.

Varianter:

  1. Representation
    • Om anropet accepteras returneras uppdaterad eller skapad resurs.
    • Om anropet accepteras med varningar returneras uppdaterad eller skapad resurs med en detectedIssue inbäddad i resursen
    • Om anropet misslyckas returneras bara OperationOutcome
  2. OperationOutcome
    • Kan returneras för att informera både om lyckade och misslyckade anrop. Om anropet misslyckas returneras alltid en OperationOutcome
  3. Minimal
    • Om anropet lyckas så är HTTP body tom
    • Om anropet misslyckas returneras OperationOutcome.

Variant 1.2 Styra vilken information som ska returneras vid skapad eller förändrad resurs

KRAV Krav-ID: TK 2

Vid anrop till Nationella läkemedelslistan som innebär att en resurs skapas eller förändras finns det möjlighet att via header-parameter i anropet styra om svaret som ges från FHIR vid lyckad skapad eller uppdaterad resurs.

När en resurs skapas eller förändras finns det vissa attribut som anropande system inte kan förändra som antingen:

  • Automatiskt kompletteras när resurs skapas eller uppdateras
  • Beräknas vid läsning av resursen.

För att anropande system ska kunna visa upp resultatet av anropet till användaren kan man välja att svaret ska innehålla hela resursen, inklusive de uträknade och kompletterade fälten.

Endast resurser som anges i anropet, vid skapande eller förändring, kan returneras. Exempelvis returneras endast den nya förskrivningen vid händelsen Förnya förskrivning. Den befintliga förskrivningen, som också förändras genom att automatiskt ändra status till avslutad, returneras alltså inte. På samma sätt returneras inte förskrivningsresursen när ett nytt uttag registreras, även om förskrivningen därmed ändrar status till slutexpedierad.

I FHIR är det valfritt för anropande system att ange vad som ska returneras enligt ovan. Detta styrs via header-paramentern return-header. NLL stödjer att anropande system väljer ett av tre alternativ för hur mycket information som ska returneras vid ett anrop via FHIR. Dessa är: Representation, Operation Outcome samt Minimal. I tabell 2 beskrivs vilka informationsmängder som returneras vid respektive angivna return-header, se även scenarion i Kapitel 3. 

Tabell 2.  Header parametern



Information som returneras vid anrop

Angivet i header-parameter
  1. Representation

2. OperationOutcome

3. Minimal (Default) 1)
Prefer: return=representation

Prefer: return=OperationOutcome

Prefer: return=minimal
Status på anropet (HTTP-status)xxx
Eventuella fel och varningar (HTTP body)xx-
Referens till skapad resurs (location)-xx
Fullständig skapad eller ändrad resurs (HTTP body)x--

1) För skapa och ändra förskrivning får default värdet minimal inte användas, eftersom eventuella AFF-Varningar ska visas upp för användaren enligt presentationskrav, Representation eller Operation Outcome behöver anges som prefer header för att anropet ska accepteras. Notera att vid ett avvisande fel returneras alltid en Operation Outcome.

Hantering av patient med skyddade personuppgifter

I de fall Hälso- och sjukvårdspersonal vid anrop till Nationella läkemedelslistan anger att en skapad eller rändrad resurs ska returneras genom att sätta return-header till "representation" för en patient som har skyddade personuppgifter enligt VR175 maskas information på resursen som returneras enligt VR176.

Kravområde 2 – Felhantering

Variant 2.1 Generella krav felhantering

Applikationsfel och systemfel  kan uppkomma i Nationella läkemedelslistans tjänster samt andra register som Nationella läkemedelslistan är integrerad med. Fel returneras via profilen NLLOperationOutcome, se kapitel 2. Hanterad information och  2.1 Resultat och felhantering. För mer detaljerad teknisk information om felhantering i Nationella läkemedelslistan, se Simplifier – ErrorHandling.  På förskrivning kan AFF-resultat ingå vid hämtning (inkluderad NLLDetectedIssue).

KRAV Krav-id: IK 15 

Tolkning av felmeddelande, se IK15 i Icke-funktionella krav

KRAV Krav-id TK 10

System ska kunna hantera att nya felkoder tillkommer utan att anslutande system slutar fungera. Kravet omfattar enbart ändringar som  inte påverkar tjänstegränssnittet. Exempel på det kan vara en ny AFF-kontroll eller verkssamhetsregel.

KRAV Krav-id TK 11
System ska kunna hantera att feltexter ändras vid behov i samband med release, se även TA 34 hämta värdemängder och kodrelationer.

Variant 2.2 Systemfel, SYSTEM ERROR 

Systemfel är fel som inte kan åtgärdas av tjänstekonsumenten/användaren. Systemfel returneras med en HTTP status som börjar på 5XX.
De felkoder och felmeddelanden som kan förekomma är beskrivna i kodverket föfhir-error-codes i Simplifier.

KRAV Krav-id: TK 12
Systemfel ska tas emot och hanteras av mottagande system. Om felet påverkar handläggning ska slutanvändaren uppmärksammas att ett fel har inträffat enligt presentationskrav P17.

Variant 2.3 Applikationsfel, APPLICATION ERROR

Applikationsfel kan förutsägas och i många fall åtgärdas av tjänstekonsumenten/användaren, applikationsfel returneras med en HTTP status som börjar på 4XX. 

De felkoder och felmeddelanden som kan förekomma är beskrivna i fhir-error-codes och aff-codes i Simplifier

KRAV Krav-id: TK 3
Applikationsfel ska tas emot och hanteras av mottagande system och visas upp för användaren enligt presentationskrav P17 och P19.

Variant 2.4 Applikationsfel, AFF-resultat

Automatisk format- och författningskontroll (AFF-kontroller) består av ett flertal olika kontrollpunkter som var och en kontrollerar innehållet i en förskrivning eller på ett uttag. Varje AFF-kontroll har en unik AFF-felkod och ingår i en eller flera kontrollsamlingar vilket beskrivs i Automatiska format- och författningskontroller (AFF-kontroller). 

Om fel eller varningar förekommer i en kontrollsamling returneras AFF-resultat i en Operation Outcome som innehåller en eller flera fel (issues).

  • Den första posten innehåller felkod 2-26-16,"Avvikelse enligt automatisk format- och författningskontroll", där  allvarlighetsgraden återspeglar AFF-status för kontrollsamlingen.
  • Efterkommande poster, en för varje fel (issues) innehåller en Detected issue med information om AFF-felet.
  • Vid kontroll av flera uttag i en expediering identifieras det unika uttaget via aktörens expeditions-id samt i fältet expression som pekar på vilken post i den inskickade expedieringen (Bundle) som felet uppkom i.

AFF-fel har allvarlighetsgrad varning (INFORMATION) eller avvisande (ERROR). Det AFF-fel med den högsta allvarlighetsgraden styr vilken AFF-status som returneras och om anropet ska avvisas eller inte enligt tabell 3 nedan.

Tabell 3. Allvarlighetsgrader för AFF resultat

Allvarlighetsgrad

Förskrivning

Uttag

NULL= Accepterad

Inga avvisande fel eller varningar förekommer, anropet har godkänts, resursen sparas eller uppdateras.

  • HTTP Status 200, returneras när en förskrivningsresurs uppdateras
  • HTTP Status 201, returneras när en förskrivningsresurs skapas

Inga fel eller varningar förekommer och anropet har godkänts uttag/uttagen sparas

  • HTTP Status 201 returneras när en uttagsresurs skapas

WARNING= Accepterad med varning

Inga avvisande fel förekommer, men det finns minst en varning. Anropet accepteras och resursen sparas,  uppdateras eller hämtas
  • HTTP Status 200, returneras när en förskrivningsresurs uppdateras eller hämtas
  • HTTP Status 201, returneras när en förskrivningsresurs skapas
n/a
ERROR = Avvisad

Anropet avvisas och förskrivningen sparas eller uppdateras inte

HTTP Status 422, returneras när anropet avvisas för en förskrivningsresurs

Anropet avvisas om det på en uttagsresurs förekommer minst ett avvisande fel eller varning på något av uttagen i expedieringen, inga uttag skapas

HTTP Status 422 , returneras när anropet avvisas för en uttagsresurs.


KRAV Krav-id: TK 5 
Om en befintlig förskrivning som hämtas innehåller varningar ska användaren uppmärksammas på att varningar finns som kan kräva åtgärd. Varningar ska kunna presenteras för användaren på användarens begäran enligt presentationskrav  P19.

Variant 2.5 Applikationsfel – Accepterade varningar

AFF-varningar på ett uttag åtgärdas genom att expedierande apotekspersonal ändrar information i sin expediering, eller uppdaterar förskrivningen så att varning inte uppkommer igen. Ett annat alternativ är att välja att acceptera varningen genom att markera vilka varningar som accepteras för respektive uttag.

REKOMMENDATION Om en varning accepteras är rekommendationen att ange orsaken till detta i uttagskommentaren. 

KRAV Krav-id: TK 6
Funktionalitet för att kunna acceptera uppkomna AFF-varningar vid händelsetyperna Expediera och Efterregistrera uttag ska implementeras. Varningarna ska presenteras enligt presentationskrav P17 och användaren måste acceptera varningarna eller åtgärda dem för att expediering ska kunna utföras.

Variant 2.6 Systemfel – Omsändning och dubblettkontroll

Omsändning definieras här som ett anrop från anslutande system till Nationella läkemedelslistan där svar uteblir (exempelvis på grund av timeout vid oplanerad nertid) och där det är oklart om anropet mottogs och bearbetades i Nationella läkemedelslistan. I dessa fall kan en omsändning av samma anrop behöva ske igen. Nationella läkemedelslistan har stöd för att upptäcka dubbletter om de uppstår. Dubbletthantering baseras på att en unik identifierare (UUID) skickas med vid alla skapa och uppdatera operationer mot Nationella läkemedelslistan. Vid omsändning av anropet från anslutande system måste samma unika identifierare användas.

För unika anrop måste Anrops-id skickas med och vara ett nytt unikt Id (enligt Informationsspecifikation – meddelandehuvud och GK1 enligt Spårbarhetskrav). Anrop som görs med avsikten att vara ett nytt försök av ett tidigare anrop (omsändning) är inte unika och därför måste Anrops-id från tidigare anropsförsök återanvändas. Anrops-id används dels för spårning och loggning (enligt Spårbarhetskrav) och dels för dubbletthantering. Kravställning på hantering av Anrops-id vid anrop eller omsändning är därför generell och gäller samtliga anrop där säkerhetsintyg krävs. Inkomna Anrops-id lagras för relevanta anropstyper (de anropstyper där dubbletthantering tillämpas) i Nationella läkemedelslistan och dess unikhet fastställs genom en kontroll (VR102 enligt Generella verksamhetsregler) då anropet behandlas. Då ett anrop inkommer där dubblettkontroll slår till ges svar med HTTP felkod 409 Conflict.  Listan med använda Anrops-id gallras dagligen efter minst 96 timmar.

KRAV Krav-id: TK 8

Anrops-id för omsända anrop. För omsändningar av anrop ska parameter Anrops-id i meddelandehuvud återanvändas (samma UUID som vid tidigare försök ska användas).

KRAV Krav-id: TK 9

Väntetid innan nytt försök av hämta-anrop. För att göra en omsändning/nytt försök av ett anrop måste minst 2 sekunder förlöpa innan nytt försök görs.

Hanterad information

I tabell 4 listas de informationsresurser, FHIR-resurser och FHIR-profiler som används. Se Generell beskrivning av FHIR för en mer generell beskrivning av FHIR-resurser och FHIR-profiler i Nationella läkemedelslistan.

Tabell 4. Informationsresurser

Informationsresurs

FHIR-Resurs

FHIR-Profil

Resultat och felhanteringOperationOutcome

NLLOperationOutcome

AFF fel och varningar

DetectedIssue

NLLDetectedIssue

Anropssvar - Meddelandehuvud/HTTP Response header

Se Informationsspecifikation – meddelandehuvud kapitel 3 Termer i Meddelandehuvud för anropssvar/HTTP Response header.

Beskriver vilken information som returneras i meddelandehuvdet vid ett anropssvar samt hur den kan tillämpas. 

Informationsresurs Resultat och felhantering

Se informationsspecifikation Resultat och felhantering – NLLOperationOutcome.  I tabell 5 listas den information i Resultat och felhantering  som tillämpas

Tabell 5. Informationsresurs Resultat och felhantering

Term

Kodat värde i FHIR

Kommentar

ResultatStrukturelement, ett per iteration

Returneras alltid

Allvarlighetsgrad

WARNING eller ERROR

Returneras alltid

ERROR för fel som är avvisande och hindrar att resurs skapas eller uppdateras.
WARNING , för varningar som inte hindrar att resursen skapas eller uppdateras.

Typ av resultat

Enligt kodverk

Returneras alltid

Felorsak

Struktur

Används inte för alla typer av fel, för mer info se Simplifier – ErrorHandling

Fel

Behållare för detaljerad felinformation om fel

Returneras alltid om felorsak används

Felkod


Returneras alltid om felorsak används

Felmeddelande


Returneras alltid om felorsak används

Feldiagnostik



AFF-fel



Inbäddad resurs se, AFF-fel och varningar – NLLDetectedIssue.

Returneras om det finns AFF-fel

Om flera uttag hanteras i en transaktion returneras en NLLDetectedIssue per uttag som det förekommer fel i.

Felkälla


Används för att precisera i vilken resurs felet uppkom.

Informationsresurs AFF-fel och varningar 

AFF-fel och varningar returneras alltid som inbäddad resurs i OperationOutcome, MedicationRequest eller MedicationDispense. Se informationsspecifikation AFF-fel och varningar – NLLDetectedIssueI tabell 6 nedan beskrivs tre olika scenarion för hur AFF fel och varningar hanteras.

Tabell 6. Informationsresurs AFF-fel och varningar

Term 

Kodat värde i FHIR

Felhantering – OperationOutcome
Scenario 1 – AFF-resultat 

Förskrivning – Medication Request Scenario 2 – Visa varningar på en förskrivning

Uttag – MedicationDispense

Scenario 3 – Acceptera varningar

Aktörens Expeditionsradnummer
  • Definiera vilket av uttagen i expeditionen fel avser. Gäller för kontrollsamlingarna AFF-EXP, AFF-KEX och AFF-ERU
  • Inget värde returneras för övriga kontrollsamlingar

n/a

Definierar i vilket uttag en varning accepterats. Kan användas i AFF-EXP och AFF-ERU

Status på avvikelse

PRELIMINARY

Obligatorisk

Obligatorisk

Kompletteras med
"Preliminary"

AFF-resultat





AFF-felkod


Obligatorisk

Obligatorisk

Obligatoriskt.

Enbart AFF-kontroller med allvarlighetsgrad 1=Varning, kan accepteras, övriga AFF koder ignoreras.

AFF-felmeddelande


Obligatorisk

ObligatoriskIgnoreras

Allvarlighetsgrad


Obligatorisk

ObligatoriskIgnoreras
Kontrolltidpunkt

Obligatorisk

Obligatorisk

Ignoreras

Scenario 1 – AFF-resultat

Resursen beskriver AFF-resultat, det vill säga AFF-fel och AFF-varningar som har uppkommit i samband med att en kontrollsamling utförs

  • när en förskrivning skapas eller uppdateras
  • när ett eller flera uttag expedieras.

Hur resultatet returneras beskrivs i tabell 7 nedan. Hur resultat returneras är beroende av vad som är angivet i Response header (se variant 1.2 ovan).

Tabell 7. Scenario 1 - AFF-resultat

Resurs

Prefer header

Kommentar

MedicationRequestMinimal
  • Om anropet accepteras returneras enbart status
  • Om anropet accepteras med varningar kommer ett fel returneras eftersom Minimal inte får anges som response header för förskrivningsresursen
  • Om anropet misslyckas och innehåller något avvisande AFF-fel returneras OperationOutcome
MedicationDispenseMinimal
  • Om anropet accepteras returneras enbart status
  • Om anropet misslyckas och innehåller något avvisande AFF-fel  eller varning returneras OperationOutcome.

MedicationRequest 


Operation Outcome
  • Om anropet accepteras utan AFF-Varningar så returneras enbart status
  • Om anropet accepteras men AFF-Varningar returneras OperationOutcome.
  • Om anropet misslyckas returneras en OperationOutcome.

Notera! Att en förskrivning kan skapas eller uppdateras med varning.

MedicationDispenseOperation Outcome
  • Om anropet accepteras returneras enbart status
  • Om anropet misslyckas returneras OperationOutcome.

Notera! För uttag så accepteras inte anropet om det innehåller varningar som inte har accepterats av Farmaceut i anropet.

MedicationRequest

Representation
  • Om anropet accepteras returneras den uppdaterade versionen av resursen
  • Om anropet accepteras med varningar returneras MedicationRequest med de AFF-varningar som uppkom när resursen skapades eller uppdaterades
  • Om anropet misslyckas returneras OperationOutcome
MedicationDispenseRepresentation
  • Om anropet accepteras returneras den skapade resursen
  • Om anropet misslyckas returneras OperationOutcome

Scenario 2 – Visa varningar på en förskrivning

På en förskrivning används resursen (Detected Issue) för att visa vilka AFF-varningar som finns när förskrivningen hämtas. Vilka varningar som kan förekomma när en förskrivning hämtas är definierade i kontrollsamlingen för AFF-LÄS, för mer info se Automatiska format- och författningskontroller (AFF-kontroller)

Scenario 3 – Acceptera varningar

Vid en expediering kan man för varje uttag ange om en uppkommen varning accepterats av farmaceut.

Scenario 4 - Avbruten kontroll

Kan en AFF-kontroll inte genomföras i sin helhet (t.ex. om ett nödvändigt bakomliggande register inte är tillgängligt) rapporteras det till anropande system.  Om AFF kontroll avser en varning (allvarlighetsgrad = 1) går anropet igenom utan att varning returneras. Om anropet avser en avvisning (allvarlighetsgrad = 2) avvisas anropet och AFF-felet returneras

Presentationskrav

Se Generella presentationskrav för anslutande aktör och system, krav P17 och P19.



Versionshistorik

VersionDatumKommentar
1.02021-11-27Ny handbok vård- och apotekstjänster
1.12022-03-30
  • Förtydligat hur anrops-id gallras i Variant 2.6 Systemfel – Omsändning/dubblettkontroll
  • Förtydligat variant 2.4 Applikationsfel, AFF-resultat. 
  • Språkliga rättningar för bättre läsbarhet
1.2 2020-05-27
  • Under 1.2  Generell Felhantering och Variant 2.4 Applikationsfel, AFF-resultat. Förtydligat att AFF-resultat kan ingå vid hämtning av förskrivning
  • Språkliga förbättringar och förtydliganden
1.32022-11-10

I variant 1.2 Styra vilken information som ska returneras vid skapad eller förändrad resurs. Lagt till kapitel om Hantering av patient med skyddade personuppgifter.

1.42023-05-04

Förtydligat krav

  • Krav-id: TK 3 flyttad flyttat till Variant 2.3 Applikationsfel, APPLICATION ERROR. Lydelse ändrad till  Applikationsfel ska tas emot och hanteras av mottagande system och visas upp för användaren enligt presentationskrav P17 och P19.

Förbättringar dokumentation

  • Lagt till symboler för krav.
  • Språkliga förbättringar för bättre läsbarhet
1.52023-11-09

Förbättringar dokumentation

  • Under tabell 2, förtydligat att en Operation Outcome alltid returneras vid ett avvisande fel.
  • Tabell 3, rättat fel avseende vilken HTTP status som returneras för ett avvisat uttag.
  • Lagt till kapitel 2.1 Anropssvar - Meddelandehuvud/HTTP Response header
  • Förtydligat ingress
1.62024-02-22

Lagt till kapitel 2.3.4 , Scenario 4 - Avbruten kontroll