A Spring Boot application that parses HL7 v2 messages, converts them into clean domain objects, sends and receives over MLLP, and enforces a strict anti-corruption boundary between the HL7 wire format and application logic.
J 87A5 ava 21 and Maven. No database, no external services.
mvn verify # compile + run the whole test suite
# push a sample file through the entire pipeline and watch the logs
# To push a sample file through you will need to create a run config and pass the sample file in as application argument
.\mvnw.cmd spring-boot:run "-Dspring-boot.run.arguments=--ingest=src/test/resources/samples/oru_r01_v25.hl7"To turn on the MLLP listener, set hl7.mllp.serverEnabled: true in application.yml.
It is off by default so file-based ingestion does not require a port.
config/ HapiConfig <- start here, it is the most important file
Hl7Properties
domain/ Patient, Admission, LabReport, Observation ... (no HAPI imports, ever)
hl7/
Hl7Read null-safe reading, and the three kinds of "empty"
Hl7Time HL7 timestamps, done properly
AckFactory AA / AE / AR and why the distinction matters
mapping/ EnvelopeMapper, PatientMapper, AdtMapper, OruMapper
inbound/ InboundMessageProcessor, MLLP listener, file ingest
outbound/ MllpSender, OruBuilder
validation/ SiteValidationRules
service/ DomainHandler, DomainDispatcher, business logic
ca.uhn.hl7v2 may only be imported under com.example.hl7lab.hl7.
The mapping layer is an anti-corruption boundary: HAPI's Message goes in, a plain
record comes out, and nothing downstream can tell the data arrived as HL7 rather than
CSV or FHIR.
When onboarding a second sender with a different HL7 version, a different message structure, and a different field for the MRN — if HAPI types have leaked into your services, that is a rewrite. If they haven't, it's a new mapper.
An ArchUnit rule can enforce this at build time: fail the build if anything outside
hl7 imports ca.uhn.hl7v2. It takes ten lines and is the single highest-value test
in an HL7 codebase.
Each of these is implemented and commented in the code, and most have a test.
-
Segment terminator is
\r, not\n. Java text blocks give you\n. This is the number one cause of "why won't this parse". →OruBuilderRoundTripTest -
A
HapiContextper message will wreck you. It is expensive and designed to be shared. →HapiConfig -
Version-specific model classes multiply your mappers. A v2.3
ADT_A01and a v2.5ADT_A01are unrelated Java types.CanonicalModelClassFactorycollapses them. →HapiConfig,AdtMapperTest.mapsAV23MessageWithTheSameCodeAsAV25One -
Validating while parsing loses you the whole message. One bad field and
parse()throws — including MSH, so you can't even build a meaningful NAK. Parse permissively, validate explicitly. →HapiConfig,SiteValidationRulesTest -
Three kinds of empty. Absent (not sent), empty (sent blank), and the HL7 null — the literal
""— which means delete the value you're holding. Collapsing them is a real data-integrity bug. →Hl7Read -
Almost everything repeats. PID-3 identifiers, PID-5 names, PID-11 addresses, PV1-7 doctors, OBX-8 flags. Taking rep 0 is how you store an account number as the MRN. →
PatientMapper,AdtMapperTest.keepsEveryPatientIdentifierNotJustTheFirst -
Timestamps have variable precision and optional offsets.
"1975"is a legal date of birth. A missing offset means the sender's local time, which is interface configuration, neverZoneId.systemDefault(). →Hl7Time,Hl7TimeTest -
OBX-5 is not a number. The same LOINC code arrives as
13.5one day andSEE COMMENTthe next. Keep it a String at the boundary. →Observation,OruMapperTest.handlesNonNumericValuesInNumericLookingResults -
An ORU is a tree, not a list. PATIENT_RESULT → ORDER_OBSERVATION → OBSERVATION. Flattening it files the glucose result under the CBC. →
OruMapper,OruMapperTest.keepsResultsAttachedToTheirOrder -
AE vs AR is the most consequential two characters in the system. AE = your message is bad, don't retry. AR = I'm broken, please retry. Mix them up and you either lose data during an outage or poison your queue forever. →
AckFactory,InboundMessageProcessorTest
| Terser paths | Generated typed model | |
|---|---|---|
| Best for | reading inbound | building outbound |
| Version changes | survives them | recompile |
| Missing data | returns null, wrap it | null-chains / NPEs |
| Repeating groups | awkward | excellent — countable and nested |
| Typos | runtime | compile time |
| Escaping | handled | handled |
This project uses Terser for reading (Hl7Read, PatientMapper, AdtMapper), the typed
model for the ORU tree walk (OruMapper) and for building (OruBuilder). The reasoning
is documented in each class.
There is a third option: superstructures like
ca.uhn.hl7v2.model.v25.message.ADT_AXX, a synthetic class holding every segment any ADT
could carry. new CanonicalModelClassFactory(ADT_AXX.class) makes every message parse
into it, giving typed access across all trigger events — at the cost of forcing all
traffic on that context into ADT_AXX, so your ORU feed needs its own HapiContext.
These are the next real problems, and none of them are HAPI problems:
- Persistence and idempotency. MSH-10 is your dedup key. Senders resend on timeout, so you will receive the same message twice.
- ACK-after-commit. Right now
InboundMessageProcessorACKs after the handler returns. Wire in a real transaction and make sure AA cannot be sent before commit. - Ordering. A02 (transfer) arriving before A01 (admit) is normal. Sequence on the event timestamp, not arrival order.
- Quarantine. Unparseable messages need to be stored raw, not logged and dropped.
- Backpressure. One slow handler will stall the MLLP connection and the sender will time out and resend, making things worse.
- HAPI HL7v2
- Configuring HAPI
- Conformance profiles / confgen
- HL7 over HTTP
- v2.5 generated Javadoc:
https://hapifhir.github.io/hapi-hl7v2/v25/apidocs/