Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Beschrijving

In de interactie met de FHR REST API kunnen zich, naast de fouten die zich voordoen aan de serverzijde, er zich ook fouten voordoen bij de verwerking van de resources door de cliënt van de FHIR REST API. Het is van belang deze fouten te melden, omdat anders de infrastructuur ervan uit kan gaan dat het clientsysteem de informatie correct verwerkt heeft, of correct kan verwerken. De foutafhandeling door de client bestaat uit het aanmaken van een AuditEvent, hiermee maakt de applicatie duidelijk aan de andere applicaties en de beheerder van het domein dat er iets niet goed is gegaan. Het type AuditEvent maakt duidelijk wat er exact aan de hand is. Een applicatie kan een FHIR resource om verschillende redenen niet verwerken. Dit onderscheid is belangrijk, omdat sommige fouten verwacht kunnen zijn en geen aandacht van een beheerder vereisen, terwijl andere type fouten onverwacht zijn en aandacht vereisen.

...

Een  ander facet van foutafhandeling is of de fout herstelbaar is of niet. Een verwerkingsfout die voortkomt uit tijdelijke problemen in de infrastructuur kunnen hersteld worden door de resource op een ander moment opnieuw proberen te verwerken. Een fout die voortkomt uit een validatiefout of ontbrekend  ontbrekend veld kan niet hersteld worden door het opnieuw aanbieden van dezelfde resource. Daarnaast kan kan de resource herstelbaar zijn door bewerking, bijvoorbeeld door het ontbrekende veld toe te voegen  of een  veld te corrigerenversie van de resource

Informeren

Het doel van de foutafhandeling aan de kant van de cliënt van de FHIR resource service is informeren. De cliënt moet in staat zijn de andere applicaties in het domein ervan op de hoogte te stellen dat de applicatie de resource niet goed verwerkt heeft. Wat de applicatie hiermee doet bepaald koppeltaal niet. Mogelijk kan een EPD inzichtelijk maken dat een resource door een van de applicaties in het domein niet goed verwerkt is. 

...

Voor terugkoppeling van een foutstatus moet de applicatie een AuditEvent object aanmaken. Voor de correcte verwerking maken we gebruik van het `geen nieuws is goed nieuws` principe. Dit omdat de FHIR resource service reeds AuditEvents vastlegt, ook van de interacties met de cliënt.  Indien er een situatie zich voordoet waarbij de verwerking niet juist verloopt moet de applicatie een audit event aanmaken.

Anchor
error_types
error_types
Type fouten

In koppeltaal gaan we ervan uit dat er drie type fouten zich kunnen voordoen aan de zijde van de client. In het onderdeel 27131374 worden voorbeelden van deze type fouten gegeven. De drie type fouten zijn:

...

De applicatie kan een subsysteem niet benaderen. De applicatie kan de entiteit niet verwerken omdat bijvoorbeeld de database niet benaderbaar is. In dit geval kan een tijdelijke fout verzonden worden.

Anchor
mapping_auditevent
mapping_auditevent
De mapping van het AuditEvent

Het AuditEvent wordt volgens de tabel beneden gemapped. In de mapping doen we een aantal aannames die we uitteenzetten.

VeldnaamWaarde

extension.request-id

De waarde van de betrokken X-Request-Id veld.

extension.correlation-id

De waarde van de betrokken X-Correlation-Id veld.

extension.trace-id

De waarde van de betrokken X-Trace-Id veld.

type


Code Block
{
 "system": "http://terminology.hl7.org/CodeSystem/audit-event-type"
 "code": "rest"
}


subtype

Afhankelijk van het type actie die wordt uitgevoerd.

Code Block
{
 "system": "http://hl7.org/fhir/restful-interaction"
 "code": "read"
 "display": "read"
}


action

R (Afhankelijk van het type actie die wordt uitgevoerd)

recorded

Timestamp van vastlegging, bijvoorbeeld: 2024-02-05T12:06:13+0000

outcome.code

"Verwacht"

4

"Onverwacht"

8

outcomeDescEen door mensen te begrijpen foutmelding.

agent.who

De client_id van de eigen applicatie

Code Block
{
 "reference": "Device/<id|client_id>"
}


agent.type


Code Block
{
 "coding" : {
  "system": "http://dicom.nema.org/resources/ontology/DCM"
  "code": "110150"   
  "display": "Application"
 }
}


agent.requestor

