ISiKSubscription (Subscription)

ISiK Subscription

Motivation

Subscription ist eine FHIR Ressource, um als Client-System Benachrichtigungen über Events auf dem FHIR Server anzufragen. Der Subscription Mechanismus in FHIR R4 ist nicht geeignet, um alle relevanten Events (hier im Speziellen das Mergen von Patienten) zu unterstützen. Daher basiert das ISiK Subscription-Profil auf dem Subscriptions R5 Backport Profil von HL7.

Um als Subsystem über ein Subsription-Event informiert zu werden, KANN der FHIR Subscription Mechanismus gemäß des Subscriptions R5 Backport IGs von HL7 genutzt werden.

Kompatibilität

Das Profil ISiKSubscription basiert auf dem Backport-Subscription Profil. Der SubscriptionStatus, sowie das Subscription Notification Bundle werden unverändert direkt aus dem Subscriptions R5 Backport IG genutzt.

Hinweise zu Inkompatibilitäten können über die Portalseite gemeldet werden.

Bestätigungsrelevanz

VerbindlichkeitSHALL

Metadaten

Canonicalhttps://gematik.de/fhir/isik/StructureDefinition/ISiKSubscription
Statusactive
Version5.0.0
Basishttp://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription

Inhalt

idΣ0..1id
metaΣ0..1Meta
implicitRulesΣ ?!0..1uri
language0..1codeBinding
text0..1Narrative
containedI0..*Resource
extensionI0..*Extension
modifierExtension?! I0..*Extension
statusS Σ ?!1..1codeBinding
contactΣ0..*ContactPoint
endΣ0..1instant
reasonS Σ1..1string
id0..1string
id0..1id
extensionI0..0Extension
url1..1uriFixed Value
valueStringstring
value0..1System.String
errorΣ0..1string
id0..1string
id0..1id
extensionI0..0Extension
url1..1uriFixed Value
valueUnsignedIntunsignedInt
timeoutI0..1Extension(unsignedInt)
maxCountI0..1Extension(positiveInt)
modifierExtensionΣ ?! I0..*Extension
id0..1string
customChannelTypeS Σ I0..0Extension(Coding)
value0..1System.String
endpointS Σ0..1url
id0..1string
contentS Σ I1..1Extension(code)
value0..1System.String
headerS Σ0..*string
<StructureDefinition xmlns="http://hl7.org/fhir">
    <id value="ISiKSubscription" />
    <url value="https://gematik.de/fhir/isik/StructureDefinition/ISiKSubscription" />
    <version value="5.0.0" />
    <name value="ISiKSubscription" />
    <title value="ISiK Subscription" />
    <status value="active" />
    <experimental value="false" />
    <date value="2025-06-26" />
    <publisher value="gematik GmbH" />
    <description value="ISiK Subscription  \n### Motivation\n\nSubscription ist eine FHIR Ressource, um als Client-System Benachrichtigungen &#252;ber Events auf dem FHIR Server anzufragen. Der Subscription Mechanismus in FHIR R4 ist nicht geeignet, um alle relevanten Events (hier im Speziellen das Mergen von Patienten) zu unterst&#252;tzen. Daher basiert das ISiK Subscription-Profil auf dem [Subscriptions R5 Backport Profil von HL7](https://hl7.org/fhir/uv/subscriptions-backport/STU1.1/StructureDefinition-backport-subscription.html).\n\nUm als Subsystem &#252;ber ein Subsription-Event informiert zu werden, KANN der FHIR Subscription Mechanismus gem&#228;&#223; des [Subscriptions R5 Backport IGs von HL7](https://hl7.org/fhir/uv/subscriptions-backport/STU1.1/index.html) genutzt werden.\n\n### Kompatibilit&#228;t\n\nDas Profil ISiKSubscription basiert auf dem [Backport-Subscription Profil](https://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition-backport-subscription.html).\nDer [SubscriptionStatus](https://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition-backport-subscription-status-r4.html), sowie das [Subscription Notification Bundle](https://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition-backport-subscription-notification-r4.html) werden unver&#228;ndert direkt aus dem [Subscriptions R5 Backport IG](https://hl7.org/fhir/uv/subscriptions-backport/index.html) genutzt.  \n\nHinweise zu Inkompatibilit&#228;ten k&#246;nnen &#252;ber die [Portalseite](https://service.gematik.de/servicedesk/customer/portal/16) gemeldet werden." />
    <fhirVersion value="4.0.1" />
    <kind value="resource" />
    <abstract value="false" />
    <type value="Subscription" />
    <baseDefinition value="http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription" />
    <derivation value="constraint" />
    <differential>
        <element id="Subscription.status">
            <path value="Subscription.status" />
            <short value="Status" />
            <comment value="**Bedeutung:** Der Status der Subscription, der den Serverstatus der Subscription angibt. \n  Neue Subscriptions werden immer mit dem Status `requested` an den Server &#252;bergeben. \n  Der Server &#228;ndert im Anschluss den Status auf `active` oder im Fehlerfall auf `error`." />
            <mustSupport value="true" />
        </element>
        <element id="Subscription.reason">
            <path value="Subscription.reason" />
            <short value="Grund der Subscription" />
            <comment value="**Bedeutung:** Beschreibung wieso diese Subscription erstellt wurde." />
            <mustSupport value="true" />
        </element>
        <element id="Subscription.criteria">
            <path value="Subscription.criteria" />
            <short value="Canonical URL des SubscriptionTopic welches man abonnieren m&#246;chte." />
            <comment value="Enth&#228;lt eines der in ISiK vereinbarten Subsription Topics." />
            <binding>
                <strength value="extensible" />
                <valueSet value="https://gematik.de/fhir/isik/ValueSet/ISiKSubscriptionTopicVS" />
            </binding>
        </element>
        <element id="Subscription.criteria.extension:filterCriteria">
            <path value="Subscription.criteria.extension" />
            <sliceName value="filterCriteria" />
            <short value="Filterkriterium." />
            <comment value="**Bedeutung:** Filterkriterium f&#252;r die Subscription. Dieses Feld ist optional und kann genutzt werden, um die Subscription auf bestimmte Events zu filtern." />
        </element>
        <element id="Subscription.criteria.extension:filterCriteria.value[x]">
            <path value="Subscription.criteria.extension.value[x]" />
            <mustSupport value="true" />
        </element>
        <element id="Subscription.channel">
            <path value="Subscription.channel" />
            <short value="Kommunikationskanal" />
            <comment value="**Bedeutung:** Kommunikationskanal &#252;ber den die Subscription Benachrichtigungen gesendet werden sollen." />
            <mustSupport value="true" />
        </element>
        <element id="Subscription.channel.extension:heartbeatPeriod">
            <path value="Subscription.channel.extension" />
            <sliceName value="heartbeatPeriod" />
            <short value="Heartbeat-Intervall" />
            <comment value="**Bedeutung:** Intervall in dem der Server pr&#252;ft, ob der Kommunikationskanal noch aktiv ist." />
            <mustSupport value="true" />
        </element>
        <element id="Subscription.channel.extension:heartbeatPeriod.value[x]">
            <path value="Subscription.channel.extension.value[x]" />
            <mustSupport value="true" />
        </element>
        <element id="Subscription.channel.type">
            <path value="Subscription.channel.type" />
            <short value="Typ des Kommunikationskanals" />
            <comment value="**Bedeutung:** Der Typ des Kommunikationskanals, &#252;ber den Subscription-Benachrichtigungen gesendet werden sollen.  \n    In ISiK MUSS der Wert `rest-hook` unterst&#252;tzt werden, weitere Werte K&#214;NNEN unterst&#252;tzt werden." />
            <mustSupport value="true" />
        </element>
        <element id="Subscription.channel.type.extension:customChannelType">
            <path value="Subscription.channel.type.extension" />
            <sliceName value="customChannelType" />
            <short value="Custom Channel Type" />
            <comment value="**Bedeutung:** Custom Channel Type welcher in ISiK aktuell nicht unterst&#252;tzt wird." />
            <max value="0" />
        </element>
        <element id="Subscription.channel.endpoint">
            <path value="Subscription.channel.endpoint" />
            <short value="Endpunkt" />
            <comment value="**Bedeutung:** Adresse des Kommunikationskanals/ Endpunkts, an den Subscription-Benachrichtigungen gesendet werden sollen. Dies ist nur f&#252;r rest-hook Subscriptions relevant." />
            <mustSupport value="true" />
        </element>
        <element id="Subscription.channel.payload">
            <path value="Subscription.channel.payload" />
            <short value="Format der Nutzdaten" />
            <comment value="**Bedeutung:** Format in dem Subscription Notifications versendet werden sollen (JSON oder XML)." />
            <mustSupport value="true" />
            <binding>
                <strength value="required" />
                <valueSet value="https://gematik.de/fhir/isik/ValueSet/FhirMimeTypeVS" />
            </binding>
        </element>
        <element id="Subscription.channel.payload.extension:content">
            <path value="Subscription.channel.payload.extension" />
            <sliceName value="content" />
            <short value="Inhalt der Nutzdaten" />
            <comment value="**Bedeutung:** Welcher Ressourceninhalt in der Nutzlast der Benachrichtigung geliefert werden soll.  \n      Zur Auswahl stehen eine leere Nutzlast (`empty`), nur die Ressourcen-id (`id-only`) oder der gesamte Inhalt der Ressource (`full-resource`)." />
        </element>
        <element id="Subscription.channel.header">
            <path value="Subscription.channel.header" />
            <short value="Falls eine REST-Enpunkt einen Authorization-Header ben&#246;tigt, kann dieser hier gesetzt werden" />
            <comment value="**Bedeutung:** http-Header welcher dazu genutzt werden kann einen Authorization-header zu setzen. Dies ist nur f&#252;r rest-hook Subscriptions relevant.  \n    **Hinweise:** ACHTUNG: dieses Datenfeld muss bei READ-Interaktionen maskiert werden! Siehe [R4 Subscriptions](https://hl7.org/fhir/R4/subscription.html)" />
            <mustSupport value="true" />
        </element>
    </differential>
