Implementierungsleitfaden ISiK-Modul Terminplanung

Operations

Es gelten die allgemeinen Vorgaben der FHIR-Kernspezifikation für die Ausführung von Custom Operations.

Buchung eines Termins

Invocations

URL: [base]/Appointment/$book

This operation changes content

Parameters (In)

Name	Cardinality	Type	Documentation
appt-resource	1..1	Appointment	Eine Appointment-Ressource entsprechend dem dazugehörigen ISiK-Profil MUSS übergeben werden. Falls das Parameter-Element 'Appointment' als einziges Parameter-Element verwendet wird, SOLLTE die Appointment-Ressource direkt im HTTP Body übergeben werden, alternativ zu einer Parameter-Ressource inklusive dem eingebetteten Appointment-Element. Invalide Ressourcen MÜSSEN abgelehnt werden durch das Termin Repository (zur Form der Ablehnung s.u.). Das Appointment MUSS den Status 'proposed' enthalten.
cancelled-appt-id	0..1	uri	Für die vorliegende Spezifikation ist die Verschiebung eines Termin eins zwei-stufiger Prozess, bei dem ein Termin storniert und ein neuer Termin neu gebucht wird. Dieser Parameter repräsentiert die Ressourcen-Id des stornierten Appointments. Der uri-Parameter kann eine absoulte URL enthalten, Server SOLLTEN jedoch nur Termine für ihre eigene Domäne verwalten. Im neu-angelegten Appointment MUSS eine Reference auf den abgesagten Termin hinterlegt werden (vgl. Appointment.extension:replaces). Der Status der abgesagten Ressource MUSS durch den Server angepasst werden.
schedule	0..1	Reference(ISiKKalender)	Im Falle dass ein Appointment keine Referenz auf ein oder mehrere Slots enthält, MUSS der Server die benötigten Slots auf Basis der Referenz auf Schedule, sowie dem Start- und Endzeitpunkt im Appointment ermitteln.

Return Values (Out)

Name	Cardinality	Type	Documentation
return	0..1	Appointment	Falls die Interaktion erfolgreich ist, ist der Status Code HTTP 201 - Created zurückzugeben. Im Erfolgsfall MUSS als Return-Parameter eine Appointment-Ressource (entsprechend dem dazugehörigen ISiK-Profil) zurückgegeben werden. Das id-Element der Appointment-Ressource MUSS korrekt gefüllt werden. Der Status der Appointment-Ressource MUSS auf 'booked' oder 'pending' geändert wurden sein durch den Server. Der Server MUSS die verwendeten Slot-Ressourcen als Referenz im Appointment angeben. Die Appointment-Ressource SOLLTE direkt im HTTP Body zurückgegeben werden, falls es sich um den einzigen Rückgabewert handelt. Alternativ kann die Appointment-Ressource innerhalb einer Parameter-Ressource zurückgegeben werden. Als Teil der Parameter-Ressource können zusätzlich Hinweise zum Termin als OperationOutcome zurückgegeben werden.
return	0..1	OperationOutcome	Falls die Interaktion fehlschlägt, MUSS als Return-Parameter eine OperationOutcome-Ressource zurückgegeben werden. Syntaktische Fehler in der Appointment-Ressource MUSS mit einem HTTP Status-Code 400 - Bad Request zurückgewiesen werden. Anderweitig invalide Appointment-Ressourcen MÜSSEN mit einer OperationOutcome-Ressource abgewiesen werden. In diesem Fall SOLLTE der HTTP Status-Code HTTP 422 - Unprocessable Entity verwendet werden. Eine OperationOutcome-Ressource KANN zu informativen Zwecken in jedem Fall zurückgegeben werden (s.o.).

Übersicht Interaktion Termin-Requestor mit Termin-Repository

Folgende Schritte KÖNNEN notwendig sein, sodass ein Termin durch einen Termin-Requestor innerhalb eines Termin-Repository eingestellt wird. Es ist zu beachten, dass für spezielle Implementierungen nicht alle Schritte hiervon relevant sind und übersprungen werden können.

Generell wird darauf hingewiesen, dass abhängig davon, welcher Client oder Benutzer eine Interaktion ausführt, unterschiedliche Ergebnisse zurückgeliefert werden können. Die vorliegende Spezifikation macht keine Vorgaben, wie eine Authentifizierung und Autorisierung zu implementieren ist. Es wird hierzu auf das ISiK-Modul 'Sicherheit' verwiesen.

User Story für die folgenden Beispiele: Ein Patient bucht über ein externes Patientenportal einen Termin in der allgemeinmedizinischen Ambulanz eines Krankenhauses. Da der Patient seit Tagen Bauchschmerzen hat, die in den letzten Stunden stärker werden, wählt er die Priorität "Notfall".

Abfrage aller Kodierungen der Behandlungsleistungen durch den Termin-Requestor: GET https://example.org/fhir/CodeSystem?context-type-value=https://gematik.de/fhir/isik/v3/Terminplanung/CodeSystem/ContextType|ResourceUsage$http://hl7.org/fhir/resource-types|HealthcareService

