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. Se Simplifier – 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:
|
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 | ||
---|---|---|---|
| 2. OperationOutcome | 3. Minimal (Default) 1) | |
Prefer: return=representation | Prefer: return=OperationOutcome | Prefer: return=minimal | |
Status på anropet (HTTP-status) | x | x | x |
Eventuella fel och varningar (HTTP body) | x | x | - |
Referens till skapad resurs (location) | - | x | x |
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 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.
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ö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.
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.
| Inga fel eller varningar förekommer och anropet har godkänts uttag/uttagen sparas
|
WARNING= Accepterad med varning | Inga avvisande fel förekommer, men det finns minst en varning. Anropet accepteras och resursen sparas, uppdateras eller hämtas
| 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 felhantering | OperationOutcome | 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 |
---|---|---|
Resultat | Strukturelement, 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. |
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 – NLLDetectedIssue. I 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 | Förskrivning – Medication Request Scenario 2 – Visa varningar på en förskrivning | Uttag – MedicationDispense Scenario 3 – Acceptera varningar |
---|---|---|---|---|
Aktörens Expeditionsradnummer |
| 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 |
AFF-resultat | ||||
AFF-felkod | Obligatorisk | Obligatorisk | Obligatoriskt. Enbart AFF-kontroller med allvarlighetsgrad 1=Varning, kan accepteras, övriga AFF koder ignoreras. | |
AFF-felmeddelande | Obligatorisk | Obligatorisk | Ignoreras | |
Allvarlighetsgrad | Obligatorisk | Obligatorisk | Ignoreras | |
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 |
---|---|---|
MedicationRequest | Minimal |
|
MedicationDispense | Minimal |
|
MedicationRequest | Operation Outcome |
Notera! Att en förskrivning kan skapas eller uppdateras med varning. |
MedicationDispense | Operation Outcome |
Notera! För uttag så accepteras inte anropet om det innehåller varningar som inte har accepterats av Farmaceut i anropet. |
MedicationRequest | Representation |
|
MedicationDispense | Representation |
|
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
Version | Datum | Kommentar |
---|---|---|
1.0 | 2021-11-27 | Ny handbok vård- och apotekstjänster |
1.1 | 2022-03-30 |
|
1.2 | 2020-05-27 |
|
1.3 | 2022-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.4 | 2023-05-04 | Förtydligat krav
Förbättringar dokumentation
|
1.5 | 2023-11-09 | Förbättringar dokumentation
|
1.6 | 2024-02-22 | Lagt till kapitel 2.3.4 , Scenario 4 - Avbruten kontroll |