KHCC HL7 Integration with HAKEEM

Most engineers have never seen a real HL7 message.

If you’ve worked in fintech you’ve probably parsed ISO 8583. If you’ve worked in logistics you’ve dealt with EDI. If you’ve built a live integration between two hospital systems, you’ve seen HL7 v2, and you have opinions about it that you didn’t have before.

The team at Electronic Health Solutions built the HL7 integration between King Hussein Cancer Centre (KHCC) and HAKEEM, Jordan’s national EHR, during the 2010–2013 engagement. Here’s what that actually looked like.

What an HL7 v2 message looks like

The wire format is the first thing that makes engineers make a face.

MSH|^~\&|KHCC|KHCC|HAKEEM|MOH|20120315120000||ADT^A01|MSG00001|P|2.3
EVN|A01|20120315120000
PID|1||12345^^^KHCC^MR||AL-MANSOUR^AHMAD^MOHAMMED||19750304|M|||AMMAN^JO||||AR|M||12345
PV1|1|I|ONCOLOGY^101^1^KHCC||||SMITH^JOHN^A^^^DR

That’s an ADT^A01 — an admit/discharge/transfer message, event A01 meaning patient admission. Every segment is pipe-delimited. Fields within a segment are delimited by pipes. Sub-fields by ^. Sub-sub-fields by &. Repeating fields by ~.

The MSH segment is the message header: sending application, sending facility, receiving application, receiving facility, timestamp, message type, message ID, processing ID, version. The PID segment is patient identity: ID list, name, date of birth, gender, address, language. The version — HL7 v2.3 — was finalized in 1997. The pipe-delimited format predates XML’s conquest of enterprise systems. It’s not beautiful. It maps directly to how hospitals actually store and exchange patient data, which is why it’s still the dominant wire format in healthcare decades later, despite FHIR, CDA, and every standard meant to replace it.

Why KHCC was a specific challenge

King Hussein Cancer Centre is not a general hospital. It’s Jordan’s flagship specialist oncology facility — a centre of excellence founded under the patronage of Princess Ghida Talal, with a mission that spans treatment, research, and education across the region. Patients arrive via referral from other hospitals, many of which were already on HAKEEM.

This means a patient’s record doesn’t start at KHCC. It starts at the referring facility — say, Prince Hamza Hospital — where they were first diagnosed with a condition requiring oncology expertise. Their demographics, initial diagnosis, medication history, and lab results all live in HAKEEM.

When that patient arrives at KHCC, KHCC has its own EHR. Its own patient ID space. Its own data model for chemotherapy protocols, radiation treatment plans, and oncology-specific lab panels.

The challenge is not “get KHCC’s data into HAKEEM.” The challenge is patient identity resolution across two systems that assigned different IDs to the same human being, followed by bidirectional synchronization that keeps both systems current without creating duplicates or losing clinical context.

HL7 v2 is the transport layer for that problem. It is not the solution to it.

The parts that are actually hard

Patient identity is not a solved problem. KHCC assigned their own Medical Record Numbers. HAKEEM maintained its own national patient identifier scheme. The PID-3 field specifically accommodates a patient ID list — because a patient has multiple identifiers across multiple systems. But knowing that patient 12345 at KHCC is patient 98765 in HAKEEM requires a mapping table, and building that table requires either probabilistic matching on name + DOB + gender + address, or manual reconciliation, or — in practice — both, with different rules for different confidence thresholds.

Event sequencing matters clinically. An HL7 ADT message carries an event type: A01 is admission, A02 is transfer, A03 is discharge, A08 is information update. These events must arrive and be processed in order, or the clinical picture is wrong. A patient who was admitted, transferred, then discharged looks very different from one where those messages arrive out of sequence and get processed as admitted, discharged, transferred to a department they already left.

In a high-volume integration, messages don’t always arrive in order. TCP gives you reliable delivery; it doesn’t give you application-level ordering guarantees when messages are produced asynchronously. You need sequence numbers, acknowledgment (ACK/NAK), and a queue with retry logic that handles NAKs without losing the message or flooding the destination with duplicates.

The sending system’s implementation is the real specification. HL7 v2.3 is a standard with optional fields and significant room for implementation variation. What KHCC’s EHR actually sent in PID-3 was what mattered — not what the spec said should be there. Time was spent with KHCC’s technical team analyzing their actual outbound messages because the implementation documentation was incomplete. This is normal. Every HL7 integration has this story.

What the routing layer looked like

The integration used the HL7 Messaging package in VistA — MUMPS routines that handled inbound message parsing and routing on the HAKEEM side. The team wrote routines for specific event types: primarily ADT events for patient movement, and ORM/ORU pairs for lab orders and results.

The referral flow:

1. Referring hospital (on HAKEEM) sends the patient to KHCC.
2. KHCC registers the patient, assigns their MRN.
3. KHCC sends an ADT^A01 to HAKEEM acknowledging admission.
4. The HAKEEM routing layer receives the A01, resolves patient identity via the master patient index mapping, and updates the patient record with the KHCC encounter information.
5. Lab results from KHCC’s oncology panels flow back via ORU^R01 messages and land in the patient’s HAKEEM record — visible to the referring physicians who still hold the patient’s primary care relationship.

That last point matters clinically. An oncologist at KHCC is treating the cancer. The general physician at the referring hospital is still managing the patient’s hypertension, diabetes, everything else. They need to see the oncology results without requiring the patient to carry paper records between facilities. The HL7 integration is what makes that possible.

What this looks like twelve years later

HL7 v2 is not beautiful software. But it’s the kind of ugly that earns respect — ugly because the problem domain is ugly, not because the designers didn’t try. Healthcare data is messy because healthcare is messy. Patients have multiple identifiers because they interact with multiple systems. Events need ordering because clinical timelines matter for diagnosis. The field optionality looks like looseness; it’s actually the standard accommodating the breadth of clinical specialties that have to use it.

FHIR is genuinely better in most respects. In 2012, FHIR was a draft spec. HL7 v2 was what hospital systems spoke. You integrate with what’s there.

The engineers who build healthcare integrations are doing work that most of the industry doesn’t see. The HL7 message that carries a lab result from the lab system to the chart to the doctor’s screen is plumbing. Nobody notices the plumbing until it breaks. These pipes still run.