State configuration

Note

FHIR Connect State comprises of 2 main files: context and model mappers. Read more on the official FHIR Connect specification.

State required by the engine are mapping files according to FHIR Connect specification and are split to context.yaml files and model.yaml files. Additionally, state required by the engine are also openEHR Operational Templates (.opt), which can either be part of the openFHIR Engine’s state or it can come from an integrated openEHR repository (see more: Integrations).

As an example, for a mapping of a blood pressure template, you’d need the following files (state) configured:

  • Blood Pressure.opt

  • simple-blood-pressure.context.yaml

  • blood-pressure.model.yaml

Bootstrapping

State configuration can be achieved by POSTing OPT and YAML files to the designated /opt and /fc/(context, model) endpoints. Alternatively, these files can be placed in a bootstrapping directory where they are picked from during the engine’s startup, as well as on demand through POST /$bootstrap. This approach minimizes the need for repetitive API calls, allowing for faster and more efficient configuration of pre-existing mappings.

Bootstrapping location is configured with environment variable BOOTSTRAP_DIR, default being /app/bootstrap/.

For example, setting -e BOOTSTRAP_DIR=/etc/bootstrapping-dir and placing files in this folder (/etc/bootstrapping-dir) will make the engine pick them up at startup and process them. The same directory is re-scanned whenever POST /$bootstrap is called.

If you have files to be bootstrapped separated in sub-folders, you may also add RECURSIVELY-OPEN-DIRECTORIES=true, which will make openFHIR Bootstrapper open all sub-folders as well and look inside for any matching files to be bootstrapped.

Files are picked according to their suffixes:

  • model files need to be suffixed with *.yaml or *.yml, i.e. blood.pressure.model.yaml

  • context files need to be suffixed with *.context.yaml or *.context.yml, i.e. simple-blood-pressure.context.yaml

  • operation template files need to be suffixed with *.opt, i.e. BloodPressure.opt

  • terminology concept maps (read more in Terminology) need to be suffixed with *.json, i.e. concept-map.json

Every bootstrapped file is recorded in a ledger (bootstrap collection) together with the path it was bootstrapped from, a hash of the content that was applied, and the id of the entity it created. On every scan, openFHIR compares each file on disk against this ledger and:

  • creates an entity for a file it has not seen before,

  • updates a file whose content changed since it was last bootstrapped, in place and under the same entity id, so no duplicates are created,

  • skips a file whose content is unchanged.

Files that were bootstrapped before but are no longer on disk are reported with a warning in the log; their entities are left untouched and are not removed from the engine.

Note

Ledger entries are keyed by the file’s path relative to the bootstrap directory, so identically named files in different sub-folders no longer collide.

Re-running the bootstrap

The bootstrap directory scan is no longer limited to startup. POST /$bootstrap re-runs it on demand, without requiring a restart, and returns a JSON summary of what happened:

  • created, updated, unchanged and failed counts

  • files, a per-file breakdown with each file’s path, outcome (CREATED, UPDATED, UNCHANGED or FAILED), entityType, entityId and, where the file failed, a message

If a scan is already in progress, the endpoint returns 409 Conflict instead of starting a second one.

GET /bootstrap returns the bootstrap ledger of the logged-in user: which files have been bootstrapped, from which path, and which entity each one created.

Note

The web server accepts requests before the startup scan has finished. GET /health returns 503 STARTING until the startup scan completes and 200 UP afterwards, so it can be used as a “safe to send traffic” gate by orchestrators and test harnesses. Calling POST /$bootstrap before the startup scan completes will return 409 Conflict.

The bootstrap ledger is tenant-scoped. GET /$purge therefore clears the bootstrap entries of the logged-in user’s tenant along with the rest of its state, meaning that tenant’s bootstrapped files will be created again on the next scan.

Through REST

State configuration can be achieved by POSTing OPT and YAML files to the designated /opt and /fc/(context, model) endpoints. See RESTful APIs for more information.