Magentus Practice Management FHIR® Implementation Guide - Downloaded Version 1.3.2 See the Directory of published versions

Bookings

Theatre Bookings use a combination of Appointment and AppointmentResponse resources to negotiate agreement for 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.

The full set of participant slices on EBookingsAppointment.participant is shown below. Each slice has a fixed participant.type coding so a hospital can discriminate roles without inspecting the actor reference. required = #required is set on the patient, hospital, and provider slices in the profile.

At this stage, the Hospital is only focussed on the Hospital's role in the Theatre Booking which is inclusive of location/theatre, staff, and equipment as managed by the Hospital. In future, we expect to represent these as independent participants so that theatre booking agreement can be more transparent and granular.

Theatre Booking Information Model

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

Appointment data dictionary

Required and Must-Support elements on EBookingsAppointment:

Supporting information

supportingInformation on EBookingsAppointment is open-sliced with three Magentus-defined slices. Each slice has a different cardinality and role:

The anaesthetic and prosthesis slots can be carried either by reference (a standalone resource on the server) or contained inside the EBookingsAppointment. The pdf slot is reference-only — there is no contained slice for PDFs.

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 and then acted upon. 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 within the AppointmentResponse. There may be multiple iterations of Appointment updates and AppointmentResponses.

Theatre Booking Resource Profiles

Profiles referenced directly from the Appointment and the wider booking graph:

supportingInformation reference targets on the Appointment:

Profiles carried as contained resources:

Theatre Booking Response Model

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

Theatre Booking Response Profiles

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

Responding to a Booking

When a hospital receives a new or updated Appointment, it creates an AppointmentResponse to indicate its participation status. The response references the Appointment and identifies the hospital via a GSHealthcareService actor carrying the hospital's provider number.

Key fields

Creating a response

POST [base]/AppointmentResponse

{
  "resourceType": "AppointmentResponse",
  "meta": {
    "profile": ["http://fhir.geniesolutions.io/StructureDefinition/ebookings-appointmentresponse"]
  },
  "appointment": { "reference": "Appointment/840fdd86-f273-4c56-89af-cc5dcda59" },
  "start": "2022-04-01T11:45:00.000+10:00",
  "participantType": [{ "coding": [{ "system": "http://snomed.info/sct", "code": "22232009", "display": "Hospital" }] }],
  "actor": {
    "reference": "HealthcareService/ashford-private-hospital",
    "identifier": {
      "type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "PRN" }], "text": "Hospital Provider Number" },
      "system": "https://www.health.gov.au/resources/publications/list-of-declared-hospitals",
      "value": "0065020L"
    },
    "display": "Ashford Private Hospital"
  },
  "participantStatus": "accepted",
  "comment": "Awaiting admission form from patient"
}

See AppointmentResponse Example for a full example.

Updating a response

To change an existing response (e.g. from tentative to accepted), PUT to the existing resource. Use the If-Match header carrying the resource's current meta.versionId so the server can detect lost updates (optimistic concurrency).

PUT [base]/AppointmentResponse/[id]
If-Match: W/"4"

Response Statuses and Hospital Triage

Hospitals rarely accept a booking in one step. A booking typically passes through two layers, and the response status tells the VMO which layer it has reached.

1. Automated triage. An agent checks the booking against the hospital's own data requirements — needs that are local to the hospital, and are neither mandated by this IG nor enforced by the PMS. If something is missing, the hospital responds needs-action.
2. Human triage. Most hospitals do not pass a booking straight to their PAS. Once it clears automated triage it waits for a booking clerk. The hospital responds tentative to say the booking has progressed but no acceptance decision has been made.

The clerk then sends it to the PAS and responds accepted, raises a needs-action of their own, or declines.

Current behaviour: the platform does not leave the booking unchanged after a declined response. When a hospital or a patient responds declined, the platform sets Appointment.status to cancelled and tells the practice. The VMO does not cancel the booking. A consumer should expect a declined response to be followed by an update of the Appointment to cancelled. A hospital that will not fulfil a booking responds declined. It does not change the Appointment itself.

