HL7 SQM Messages: Schedule Query

HL7 SQM messages ask a scheduling system what appointment slots, services, or resources match a set of criteria — they are a query, not a booking. An SQM message is sent by an application that wants to read the schedule, and the scheduling system answers with an SQR schedule query response carrying the matching appointments. This is the read side of HL7 scheduling: where an SRM requests a booking change and an SIU notifies subscribers of one, SQM simply asks a question and waits for the answer. This page explains what an SQM message represents, the trigger event that carries it, every segment the message can contain and what each one holds, and how a schedule query relates to FHIR. Sample content is constructed for illustration with fictional identifiers.

What an SQM message represents

An SQM message — SQM stands for Schedule Query Message — is a request to a scheduling system to return information about appointments, services, and resources that satisfy the query's criteria. It carries no instruction to create, modify, or cancel anything; it only asks the filler application to look up matching schedule data and return it.

The sender is the querying application — an EHR, a referral system, or a patient-access portal — and the receiver is the scheduling system that owns the calendar. Because SQM is a query, it follows the request/response pattern: the querying application sends one SQM message and blocks (or correlates asynchronously) on the corresponding SQR response, rather than broadcasting an event to many subscribers the way an unsolicited SIU notification does.

In HL7 v2.5.1, SQM uses the original-style query definition: the criteria are expressed through the QRD and QRF segments — the same query/filter segments the standard uses for other original-mode queries — combined with the scheduling-specific appointment segments ARQ and APR that describe the appointment and the preferences being matched.

When an SQM message is sent

An SQM message is sent whenever an application needs to read the schedule rather than change it — for example to find open slots before requesting a booking, to confirm the status of an existing appointment, or to list the appointments tied to a patient or a resource. The query is synchronous in spirit: each SQM expects exactly one SQR response, correlated through the query and message-control identifiers.

Trigger event

The SQM message type carries a single trigger event:

• SQM^S25 – Schedule query message.

The matching response is SQR^S25, the schedule query response, which returns the appointments and resources that satisfied the query. Because SQM has one trigger event, the receiver's handling turns on the query criteria carried in QRD, QRF, and the appointment segments rather than on the trigger code in MSH-9.

Integration topology

The diagram shows a querying application asking the scheduling system for matching schedule data and receiving the response back through the integration engine.

{{diagram: querying application (EHR / portal) → SQM^S25 query → integration engine → scheduling system → SQR^S25 response back}}

Typical senders: EHR, referral or order-entry system, patient-access or scheduling portal.

Typical receivers: the scheduling system that owns the appointment calendar and resource book.

Direction: request/response — the querying application sends the SQM and receives a single correlated SQR in return, not a one-way broadcast.

Segments in an SQM message

The SQM_S25 message is built from the original-style query segments at the top — MSH, QRD, and an optional QRF — followed by an optional REQUEST group that expresses what is being scheduled. Within the REQUEST group, the appointment request ARQ and the patient are optional, and a repeating RESOURCES group describes the service, general-resource, personnel, and location resources being matched. The structure below follows the HAPI v2.5.1 generated model. Cardinality follows HL7 notation: [X] optional, {X} repeating, [{X}] optional and repeating; a bare code is required. Each segment code links to its canonical field-by-field reference.

[ ] = optional, { } = repeating

The REQUEST group as a whole is optional, and within it the RESOURCES group repeats; each resource group can in turn carry repeating SERVICE, GENERAL_RESOURCE, PERSONNEL_RESOURCE, and LOCATION_RESOURCE sub-groups. The canonical segment pages carry the full field-by-field detail.

Sample SQM message

Note. Constructed for illustration. Patient identifiers, appointment ids, dates, and names are fictional.

MSH|^~&|EHR|MERCYGEN|SCHED|MERCYGEN|202006031000||SQM^S25^SQM_S25|MSG00045|P|2.5.1
QRD|202006031000|R|I|Q0045|||10^RD|MR12345^^^MERCYGEN^MR|APPT|||
QRF|SCHED^Cardiology Clinic||20200610|20200617|
ARQ|APPT0001^EHR||||||CARDIO^Cardiology consult|ROUTINE|30^MIN||20200610^20200617
APR|^^^20200610^20200617
PID|1||MR12345^^^MERCYGEN^MR||DOE^JOHN^Q||19800101|M
RGS|1|A
AIP|1|A|1234^SMITH^JANE^A^^^MD^^^CARDIOLOGY

What this sample shows

The SQM^S25 in MSH-9 marks a schedule query, and MSH-10 carries the control id MSG00045 the response will echo. The QRD defines the query — a record-oriented format (R) at immediate priority (I), limited to 10 results, scoped to the appointment subject. The QRF filters it to the cardiology clinic over the week of 10–17 June. The ARQ describes the appointment being sought — a routine cardiology consult of 30 minutes within that date range — and the APR carries the start-time range as a preference. PID ties the query to patient MR12345, and the RESOURCES group (RGS then AIP) asks specifically about the availability of provider 1234 in cardiology. The scheduling system answers with an SQR carrying the matching slots.