true (Deze applicatie is de requester)

entity.what

Referentie naar de specifieke resource en versie, indien van toepassing.

Code Block
{
 "reference": "<ResourceType>/<id>/_history/<version>"
}

entity.name

Enkel als er geen entity.what van toepassing is.


entity.query

De betrokken query, indien van toepassing. De query wordt base64 geëncodeerd opgeslagen. 

source.site

Base URL van de applicatie waar het event wordt vastgelegd.

source.observer

De device reference van het device dat het event waarneemt, it dit geval de applicatie die het event aanmaakt.

Code Block
{
 "reference": "Device/<id|client_id>"
}


...

De verschillende type fouten worden gemapped door middel van twee velden. De type en outcome. De data error wordt als een validate type weergegeven. Dit omdat hij verwacht is. De andere twee type fouten vallen onder transmit, omdat het uiteindelijk gaat om het uitwisselen van gegevens. Het onderscheid tussen een terminale error wordt door de outcome weergegeven. Een 4 geeft aan “kleine fout”, 8 “serieuze fout” en 12 “fatale fout”. Een terminale error is een 8 “serieuze fout”, een gegevensverwerkingsfout valt onder een 4 “kleine fout”. Een tijdelijke fout is in principe type 4 “kleine fout”, maar het systeem kan ook besluiten dat het niet in staat is gegevens verder te verwerken en een 12 “fatale fout” te sturen om aan te geven helemaal geen gegevens meer te kunnen verwerken.Hier wordt onderscheid gemaakt tussen drie typen:

  • Een tijdelijke fout kan van type 4 (kleine fout) of 12 “fatale fout” indien het systeem tijdelijke beschikbaarheidsproblemen heeft.
  • Een gevensverwerkingsprobleem wordt altijd op outcome 4 gemapped.
  • Een interne verwerkingsfout die in principe niet aan de input data valt te koppelen wordt altijd outcome 8.

In alle gevallen is het type "transmit"

 

Tijdelijke fout

Gegevensverwerkingsfout

Terminale Interne fout

AuditEvent.type

transmit

verifytransmit

transmit

AuditEvent.outcome

4 of 12

4

8

In het codesysteem http://hl7.org/fhir/audit-event-outcome worden de foutcodes als volgt vastgelegd.

CodeDisplayDefinition
0SuccessThe operation completed successfully (whether with warnings or not).
4Minor failureThe action was not successful due to some kind of minor failure (often equivalent to an HTTP 400 response).
8

Serious failure

The action was not successful due to some kind of unexpected error (often equivalent to an HTTP 500 response).

12Major failureAn error of such magnitude occurred that the system is no longer available for use (i.e. the system died).

De action

De action wordt gemapped op R van Read E van Execute, omdat het een verwerking van gegevens betreft die worden gelezen in de FHIR storeapplicatie.

Entity en query

De overige velden wijken niet af van wat verwacht wordt.  De entity heeft betrekking op de entity die onverwerkbaar is, indien er in een resultaat (bundle) meerdere enities voorkomen die niet verwerkt kan worden, moet voor elke entity een AuditEvent worden aangemaakt met meerdere entities. Indien er sprake is van een query moet deze in het query veld gevuld worden.

...

De waarde van dit veld kan gevuld worden met een begrijpelijke beschrijving van de melding, met als doelgroep de beheerder van het domein waarin duidelijk leesbaar is wat het probleem heeft veroorzaakt. Hou er rekening mee dat de beschrijving absoluut geen herleidbare gegevens mag bevatten.

Eisen

  • Een client van de FHIR resource service MOET een AutitEvent aanmaken indien deze niet in staat is de gegevens van de FHIR resource service als door het domein wordt verwacht te verwerken. Het AutitEvent is een manier om het domein te laten weten dat de applicatie het FHIR object niet in goede order verwerkt heeft.
  • Het applicatie moet de relevante waarden van de X-Request-Id, X-Correlation-Id, en X-Trace-Id uit het originele request in het AuditEvent meesturen.
  • De POST request headers moet een nieuw X-Request-Id bevatten, de waarde van het originele X-Request-Id, X-Correlation-Id als de X-Trace-Id meegeven volgen de standaard regels rond het vullen van deze waarden.
  • De mapping uit tabel x (TODO link) is het onderdeel De mapping van het AuditEvent is van toepassing op de inhoud van het AuditEvent object.

...