FHIR Map
Category: Healthcare Standards
Node id: fhir-map
Maturity: beta
Risk tier: C
Standards: HIPAA, GDPR
Declarative table/JSON → FHIR R4 mapper: maps each record to one or more resources (target element path ← column, transform, constant), deterministic ids, references between the resources of a record, and a transaction or collection Bundle. Refused values are reported per record, never dropped.
What it does
- Declarative, reviewable row → FHIR R4 mapping edited in the Studio field mapper
- Several resources per record with references between them (Encounter.subject → Patient)
- Deterministic ids from key columns; repeated rows produce one resource; disagreeing rows are reported as conflicts
- Typed transforms for date, dateTime, instant, decimal, integer, boolean, code, URI and value maps
- FHIR R4 mandatory elements and required code bindings checked for common resources
Use cases
- Map a joined patients/episodes/lab results table to Patient, Encounter and Observation and store them in one transaction
- Map a vendor JSON document to a FHIR Patient for the viewer
- Produce a collection Bundle from landed rows for fhir-to-omop
Runtime
- Performance tier:
fast - Effect:
read
Input ports
| Name | Type | Required | Description |
|---|---|---|---|
records | json | Yes | Rows to map: a list of objects (connector records), one object, or {records:[…]} |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
bundle | fhir-bundle | No | Bundle of every mapped resource; transaction entries are PUT Type/id (POST when no id template) |
resources | json | No | The mapped resources as a list, without bundle wrapping |
errors | json | No | One entry per refused value or rule: record index, resource mapping, element, source column, value, message |
stats | json | No | records, records_mapped, records_failed, resources per type, errors |
success | boolean | No | True when every record mapped without an error |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Resource Mappings | resources | array | Yes | One entry per resource each record produces, in order. References may point to any other entry by name. | ||
| Bundle Type | bundle_type | enum | No | transaction | transaction, collection | transaction to store with fhir-crud (operation transaction); collection to pass resources on (e.g. to fhir-to-omop) |
| Source Timezone | timezone | string | No | IANA zone of timestamps that carry none (e.g. Europe/Madrid). Unset: such timestamps are refused, not assumed UTC |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| On Record Error | on_error | enum | No | skip_record | skip_record, fail | skip_record: the record contributes nothing and is listed on errors; fail: any error fails the node |
Errors
| Code | Description |
|---|---|
INVALID_MAPPING | The mapping config is malformed (unknown resource type, bad path, unknown transform, missing value map, dangling reference) |
NO_RECORDS | Nothing is wired to the records port |
RECORD_REFUSED | With on_error=fail, at least one record had an invalid value, a missing required element or a conflicting id |
Runtime notes
- A record with any error contributes nothing to the bundle and appears on errors; success is false when any record failed
- Element paths are dotted FHIR element names with optional [n] indices; a source path may reach into nested JSON (person.name.family); an exact column name wins over a path
- An empty source leaves the element out unless the pair has a default; a default with no source is a constant
- No transform passes the value through unchanged; use date/dateTime/decimal/code to get validated FHIR primitives
- Patient.gender and other required-binding codes must already be FHIR codes — map local values with value_map; there is no built-in sex mapping (H/M differ between languages)
- A driver time value is taken with the zone the driver gave it; for TIMESTAMP WITHOUT TIME ZONE columns select text (e.g. TO_CHAR) and set timezone, or local times are labelled UTC
- Transaction entries are PUT Type/id when an id template is set (idempotent re-runs), POST otherwise
- Wire bundle to fhir-crud (operation transaction, port bundle) and to fhir-to-omop (port bundle)
See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.
Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.