Das Termin-Repository MUSS alle CodeSysteme exponieren, welche für die Kodierung eines HealthcareService relevant sind. Die Anfrage ist nicht auf HealthcareService beschränkt, weitere Ressourcen-Kontexte können abgefragt werden. Alle verwendeten CodeSysteme MÜSSEN exponiert werden, insoweit diese sich als CodeSystem-Ressourcen ausdrücken lassen.

Hinweis: Diese Abfrage ist für eine Initialisierung des Termin-Requestors gedacht. Es ist davon auszugehen, dass diese Auswahlliste nicht dynamisch angepasst wird durch das Termin-Repository und nicht bei jeder Terminbuchung erneut abgefragt werden muss.

Abfrage aller verfügbaren Kalender durch den Termin-Requestor: GET https://example.org/fhir/Schedule

Der Termin-Requestor KANN durch die Abfrage aller verfügbaren Kalender alle Ressourcen abfragen, für die eine Termin-Buchung zur Verfügung steht.

Abfrage aller verfügbaren Slots für einen Kalender durch den Termin-Requestor: GET https://example.org/fhir/Slot?schedule=<Schedule/ISiKKalenderExample>&status=free

In diesem Fall ist auch ein Chaining auf weitere verknüpfte Akteure möglich: GET https://example.org/fhir/Slot?schedule.actor:HealthcareService.type=http://dicom.nema.org/resources/ontology/DCM|CT

Anlage einer Patient-Ressource durch den Termin-Requestor: POST https://example.org/fhir/Patient

{
    "resourceType": "Patient",
    "meta": {
        "tag": [
            {
                "system": "http://fhir.de/CodeSystem/common-meta-tag-de",
                "code": "external"
            }
        ]
    }
    [...]
}

Aufruf der $book-Operation durch den Termin-Requestor: POST https://example.org/fhir/Appointment/$book

{
  "resourceType": "Appointment",
  "id": "ISiKTerminExample",
  "meta": {
    "tag": [
      {
        "code": "external",
        "system": "http://fhir.de/CodeSystem/common-meta-tag-de"
      }
    ],
    "profile": [
      "https://gematik.de/fhir/isik/v3/Terminplanung/StructureDefinition/ISiKTermin"
    ]
  },
  "extension": [
    {
      "url": "https://gematik.de/fhir/isik/v3/Terminplanung/StructureDefinition/ISiKNachrichtExtension",
      "valueReference": {
        "reference": "Communication/ISiKNachrichtExample"
      }
    }
  ],
  "status": "proposed",
  "start": "2022-12-10T09:00:00Z",
  "end": "2022-12-10T09:30:00Z",
  "slot": [
    {
      "reference": "ISiKSlotExample"
    }
  ],
  "serviceType": [
    {
      "coding": [
        {
          "code": "124",
          "system": "http://terminology.hl7.org/CodeSystem/service-type"
        }
      ]
    }
  ],
  "specialty": [
    {
      "coding": [
        {
          "code": "010",
          "system": "urn:oid:1.2.276.0.76.5.114"
        }
      ]
    }
  ],
  "participant": [
    {
      "actor": {
        "display": "Test Patient",
        "reference": "Patient/example"
      },
      "status": "accepted"
    }
  ],
  "_priority": {
    "extension": [
      {
        "url": "https://gematik.de/fhir/isik/v3/Terminplanung/StructureDefinition/ISiKTerminPriorityExtension",
        "valueCodeableConcept": {
          "coding": [
            {
              "code": "25876001",
              "system": "http://snomed.info/sct"
            }
          ]
        }
      }
    ]
  }
}

Antwort des Termin-Repository:

{
  "resourceType": "Appointment",
  "id": "ISiKTerminExample",
  "meta": {
    "tag": [
      {
        "code": "external",
        "system": "http://fhir.de/CodeSystem/common-meta-tag-de"
      }
    ],
    "profile": [
      "https://gematik.de/fhir/isik/v3/Terminplanung/StructureDefinition/ISiKTermin"
    ]
  },
  "extension": [
    {
      "url": "https://gematik.de/fhir/isik/v3/Terminplanung/StructureDefinition/ISiKNachrichtExtension",
      "valueReference": {
        "reference": "Communication/ISiKNachrichtExample"
      }
    }
  ],
  "status": "booked",
  "start": "2022-12-10T09:00:00Z",
  "end": "2022-12-10T09:30:00Z",
  "slot": [
    {
      "reference": "ISiKSlotExample"
    }
  ],
  "serviceType": [
    {
      "coding": [
        {
          "code": "124",
          "system": "http://terminology.hl7.org/CodeSystem/service-type"
        }
      ]
    }
  ],
  "specialty": [
    {
      "coding": [
        {
          "code": "010",
          "system": "urn:oid:1.2.276.0.76.5.114"
        }
      ]
    }
  ],
  "participant": [
    {
      "actor": {
        "display": "Test Patient",
        "reference": "Patient/example"
      },
      "status": "accepted"
    }
  ],
  "_priority": {
    "extension": [
      {
        "url": "https://gematik.de/fhir/isik/v3/Terminplanung/StructureDefinition/ISiKTerminPriorityExtension",
        "valueCodeableConcept": {
          "coding": [
            {
              "code": "25876001",
              "system": "http://snomed.info/sct"
            }
          ]
        }
      }
    ]
  }
}