</StructureDefinition>
{
    "resourceType": "StructureDefinition",
    "id": "ISiKSubscription",
    "url": "https://gematik.de/fhir/isik/StructureDefinition/ISiKSubscription",
    "version": "5.0.0",
    "name": "ISiKSubscription",
    "title": "ISiK Subscription",
    "status": "active",
    "experimental": false,
    "date": "2025-06-26",
    "publisher": "gematik GmbH",
    "description": "ISiK Subscription  \n### Motivation\n\nSubscription ist eine FHIR Ressource, um als Client-System Benachrichtigungen über Events auf dem FHIR Server anzufragen. Der Subscription Mechanismus in FHIR R4 ist nicht geeignet, um alle relevanten Events (hier im Speziellen das Mergen von Patienten) zu unterstützen. Daher basiert das ISiK Subscription-Profil auf dem [Subscriptions R5 Backport Profil von HL7](https://hl7.org/fhir/uv/subscriptions-backport/STU1.1/StructureDefinition-backport-subscription.html).\n\nUm als Subsystem über ein Subsription-Event informiert zu werden, KANN der FHIR Subscription Mechanismus gemäß des [Subscriptions R5 Backport IGs von HL7](https://hl7.org/fhir/uv/subscriptions-backport/STU1.1/index.html) genutzt werden.\n\n### Kompatibilität\n\nDas Profil ISiKSubscription basiert auf dem [Backport-Subscription Profil](https://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition-backport-subscription.html).\nDer [SubscriptionStatus](https://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition-backport-subscription-status-r4.html), sowie das [Subscription Notification Bundle](https://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition-backport-subscription-notification-r4.html) werden unverändert direkt aus dem [Subscriptions R5 Backport IG](https://hl7.org/fhir/uv/subscriptions-backport/index.html) genutzt.  \n\nHinweise zu Inkompatibilitäten können über die [Portalseite](https://service.gematik.de/servicedesk/customer/portal/16) gemeldet werden.",
    "fhirVersion": "4.0.1",
    "kind": "resource",
    "abstract": false,
    "type": "Subscription",
    "baseDefinition": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription",
    "derivation": "constraint",
    "differential": {
        "element":  [
            {
                "id": "Subscription.status",
                "path": "Subscription.status",
                "short": "Status",
                "comment": "**Bedeutung:** Der Status der Subscription, der den Serverstatus der Subscription angibt. \n  Neue Subscriptions werden immer mit dem Status `requested` an den Server übergeben. \n  Der Server ändert im Anschluss den Status auf `active` oder im Fehlerfall auf `error`.",
                "mustSupport": true
            },
            {
                "id": "Subscription.reason",
                "path": "Subscription.reason",
                "short": "Grund der Subscription",
                "comment": "**Bedeutung:** Beschreibung wieso diese Subscription erstellt wurde.",
                "mustSupport": true
            },
            {
                "id": "Subscription.criteria",
                "path": "Subscription.criteria",
                "short": "Canonical URL des SubscriptionTopic welches man abonnieren möchte.",
                "comment": "Enthält eines der in ISiK vereinbarten Subsription Topics.",
                "binding": {
                    "strength": "extensible",
                    "valueSet": "https://gematik.de/fhir/isik/ValueSet/ISiKSubscriptionTopicVS"
                }
            },
            {
                "id": "Subscription.criteria.extension:filterCriteria",
                "path": "Subscription.criteria.extension",
                "sliceName": "filterCriteria",
                "short": "Filterkriterium.",
                "comment": "**Bedeutung:** Filterkriterium für die Subscription. Dieses Feld ist optional und kann genutzt werden, um die Subscription auf bestimmte Events zu filtern."
            },
            {
                "id": "Subscription.criteria.extension:filterCriteria.value[x]",
                "path": "Subscription.criteria.extension.value[x]",
                "mustSupport": true
            },
            {
                "id": "Subscription.channel",
                "path": "Subscription.channel",
                "short": "Kommunikationskanal",
                "comment": "**Bedeutung:** Kommunikationskanal über den die Subscription Benachrichtigungen gesendet werden sollen.",
                "mustSupport": true
            },
            {
                "id": "Subscription.channel.extension:heartbeatPeriod",
                "path": "Subscription.channel.extension",
                "sliceName": "heartbeatPeriod",
                "short": "Heartbeat-Intervall",
                "comment": "**Bedeutung:** Intervall in dem der Server prüft, ob der Kommunikationskanal noch aktiv ist.",
                "mustSupport": true
            },
            {
                "id": "Subscription.channel.extension:heartbeatPeriod.value[x]",
                "path": "Subscription.channel.extension.value[x]",
                "mustSupport": true
            },
            {
                "id": "Subscription.channel.type",
                "path": "Subscription.channel.type",
                "short": "Typ des Kommunikationskanals",
                "comment": "**Bedeutung:** Der Typ des Kommunikationskanals, über den Subscription-Benachrichtigungen gesendet werden sollen.  \n    In ISiK MUSS der Wert `rest-hook` unterstützt werden, weitere Werte KÖNNEN unterstützt werden.",
                "mustSupport": true
            },
            {
                "id": "Subscription.channel.type.extension:customChannelType",
                "path": "Subscription.channel.type.extension",
                "sliceName": "customChannelType",
                "short": "Custom Channel Type",
                "comment": "**Bedeutung:** Custom Channel Type welcher in ISiK aktuell nicht unterstützt wird.",
                "max": "0"
            },
            {
                "id": "Subscription.channel.endpoint",
                "path": "Subscription.channel.endpoint",
                "short": "Endpunkt",
                "comment": "**Bedeutung:** Adresse des Kommunikationskanals/ Endpunkts, an den Subscription-Benachrichtigungen gesendet werden sollen. Dies ist nur für rest-hook Subscriptions relevant.",
                "mustSupport": true
            },
            {
                "id": "Subscription.channel.payload",
                "path": "Subscription.channel.payload",
                "short": "Format der Nutzdaten",
                "comment": "**Bedeutung:** Format in dem Subscription Notifications versendet werden sollen (JSON oder XML).",
                "mustSupport": true,
                "binding": {
                    "strength": "required",
                    "valueSet": "https://gematik.de/fhir/isik/ValueSet/FhirMimeTypeVS"
                }
            },
            {
                "id": "Subscription.channel.payload.extension:content",
                "path": "Subscription.channel.payload.extension",
                "sliceName": "content",
                "short": "Inhalt der Nutzdaten",
                "comment": "**Bedeutung:** Welcher Ressourceninhalt in der Nutzlast der Benachrichtigung geliefert werden soll.  \n      Zur Auswahl stehen eine leere Nutzlast (`empty`), nur die Ressourcen-id (`id-only`) oder der gesamte Inhalt der Ressource (`full-resource`)."
            },
            {
                "id": "Subscription.channel.header",
                "path": "Subscription.channel.header",
                "short": "Falls eine REST-Enpunkt einen Authorization-Header benötigt, kann dieser hier gesetzt werden",
                "comment": "**Bedeutung:** http-Header welcher dazu genutzt werden kann einen Authorization-header zu setzen. Dies ist nur für rest-hook Subscriptions relevant.  \n    **Hinweise:** ACHTUNG: dieses Datenfeld muss bei READ-Interaktionen maskiert werden! Siehe [R4 Subscriptions](https://hl7.org/fhir/R4/subscription.html)",
                "mustSupport": true
            }
        ]
    }
}

