# Generelle Prinzipien - Implementation Guide ePA Basisfunktionalitäten v1.3.1

Implementation Guide

ePA Basisfunktionalitäten

Version 1.3.1 - release 

* [**Table of Contents**](toc.md)
* **Generelle Prinzipien**

## Generelle Prinzipien

Dieser Implementation Guide verwendet die Schlüsselwörter **MUSS**, **DARF NICHT**, **SOLL NICHT** und **KANN** als deutsche Pendants des [RFC2119], um Anforderungen als Ausdruck normativer Festlegungen zu kennzeichnen. Anforderungen werden im Implementation Guide wie folgt dargestellt:

**<IG-ID-Version> - <Titel der Anforderung>**
 Text / Beschreibung
 [<=]

### Übergeordnete Anforderungen

Der Audit Event Service berücksichtigt als Ausprägung eines FHIR Data Service allgemeingültige [gemIG_TI_Common#Audit] Anforderungen.

Der Patient Service berücksichtigt als Ausprägung eines FHIR Data Service allgemeingültige [gemIG_TI_Common#Patient] Anforderungen.

### Schnittstellenimplementierung

Der FHIR Data Service im ePA-Aktensystem MUSS folgende HTTP Status Codes unterstützen:

| | | | |
| :--- | :--- | :--- | :--- |
| `200` | Successful operation | - | - |
| `403` | Requestor not authorized | `invalAuth` | no user session with valid ID-Token available |
| `403` | Requestor has no valid entitlement | `notEntitled` | - |
| `403` | Requestor role is not in the list of allowed user groups | `invalidOid` | - |
| `403` | Device registration does not exist | `unregisteredDevice` | if requestor role is oid_versicherter only |
| `404` | Health record is in state UNKNOWN or INITIALIZED | `noHealthRecord` | - |
| `409` | Request conflicts with the current state of the health record | `statusMismatch` | siehe['Wiederholungsintervalle'](#wiederholungsintervalle) |
| `431` | Requesting Organization Header exceeds maximum size | `SVC_ORG_HEADER_TOO_LARGE` | - |
| `500` | Any other error | `internalError` | siehe['Wiederholungsintervalle'](#wiederholungsintervalle) |

**Tabelle:**HTTP Status Codes für die FHIR-Data-Service-Antwortnachrichten

Der FHIR Data Service im ePA-Aktensystem MUSS einen Fehlercode mit dem entsprechenden HTTP Status Code im Media Type
*application/json*nach folgendem Schema zurückgeben:

```
    {
      "errorCode": "statusMismatch"
    }
```

Der FHIR Data Service MUSS für die Fehlermeldung
*SVC_IDENTITY_MISMATCH*den HTTP Status Code
*403*verwenden, wenn die Telematik-ID im ID-Token (ausgestellt durch den IDP-Dienst) oder die KVNR im
*x-insurantid*-HTTP Header nicht mit den FHIR-Daten übereinstimmt.
**Beispiel für ein OperationOutcome mit SVC_IDENTITY_MISMATCH**

Der FHIR Data Service im ePA-Aktensystem MUSS – für den Fall, dass sich die Akte im Status SUSPENDED oder INACCESSIBLE befindet – den HTTP Status Code
*409 statusMismatch*unterstützen.

Der FHIR Data Service MUSS beim Erstellen und Aktualisieren von FHIR-Ressourceninstanzen die übermittelten Daten gemäß dem für die jeweilige Ressource geltenden FHIR-Profil validieren und bei fehlgeschlagender Validierung die Operation mit dem HTTP Status Code
*422 Unprocessable Entity*sowie einer
*OperationOutcome*-Ressource ablehnen, die mindestens einen
*issue*-Eintrag mit
*issue.code = invalid*und
*issue.severity = error*enthält.

#### Wiederholungsintervalle

Die folgenden Wiederholungsintervalle werden im Falle einer Fehlerantwort definiert:

* *409* Conflict (statusMismatch) 
* etwa 24 Stunden
 
* *500* Internal Error 
* etwa 10 Minuten
 

### Leistungserbringerinstitutionserkennung mittels X-Requesting-Organization

Zur Identifikation der Leistungserbringerinstitution, desssen Primärsystem eine FHIR-Operation auslöst, wird der HTTP Header **X-Requesting-Organization** verwendet. Dieser Header überträgt eine FHIR **Organization**-Ressource im JSON-Format, base64-kodiert gemäß [RFC4648].

Die übermittelte **Organization** muss dem Profil **TIOrganization** entsprechen und enthält unter anderem die Telematik-ID der Leistungserbringerinstitution. Diese wird vom FHIR Data Service mit der im ID-Token enthaltenen Telematik-ID verglichen, um die Identität der Leistungserbringerinstitution zu verifizieren. Dabei ist zu beachten, dass der HTTP Header **X-Requesting-Organization** eine maximale Größe von 8 KByte nicht überschreiten darf.

Neben der Validierung dient die übermittelte Leistungserbringerinstitution bzw. der Organization-Datensatz auch der automatischen Referenzierung in **Provenance**-Ressourcen, die bei Änderungsoperationen erzeugt werden. So kann jede Änderung systematisch der verantwortlichen Leistungserbringerinstitution zugeordnet werden.

Der FHIR Data Service MUSS den HTTP Header
*X-Requesting-Organization*unterstützen, um die anfragende Organisation im Rahmen einer Anfragenachricht zu identifizieren.

Der FHIR Data Service MUSS ausschließlich den HTTP Header
*X-Requesting-Organization*mit einer gemäß [RFC4648] Base64-kodierten, vollständig serialisierten FHIR
*Organization*-Ressource im Format
*FHIR+JSON*für eine Weiterverarbeitung der Anfragenachricht akzeptieren.

Der FHIR Data Service MUSS sicherstellen, dass die im HTTP Header
*X-Requesting-Organization*enthaltene
*Organization*-Ressource dem Profil
*TIOrganization*entspricht. Bei fehlgeschlagender Validierung ist die Operation mit HTTP Status Code
*422 Unprocessable Entity*und einem
*OperationOutcome*mit dem Fehlercode
*issue.code=invalid*und
*issue.details=SVC_ORG_HEADER_PROFILE_MISMATCH*abzulehnen.

Der FHIR Data Service MUSS die in der übermittelten
*Organization.identifier*enthaltene Telematik-ID mit der im ID-Token (ausgestellt durch den IDP-Dienst) enthaltenen Telematik-ID vergleichen. Stimmen die beiden Werte nicht überein, ist die Anfrage mit dem HTTP Status Code
*403 Forbidden*abzulehnen. Zusätzlich ist eine
*OperationOutcome*-Ressource mit dem Fehlercode
*SVC_IDENTITY_MISMATCH*zurückzugeben.

Der FHIR Data Service MUSS eine Anfrage ablehnen, wenn der HTTP Header
*X-Requesting-Organization*einschließlich seiner Base64-Kodierung eine Größe von mehr als
*8 KByte*überschreitet und dabei den HTTP Status Code
*431 Request Header Fields Too Large*zurückgeben. Das Größenlimit bezieht sich auf den vollständigen Header-Eintrag, also den Header-Namen
*X-Requesting-Organization*, den Doppelpunkt, das Leerzeichen sowie den Base64-kodierten Header-Wert.
#### Beispiel HTTP Request mit X-Requesting-Organization Header

```
POST /epa/medication/api/v1/fhir/$add-emp-entry HTTP/1.1
Host: epa4all
Content-Type: application/fhir+json
X-Request-ID: bb22b14f-9c95-49fe-b889-d03e2d692bca
x-insurantid: Z123456789
x-useragent: CLIENTID1234567890AB/2.1.12-45
X-Requesting-Organization:  


```

### Erstellen und Verwenden eines Änderungseintrags (Provenance)

Änderungseinträge im FHIR Data Service des ePA-Aktenkontos werden mit der Ressource **Provenance** dokumentiert. Sie erfassen, welche Änderungen an Ressourcen durchgeführt wurden, welche Versionen dieser Ressourcen dadurch entstanden sind, sowie wer für diese Änderung verantwortlich war und wann diese fachlich durchgeführt und technisch dokumentiert wurde.

Für diese Änderungseinträge muss das Profil **EPAActivityProvenance** verwendet werden. Dieses Profil legt verbindlich fest,

* welche Angaben zu den betroffenen Ressourcen (**target**) zu machen sind,
* wie der verantwortliche Akteur (**agent**) als Leistungserbringer:in, Institution oder System referenziert wird,
* und wie die Art der Aktivität (**activity**) sowie die zeitlichen Angaben (**occurred**, **recorded**) anzugeben sind.

Ein Änderungseintrag dient dabei nicht nur als technisches Audit, sondern als fachlich relevanter Nachweis im Kontext des jeweiligen FHIR Data Service. Jede betroffene Ressourceninstanz wird versioniert referenziert, sodass der genaue Zustand der jeweiligen FHIR-Instanzen zum Zeitpunkt der Änderung eindeutig nachvollzogen werden kann.

Die **Provenance**-Instanzen werden ausschließlich vom jeweiligen FHIR Data Service selbst erstellt. Eine Erstellung oder Bearbeitung dieser Änderungseinträge durch externe Systeme oder Clients ist nicht vorgesehen. Die Provenance entsteht typischerweise im Rahmen von Operationen, die fachliche Änderungen an Ressourceninstanzen bewirken. Es wird nicht für jede einzelne Ressourceninstanz automatisch ein Änderungseintrag erstellt. Die jeweilige Geschäftslogik des FHIR Data Service definiert, für welche fachlich relevanten Änderungen ein Änderungseintrag erzeugt wird. Beispielsweise kann eine zusammengehörige Gruppe von Instanzen, die gemeinsam einen Verschreibungs- unad Abgdabedatensatz bilden, in einem einzigen Änderungseintrag dokumentiert werden.

Der FHIR Data Service MUSS für Änderungseinträge das Profil
*EPAActivityProvenance*verwenden.

Der FHIR Data Service MUSS im Änderungseintrag (
*Provenance.target*) ausschließlich versionierte Referenzen (
*ResourceType/id/_history/vid*) auf die durch die Änderung entstandenen oder aktualisierten Ressourceninstanz angeben.

Der FHIR Data Service MUSS im Änderungseintrag sowohl den fachlichen Zeitpunkt der Änderung (
*Provenance.occurred*) als auch den technischen Erfassungszeitpunkt (
*Provenance.recorded*) angeben.
*Hinweis:* In FHIR Data Services der ePA enthalten *Provenance.occurred* und *Provenance.recorded* bei der oben genannten Befüllung denselben Zeitpunkt.

Der FHIR Data Service MUSS im Änderungseintrag (
*Provenance.activity*) die Art der Änderung angeben. Zulässig sind nur Werte aus dem ValueSet
*EPAActivityProvenanceTypeVS*.
#### Ermittlung des verantwortlichen Akteurs (Agent)

Der verantwortliche Akteur wird im Änderungseintrag durch das Element *Provenance.agent.who* angegeben. Dabei gilt folgende Unterscheidung:

**Bei Aufrufen durch Leistungserbringerinstitutionen:**

Es ist die im Header **X-Requesting-Organization** übermittelte **Organization**-Ressource zu verwenden. Für die Referenzierung in **agent.who** gilt:

* Es ist eine Referenz auf die übermittelte **Organization**-Instanz zu verwenden, sofern diese im FHIR Data Service gespeichert ist.
* Zusätzlich sind der Identifier (Telematik-ID) sowie der Anzeigename (display) aus der übermittelten Organization in **agent.who** einzutragen.

Der FHIR Data Service MUSS bei Aufrufen den verantwortlichen Akteur im Änderungseintrag (
*Provenance.agent.who*) aus dem im Header
*X-Requesting-Organization*übermittelten
*Organization*-Ressource referenzieren und den Identifier (
*Provenance.agent.who.identifier*) sowie den Anzeigenamen (
*Provenance.agent.who.display*) angeben.

**Bei Änderungen, die der FHIR Data Service selbst durchführt:**

Es ist ein eindeutiger Identifier des jeweiligen ePA FHIR Data Service anzugeben, z. B. ein Identifier nach dem Profil EPAFHIRDataServiceIdentifier. Auch in diesem Fall ist zusätzlich ein *display* anzugeben, der den Dienstnamen beschreibt (z. B. “ePA Medication Service”).

Der FHIR Data Service MUSS bei selbstständig ausgelösten Änderungen sich selbst als verantwortlichen Akteur im Änderungseintrag (
*Provenance.agent.who*) mit einem eindeutigen Identifier gemäß dem Profil
*IdentifierEPAFHIRDataService*angeben.

#### Abruf des Änderungsverlaufs

Zur Auswertung und Nachverfolgung von Änderungen stellt der FHIR Data Service geeignete Zugriffsmöglichkeiten bereit. Diese ermöglichen es, den Änderungsverlauf zu einer oder mehreren Ressourcen gezielt abzufragen – beispielsweise basierend auf den *Provenance*-Instanzen, die für diese Ressourcen erstellt wurden. Eine direkte Abfrage kann z.B. über eine FHIR-Suche auf *Provenance* mit dem Suchparameter **target** oder über eine spezialisierte Operation des jeweiligen FHIR Data Service erfolgen.

#### Ablauf der Provenance-Erstellung bei Änderungen

Bei jeder fachlich relevanten Änderung an FHIR-Ressourcen wird eine **Provenance**-Instanz erzeugt, die den konkreten Zustand der betroffenen Ressourceninstanz zum Zeitpunkt der Änderung versioniert referenziert. Die **Provenance** wird dabei immer nach erfolgreicher Persistierung der geänderten Ressource (bzw. unmittelbar vor einem Löschvorgang) durch den FHIR Data Service erstellt.

**Erzeugung bei Erstellung (CREATE)**

Nach dem erfolgreichen Anlegen einer neuen Ressourceinstanz (z.B. **MedicationRequest**, **MedicationStatement**) wird eine **Provenance**-Instanz erzeugt, die auf die neu entstandene Version der Ressource verweist:

* `Provenance.target → Resource/id/_history/1`
* `Provenance.activity = CREATE`

Diese **Provenance**-Instanz dokumentiert die fachliche Erstellung der Ressourceninstanz durch den verantwortlichen Akteur (z.B. Leistungserbringerinstitution).

**Erzeugung bei Aktualisierung (UPDATE)**

Wird eine bestehende Ressourceninstanz geändert, entsteht eine neue Version. Nach erfolgreicher Aktualisierung wird eine **Provenance**-Instanz erzeugt, die auf die neu erzeugte Version verweist:

* `Provenance.target → Resource/id/_history/n`
* `Provenance.activity = UPDATE`

Damit ist nachvollziehbar, welche Änderungen an einer bestehenden Ressourceninstanz vorgenommen wurden und welcher konkrete Zustand dadurch entstanden ist.

**Erzeugung bei Löschung (DELETE)**

Beim Löschen einer Ressource wird eine **Provenance**-Instanz erstellt, bevor der Löschvorgang ausgeführt wird, um die letzte gültige Version der Ressourceninstanz zu referenzieren:

* `Provenance.target → Resource/id/_history/n` (letzte Version vor Löschung)
* `Provenance.activity = DELETE`

So bleibt der letzte bekannte Zustand der Ressourceninstanz nachvollziehbar.

**Beispiel: Versionierung und Nachvollziehbarkeit**

Durch dieses Vorgehen entsteht eine lückenlose Kette von **Provenance**-Einträgen:

* `Provenance(CREATE)` → Version 1
* `Provenance(UPDATE)` → Version 2
* `Provenance(UPDATE)` → Version 3
* `Provenance(DELETE)` → Version 3

### FHIR-spezifische Anforderungen

Der FHIR Data Service MUSS im Element Reference bei gleichzeitiger Angabe einer literal reference (
*References.reference*) und einer logischen Referenz (
*References.identifier*) die literal reference bevorzugt auswerten. Die Verarbeitung der logischen Referenz erfolgt nur, wenn keine literal reference vorhanden ist.

Der FHIR Data Service MUSS interne Literal-Referenzen in allen Elementen vom Typ
*Reference*ausschließlich in Form relativer URLs bereitstellen. Eine relative URL besteht aus der Kombination des Ressourcentyps und der Resource-ID im Format
*[ResourceType]/[ResourceID]*.

Der FHIR Data Service des ePA-Aktensystems MUSS sicherstellen, dass der Host der absoluten URL im Feld
*Bundle.entry.fullUrl*stets
**epa4all**ist. Andere Hostnamen sind unzulässig.
**Beispiel**

```
http://epa4all/epa/audit/api/v1/fhir/AuditEvent/ea01ccbc-aa5d-4c34-8292-d95678d52c98

```

Der FHIR Data Service MUSS sicherstellen, dass bei der Erstellung von Referenzen zu einer
*Practitioner*- oder
*Organization*-Resourceninstanz die
*Reference.display*Eigenschaft mit der Information aus
*Practitioner.name.text*bzw.
*Organization.name*der referenzierten
*Practitioner*- bzw.
*Organization*-Instanz gefüllt wird.

Der FHIR Data Service MUSS sicherstellen, dass bei der Erstellung von Referenzen zu einer
*PractitionerRole*-Resourceninstanz die
*Reference.display*-Eigenschaft, falls in der referenzierten
*PractitionerRole*-Instanz
* das Element *PractitionerRole.practitioner* gesetzt ist, aber nicht das Element *PractitionerRole.organization*, mit der Information aus *Practitioner.name.text* der unter *practitioner* referenzierten Instanz gefüllt wird,
* das Element *PractitionerRole.organization* gesetzt ist, aber nicht das Element *practitioner*, mit der Information aus *Organization.name* der unter *PractitionerRole.organization* referenzierten Instanz gefüllt wird,
* sowohl das Element *organization* als auch das Element *practitioner* gesetzt ist, mit der Konkatination befüllt wird aus 
1. der Information aus*Practitioner.name.text*der unter*practitioner*referenzierten Instanz
1. dem von Leerzeichen umgebenen Trennzeichen "/"
1. der Information aus*Organization.name*der unter*organization*referenzierten Instanz
 

Ein Beispiel für den Display-Wert für den Fall, dass sowohl eine *Practitioner*- als auch eine *Organization*-Instanz in der *PractitionerRole* referenziert ist, wäre “Dr. Erika Mustermann / Gemeinschaftspraxis Mustermann”.

Der FHIR Data Service MUSS bei schreibenden Operationen ausschließlich die als
*Must Support*gekennzeichneten FHIR-Elemente berücksichtigen und in neu erzeugte FHIR-Instanzen dauerhaft speichern.
Dies bedeutet, dass bei FHIR Operationen nur mit *Must Support* gekennzeichnete FHIR-Elemente aus den Eingabedaten in neu erzeugte FHIR-Instanzen übernommen und gespeichert werden dürfen. Dies schränkt jedoch nicht die Persistierung von Elementen ein, die innerhalb von Geschäftlogiken gefüllt werden.

#### Persistieren der Profilversion in FHIR

Beim Erzeugen von FHIR-Ressourcen im FHIR Data Service MUSS dieser jede zu speichernde Ressource gegen das dazugehörige aktuelle Profil validieren. Die Information, gegen welches Profil in welcher Version geprüft wurde, MUSS der FHIR Data Service in der jeweiligen Ressource in
*Meta.profile*speichern.
*Hinweis:* Validierungsgrundlage bei Erhalt und anschließender Persistierung der FHIR-Ressource ist das aktuell gültige FHIR Package der zugehörigen Spezifikation beziehungsweise des Implementation Guide.

Das Primärsystem DARF Funktionalitäten oder Implementierungsvorgaben der [FHIR-Spezifikation] NICHT implementieren, welche nicht durch die FHIR Implementation Guides [gemIG_TI_Common], [gemIG_ePA_Basic], [gemIG_ePA_Medication] sowie [gemIG_ePA_MHD] vorgegeben sind.

