# 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, {external+openfhir:doc}`fhirconnect`. (key-ideas-terms)= ## The parts (key-ideas-template)= ### 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. (key-ideas-context-mapper)= ### 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. (key-ideas-start)= ### 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. (key-ideas-model)= ### 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**. (key-ideas-mapping)= ### 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: - **Maps**: the FHIR path and the openEHR path ({doc}`/map/paths`). - **Only when**: optional conditions that limit the mapping to some values ({doc}`/map/conditions`). - **Values**: fixed values to write, and code translation ({doc}`/map/fixed-values`, {doc}`/codes-and-profiles/translate-codes`). - **Continues into**: what happens below this point, through *followed by*, a *slot* or a *reference*. - **Advanced**: *unidirectional*, a mapping code, and for extension models how the mapping extends the model it extends. 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. (key-ideas-followed-by)= ### 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. (key-ideas-slot)= ### 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" ({doc}`/map/connect-models`). (key-ideas-reference)= ### 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. (key-ideas-extension)= ### 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**. (key-ideas-conceptmap)= ### 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 ({doc}`/codes-and-profiles/conceptmaps`, {doc}`/codes-and-profiles/translate-codes`, and in the engine documentation {external+openfhir:doc}`terminology`). (key-ideas-fhir-package)= ### 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 ({doc}`/codes-and-profiles/fhir-packages`). Without it, Atlas works against base FHIR and says which profiles are missing. (key-ideas-walk)= ## 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: ::::{grid} 1 2 2 4 :gutter: 2 :::{grid-item-card} 1 · Context mapper `health_summary.context` is the context mapper of the template *International Patient Summary*. Its start is `COMPOSITION.health_summary.v1`. ::: :::{grid-item-card} 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. ::: :::{grid-item-card} 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. ::: :::{grid-item-card} 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. (key-ideas-directions)= ## 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 ({doc}`/check/see-in-action`). ## Related - {doc}`tour`: where these parts appear in Atlas. - {doc}`first-mapping`: change a mapping of the demo data and see the effect. - {doc}`/map/connect-models`: slots, links and references in practice. - {doc}`/reference/glossary`: every term used in Atlas. - {external+openfhir:doc}`fhirconnect` and {external+openfhir:ref}`state-configuration`: the engine's view of the same files.