Mapping HL7v2 ADT (A01, A03, A04, A08) to US Core Patient: Field Reference
All four common ADT trigger events carry the same PID demographics, so they map to US Core Patient through one rule set. The field table below is shared; the trigger events differ only in what else the message means.
Field-by-field mapping
Every rule in the Interoperall template is shown below: the source field, the FHIR target path it populates, and the transform applied. This table is generated from the live template, so it matches exactly what runs when you fork it.
| Source | FHIR path | Transform |
|---|---|---|
| (literal "usual") | Patient.identifier[0].use | Copied directly |
| PID-3.1 | Patient.identifier[0].value | Copied directly |
| PID-5.1 | Patient.name[0].family | Copied directly |
| PID-5.2 | Patient.name[0].given[0] | Copied directly |
| PID-7 | Patient.birthDate | Date reformat %Y%m%d → %Y-%m-%d |
| PID-8 | Patient.gender | Value-set lookup (M→male, F→female, O→other, U→unknown; fallback "unknown") |
| PID-11.1 | Patient.address[0].line[0] | Copied directly |
| PID-11.3 | Patient.address[0].city | Copied directly |
| PID-11.4 | Patient.address[0].state | Copied directly |
| PID-11.5 | Patient.address[0].postalCode | Copied directly |
| (literal "phone") | Patient.telecom[0].system | Copied directly |
| (literal "home") | Patient.telecom[0].use | Copied directly |
| PID-13.1 | Patient.telecom[0].value | Copied directly |
Source HL7v2 message
The sample input this template is designed to handle:
MSH|^~\&|EPIC|HOSP|REC|REC|20240115093045||ADT^A01|MSGCTRL1234|P|2.5.1
EVN||20240115093045
PID|1||MRN12345^^^EPIC^MR||DOE^JOHN^A||19800101|M|||123 MAIN ST^^CITYTOWN^WA^98101||555-555-0100
PV1|1|I|ICU^101^ATrigger events this mapping covers
These trigger events carry the same PID demographics and share the rule set above. Each has its own template in the Mapping Library, so you can fork the one that matches the message you actually receive.
- ADT^A03 — Discharge event. Same Patient demographics as A01, plus PV1-45 discharge timestamp into an extension.
- ADT^A04 — Outpatient registration event. Maps PID demographics plus PV1 outpatient class into US Core Patient.
- ADT^A08 — Patient information update. Re-applies full demographics so receivers reconcile latest PID values.
Common gotchas
- HL7v2 identifiers (PID-3) carry an assigning authority and ID type in later components. FHIR needs an `identifier.system` (a URI/OID), so you must map your local authority to a real, stable system URI, not just copy the code.
- HL7v2 dates are `YYYYMMDD` (or `YYYYMMDDHHMMSS`); FHIR `date`/`dateTime` need ISO-8601 (`YYYY-MM-DD`). This template applies a date-format transform - drop it and validation will reject the value.
- This template performs a value-set lookup. HL7v2 `M`/`F` is not the same token as FHIR `male`/`female`, and an unmapped code should fall back rather than pass through raw.
Target profile
This mapping targets http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient. After mapping, validate the output against the profile - the template populates the Must Support elements, but required elements missing from your source data will still fail. Score it against US Core.
Frequently asked questions
How do I map an HL7v2 ADT^A01 message to a FHIR Patient?
Parse the ADT^A01 message into segments, then map each relevant field to its FHIR path: identifiers and coded values need value-set lookups, and HL7v2 date fields need reformatting to ISO-8601. The field table on this page lists every source-to-target rule used by the Interoperall template, which you can fork and run in the Mapping Builder.
Which segments does the ADT^A01 → Patient mapping read?
It reads the PID segment. Other segments in the message are left unmapped unless you add rules for them.
Is this Patient mapping US Core compliant?
It targets http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient. The template populates the elements US Core marks as Must Support, but you should always validate the output against the profile. Required elements that are absent in your source data will still fail.
Can I customize the ADT^A01 mapping?
Yes. Forking gives you an editable copy of all 13 rules, reading the PID segment. From there you can re-target a path, swap the value set behind a coded field, or add rules for anything this template leaves unmapped.