Two points follow from this.

• tentative always leaves the booking pending. If the Appointment was already booked — for example the booking was modified and re-entered triage — a tentative response returns it to pending.
• tentative is not a resting state. It records progress, not a decision, and is expected to resolve to accepted, needs-action or declined. A VMO should not treat it as an outcome.

The distinction that matters to a VMO is whether action is required. needs-action asks the VMO for something. tentative asks for nothing and simply reports movement.

start is a proposal only with needs-action. A counter-proposed operation time is a request to the practice, so only the one status that asks for something can carry one. With accepted, start may echo the booked time for information, as in the worked example below. It should match Appointment.start. If it does not, Appointment.start stays the source of truth and the placer ignores the difference. A hospital that wants a different time sends needs-action. With tentative or declined, start is not expected: tentative reports that no decision has been made, and declined ends the hospital's involvement. A placer treats start as a proposal only when participantStatus is needs-action.

Send a comment with a tentative response. It is the hospital's opportunity to say where the booking sits and when a decision is likely — "with the booking clerk, expected Thursday", "theatre list not yet drafted for that week". This is worth doing, and it is the best defence against the stall described below.

A comment on a tentative response is informational only. Unlike a comment accompanying needs-action, it never implies work for the practice. A VMO should read it for context and must not treat it as a task.

When a booking stalls at tentative

That last point carries a hazard. needs-action prompts the VMO, so it surfaces on its own — someone is waiting on the practice and the practice can see it. tentative prompts nobody. The booking is waiting on a hospital clerk, and nothing on the VMO side asks for attention.

A booking can therefore sit at tentative indefinitely, for ordinary human reasons: the clerk is away, the queue is long, the item was missed, the person has moved on. Neither system is at fault and no error is raised. The booking simply goes quiet while the operation date approaches.

A placer should age-monitor for this rather than wait to be told. The condition is:

• the Appointment is still pending, and
• the most recent AppointmentResponse for it has participantStatus of tentative, and
• that response is older than the practice's tolerance.

Search for the responses to a booking and take the most recent by meta.lastUpdated:

GET [base]/AppointmentResponse?appointment=Appointment/[id]&_sort=-_lastUpdated&_count=1

Set the tolerance against the operation date, not the response date. A booking tentative for a fortnight with theatre three months away is unremarkable; the same booking with theatre next week needs a phone call. Escalation is a practice matter, not a FHIR one — the remedy is to contact the hospital, not to change the resource. A placer must not resolve a tentative on the hospital's behalf.

Theatre Lists

A Theatre List is a snapshot of multiple theatre bookings — typically a day's operating list for a hospital — packaged as a FHIR document for sharing with the hospital. A theatre list is distinct from an individual booking: bookings are negotiated between the VMO and the hospital via Appointment and AppointmentResponse, whereas a theatre list is a read-only, attested record at a point in time that aggregates many bookings into a single artefact.

The list is modelled as a Bundle of type = #document whose first entry is a Composition. Each section of the Composition corresponds to one booking and references the booking's Appointment, ServiceRequest, Consent, and other supporting resources via Bundle entry fullUrl.

See Theatre List for the document shape, per-booking section structure, status mapping, and a worked example.

Profiles

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 an AppointmentResponse received from a Hospital and other business needs of the VMO. The following diagram shows the status changes in a booking.

The valid Appointment.status transitions are:

A tentative response can only leave the booking in pending. See Response Statuses and Hospital Triage.

cancelled is a terminal state — no further transitions are permitted once a booking reaches this status.

fulfilled is not currently used. That the booked procedure was performed is not recorded on the Appointment in this release. The hospital records the admission on the Encounter instead, and sets Encounter.status = finished and period.end when the patient is discharged. A practice may take a finished encounter to mean that the procedure was performed, unless the booking was cancelled. For an inpatient stay, discharge can be days after the operation.

Theatre Booking Content Changes

