# Migration Guide
This guide walks through moving to `hl7v2` from another HL7 v2.x
library. Each section pairs the library you already know with the
equivalent `hl7v2` API so the diff is obvious.
Covered:
- [`elixir_hl7`](#from-elixir_hl7) — the main Elixir alternative
- [HAPI v2 (Java)](#from-hapi-v2-java) — mental-model mapping
- [HL7apy (Python)](#from-hl7apy-python) — mental-model mapping
At the end you'll find a
[feature comparison](#feature-comparison) and a short
[adoption checklist](#adoption-checklist).
## From `elixir_hl7`
`elixir_hl7` parses HL7 v2 messages as generic lists and exposes a
path-based query API. `hl7v2` parses into **typed segment structs**
with named fields backed by the HL7 v2.5.1 + v2.6/v2.7 catalogs, and
additionally preserves unknown segments losslessly.
### 1. Install
```elixir
# Old
def deps, do: [{:elixir_hl7, "~> 0.9"}]
# New
def deps, do: [{:hl7v2, "~> 3.8"}]
```
### 2. Parse
```elixir
# elixir_hl7
hl7 = HL7.Message.new(wire)
# => %HL7.Message{segments: [...], ...}
# hl7v2 — raw mode, same shape
{:ok, raw} = HL7v2.parse(wire)
# => %HL7v2.RawMessage{segments: [{"MSH", [...]}, {"PID", [...]}]}
# hl7v2 — typed mode, gives you structs
{:ok, msg} = HL7v2.parse(wire, mode: :typed)
# => %HL7v2.TypedMessage{segments: [%HL7v2.Segment.MSH{...}, %HL7v2.Segment.PID{...}]}
```
`hl7v2.parse/2` returns `{:ok, msg}` / `{:error, reason}` rather than
raising. Typed mode is strictly more powerful — you still get raw
access to any fields by path.
### 3. Field access by path
`elixir_hl7` uses a path string query API. `hl7v2` provides the same
string API plus typed struct access.
```elixir
# elixir_hl7
HL7.Message.get_value(hl7, "PID-5.2")
HL7.Message.get_values(hl7, "OBX-5")
# hl7v2 — path API (mirrors elixir_hl7)
HL7v2.get(msg, "PID-5.2")
HL7v2.get_all(msg, "OBX-5")
# hl7v2 — typed access (new, preferred)
pid = Enum.find(msg.segments, &is_struct(&1, HL7v2.Segment.PID))
first_name = hd(pid.patient_name).given_name
```
Typed access is autocompletion-friendly, catches typos at compile
time, and returns **nil** (not empty string) when a field is absent —
so `nil` guards work instead of truthy-string checks.
### 4. Build messages
```elixir
# elixir_hl7 — hand-assemble lists
segments = [
["MSH", "|", "^~\\&", "HIS", "HOSP", ...],
["PID", "1", "", "12345^^^MRN", "", "Smith^John"]
]
HL7.Message.new(segments)
# hl7v2 — struct builder
alias HL7v2.Segment.{PID, EVN, PV1}
alias HL7v2.Type.{CX, XPN, FN, PL}
msg =
HL7v2.new("ADT", "A01",
sending_application: "HIS",
sending_facility: "HOSP",
receiving_application: "PACS",
receiving_facility: "IMG"
)
|> HL7v2.Message.add_segment(%EVN{event_type_code: "A01"})
|> HL7v2.Message.add_segment(%PID{
patient_identifier_list: [%CX{id: "12345", identifier_type_code: "MRN"}],
patient_name: [%XPN{family_name: %FN{surname: "Smith"}, given_name: "John"}]
})
wire = HL7v2.encode(msg)
```
You get compile-time safety, no manual separator management, and
type-aware composite encoding (`XPN`, `CX`, `PL`, ...).
### 5. Validate
`elixir_hl7` has no validation. `hl7v2` ships structural, positional,
conditional, field-level, version-aware, and table validation plus
user-defined conformance profiles:
```elixir
# Basic validation
case HL7v2.validate(msg) do
:ok -> :ok
{:error, errors} -> Enum.each(errors, &IO.inspect/1)
end
# Conformance profile
profile =
HL7v2.Profile.new("Hospital_ADT", message_type: {"ADT", "A01"})
|> HL7v2.Profile.require_segment("NK1")
|> HL7v2.Profile.require_field("PID", 18)
HL7v2.validate(msg, profile: profile)
```
See [`guides/conformance-profiles.md`](conformance-profiles.md) for
the full profile DSL.
### 6. ACK / NAK
```elixir
# elixir_hl7 — no built-in helper, you hand-build the MSA
# hl7v2
{ack_msh, msa} = HL7v2.Ack.accept(hd(msg.segments))
accept_wire = HL7v2.Ack.encode({ack_msh, msa})
{ack_msh, msa, err} =
HL7v2.Ack.reject(hd(msg.segments),
error_code: "207",
error_text: "Application internal error"
)
reject_wire = HL7v2.Ack.encode({ack_msh, msa, err})
```
### 7. MLLP transport
`elixir_hl7` does not ship an MLLP transport. `hl7v2` includes an
integrated Ranch 2.x listener/client with TLS and mutual-TLS support.
This is typically the point where downstream users reach for a
separate `mllp` package — with `hl7v2`, it's already in the box.
```elixir
# Server
{:ok, _pid} = HL7v2.MLLP.Listener.start_link(port: 2575, handler: MyHandler)
# Client
{:ok, client} = HL7v2.MLLP.Client.start_link(host: "localhost", port: 2575)
{:ok, ack} = HL7v2.MLLP.Client.send_message(client, wire)
```
See [`getting-started.md`](getting-started.md#mllp-transport) for the
full transport API.
### 8. Unknown / Z-segments
Both libraries preserve unknown segments on parse. In `hl7v2`:
- Segments with an ID starting with `Z` become `%HL7v2.Segment.ZXX{}`
- Any other unknown segment stays as `{name, raw_fields}`
- Both forms encode back to wire format via `HL7v2.encode/1`
- `HL7v2.get/2` with a path string works uniformly across typed
structs, ZXX, and raw tuples
### 9. Pitfalls worth knowing
If you're coming from a busy `elixir_hl7` codebase, watch for these:
- **Empty-string vs nil.** `elixir_hl7` returns `""` for absent
fields; `hl7v2` returns `nil`. Replace `x != ""` checks with
`is_nil/1` or pattern matching.
- **Repeating fields.** `elixir_hl7` returns a list always;
`hl7v2` returns a typed list for `unbounded` fields and a single
struct otherwise. Follow the segment module's declared cardinality.
- **Separator handling.** `elixir_hl7` exposes separators as strings;
`hl7v2` threads them via a `%HL7v2.Separator{}` struct and handles
subcomponent escaping automatically on encode.
- **Version.** `hl7v2` reads `MSH-12` on parse and applies
version-aware field presence rules (v2.3 → v2.8+). If you parse
v2.3 payloads, you'll now get v2.3-correct validation instead of
v2.5.1-flavored warnings.
## From HAPI v2 (Java)
HAPI's model-based API maps almost 1:1 onto `hl7v2`:
| HAPI | `hl7v2` |
| -------------------------------- | -------------------------------------- |
| `PipeParser().parse(wire)` | `HL7v2.parse(wire, mode: :typed)` |
| `message.getMSH()` | `hd(msg.segments)` (or `Enum.find/2`) |
| `pid.getPatientName(0).getGivenName()` | `hd(pid.patient_name).given_name` |
| `new ADT_A01()` | `HL7v2.new("ADT", "A01", opts)` |
| `message.encode()` | `HL7v2.encode(msg)` |
| `Acknowledgment.generateACK(...)`| `HL7v2.Ack.accept(msh)` |
| `HapiContext.getValidationContext()` | `HL7v2.Profile` + `HL7v2.validate/2` |
| `MinLowerLayerProtocol` | `HL7v2.MLLP.Listener` / `.Client` |
The mental model is the same — segment objects with named accessors —
but you replace generated Java classes with first-class Elixir structs
and idiomatic pipelines. Segment names, field names, and composite
types match the HL7 v2.5.1 spec and use `snake_case` instead of
camelCase.
## From HL7apy (Python)
HL7apy exposes HL7 as a hierarchy of attribute-addressable objects.
The Elixir equivalents:
| HL7apy | `hl7v2` |
| --------------------------------------- | --------------------------------------- |
| `parse_message(wire)` | `HL7v2.parse(wire, mode: :typed)` |
| `msg.MSH.msh_9` | `hd(msg.segments).message_type` |
| `msg.PID.pid_5.xpn_1.fn_1` | `hd(pid.patient_name).family_name.surname` |
| `Message("ADT_A01")` | `HL7v2.new("ADT", "A01", opts)` |
| `msg.to_er7()` | `HL7v2.encode(msg)` |
| `msg.validate()` (message profile) | `HL7v2.validate(msg, profile: profile)` |
HL7apy's implicit-null attribute traversal becomes explicit `nil`
handling in Elixir — use `get_in/2`, pattern matching, or
`HL7v2.get/2` with a path string when you don't want to walk structs
manually.
## Feature comparison
| Feature | `hl7v2` | `elixir_hl7` | HAPI Java | HL7apy |
| --------------------------------- | :-----: | :----------: | :-------: | :----: |
| Typed segment structs | yes | no | yes | yes |
| Positional structural validation | yes | no | yes | yes |
| Conditional field validation | yes | no | yes | no |
| Version-aware rules (v2.3-v2.8) | yes | no | yes | yes |
| Table validation (opt-in) | yes | no | yes | yes |
| Conformance profiles (DSL) | yes | no | yes | partial |
| ACK / NAK helpers | yes | no | yes | yes |
| MLLP transport (TLS + mTLS) | yes | no | yes | no |
| Unknown segment preservation | yes | yes | yes | yes |
| Telemetry | yes | no | no | no |
| Pure-BEAM, no NIFs | yes | yes | no | no |
## Adoption checklist
Port your codebase incrementally:
1. **Swap the dep** (`elixir_hl7` → `hl7v2`). Raw mode parses first.
2. **Adapt path lookups** — `HL7.Message.get_value/2` → `HL7v2.get/2`.
3. **Flip empty-string checks** to nil checks.
4. **Move one message flow at a time** to typed mode
(`mode: :typed`), starting with the ones you know the segments for.
5. **Replace hand-assembled segment lists** with struct builders.
6. **Turn on validation** (`validate: true`) in a logging-only mode.
7. **Promote warnings to errors** per integration, optionally with
`HL7v2.Profile`.
8. **Swap your MLLP transport** (`mllp`, handmade TCP handler) for
`HL7v2.MLLP.Listener` + `.Client`.
9. **Subscribe to telemetry events** for observability
(`[:hl7v2, :parse, :start | :stop | :exception]`, etc.).
If you hit a segment that isn't typed yet, it keeps parsing as a raw
tuple — nothing gets lost — and you can still address it via
`HL7v2.get/2` paths. File an issue and it'll usually show up in the
next release.