Constraints/Invarianten

Terminology-Bindings

ElementStaerkeValueSet
Subscription.criteriaextensiblehttps://gematik.de/fhir/isik/ValueSet/ISiKSubscriptionTopicVS
Subscription.channel.payloadrequiredhttps://gematik.de/fhir/isik/ValueSet/FhirMimeTypeVS

Anmerkungen zu Must-Support-Feldern

FeldnameKurzbeschreibungHinweise
Subscription.statusStatus

Bedeutung: Der Status der Subscription, der den Serverstatus der Subscription angibt. Neue Subscriptions werden immer mit dem Status requested an den Server übergeben. Der Server ändert im Anschluss den Status auf active oder im Fehlerfall auf error.

Subscription.reasonGrund der Subscription

Bedeutung: Beschreibung wieso diese Subscription erstellt wurde.

Subscription.criteria.extension:filterCriteria.value[x]
Subscription.channelKommunikationskanal

Bedeutung: Kommunikationskanal über den die Subscription Benachrichtigungen gesendet werden sollen.

Subscription.channel.extension:heartbeatPeriodHeartbeat-Intervall

Bedeutung: Intervall in dem der Server prüft, ob der Kommunikationskanal noch aktiv ist.

Subscription.channel.extension:heartbeatPeriod.value[x]
Subscription.channel.typeTyp des Kommunikationskanals

