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

1. Kravområden

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

1.1.1. 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

1.1.2. 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

^{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.}

1.1.2.1. 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 fö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.

1.2. Kravområde 2 – Felhantering

1.2.1. 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.

1.2.2. 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ör 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.

1.2.3. 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.

1.2.4. 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

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.

1.2.5. 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.

1.2.6. 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. I händelse av att omsändning av förfrågan behöver göras 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.

2. 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

2.1. 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. 

2.2. 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

2.3. 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 – NLLDetectedIssue. I tabell 6 nedan beskrivs tre olika scenarion för hur AFF fel och varningar hanteras.

Tabell 6. Informationsresurs AFF-fel och varningar

2.3.1. 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

2.3.2. 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)

2.3.3. Scenario 3 – Acceptera varningar

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

2.3.4. 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

3. Presentationskrav

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

Versionshistorik