Theatre Bookings typically go through a series of changes from the time they meet the minimum data set and are accepted into the FHIR server as a booking, up until the time of theatre. These changes are of a mixed blessing. Dealing with bookings that may change means that bookings will likely be accessible earlier and thus carry the intent of theatre if not the final theatre form. Restricting or inhibiting bookings from early exposure to the hospital is more likely to result in later sharing of theatre bookings by VMOs and less time to more efficiently use theatre slots or hospital resources.

Booking changes will reflect in one or more FHIR resources that are part of the Theatre Booking data set. There are a few ways of being notified of and processing these changes:

1. Subscribe to all resource types of interest. Notifications will be received when any of these resources change or are created.
   • The downside to this approach is that it will not be clear how these individual resources relate to a particular Appointment.
2. Subscribe to only the Appointment resource for tracking changes and creation.
   • The downside to this approach is that change can occur outside of the Appointment resource and these will not automatically create a notifiable change or creation in the Appointment subscription.
   • The Appointment does carry a lastModified extension which is updated when a 'change of significance' has occurred in the booking data. However, this is only a time field and does not tell you what changed. The table below lists which resource changes count as a significant change for the purposes of bumping lastModified.
   • It is possible to look at the new Basic resource that tracks changes, additions, and modifications to data in the booking. A customised Subscription can include this change data in the notification for an Appointment.

What constitutes a change of significance

1. Subscribe to the new Basic change resource itself. It will tell you of changes in the whole of the appointment/booking data including the links to the resources and attributes that have changed. You can then decide whether that resource should be downloaded so the nature of the change can be investigated. See Basic Change Subscription below for a worked example.

Option (3) is the recommended approach. Whichever is chosen a clear path should be defined for

1. notification of change,
2. identification of change, and
3. determining if it is a change of significance for the hospital.

A change to a consent — including replacement of the signed form and withdrawal — is always conveyed as an updated Consent resource. Consumers are not expected to detect document changes by polling the URL. See Bookings Consent for the document repository, custody and withdrawal arrangements.

Retrieving a Theatre Booking

The following GET searches for Appointments which are either in a pending or cancelled state that were last updated after a provided time.

Example

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

Including Other Data Relevant to the Appointment

In order to retrieve all booking data for the above Theatre Bookings, use the following _include and _revinclude parameters.

Example

GET [base]/Appointment?status=pending,cancelled & _lastUpdated=gt2022-12-13T12:30:00Z & _include=Appointment:actor & _revinclude=Basic:subject & _include=Appointment:based-on:ServiceRequest & _include:iterate=Patient:organization & _include:iterate=PractitionerRole:practitioner & _include:iterate=PractitionerRole:organization & _revinclude:iterate=Encounter:based-on & _revinclude:iterate=ChargeItem:context & _revinclude:iterate=Consent:data & _revinclude:iterate=Condition:subject:Patient & _revinclude:iterate=AllergyIntolerance:patient & _revinclude:iterate=RelatedPerson:patient

Note that

• the above example has include the Basic resource which is profiled to carry a specification of all additions, deletions, and modifications to the whole appointment (see Theatre Booking Changes)
• the practice specialty is carried in a contained HealthcareService included with the practice Organization resource

An example search response is shown in Bookings Appointment SearchSet Bundle

Retrieving a Specific Appointment

A similar approach is used to search for a specific Appointment with a known id.

Example

GET [base]/Appointment?_id=840fdd86-f273-4c56-89af-cc5dcda59 & _revinclude=Basic:subject & _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

Registering Subscriptions

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

If the Subscription is successfully processed by the FHIR server, the Subscription.status will be changed to active. There are other optional attributes in a FHIR Subscription. Amongst these is Subscription.end that specifies a time at which the Subscription should be ended.

Example The following example creates a new Subscription for the Appointment resource filtering on the status 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 [base]/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"]
  }
}

Basic Change Subscription