Bedeutung: Der Typ des Kommunikationskanals, über den Subscription-Benachrichtigungen gesendet werden sollen.
In ISiK MUSS der Wert rest-hook unterstützt werden, weitere Werte KÖNNEN unterstützt werden.

Subscription.channel.endpointEndpunkt

Bedeutung: Adresse des Kommunikationskanals/ Endpunkts, an den Subscription-Benachrichtigungen gesendet werden sollen. Dies ist nur für rest-hook Subscriptions relevant.

Subscription.channel.payloadFormat der Nutzdaten

Bedeutung: Format in dem Subscription Notifications versendet werden sollen (JSON oder XML).

Subscription.channel.headerFalls eine REST-Enpunkt einen Authorization-Header benötigt, kann dieser hier gesetzt werden

Bedeutung: http-Header welcher dazu genutzt werden kann einen Authorization-header zu setzen. Dies ist nur für rest-hook Subscriptions relevant.
Hinweise: ACHTUNG: dieses Datenfeld muss bei READ-Interaktionen maskiert werden! Siehe R4 Subscriptions

Interaktionen

InteraktionVerbindlichkeit
readSHALL
createSHALL
updateSHALL
deleteSHALL
search-typeSHALL
ParameterTypVerbindlichkeitHinweise
_idtokenSHALL

