Implementation Guide
Version 1.4.0 - release

Errorhandling

Seiteninhalt:

ATF Fehlerbehandlung

Behandlung von Fehlern im OperationOutcome

Für die Rückmeldung von Fehlern im Rahmen des Nachrichtenaustauschs ist das Profil ATFOperationOutcome zu verwenden. Dabei gelten folgende Vorgaben für den Umgang mit Fehlern:

  • Severity: Bei Fehlern MUSS OperationOutcome.issue.severity = "error" gesetzt werden.
  • Code: Es sind ausschließlich die Codes "invalid" oder "processing" zu verwenden.

Bedeutung der Codes:

  • invalid:
    Dieser Code signalisiert einen technischen Fehler, beispielsweise eine ungültige Struktur oder ein nicht interpretierbares Format.
    • Das empfangende System DARF den Inhalt des Datensatzes dem Nutzer NICHT anzeigen.
    • Stattdessen MUSS der Nutzer darauf hingewiesen werden, dass ein technischer Fehler aufgetreten ist.
    • Zusätzlich SOLL eine Option angeboten werden, den Fehler automatisiert oder manuell an den Support zu melden.

<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="ExampleFailedToValidateOperationOutcome"/>
  <meta>
    <profile
             value="https://gematik.de/fhir/atf/StructureDefinition/atf-operation-outcome"/>
  </meta>
  <text>
    <status value="extensions"/>
    <div xmlns="http://www.w3.org/1999/xhtml"><p class="res-header-id"><b>Generated Narrative: OperationOutcome ExampleFailedToValidateOperationOutcome</b></p><a name="ExampleFailedToValidateOperationOutcome"> </a><a name="hcExampleFailedToValidateOperationOutcome"> </a><div style="display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%"><p style="margin-bottom: 0px"/><p style="margin-bottom: 0px">Profile: <a href="StructureDefinition-atf-operation-outcome.html">ATF Operation Outcome</a></p></div><p><b>ATF Message ID EX</b>: 8573faac-abf6-4021-be80-750c8619ec06</p><h3>Issues</h3><table class="grid"><tr><td style="display: none">-</td><td><b>Severity</b></td><td><b>Code</b></td><td><b>Diagnostics</b></td></tr><tr><td style="display: none">*</td><td>Error</td><td>Invalid Content</td><td>Ressourcen konnten nicht validiert werden</td></tr></table></div>
  </text>
  <extension
             url="https://gematik.de/fhir/atf/StructureDefinition/atf-message-id-ex">
    <valueString value="8573faac-abf6-4021-be80-750c8619ec06"/>
  </extension>
  <issue>
    <severity value="error"/>
    <code value="invalid"/>
    <diagnostics value="Ressourcen konnten nicht validiert werden"/>
  </issue>
</OperationOutcome>
  • processing:
    Dieser Code signalisiert einen fachlichen Fehler, den der Nutzer ggf. selbst beheben kann (z.B. fehlende Pflichtangaben wie Medikamentenname).
    • Im Feld OperationOutcome.issue.diagnostics MUSS ein menschenlesbarer Text enthalten sein, der den Fehler beschreibt.
    • Dieser Text MUSS dem Nutzer angezeigt werden.
    • Dem Nutzer SOLL die Möglichkeit gegeben werden, den Datensatz zu korrigieren und erneut zu übermitteln.

<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="ExampleFailedToProcessOperationOutcome"/>
  <meta>
    <profile
             value="https://gematik.de/fhir/atf/StructureDefinition/atf-operation-outcome"/>
  </meta>
  <text>
    <status value="extensions"/>
    <div xmlns="http://www.w3.org/1999/xhtml"><p class="res-header-id"><b>Generated Narrative: OperationOutcome ExampleFailedToProcessOperationOutcome</b></p><a name="ExampleFailedToProcessOperationOutcome"> </a><a name="hcExampleFailedToProcessOperationOutcome"> </a><div style="display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%"><p style="margin-bottom: 0px"/><p style="margin-bottom: 0px">Profile: <a href="StructureDefinition-atf-operation-outcome.html">ATF Operation Outcome</a></p></div><p><b>ATF Message ID EX</b>: da669fc6-b9f9-4ced-8f31-95fe35564601</p><blockquote><p><b>issue</b></p><p><b>severity</b>: Error</p><p><b>code</b>: Processing Failure</p><p><b>diagnostics</b>: Medikamentenname wurde nicht angegeben.</p></blockquote><blockquote><p><b>issue</b></p><p><b>severity</b>: Warning</p><p><b>code</b>: Processing Failure</p><p><b>diagnostics</b>: Sender der Nachricht konnte nicht ermittelt werden.</p></blockquote></div>
  </text>
  <extension
             url="https://gematik.de/fhir/atf/StructureDefinition/atf-message-id-ex">
    <valueString value="da669fc6-b9f9-4ced-8f31-95fe35564601"/>
  </extension>
  <issue>
    <severity value="error"/>
    <code value="processing"/>
    <diagnostics value="Medikamentenname wurde nicht angegeben."/>
  </issue>
  <issue>
    <severity value="warning"/>
    <code value="processing"/>
    <diagnostics value="Sender der Nachricht konnte nicht ermittelt werden."/>
  </issue>
</OperationOutcome>

Hinweis:
Die eindeutige Unterscheidung zwischen technischen und fachlichen Fehlern unterstützt eine zielgerichtete Fehlerbehandlung und verbessert die Nutzererfahrung. Die automatisierte Weiterleitung technischer Fehler an den Support erleichtert zudem eine schnelle Fehleranalyse und Behebung.

Fehlerbenachrichtigung und Meldewege bei Verarbeitungsfehlern

Im MessageHeader.source ist anzugeben, welche Software den Request initiiert hat. Es SOLL außerdem die Möglichkeit bestehen, eine E-Mail-Adresse anzugeben, über die das sendende System im Fehlerfall automatisiert benachrichtigt werden kann. So kann bei nicht validierbaren oder nicht verarbeitbaren Daten möglichst frühzeitig ein Fehlerbericht generiert und an den Hersteller übermittelt werden. Zusätzlich SOLL der Nutzer darüber informiert werden, dass ein Fehler aufgetreten ist und der Hersteller benachrichtigt wurde.

Dieses Vorgehen unterstützt insbesondere in der Entwicklungs- und Einführungsphase, da der Endnutzer einer bereits ausgelieferten Software in der Regel nicht selbst auf solche Fehler reagieren oder diese beheben kann.

Neben dem direkten Kontakt zwischen den Systemen können fehlerhafte UseCases auch öffentlich diskutiert oder gemeldet werden:

  • GitHub Discussions: Für jeden UseCase können gezielt Discussions im GitHub-Repository eröffnet werden, um offene Fragen oder Fehlverhalten strukturiert zu besprechen.
  • ERP-Find Tickets: Alternativ können Tickets im ERP-Find-System eröffnet werden. Diese werden durch die gematik betreut und ggf. intern weitergeleitet oder eskaliert, um betroffene Systeme zu identifizieren und gezielt bei der Fehlerbehebung zu unterstützen.

Ziel ist es, Fehlverhalten frühzeitig zu erkennen, systematisch zu klassifizieren und Herstellern eine präzise Rückmeldung zur Korrektur zu ermöglichen.