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)

NameCardinalityTypeDocumentation
appt-resource1..1Appointment

Eine Appointment-Ressource entsprechend dem dazugehörigen ISiK-Profil. Das Appointment MUSS den Status 'proposed' enthalten. Invalide Appointment-Ressourcen MÜSSEN mit einer OperationOutcome und dem Status Code HTTP 400 - Bad Request abgewiesen werden. Falls der Parameter als einzige Parameter verwendet wird KANN die Appointment-Ressource direkt im HTTP Body anstelle einer Parameter-Ressource übergeben werden. Die referenzierte Ressource MUSS dem ISiKTermin-Profil entsprechen. Invalide Ressource MÜSSEN abgelehnt werden durch das Termin Repository.

cancelled-appt-id0..1uri

Für die vorliegende Spezifikation ist die Verschiebubng 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.

schedule0..1Reference(ISiKKalender)

Im Falle das 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)

NameCardinalityTypeDocumentation
return0..1Bundle

Als Return-Parameter wird ein Bundle vom Typ 'searchset' zurückgegeben, welches eine aktualisierte Appointment- oder eine OperationOutcome-Ressource enthält. Im Falle das die Terminbuchung akzeptiert wird MUSS das Appointment persistiert werden. Das id-Element der Ressource MUSS korrekt gefüllt werden. Der Status der Appointment-Ressource muss auf 'booked' geändert werden. Der Server MUSS die verwendeten Slot-Ressourcen als Referenz im Appointment angeben.

Übersicht Interaktion Termin Requestor mit Termin Repository

Folgende Schritte KÖNNEN notwendig sein, sodass ein Termin durch einen Termin Requestor in ein 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 zu implementieren ist. Es wird als Best-Practice auf das ISiK-Modul 'Sicherheit' verwiesen.

  1. Abfrage aller Kodierungen der Behandlungsleistungen: GET https://example.org/fhir/CodeSystem?context-type-value=https://gematik.de/fhir/isik/v2/CodeSystem/ContextType|ResourceUsage$http://hl7.org/fhir/definition-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.

  1. Abfrage aller verfügbaren Kalender: GET https://example.org/fhir/Scheudle

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

  1. Abfrage aller verfügbaren Slot für einen Kalender: GET https://example.org/fhir/Slot?schedule=<Scheudule/ISiKKalenderExampple>

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

  1. Anlage einer Patient-Ressource: POST https://example.org/fhir/Patient
{
    "resourceType": "Patient",
    "meta": {
        "tag": [
            {
                "system": "http://fhir.de/CodeSystem/common-meta-tag-de",
                "code": "external"
            }
        ]
    }
    [...]
}

  1. Aufruf der $book-Operation: POST https://example.org/fhir/Appointment/$book
{
    "resourceType": "Parameters",
    "parameters": [
        {
            "name": "appt-resource",
            "resource": {
                "resourceType": "Appointment",
                "status": "proposed",
                "start": "2022-12-10T09:00:00Z",
                "end": "2022-12-10T11:00:00Z",
                "slot":  [
                    {
                        "reference": "ISiKSlotExample"
                    }
                ],
                "specialty":  [
                    {
                        "coding":  [
                            {
                                "code": "010",
                                "system": "urn:oid:1.2.276.0.76.5.114"
                            }
                        ]
                    }
                ],
                "participant":  [
                    {
                        "actor": {
                            "display": "Test Patient",
                            "reference": "Patient/example"
                        },
                        "status": "accepted"
                    }
                ]
            }
        }
    ]
}

Antwort:

{
    "resourceType": "Bundle",
    "type": "searchset",
    "entry": [
        {
            "fullUrl": "https://example.org/fhir/Appointment/ISiKAppointmentTest",
            "resource":         {
            "name": "appt-resource",
            "resource": {
                "resourceType": "Appointment",
                "status": "booked",
                "start": "2022-12-10T09:00:00Z",
                "end": "2022-12-10T11:00:00Z",
                "slot":  [
                    {
                        "reference": "ISiKSlotExample"
                    }
                ],
                "specialty":  [
                    {
                        "coding":  [
                            {
                                "code": "010",
                                "system": "urn:oid:1.2.276.0.76.5.114"
                            }
                        ]
                    }
                ],
                "participant":  [
                    {
                        "actor": {
                            "display": "Test Patient",
                            "reference": "Patient/example"
                        },
                        "status": "accepted"
                    }
                ]
            }
        }
        }
    ]
}


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 dieses Mechanismus.

Eine Aktualisierung der Ressource erfolgt mittels einer HTTP PATCH-Interaktion. Updates einer Appointment-Ressource MUSS das Termin Repository untersützen. Es MUSS mindestens die PATCH-Interaktion auf Basis einer FHIRPath-Patch-Parameter Ressource unterstüzt 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)

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 Termin

{
    "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.