The recommended approach (option 3 in Theatre Booking Content Changes) is to subscribe to the Basic change resource rather than the Appointment directly, so that any change of significance anywhere in the booking is notified. The following example additionally uses the Smile CDR subscription-payload-search-criteria extension to control the notification payload — it re-reads the matched Basic resource and _includes its subject so the notification carries both the change data and the Appointment it belongs to.

The channel.header values below are illustrative placeholders only — supply your own credentials.

POST [base]/Subscription

{
  "resourceType": "Subscription",
  "extension": [
    {
      "url": "http://hapifhir.io/fhir/StructureDefinition/subscription-payload-search-criteria",
      "valueString": "Basic?_id=${matched_resource_id}&_include=Basic:subject"
    }
  ],
  "status": "requested",
  "reason": "Change resource additions and modifications plus include the related Appointment",
  "criteria": "Basic?",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://api.acmehospital.com.au/notification-api/notify",
    "payload": "application/fhir+json",
    "header": [
      "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=",
      "client_id: example-client-id",
      "client_secret: example-client-secret"
    ]
  }
}

For the notification this subscription produces, see Notification for a Payload Search Criteria Subscription.

Subscription Notification

The notification's HTTP method and body depend on the Subscription. This is Smile CDR / HAPI rest-hook delivery behaviour — base FHIR R4 does not mandate either:

When you use the subscription-payload-search-criteria extension, also set payload. This IG does not describe a Subscription that has the extension but no payload.

Receivers must therefore accept both POST and PUT on the endpoint.

Example — no payload

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

Notification for a Payload Search Criteria Subscription

The Basic Change Subscription above carries the subscription-payload-search-criteria extension, so its notifications take the third form. Smile CDR runs the criteria as a search, then delivers the results as a FHIR transaction. Four consequences matter to a receiver:

• The body is a transaction Bundle, not a searchset. There is no total and no link.
• Each entry carries request.method of PUT and a request.url, not a search.mode.
• fullUrl is relative (Basic/[id]), because it defaults to the versionless resource id.
• Matched and _included resources are flattened into one list. Nothing marks which was which, so distinguish them by resource type or by following Basic.subject.

Do not execute the Bundle as a transaction against your own store. It is a delivery envelope, and the PUT verbs are an artefact of how Smile CDR packages the search results.

Example — the Basic Change Subscription

The Basic and Appointment bodies are elided for length; see EBookingDifferenceExample and the Appointment example for the full resources.

POST https://api.acmehospital.com.au/notification-api/notify
Content-Type: application/fhir+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "Basic/a7f3c1e0-92b4-4d51-8e6c-1f0b2d3a4c5e",
      "resource": {
        "resourceType": "Basic",
        "id": "a7f3c1e0-92b4-4d51-8e6c-1f0b2d3a4c5e",
        "meta": {
          "versionId": "1",
          "lastUpdated": "2026-09-24T09:14:22.117+10:00",
          "profile": ["http://fhir.geniesolutions.io/StructureDefinition/ebookings-difference"]
        },
        "code": {
          "coding": [{
            "system": "http://fhir.geniesolutions.io/CodeSystem/basic-type",
            "code": "Difference"
          }]
        },
        "subject": { "reference": "Appointment/840fdd86-f273-4c56-89af-cc5dcda592ab" },
        "extension": [
          {
            "url": "http://fhir.geniesolutions.io/StructureDefinition/ebookings-difference-addition",
            "valueReference": { "reference": "ChargeItem/d16c9bd2-db58-482a-a572-83a094676d68" }
          },
          {
            "url": "http://fhir.geniesolutions.io/StructureDefinition/ebookings-difference-deletion",
            "valueString": "ChargeItem/123456789"
          },
          {
            "url": "http://fhir.geniesolutions.io/StructureDefinition/ebookings-difference-modification",
            "extension": [
              {
                "url": "reference",
                "valueReference": { "reference": "Consent/ecaf5c8d-5f6b-46b2-89e2-6a96304d6358" }
              },
              {
                "url": "attributeList",
                "extension": [
                  { "url": "attribute", "valueString": "status" },
                  { "url": "attribute", "valueString": "active" }
                ]
              }
            ]
          }
        ]
      },
      "request": { "method": "PUT", "url": "Basic/a7f3c1e0-92b4-4d51-8e6c-1f0b2d3a4c5e" }
    },
    {
      "fullUrl": "Appointment/840fdd86-f273-4c56-89af-cc5dcda592ab",
      "resource": {
        "resourceType": "Appointment",
        "id": "840fdd86-f273-4c56-89af-cc5dcda592ab",
        "meta": {
          "versionId": "4",
          "lastUpdated": "2026-09-24T09:14:22.048+10:00",
          "profile": ["http://fhir.geniesolutions.io/StructureDefinition/ebookings-appointment"]
        },
        "status": "pending",
        "serviceType": [{ "text": "Knee Replacement" }],
        "start": "2022-04-01T11:45:00.000+10:00",
        "end": "2022-04-01T12:00:00.000+10:00"
      },
      "request": { "method": "PUT", "url": "Appointment/840fdd86-f273-4c56-89af-cc5dcda592ab" }
    }
  ]
}