Für den Fall, dass ein Termin-Repository zum aktuellen Zeitpunkt keine Terminbestätigung geben kann, wird in der Antwortnachricht zurückgegebenen Appointment-Ressource der Wert von "Appointment.status" auf "pending" gesetzt. Als HTTP-Status-Code MUSS das Termin-Repository "202 - Accepted" zurückgeben. Beispielsweise kann dies der Fall sein, falls ein Termin zunächst manuell im Termin-Repository bestätigt werden muss. Sobald ein Termin im Status "pending" seitens des Termin-Repository bestätigt oder abgesagt wurde, MUSS das Termin-Repository den Status des Termins auf "booked" bzw. "canceled" stellen. Sofern dieses unterstützt wird, SOLL eine Benachrichtigung des Termin-Consumers per Push-Mechanismus erfolgen (siehe auch nächster Abschnitt). In jedem Fall MUSS der Termin-Consumer über eine Lese- oder Such-Anfrage jederzeit den aktuellen Status der Terminbuchung ermitteln können.

Aktualisierung / Absage eines Termins

Es ist zu beachten, dass es aus Effizienzgründen für bestimmte Implementierungen sinnvoll sein kann, dass Updates einer Appointment-Ressource ausgelöst durch das Termin-Repository mittels eines Push-Mechanismus an Termin-Consumer / Termin-Requestor übermittelt werden. Im Standard-Fall müssen diese Akteure die Ressourcen mittels des entsprechenden Endpunktes eigenständig abfragen und auf Updates überprüfen. Für einen Push-Mechanismus wird auf FHIR Subscriptions verwiesen. Die vorliegende Spezifikation macht jedoch KEINE Vorgaben für die Verwendung einer solchen Methodik.

Eine Aktualisierung der Ressource erfolgt mittels einer HTTP PATCH-Interaktion. Updates einer Appointment-Ressource MUSS das Termin Repository unterstützen. Es MUSS mindestens die PATCH-Interaktion auf Basis einer FHIRPath-Patch-Parameter Ressource unterstützt werden.

Folgende Elemente DÜRFEN NICHT durch ein Update der Ressourcen verändert werden:

Appointment.slot
Appointment.start
Appointment.end
Appointment.participant.actor.where(resolve() is Patient)

Hinweis: Hinweis: Ein Termin Repository MUSS einen Termin ablehnen, falls der Termin auf einen nicht vorhandenen (gelöscht oder inkativ) Patienten referenziert. Dies gilt insbesondere auch nachträglich für vorläufig angelegte Patienten-Ressourcen.

Sollte die PATCH-Parameter-Ressource eins dieser Elemente verändern, MUSS die Operation mit einem Status Code "HTTP 400 - Bad Request" zurückgewiesen werden. Eine OperationOutcome Ressource MUSS zurückgegeben werden, die in kodierter Form den entsprechenden Fehler beschreibt.

Beispiel: Absage eines Termins

{
    "resourceType": "Parameters",
    "parameter": [{
        "name": "operation",
        "part": [
            {
                "name": "type",
                "valueCode": "replace"
            },
            {
                "name": "path",
                "valueString": "Appointment.status"
            },
            {
                "name": "value",
                "valueCode": "canceled"
            }
        ]
    }]
}

Anlage einer Patient-Ressource

Ein Termin Repository MUSS die Anlage (Create-Interaktion) einer Patient-Ressource entsprechend der Vorgaben des ISiK-Basismoduls unterstützen.

Asynchrone Ausführung $book

Die Operation zur Buchung eines Termin MUSS ebenfalls asynchron ausgeführt werden können, für den Fall, dass ein Termin-Repository keine Zusagen zu Antwortzeiten machen kann und so dass Problem besteht, dass der Client in einen Timeout läuft. Beispielsweise kann dies der Fall sein, wenn die Buchungsanfrage im Termin-Repository asynchrone Anfragen an andere Systeme auslöst und der Termin erst bestätigt werden kann, wenn diese durchgelaufen sind. Es gelten die Regeln der FHIR Kernspezifikation - Abschnitt 3.2.0.7 Executing an Operation Asynchronously:

Der Aufruf der $book-Operation erfolgte auch im asynchronen Fall durch einen POST-Request
Ein HTTP-Header mit dem Namen "Prefer" und dem Inhalt "respond-async" MUSS im Aufruf der Operation enthalten sein
Als HTTP-Status-Code MUSS das Termin-Repository 202 - Accepted zurückgeben
Im Fehlerfall MUSS ein 4XX- oder 5XX-HTTP-Status-Code zurückgeben werden
Zudem MUSS das Termin-Repository einen "Content-Location"-Header zurückliefern indem eine valide absolute URL enthalten ist unter welcher die oben beschriebene Appointment- bzw OperationOutcome-Ressource als Antwort auf die Buchung des Termins abgerufen werden kann