8000 GitHub - DTSmth/hl7-lab: A working Spring Boot project that parses real HL7 v2 messages, converts them into clean domain objects, sends and receives over MLLP · GitHub
[go: up one dir, main page]

Skip to content
DTSmthPublic

About

A working Spring Boot project that parses real HL7 v2 messages, converts them into clean domain objects, sends and receives over MLLP

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

hl7-lab — HAPI HL7 v2 Integration Service

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.


Running it

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.


Layout

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

The one rule

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.


Key design decisions

Each of these is implemented and commented in the code, and most have a test.

  1. 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

  2. A HapiContext per message will wreck you. It is expensive and designed to be shared. → HapiConfig

  3. Version-specific model classes multiply your mappers. A v2.3 ADT_A01 and a v2.5 ADT_A01 are unrelated Java types. CanonicalModelClassFactory collapses them. → HapiConfig, AdtMapperTest.mapsAV23MessageWithTheSameCodeAsAV25One

  4. 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

  5. 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

  6. 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

  7. 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, never ZoneId.systemDefault(). → Hl7Time, Hl7TimeTest

  8. OBX-5 is not a number. The same LOINC code arrives as 13.5 one day and SEE COMMENT the next. Keep it a String at the boundary. → Observation, OruMapperTest.handlesNonNumericValuesInNumericLookingResults

  9. 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

  10. 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


Which HAPI API for which job

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.


What is not covered

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 InboundMessageProcessor ACKs 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.

Reference

About

A working Spring Boot project that parses real HL7 v2 messages, converts them into clean domain objects, sends and receives over MLLP

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0