Working with SQM messages

Correlate the response, do not broadcast

SQM is a query, so each message expects exactly one SQR in return. Correlate the response against the message control id in MSH-10 and the query id carried in QRD, rather than treating the exchange as a fire-and-forget notification. An unmatched SQM is an unanswered question, not a missed event.

Read the criteria from QRD and QRF, then the appointment segments

The scope of the query lives in QRD and QRF — the format, priority, result limit, subject filters, and date range — while what is being scheduled lives in the appointment segments ARQ and APR and the resource groups. Build the lookup from both halves: the filter narrows the search, and the appointment and resource segments say what to match.

Respect the result limit

QRD-7, the quantity-limited request, bounds how many results the querying application wants. Honour it on the response side and use the continuation pointer DSC to page through a larger result set rather than overflowing a single response.

Original-style query, not Query By Parameter

In v2.5.1 the SQM schedule query uses the original-style QRD/QRF definition segments. Later HL7 query work introduced the Query By Parameter (QBP) model with its own segments; SQM as defined here does not use them. Implement against the QRD/QRF segments for this message rather than assuming a QBP-style query.

Vendor variance. The REQUEST group and its appointment and resource segments are optional, so some systems issue a thin SQM carrying only the QRD/QRF criteria while others populate the full appointment and resource detail. Confirm a partner's field usage against their interface specification rather than assuming the base standard.

FHIR equivalent

A schedule query corresponds conceptually to a FHIR search — reading available time against the Slot, Schedule, and Appointment resources — rather than to any single resource instance. An SQM asks which appointments or open slots match a set of criteria, which is the question a FHIR Slot or Appointment search answers.

There is, however, no published mapping to lean on. The HL7 v2-to-FHIR Implementation Guide publishes official message maps only for a subset of messages — the ADT subset, OML_O21, ORM_O01, VXU_V04, ORU_R01, MDM_T02, and SIU_S12 — and SQM_S25 is not among them. The IG also publishes no ConceptMap for the QRD or QRF query segments. Any FHIR representation of a schedule query is therefore derived manually, translating the query criteria into FHIR search parameters against Slot, Schedule, or Appointment, with no standard ConceptMap to follow.

Common pitfalls

Pitfall. Treating SQM as a booking. SQM only reads the schedule; it never creates, modifies, or cancels an appointment. A booking change is an SRM request, and a notification of one is an SIU.

Pitfall. Ignoring the result limit and continuation. Skipping QRD-7 and the DSC continuation pointer can produce an oversized response or a silently truncated result set; page through results instead.

Pitfall. Assuming a fixed date-time precision. Some senders express the QRF date range as YYYYMMDD and others as a full timestamp with an offset; do not assume a timezone — normalize on ingest.

Pitfall. Assuming QBP query segments. SQM in v2.5.1 uses the original-style QRD/QRF segments, not the Query By Parameter model; parsing for QBP segments will fail against a conformant SQM.

How Vorro handles SQM messages

Vorro receives the SQM query over MLLP or another transport, reads the criteria from QRD and QRF together with the appointment and resource segments, and routes the lookup to the scheduling system that owns the calendar. Vorro correlates the SQR response back to the originating query through the message control id in MSH-10, honours the result limit in QRD-7, and, where a FHIR destination is configured, translates the query into a search against the Slot, Schedule, or Appointment resources — composed manually, since the v2-to-FHIR Implementation Guide publishes no map for this message.

Related messages

• SQR — the schedule query response that returns the appointments and resources matching an SQM.
• SIU — the unsolicited scheduling notification that informs subscribers of a booking event.
• SRM — the schedule request message that asks to create, modify, or cancel an appointment.

Sources

• HL7 v2.5.1 Standard — Chapter 10 (Scheduling), hl7.eu mirror — confirms the SQM^S25 trigger event and message structure
• HL7 v2.5.1 Standard — Chapter 5 (Query), hl7.eu mirror — QRD and QRF original-style query segment definitions
• HAPI HL7v2 v2.5.1 apidocs — SQM_S25 message — confirms required/optional segment structure
• HAPI HL7v2 v2.5.1 apidocs — SQM_S25_REQUEST group
• HAPI HL7v2 v2.5.1 apidocs — SQM_S25_RESOURCES group
• HAPI HL7v2 v2.5.1 apidocs — SQM_S25_SERVICE group
• HAPI HL7v2 v2.5.1 apidocs — ARQ segment
• HAPI HL7v2 v2.5.1 apidocs — APR segment
• HAPI HL7v2 v2.5.1 apidocs — SQR_S25 message — confirms the SQR^S25 response structure
• HL7 v2-to-FHIR IG — message maps index — confirms no message map for SQM_S25
• HL7 v2-to-FHIR IG — segment maps index — confirms no ConceptMap for QRD/QRF </content>

</invoke>