Beispiel: GET [base]/[Resourcetype]?_id=103270 Anwendungshinweis: Der Parameter _id wird selten alleinstehend verwendet, da sich zum Abruf einer Ressource anhand der id die READ-Interaktion besser anbietet. Der Parameter kann jedoch verwendet werden, um den Abruf einer Ressource bspw. mit einem _include weiterer Ressourcen zu verbinden, z.B. zum Abruf eines Encounters in Verbindung mit dem zugehörigen Patienten: GET [base]/Encounter?_id=103270&_include=Encounter:patient Weitere Details siehe FHIR-Kernspezifikation, Abschnitt Parameters for all resources. Dieser Suchparameter ist für die Umsetzung des IHE PDQm Profils verpflichtend.

_tagtokenSHALL

Beispiel: GET [base]/[Resourcetype]?_tag=https://example.org/codes|needs-review Anwendungshinweis: Weitere Details siehe FHIR-Kernspezifikation, Abschnitt Parameters for all resources sowie Abschnitt Tags.

_countnumberSHALL

Beispiel: GET [base]/[Resourcetype]?_count=100 Anwendungshinweis: Weitere Details siehe FHIR-Kernspezifikation, Abschnitt Page Count.

_hasstringMAY

Beispiel: Suche nach allen Patienten, die eine Observation mit dem Code '1234-5' haben GET [base]/Patient?_has:Observation:patient:code=1234-5 Beispiel: Suche nach allen Encountern, bei denen die Diagnose 'A12.3' gestellt wurde GET [base]/Encounter?_has:Condition:encounter:code=A12.3 Anwendungshinweis: Weitere Details siehe FHIR-Kernspezifikation, Abschnitt Reverse Chaining.

