Guides
Guides
One task per page, each with the API calls that do it and the reasoning behind the choices these crates make. Guides assume you have read the quick start; they do not assume you have read each other.
Working with a v2 message
The five guides that cover the life of a message inside your process: getting it in, finding things in it, changing it, checking it, and teaching the parser a dialect it does not know.
Parsing
The three modes, and which one a given integration wants.
Navigating
Paths, the tree, repetitions, and reading a value back out.
Modifying and building
Set, null, append a segment, build an acknowledgement, render ER7.
Validating
Errors versus warnings, strict mode, and what a Z-segment does not break.
Vendor dictionaries
Teach the parser a dialect in JSON — or generate one from a site’s XSDs.
Struct mode and derive
Map paths onto a struct once, and keep an escape hatch for the day it changes.
Moving messages around
Getting a message to or from another system — over a socket, over HTTP, or into a format something downstream can read.
Converting formats
ER7 to XML or JSON and back, in the library and from the shell.
MLLP over TCP
Framing, streaming, transports, acknowledgements, and strictness.
SOAP over HTTP
Receiving, sending, faults with the right status, and reading a reply.
The other standard
HL7 v3
The RIM backbone, the data types, and the three-level envelope.
A suggested reading order
If you are integrating a new v2 feed and want to read straight through, this is the order the work usually happens in:
- Parsing — pick a mode. Almost everyone starts in generic mode whether they mean to or not.
- Navigating — learn the path grammar. Everything else takes paths.
- Validating — decide what you will reject, before a bad message decides for you.
- Vendor dictionaries — the first time the sender's Z-segments matter.
- Struct mode — once the interface has held still long enough to trust.
- Modifying and building — because a system that reads HL7 almost always has to answer in it.
- MLLP or SOAP — whichever the far end speaks.
For longer, start-to-finish walkthroughs of the same ground, see Tutorials. For short copyable snippets with no prose around them, see Examples.