Key ideas in plain words

Atlas edits the mappings that the openFHIR engine follows when it converts openEHR data to FHIR and back. The mappings are files in the FHIR Connect format; Atlas shows them as forms and outlines, so you rarely see the files themselves. This page explains the words Atlas uses for their parts, and how the engine walks through them during a conversion. The exact rules of the format are in the engine documentation, FHIR Connect.

The parts

Template (OPT)

An operational template (OPT, an .opt file) describes one kind of openEHR composition: which archetypes it contains, where, how often, and with which data types. For example, the International Patient Summary template holds a problem list with problem/diagnosis entries, an allergy list and a medication summary.

Atlas lists the templates loaded in the engine on Engine state. Every mapping you write belongs to a template, and Atlas checks your openEHR paths against it.

Context mapper

The context mapper (one per template) is the entry point of the mappings. It says:

  • which template it is for, and which FHIR profile the result has (for example a Bundle, or the IPS Composition);

  • which models take part (its archetypes list) and which extension models apply (extensions);

  • which model to start with (start).

The engine finds the context mapper of a conversion by its template id or its FHIR profile. In the Workspace, the <> button on a template’s overview (Edit the context mapper YAML) opens it.

Start archetype

The start archetype is the model the engine begins every conversion with, usually the model of the template’s COMPOSITION archetype. The Workspace shows it first in a template’s overview, marked START. Everything else is reached from it, through slots.

Model (model mapper)

A model, or model mapper, maps one openEHR archetype to one FHIR type. It names:

  • its openEHR archetype, for example openEHR-EHR-EVALUATION.problem_diagnosis.v1;

  • its FHIR side: a resource, a data type, or a profile (Condition, a BackboneElement, the IPS Composition profile);

  • its mappings.

A model is written once per archetype and can be used by several templates. Engine state calls them model mappers; the Workspace shows the open template’s models as cards under ARCHETYPE MAPPINGS.

Mapping

A mapping is one rule inside a model: this FHIR path corresponds to that openEHR path. Its parts, as the Workspace’s editing sheet shows them:

The engine handles each value it finds at the paths. A mapping whose openEHR path doesn’t exist in the template is skipped, which is why Atlas reports it as a problem.

Followed by

Followed by gives a mapping child mappings. Their paths are relative to the parent’s: for each value the parent maps, the children map the parts inside it. For example, a systolic mapping finds the systolic component of a blood pressure; its children map that component’s value and code. In the Workspace’s outline, child mappings are indented under their parent.

Slot

A slot hands over to another model. A mapping with a Slot archetype says: at this node, the mappings of that model take over. The International Patient Summary’s start model, for example, has a slot for the problem list section, and the problem list’s model has a slot for each problem/diagnosis entry.

A model that no slot reaches is never used in a conversion, even when it is listed in the context mapper. The Workspace marks such a model “Not linked” (Connect models: slots, links, references).

Reference

A reference makes a separate FHIR resource and points to it. The FHIR element of the mapping is a Reference, and the mappings under Reference build the referenced resource, of the resource type you choose. The IPS problem list section, for example, refers to one Condition per problem (Composition.section.entry), and the problem/diagnosis model fills in each Condition.

Extension model

An extension model changes another model without copying it. It names the model it extends and lists mappings, each with what it does to that model:

add

Adds the mapping to the model.

append

Adds to an existing mapping, named in Append to: its conditions, and its child mappings at the end of that mapping’s children.

overwrite

Replaces the model’s mapping of the same name.

The context mapper lists the extensions it uses, so one template can extend a shared model while other templates use the model as it is. In the IPS demo, IPS_problem_diagnose extends EVALUATION.problem_diagnosis.v1 with IPS-specific mappings. The Workspace shows an extension model under the model it extends, marked EXTENSION.

ConceptMap

A ConceptMap is a FHIR resource that lists code pairs: this code in one code system corresponds to that code in another. When the codes on the openEHR side differ from the codes the FHIR side expects, a model or a single mapping uses a ConceptMap (or a few code pairs written into the mapping) to translate them during the conversion. You manage the engine’s ConceptMaps on the Terminology page (Manage ConceptMaps, Translate codes, and in the engine documentation Terminology).

FHIR package and profile

A profile narrows a FHIR resource for one use: which elements are required, which are must support, which codes are allowed, which extensions exist. Profiles are published in implementation guide packages (.tgz), such as the IPS package.

When a model follows a profile, Atlas uses it for path suggestions, for the checks in the Problems dock, for coverage, and for validating the converted FHIR. For that, the package that defines the profile has to be loaded in the engine, on the FHIR packages page (Use FHIR profiles and IG packages). Without it, Atlas works against base FHIR and says which profiles are missing.

How a conversion walks through the mappings

The engine starts at the context mapper and follows slots and references from model to model. Here is the path one problem in an International Patient Summary takes, from the composition down to the body site of the problem, as the demo data maps it:

1 · Context mapper

health_summary.context is the context mapper of the template International Patient Summary. Its start is COMPOSITION.health_summary.v1.

2 · Start model

COMPOSITION.health_summary.v1 builds the IPS Composition. Its mapping sectionActiveProblems maps the section named Problem List, only when the section code is 11450-4, and slots SECTION.adhoc.v1_problem_list there.

3 · Slotted model

SECTION.adhoc.v1_problem_list maps the section. Its mapping entry is a reference to a Condition, whose mapping problemDiagnosis slots EVALUATION.problem_diagnosis.v1, once per problem.

4 · Mappings

EVALUATION.problem_diagnosis.v1, with the additions of its extension IPS_problem_diagnose, maps each problem’s elements. Its mapping bodySite maps the problem’s Body site to Condition.bodySite.

Put together, the engine places bodySite at Composition.section.entry.as(Reference).resolve().bodySite: the bodySite of the Condition that a section entry of the Composition refers to. The Resolved paths tab of the Workspace’s editing sheet shows where a mapping ends up in the whole conversion.

Both directions, and “unidirectional”

The same mappings work both ways:

openEHR → FHIR

The engine reads a composition and, for each mapping, writes the value it finds at the openEHR path to the FHIR path. The result is the FHIR resource or Bundle of the context mapper’s profile.

FHIR → openEHR

The engine reads FHIR and, for each mapping, writes the value it finds at the FHIR path to the openEHR path. The result is a composition of the template, in the flat format.

A unidirectional mapping runs in one direction only. Set it in the editing sheet under Advanced → Unidirectional:

openehr->fhir

The mapping is used only when converting openEHR to FHIR. Use it, for example, for a FHIR element that has nothing to give back to openEHR.

fhir->openehr

The mapping is used only when converting FHIR to openEHR.

The Workspace converts in both directions while you edit: its left pane holds an openEHR example and its right pane a FHIR example, and Atlas converts from the one you edit to the other (See your mapping in action).