Te Whatu Ora, Central Region Integration Hub
1.0.12-rc1 - ci-build New Zealand flag

Te Whatu Ora, Central Region Integration Hub, published by Te Whatu Ora, Te Pae Hauora o Ruahine o Tararua, MidCentral. This guide is not an authorized publication; it is the continuous build for version 1.0.12-rc1 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/tewhatuora/centralRegion-integrationHub-ig/ and changes regularly. See the Directory of published versions

Patient Update Subscriptions

The Refer Patient use case includes a step whereby API client registers a Subscription to receive notifications for updates to a particular Patient record.

The Central Region Integration Hub only accepts subscriptions with the rest-hook channel type. The API client is able to choose between two styles of notification:

  1. Single resource notifications, where the updated resource is included in the notification call-back.
  2. Bundle resource notifocations, where the notifcation call-back payload can be an arbitrary bundle of resources.

Single Resource Notification (Patient)

Sample Subscription for a single resource notification on changes to Patient with NHI of ZKG3868. The matching callback will:

  • be an http PUT rest call to a url constructed from the given endpoint value plus the patient resource identifier, eg: http:localhost:3000/fhir/callback/Patient/1956
  • contain a single updated Patient resource.
{
    "resourceType": "Subscription",
    "status": "active",
    "criteria": "Patient?identifier=ZKG3868",
    "channel": {
        "type": "rest-hook",
        "endpoint": "http://localhost:3000/fhir/callback",
        "payload": "application/json"
    },
}

The expected notification will have the form:

{
   "resourceType": "Patient",
   "id": "326"

   ...

}

Bundle Resource Notification (Patient)

Sample Subscription for a bundle resource notification on changes to Patient with NHI of ZKG3868. The matching callback will:

  • be an http POST rest call to the given endpoint value: http:localhost:3000/fhir/callback
  • contain an arbitrary Bundle resource containing the various resources included in the payload-search-criteria parameter.

Details on all the various query parameters that can be included in the payload-search-criteria parameter are given in the relevant FHIR Tutorial. In the following example we get the triggering Patient resource plus:

  • Flag resources with the given Patient as subject.
  • AllergyIntolerance resources with the given Patient as patient.
  • ClinicalImpression resources with the given Patient as subject.
  • ServiceRequest resources with the given Patient as subject.
{
    "resourceType": "Subscription",
    "id": "325",
    "status": "active",
    "criteria": "Patient?identifier=ZKG3868",
    "channel": {
        "type": "rest-hook",
        "endpoint": "http://localhost:3000/fhir/callback",
        "payload": "application/json"
    },
    "extension": [ {
        "url": "http://hapifhir.io/fhir/StructureDefinition/subscription-payload-search-criteria",
        "valueString": "Patient?_id=${matched_resource_id}&_include=*&_revinclude=Flag:*&_revinclude=AllergyIntolerance:*&_revinclude=ClinicalImpression:*&_revinclude=ServiceRequest:*"
      } ]
}

The expected notification will have the form:

{
  "resourceType": "Bundle",
  "id": "b1a0635f-3527-4d6c-b5c0-c727d2a2d2be",
  "meta": {
    "lastUpdated": "2024-06-07T12:55:31.933+12:00"
  },
  "type": "searchset",
  "total": 1,
  "link": [ {
    "relation": "self",
    "url": "http://localhost:8080/fhir/Patient?_id=326&_include=*&_revinclude=Flag:*&_revinclude=AllergyIntolerance:*&_revinclude=ClinicalImpression:*&_revinclude=ServiceRequest:*"
  } ],
  "entry": [ {
    "fullUrl": "http://localhost:8080/fhir/Patient/326",
    "resource": {
      "resourceType": "Patient",
      "id": "326"

      ...
    } 
  } ]
}

Bundle Resource Notification (Referral)

Sample Subscription for a bundle resource notification on patient referrals to the Mental Health and Additiction Serivces clinics. The matching callback will:

  • be an http POST rest call to the given endpoint value: http:localhost:3000/fhir/callback
  • contain an arbitrary Bundle resource containing the various resources included in the payload-search-criteria parameter.

Details on all the various query parameters that can be included in the payload-search-criteria parameter are given in the relevant FHIR Tutorial. In the following example we get the triggering ServiceRequest resource plus:

  • Practitioner resources for the three Practitioners involved in the referral:
    1. requestor
    2. performer
    3. consultingPractitioner
  • Organization resource for the referringPractice in the referral.
  • Patient resource for the referred patient.
  • Flag resources with the referred Patient as subject.
  • AllergyIntolerance resources with the referred Patient as patient.
  • ClinicalImpression resources with the referred Patient as subject. 
    {
"resourceType": "Subscription",
"id": "325",
"status": "active",
"criteria": "ServiceRequest?clinicType=MMA",
"channel": {
    "type": "rest-hook",
    "endpoint": "http://localhost:3000/fhir/callback",
    "payload": "application/json"
},
"extension": [ {
    "url": "http://hapifhir.io/fhir/StructureDefinition/subscription-payload-search-criteria",
    "valueString": "ServiceRequest?_id=${matched_resource_id}&_include=ServiceRequest:*&_include=Patient:*&_revinclude:iterate=AllergyIntolerance:*&_revinclude:iterate=Flag:*&_revinclude:iterate=ClinicalImpression:*"
  } ]
}

The expected notification will have the form:

{
  "resourceType": "Bundle",
  "id": "b1a0635f-3527-4d6c-b5c0-c727d2a2d2be",
  "meta": {
    "lastUpdated": "2024-06-07T12:55:31.933+12:00"
  },
  "type": "searchset",
  "total": 1,
  "link": [ {
    "relation": "self",
    "url": "http://localhost:8080/fhir/Patient?_id=326&_include=*&_revinclude=Flag:*&_revinclude=AllergyIntolerance:*&_revinclude=ClinicalImpression:*&_revinclude=ServiceRequest:*"
  } ],
  "entry": [ {
    "fullUrl": "http://localhost:8080/fhir/Patient/326",
    "resource": {
      "resourceType": "Patient",
      "id": "326"

      ...
    } 
  } ]
}

Manual Subscription Triggering

The test instance of SmileCDR at test-smilecdr.mdhb.health.nz has been configured to allow manual triggering of subscriptions. Full details on this capability are available at SmileCDR Documentation.

In short, posting a suitable Parameter structure to https://test-smilecdr.mdhb.health.nz:8000/Subscripton/{id}/$trigger-subscription will cause the Subscription's notification(s) to be sent out.

The Parameter request body is as follows:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "searchUrl",
      "valueString": "Patient?identifier=ZKG3868"
    }
  ]
}

Subscription Status

Subscriptions once created can be switched on and off by setting the status field to the appropriate value:

  • active - The subscription is active.
  • off - The subscription has expired.