One substitution quirk to allow for: ${matched_resource_id} expands to the versionless qualified id, so Basic?_id=${matched_resource_id} becomes Basic?_id=Basic/a7f3c1e0-…. Smile CDR accepts that form; it is worth knowing when reading server search logs.

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.

Retrieving Notification Data

If no payload is specified in the Subscription or additional Theatre Booking data is required then it is up the hospital to retrieve the data from the FHIR server using a search. This will be different depending on whether the notification included FHIR resource data such as an Appointment or if it was an empty notification.

• If the id of the Appointment is available through the notification data then this can be used as the basis of the FHIR search. This is described in Retrieving a Specific Appointment above.

• If an empty notification was received then a search for all recent Theatre Booking changes should be performed as described in Retrieving a Theatre Booking above.

Note

If the Subscription is for the Basic changes resource and that resource arrives in the notification body — see Notification for a Payload Search Criteria Subscription — then data in that resource is sufficient to find all the changed Theatre Booking content. Note that this is not all the Theatre Booking data but rather links to only that which has changed. If the entire Theatre Booking data is required then follow the Retrieving a Specific Appointment guidance based on the Basic.subject reference to the Appointment.

Patient Identity Matching

A Theatre Booking arrives at the hospital with a patient already populated on the VMO side. The hospital must reconcile this against its own patient master index. EBookingsPatient carries the identifier slices needed to do this:

The matching algorithm is the receiver's responsibility. Recommended ordering: IHI exact match → Medicare exact match → DVA exact match → demographic match (family name + given + DOB + sex). When no confident match exists, the hospital should create a new candidate record and flag for manual reconciliation rather than silently merge.

Authorization

This IG is silent on authentication and authorization — the choice is implementation-specific between the shared FHIR server and its clients. Typical patterns observed in deployment:

• SMART on FHIR backend services (client_credentials grant) for server-to-server flows between the VMO PMS, the hospital, and the shared FHIR server. Each party uses a distinct client_id with system/* scopes scoped to the resource types they own or consume (typically system/Appointment.rs, system/AppointmentResponse.crus, system/Patient.rs, etc).
• Bearer tokens on subscription notifications via Subscription.channel.header = "Authorization: Bearer …" (shown in the Registering Subscriptions example) so the webhook target can verify the FHIR server.
• TLS pinning / mutual TLS for production endpoints, configured at the infrastructure layer.

Deployers should document their chosen scheme separately; integration partners need that document before they can connect.

Validation and Error Handling

Conformance failures are returned in standard FHIR shape — implementations should not surface them as opaque HTTP errors.

Business validation errors that are specific to the Theatre Booking workflow (for example, theatre slot conflict, hospital declines acceptance) are conveyed via Appointment.status / AppointmentResponse.participantStatus transitions and the Basic change record, not via HTTP error responses — the booking resource is accepted by the server even when the business outcome is a decline.