Intro · Health Samurai
How we went from custom one-off integrations to a reusable, testable, AI-assisted framework.
Our experience
We've built multiple HL7v2 tools and delivered production integrations with major EHR vendors.
Native HL7v2 message parser integrated into the Aidbox platform for receiving and parsing messages out of the box.
Two internal mapping engines: one built on the JUTE DSL for declarative transformations, another using Zen configuration for HL7v2-to-FHIR mapping.
Standalone Python-based mapping service for teams that need flexibility outside the Aidbox runtime.
Multiple projects delivered with Epic, Cerner, and Meditech — both inbound and outbound HL7v2 messaging in production.
Challenges · Pain points
Six problems that every HL7v2 integration team eventually faces.
01
Patient record matching, deduplication, and identity resolution across multiple identifier systems. Different facilities assign different IDs to the same patient.
02
Different EHR systems format messages differently. Meditech and Cerner use different fields for the same clinical data like allergies, identifiers, and visit numbers.
03
Local lab codes, patient class codes, and status values need mapping to standard code systems like LOINC, SNOMED, and FHIR ValueSets. Each sender has its own local codes.
04
In production, messages fail. Teams need to see errors, understand what went wrong, fix mappings or data issues, and reprocess messages without losing anything.
05
Adding support for a new message type requires significant engineering effort. Each new HL7v2 event means custom parsing, mapping, and conversion logic from scratch.
06
Difficult to test end-to-end and risky to deploy updates to production.
Solution
Messages flow through a durable queue. Operations UI and Developer Workspace wrap the runtime.
Message queue · Mapping tasks · Error recovery
EHR Sources
MeditechCernerEpicHL7v2 · MLLP
Work Queue
received
error
mapping_error
Processing Pipeline
Aidbox
PatientEncounterObservation…Mappings as code · Type-safe SDKs · AI agent · HL7v2 spec tool
Status-based work queues
Messages are persisted as resources. Status transitions drive the processing pipeline end-to-end.
Status machine
received
processing
processed
on fail
error
mapping_error
Every message and its current state is visible. Query by status to see what's pending, what failed, and what succeeded.
Messages are never lost. Failed messages stay in the queue and can be retried. Mapping errors auto-requeue after resolution.
Mappings as code
Use the $N_fieldName pattern (e.g., pid.$5_name).
Available at every nesting level.
Unit and integration tests for every message type.
Code review and version control for mapping changes.
export function convertPIDToPatient(
pid: PID,
policy: PatientConversionPolicy = DEFAULT_PATIENT_CONVERSION_POLICY,
): Patient {
const patient: Patient = { resourceType: "Patient" };
// PID-3: Patient Identifier List
patient.identifier = pid.$3_identifier
?.map(convertCXToIdentifier)
.filter(Boolean);
// PID-5: Patient Name
patient.name = pid.$5_name
?.map(convertXPNToHumanName)
.filter(Boolean);
// PID-7: Date of Birth
if (pid.$7_birthDate) {
patient.birthDate = convertDTMToDate(pid.$7_birthDate);
}
// PID-8: Administrative Sex
if (pid.$8_gender) {
patient.gender = GENDER_MAP[pid.$8_gender.toUpperCase()];
}
return patient;
}SDKs · HL7v2 & FHIR
Two packages cover both sides of the wire: HL7v2 segments on input, FHIR resources on output.
@atomic-ehr/hl7v2
Typed HL7v2 parser with generated types for every segment, field, and component. Access PID-3, OBX-5, or MSH-9 with full autocomplete.
Read a field
msg.pid.$5_familyName
@atomic-ehr/codegen
Generate FHIR R4 TypeScript types from the spec. Build Patient, Observation, and Bundle resources with compile-time validation.
Build a resource
Patient.name[0]
Source preprocessors
Handle EHR-specific message variations before they reach the conversion logic.
Each message type declares which preprocessors to run in the config file. Preprocessors normalize sender-specific quirks so converters only deal with clean, consistent data.
Each gets a small, testable preprocessor.
Operations UI
A built-in web interface covers queue inspection, mapping resolution, and error recovery.
01
Filter by status, sender, message type. Inspect raw HL7v2 and resulting FHIR resources.
02
Resolve unmapped local codes to LOINC / SNOMED. Messages auto-reprocess after resolution.
03
View error details, fix the root cause, one-click retry without data loss.
AI-friendly
New message type
From a day of engineering to a guided conversation.
Describes the project architecture for AI assistants.
For common tasks like adding message types or creating preprocessors.
Lets AI deeply understand different versions of the HL7v2 format.
Developer workspace
01
Reads AGENTS.md, understands project structure, generates converters and tests.
02
AI looks up segment definitions, field types, and version differences on demand.
03
Autocomplete for HL7v2 segments and FHIR resources; catch errors at compile time.
04
AI runs tests to validate its own changes before submitting.
Demo
The full pipeline, operations UI, and developer workspace — ready to explore.
Recommended path
License · Software
Our new high-performance workflow engine. Drop the HL7v2 pipeline into Interbox to run it as a durable, observable workflow alongside the rest of your integrations.
Learn more →
Engagement · With our team
Our engineers work alongside yours to adopt the pipeline — converters for your message types, EHR wiring, operations handoff. You ship faster, your team owns it after.
Together: a production HL7v2 → FHIR pipeline in weeks, not quarters.