HL7® FHIR® Malaysia Core (MY Core) Implementation Guide
2.0.1 - ci-build

HL7® FHIR® Malaysia Core (MY Core) Implementation Guide - Local Development build (v2.0.1) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Scheduling and Appointment

Overview

A Scheduling record comprises of a Schedule (MY Core) and a Slot (MY Core).

  • In HIE, both these records are created in conjunction with one another thus it is recommended to be sent as a Bundle operation.
  • Each Schedule and Appointment is required to reference an existing HealthcareService (MY Core).
    • A HealthcareService must be set up before a Schedule, Slot and/or Appointment record can be made.
  • The Schedule elements Schedule.serviceCategory, Schedule.serviceType and Schedule.specialty must go according to the referenced HealthcareService.
  • The Slot elements Slot.serviceCategory, Slot.serviceType and Slot.specialty must go according to the referenced HealthcareService.

An Appointment booking is stored as an Appointment (MY Core).

  • Generally, an Appointment will reference an existing Slot in HIE.
  • However, an Appointment can also be created independently without a Slot referenced, for example walk-in clinics with no quotas. For such a use case, base FHIR® Appointment has set a constraint that the Appointment.status cannot be defined as "booked".
  • When an Appointment is booked under an existing Slot, it must reference the Slot in Appointment.slot.reference
Sample Data and API

[base] = address url e.g. "https://fhir.hie.moh.gov.my/baseR4/"
[type] = resource type e.g. "Patient | Appointment | Schedule"
@recordId = unique record ID defined from source system e.g. "appointment-sample"

Sample Description Sample Body API Method API
Create/Update scheduling

1. Bundle with ID

2. Bundle without ID

 POST [base]
Create/Update booking

Booking Bundle

 POST [base]
Retrieve record with ID - GET [base]/[type]/@recordId
Retrieve Schedule record with Slot included - GET [base]/Schedule?_revinclude=Slot:schedule&_id=@scheduleId
Retrieve Slot record with Schedule included - GET [base]/Schedule?_include=Slot:schedule&_id=@slotId
Create and update Appointment record Appointment PUT [base]/Appointment/@appointmentId

Slot quota

The Slot resource has an extension ExtensionSlotQuota (MY Core) where the elements "quota" and "available" are defined, Slot.extension.where (url = "http://fhir.hie.moh.gov.my/StructureDefinition/slot-quota-my-core"):

  • "quota" represents the total amount of appointments allowed.
  • "available" represents current available appointment spaces in the Slot.

A slot "available" count is deducted when an appointment references it, therefore:

  • it is suggested to update both the Appointment and Slot together as a Bundle operation.
  • the total amount of Appointment booked must not exceed the quota defined to prevent overbooking.

Diagram below shows the visual flow of the relation between each resources.

Scheduling-flow

Type of Schedule

Schedule (MY Core) currently defines 3 types of Scheduling, namely "Internal", "Affiliate" and "Public", stored in Schedule.scheduleType.

  • "Internal" type indicates that the Schedule is only open for Appointment booking by an internal user (within the same organization).
  • "Affiliate" type indicates that the Schedule is open for Appointment booking internally and by affiliated facilities (through OrganizationAffiliation (MY Core) setup).
  • "Public" type indicates that the Schedule is open for Appointment booking by any party including the public such as a patient or customer.

Scheduling & Appointment Integration

Scheduling integration with a different source system can be achieved when a Schedule record complies to the Schedule (MY Core) and Slot (MY Core) standards. By creating Schedules and Slots in HIE, users using RekodPesakit or RekodSaya will be able to book Appointments referencing the created Schedules and Slots. If there are other sources to create an Appointment such as from the source system itself, it is important that the Schedule and Slot version in HIE must always be updated to prevent multiple versions of the same Schedule.

The diagram below shows an overview of the Scheduling and Appointment booking flow integration points.

Scheduling and Integration


  1. Source System uses HIE API to send Schedule and Slot record.
  2. Appointment is booked through HIE RekodPesakit/RekodSaya.
  3. The Slot referenced by the Appointment will be updated to -1 quota in HIE and a record of the Appointment is created in Kafka.
  4. Source System is able to retrieve the Appointment Record in Kafka to update their record.
  5. Once the Appointment has been updated (fulfilled, noshow, etc) at source, the source system is also expected to update the initial Appointment created in HIE (Otherwise the HIE portal will update status:"noshow" by default on the following day based on the start date of the appointment).

Refer to the Subscription Guide section under "Appointment topic" for details on subscriptions using Kafka Apache.

Appointment Integration Only

An Appointment (MY Core) can be created even if no Scheduling is present (when slot is not referenced in Appointment). Once the Appointment has been updated (fulfilled, noshow, etc) at source, the source system is also expected to update the initial Appointment created in HIE (Otherwise the HIE portal will update status:"noshow" by default on the following day based on the start date of the appointment).