Magentus Practice Management FHIR Implementation Guide - Local Development build (v1.2.35) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Bookings

Theatre Bookings uses a combination of Appointment and AppointmentResponse resources to negotiate agreement around the finalisation of a Theatre Booking. Appointment resources are created and managed by the VMO while AppointmentResponses are created by participants in the booking to indicate their ability to participate, or in our case the acceptance of the proposed Theatre Booking to the hospital. Participants can include people, equipment, and locations. Our initial implementation identifies the following participants: VMO, Hospital, Patient, Assistant, and Anaesthetist. At this stage, the Hospital is only focussed on the Hospital's role in the Theatre Booking whoich is inclusive of location/theatre, staff, and equipment as managed by the Hospital.

Theatre Booking Information Model

The FHIR Resources for a Theatre Booking and manifested through a FHIR Appointment are shown in the diagram below. The Appointment is at the centre of this set of FHIR Resources and link to/from this resource allowing the package of resources to be discovered through an Appointment search.

Theatre Booking Interaction Model

Unlike traditional healthcare integration approaches, our approach to Theatre Booking is not based on a point-to-point messaging model. Instead the VMO Practice Management System (PMS) and the Hospital interact through a shared FHIR server in which Appointments and AppointmentResponses are stored. Each partner tracks change in this common FHIR repository to understand the status of a Theatre Booking. Monitoring for booking changes can either be through polling with a FHIR search or via a subscription to changes based on search criteria of interest. Key to these interactions are changes in the Status of the Appointment and Status of a participant's agreement via the AppointmentResponse.

Theatre Booking Status Changes

Bookings that end up in a cancelled state do not change from that final state. However, pending and booked states for a Theatre Booking can change depending on the status of a AppointmentResponse received from a Hospital. The following diagram shows the status changes in a booking based upon those responses.

Theatre Booking Resource Profiles

The FHIR Profiles for the resources of interest are listed below.

Additional EBooking Resources are contained within the resources above, the FHIR profiles for these resources are listed below.

Theatre Booking Response Model

The FHIR Resources generated and referenced by the Bookings Partner are shown in the diagram below.

Bookings Response Profiles

The FHIR Profiles used by the Bookings Partner are listed below.

Bookings POST Notification Subscriptions

Registering a POST Notification Subscription

In order to receive subcription notifications from the FHIR Server when resources of interest are created or updated, a subscription is registered. A subscription request includes the following properties.

Example The following example creates a new Subscription for the Appointment resource with a criteria on the status element filtering on the values of pending OR cancelled (Note: the comma delimitor between parameter values represents an OR, see https://hl7.org/fhir/r4/search.html#combining).

POST /Subscription

{
  "resourceType": "Subscription",
  "criteria": "Appointment?status=pending,cancelled",
  "status": "requested",
  "reason": "Appointment pending and cancelled subscription",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://webhook.site/bbd78ee4-e267-4633-8acc-38a5e1dc54a0",
    "header": ["Authorization: Bearer secret-token-abc-123"]
  }
}

The Subscription endpoint can also be used to Search, Read, Update and Delete as per the standard FHIR REST API pattern.

Subscription POST Notification

A subcription notification is received as a POST request on the endpoint specified in the subscription registration request. The POST request has an empty body.

Example

POST https://webhook.site/bbd78ee4-e267-4633-8acc-38a5e1dc54a0
Authorization: Bearer secret-token-abc-123

Responding to a Subscription Notification

The subscription notification shall respond as quickly as possible with a success status of 200 OK or 202 Accepted, and an empty body. The latter is normally returned when the request is accepted for processing but processing will commence after the response has been returned, which is the preferred approach for subscription notifications.

Any error response may result in a subsequent retry by the FHIR Server to submit the Subscription Notification until the number of retries is exceeded at which time the FHIR Server will stop the subscription. See Managing Subscriptions and Errors for more details.

Retreiving Subscription POST Notification Data

When a subscription notification is received, perform a Search request with the corresponding criteria along with a _lastUpdated parameter with the timestamp when the last search request was performed with the gt prefix (see https://hl7.org/fhir/r4/search.html#prefix).

Example

GET /Appointment?status=pending,cancelled&_lastUpdated=gt2022-12-13T12:30:00Z

Include Referenced Resources

In order to retrieve the entire Bookings transaction, use the following _include and _revinclude parameters.

Example

GET /Appointment?status=pending,cancelled&_lastUpdated=gt2022-12-13T12:30:00Z&_include=Appointment:based-on&_include:iterate=ServiceRequest:requester&_include=Appointment:actor&_revinclude:iterate=Encounter:based-on&_revinclude:iterate=Consent:data&_include:iterate=Patient:organization&_revinclude:iterate=ChargeItem:context&_include:iterate=PractitionerRole:practitioner&_include:iterate=PractitionerRole:organization

An example search response is shown in Bookings Appointment SearchSet Bundle

POST Search Request

Alternatively, the FHIR _search request using a HTTP POST may be used as shown in the following example.

Example

POST /Appointment/_search
Content-Type: application/x-www-form-urlencoded

status=pending,cancelled
_lastUpdated=gt2022-12-13T12:30:00Z
_include=Appointment:based-on
_include=iterate:ServiceRequest:requester
_include=Appointment:actor
_revinclude:iterate=Encounter:based-on
_revinclude:iterate=Consent:data
_include:iterate=Patient:organization
_revinclude:iterate=ChargeItem:context
_include:iterate=PractitionerRole:practitioner
_include:iterate=PractitionerRole:organization

Bookings PUT Notification Subscriptions

Alternativly, you can create a Subscription that executes a PUT notification request that contains the relative reference to the FHIR Resource that triggered the notification.

This approach may be preferred as it will enable the notification listener to retrieve only the specific resource that triggered notification and not need to manage the possibility of retreiving multiple resources to process as part of the notification's corresponding Search request.

Registering a PUT Notification Subscription

In order to receive subcription notifications from the FHIR Server with the resource reference that triggered the notification, use a subscription registration request with the following parameters.

Example

POST /Subscription

{
  "resourceType": "Subscription",
  "criteria": "Appointment?status=pending,cancelled",
  "status": "requested",
  "reason": "Appointment pending and cancelled subscription with resource reference",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://webhook.site/bbd78ee4-e267-4633-8acc-38a5e1dc54a0",
    "header": ["Authorization: Bearer secret-token-abc-123"],
    "payload": "application/fhir+json"
  }
}

Subscription PUT Notification

This subcription notification is received as a PUT request on the endpoint specified in the subscription registration request. The PUT request conatines the relative reference to the Resource that triggered the notification and an empty body.

Example

PUT https://webhook.site/bbd78ee4-e267-4633-8acc-38a5e1dc54a0/Appointment/840fdd86-f273-4c56-89af-cc5dcda59
Authorization: Bearer secret-token-abc-123

Retreiving Subscription PUT Notification Data

When a subscription PUT notification is received, you can retreive the referenced resource using a Search request with an _id parameter. Note that there is no need for the corresponding subscription criteria and _lastUpdated parameters as this request will directly retreive the specific resource that triggered the subscription.

Example

GET /Appointment?_id=840fdd86-f273-4c56-89af-cc5dcda59

The _include and _revinclude parameters may also be used as described above.