Skip to main content

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​

NameTypeRequiredDescription
recordsjsonYesRows to map: a list of objects (connector records), one object, or {records:[…]}

Output ports​

NameTypeRequiredDescription
bundlefhir-bundleNoBundle of every mapped resource; transaction entries are PUT Type/id (POST when no id template)
resourcesjsonNoThe mapped resources as a list, without bundle wrapping
errorsjsonNoOne entry per refused value or rule: record index, resource mapping, element, source column, value, message
statsjsonNorecords, records_mapped, records_failed, resources per type, errors
successbooleanNoTrue when every record mapped without an error

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Resource MappingsresourcesarrayYesOne entry per resource each record produces, in order. References may point to any other entry by name.
Bundle Typebundle_typeenumNotransactiontransaction, collectiontransaction to store with fhir-crud (operation transaction); collection to pass resources on (e.g. to fhir-to-omop)
Source TimezonetimezonestringNoIANA zone of timestamps that carry none (e.g. Europe/Madrid). Unset: such timestamps are refused, not assumed UTC

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
On Record Erroron_errorenumNoskip_recordskip_record, failskip_record: the record contributes nothing and is listed on errors; fail: any error fails the node

Errors​

CodeDescription
INVALID_MAPPINGThe mapping config is malformed (unknown resource type, bad path, unknown transform, missing value map, dangling reference)
NO_RECORDSNothing is wired to the records port
RECORD_REFUSEDWith 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.

Something unclear? Send documentation feedback by email.