MHNexus Sdn Bhd
0.1.0 - ci-build

Scheduling & Appointment

A container for slots of time that may be available for booking appointments.

Sample Data and API

Click MY Core postman API link to view common API used in HIE.

[base] = address url e.g. "https://fhir.hie.moh.gov.my/baseR4/"
[type] = resource type e.g. "Patient | Encounter | Compostion"
@recordId = unique record id defined from source system e.g. "immunization-sample" | "immunizationrecommendation-sample"
@patientIdentifier = patient identifier such as mykad number or MRN e.g "HIE-00000003"

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

Overview

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

  • In HIE, both these record are created in conjunction to 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 record must be setup in HIE prior Schedule, Slot and/ or Appointment record can be sent to HIE.
  • The Schedule element Schedule.serviceCategory, Schedule.serviceType and Schedule.specialty must follow the referenced HealthcareService.
  • The Slot element Slot.serviceCategory, Slot.serviceType and Slot.specialty must follow the referenced HealthcareService.

Appointment booking is stored as Appointment (MY Core).

  • Generally, an appointment will be referenced to an existing slot record in HIE.
  • However, an appointment can also be created independantly without a slot referenced, such use case for example are walk-in scenarios. For such use case, base FHIR Appointment has set constraint that the Appointment.status cannot be defined as "booked".
  • When An Appointment is booked under an existing slot. It must reference the slot Appointment.slot.reference

Slot quota

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

  • "quota" represent the total amount of appointment allowed to book.
  • "availble" represent currently available appointment allowed to book.

A slot "available" count is required to be deducted when an appointment references it.

  • 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 overbooked.

Diagram below shows the visual flow of the relation between each ressources. Scheduling-flow

Type of Schedule

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

  • "Internal" type indicates that the schedule is only allowed to be booked by the internal user only (Same organization).
  • "Affiliate" type indicates that the schedule is allowed to be booked internally and by other recognized facility (through OrganizationAffiliation (MY Core) setup).
  • "Public" type indicates that the schedule is allowed to be booked by any party including the public such as a patient or a customer.

Scheduling & Appointment Integration

Scheduling integration with a different source system can be achieved when a scheduling record complies to the Schedule (MY Core) and Slot (MY Core) standards when creating scheduling in HIE. It is recommended that only schedules of scheduleType:"affiliate" or schedulType:"public" shared for integration as sheduleType:"internal" is meant to be booked at each own respective source system thus has little benefit to be shared in HIE (as user at the facility likely will not be using RekodPesakit to do booking).

By creating schedule and slot in HIE, users using RekodPesakit or RekodSaya will be able to book appointments referencing created schedule and slot. If there are other sources to create an appointment such as from the source system itself, it is imoportant note that the Schedule and Slot version in HIE must always be updated to prevent alternate version relating to the same scheduling.

Diagram below shows the overview flow of Scheduling and Appointment booking integration points.

Scheduling 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 to HIE and a record of the appointment is created in Kafka.
  4. Source System able to retrieve the Appointment Record in Kafka to update their record.
  5. Once Appointment has been updated (fulfilled, noshow, etc) from source system, it is expected from source system to also update in HIE the initial Appointment created (Otherwise HIE portals will default update status:"noshow" the following day based on start date of the appointment).

Refer to Subscription Guide section under "Appointment topic" for subscription using Kafka Apache details.

Appointment Integration Only

An Appointment (MY Core) can be created even if no scheduling is present (when slot is not reference in Appoinment). When created in HIE as status:"booked" once the appointment is updated (fulfilled, noshow, etc) is is expected to also update the Appointment record in HIE (Otherwise HIE portals will default update status:"noshow" the following day based on start date of the appointment).