Aller au contenu principal

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.

Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.