criteriastringSHALL

Beispiel:
GET [base]/Subscription?criteria=https://gematik.de/fhir/isik/SubscriptionTopic/patient-merge
Anwendungshinweis:
Dient dazu eine Subscription zu finden, die auf ein bestimmtes SubscriptionTopic verweist.
Weitere Details siehe FHIR-Kernspezifikation.

statustokenSHALL

Beispiel:
GET [base]/Subscription?status=requested
Anwendungshinweis:
Weitere Details siehe FHIR-Kernspezifikation.

urluriSHALL

Beispiel:
GET [base]/Subscription?url=http://example.org/fhir/
Anwendungshinweis:
Dient dazu eine Subscription zu finden, die auf einen REST-Endpoint verweist welcher die Subscription Notifications empfangen soll.
Weitere Details siehe FHIR-Kernspezifikation.

(Reverse-)Include

Command 'pagelink' could not render: Page not found.

Beispiele

Subscription
<Subscription xmlns="http://hl7.org/fhir">
    <id value="PatientMergeSubscriptionExample" />
    <meta>
        <profile value="https://gematik.de/fhir/isik/StructureDefinition/ISiKSubscription" />
    </meta>
    <status value="requested" />
    <reason value="Patient merge subscription" />
    <criteria value="https://gematik.de/fhir/isik/SubscriptionTopic/patient-merge" />
    <channel>
        <type value="rest-hook" />
        <endpoint value="http://localhost:8081/fhir/Bundle" />
        <payload value="application/fhir+json">
            <extension url="http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content">
                <valueCode value="full-resource" />
            </extension>
        </payload>
        <header value="Authorization: Bearer xxxxxxxxxx" />
    </channel>
</Subscription>
{
    "resourceType": "Subscription",
    "id": "PatientMergeSubscriptionExample",
    "meta": {
        "profile":  [
            "https://gematik.de/fhir/isik/StructureDefinition/ISiKSubscription"
        ]
    },
    "channel": {
        "type": "rest-hook",
        "endpoint": "http://localhost:8081/fhir/Bundle",
        "payload": "application/fhir+json",
        "_payload": {
            "extension":  [
                {
                    "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
                    "valueCode": "full-resource"
                }
            ]
        },
        "header":  [
            "Authorization: Bearer xxxxxxxxxx"
        ]
    },
    "status": "requested",
    "reason": "Patient merge subscription",
    "criteria": "https://gematik.de/fhir/isik/SubscriptionTopic/patient-merge"
}