# Your first mapping in 15 minutes ## What you'll do You load the demo mappings into an empty engine, open the International Patient Summary (IPS) template in the Workspace, and fix two things the demo data gets wrong: a problem's body site that never reaches FHIR, and two mappings with the same name. On the way you read a mapping in the editing sheet, pick a path from suggestions, watch the example convert, work from the Problems dock, and check what the template's mappings cover. ```{figure} ../images/start/panes-updated.png :class: screenshot :alt: The Workspace with the bodySite mapping selected, its openEHR path fixed, and the body site highlighted in both example panes The end result of the first part: the problem's body site now converts, and both example panes highlight it. ``` ## Before you start - You can sign in to Atlas ({doc}`before-you-start`), in a window at least 768 pixels wide. - The engine has no templates yet, so **Engine state** offers the demo data. If it already has the demo templates (on the public demo it usually does), start at step 2. - The demo data is about to change: everything you edit is saved to the engine. Use an engine where that is fine, such as your sandbox. - {doc}`key-ideas` explains template, model, mapping and slot, if the words are new to you. ## Steps ### 1. Load the demo mappings 1. Click **Engine state** in the sidebar. On an empty engine it shows a welcome card. 2. Click **Load demo mappings** [1]{.callout}. ```{figure} ../images/start/welcome.png :class: screenshot :alt: The welcome card of an empty engine with Demo data, API Access and Documentation and Support The welcome card of an empty engine, with **Load demo mappings** [1]{.callout}. ``` 3. When the button stops spinning, **Engine state** lists three templates: *Blood Pressure*, *Growth chart* and *International Patient Summary* [1]{.callout}, and the model mappers they use. *International Patient Summary* says **Partially mapped**: the demo maps only part of it. ```{figure} ../images/start/demo-loaded.png :class: screenshot :alt: Engine state with the three demo templates and their model mappers **Engine state** with the demo data. The IPS template [1]{.callout}. ``` ### 2. Open the IPS template in the Workspace 1. Click the *International Patient Summary* row, then **Open in workspace**. 2. The Workspace opens on the template's overview: ```{figure} ../images/start/ips-overview.png :class: screenshot :alt: The Workspace overview of the International Patient Summary template with numbered callouts The IPS template in the Workspace. ``` **START** [1]{.callout} : The start model, `COMPOSITION.health_summary.v1`: every conversion begins here. A model card [2]{.callout} : `EVALUATION.problem_diagnosis.v1` maps the problem/diagnosis archetype to a FHIR `Condition`. The red **⊗ 1** says it has one error; the bar at the bottom, how much of the archetype it maps (`8 / 10`). The openEHR example [3]{.callout} : A composition Atlas generated from the template, in the flat format. The generated texts read "Lorem ipsum". The FHIR example [4]{.callout} : The same composition converted to FHIR with the saved mappings: here a Bundle with the IPS Composition, a Condition and an AllergyIntolerance. The problem counts [5]{.callout} : The template's errors and warnings. They include the findings of the FHIR validation that runs after each conversion, so they depend on which FHIR packages your engine has. The coverage [6]{.callout} : The share of the template's elements that something maps. ### 3. Select a mapping and read the editing sheet 1. Click the `EVALUATION.problem_diagnosis.v1` card. The middle pane shows the model's mappings as an outline. 2. Click the `bodySite` row [1]{.callout}. The editing sheet opens under the outline: ```{figure} ../images/start/inspector.png :class: screenshot :alt: The outline of EVALUATION.problem_diagnosis.v1 with bodySite selected, and the editing sheet of bodySite The `bodySite` mapping in the editing sheet. ``` The selected row [1]{.callout} : Marked **EDITING**. The red dot at its end is its status: it has an error. The status [2]{.callout} : **2 problems**. Point at it to read them; click it to list them in the Problems dock. The first is the engine's: "Mapping 'bodySite' of model mapper 'EVALUATION.problem_diagnosis.v1': openEHR path '…/data[at0012]' does not exist in the template ('data[at0012]' not found); the mapping is skipped." The second is a hint from the example: "The example has 0 FHIR values but 1 openEHR node for it — a missing [n] / iteration or a condition that selects too much or too little?" **FHIR** [3]{.callout} : `$resource.bodySite`: the `bodySite` of the model's resource. The line under it shows what that resolves to, `Condition.bodySite`, a `CodeableConcept`. **openEHR** [4]{.callout} : `$archetype/data[at0012]`: a node of the problem/diagnosis archetype. The warning [5]{.callout} : "The engine could not resolve this path against the template." The archetype has no node `data[at0012]`: *Body site* is the item `at0012` inside `data[at0001]`. The footer tabs [6]{.callout} : **Resolved paths** shows where the mapping lands in the whole conversion, **Example values** the values it moves in the example (`0 ⇄ 1`: nothing on the FHIR side, one value on the openEHR side), **Translation** the code translation it uses. ### 4. Change the openEHR path with a suggestion 1. Click into the **openEHR** field, select its text and type `$archetype/body`. 2. Suggestions open below the field. openEHR suggestions match the *names* of the template's nodes, so typing "body" finds *Body site* and offers its whole path. ```{figure} ../images/start/path-suggestions.png :class: screenshot :alt: The openEHR field with $archetype/body typed and a list of suggestions, the first being data[at0001]/items[at0012], Body site, ELEMENT 0..* Suggestions for `$archetype/body`. ``` 3. The first suggestion is `data[at0001]/items[at0012]`, *Body site*, an `ELEMENT` that may occur any number of times (`0..*`). Press {kbd}`Enter` (or click it). The field now reads `$archetype/data[at0001]/items[at0012]`, and the line under it ends in **Body site · ELEMENT**. Use {kbd}`↑` and {kbd}`↓` to move through the suggestions, {kbd}`Enter` or {kbd}`Tab` to take one, and {kbd}`Esc` to close the list. {kbd}`Ctrl+Space` opens it without typing. ### 5. Watch both example panes update With **Auto save** on (the check box at the bottom of the middle pane, on by default), Atlas saves shortly after you stop typing and converts the example again: ```{figure} ../images/start/panes-updated.png :class: screenshot :alt: The Workspace after the save, with Saved in the top bar and bodySite highlighted in both panes After the save: **Saved** [1]{.callout}, and the body site in the openEHR [2]{.callout} and FHIR [3]{.callout} examples. ``` 1. The top bar shows **Saving & running…**, then **Saved** [1]{.callout}. 2. Atlas converts the openEHR example to FHIR, then the result back to openEHR, so both panes show what the mappings do now. 3. The FHIR pane [3]{.callout} has a new element in the Condition, highlighted because `bodySite` is the selected mapping: ```json "bodySite": [ { "text": "Lorem ipsum" } ], ``` The openEHR pane [2]{.callout} highlights the body site the value came from. 4. The status of `bodySite` is gone from the editing sheet, the red dot from its row, and **Example values** reads `1 ⇄ 1`. The red wavy underlines in the FHIR pane are findings of the FHIR validation, not of your edit; see {doc}`/check/validate`. ### 6. Read a problem and fix it from the dock 1. Click the problem counts in the top bar. The **Problems** dock opens under the three panes, its problems grouped by model. ```{figure} ../images/start/problems-dock.png :class: screenshot :alt: The Problems dock with severity toggles, the source filter, and the problems of SECTION.adhoc.v1_problem_list The Problems dock. ``` The severity toggles [1]{.callout} : The number of errors, warnings and infos. Click one to hide or show that severity. **All sources** [2]{.callout} : Shows only the problems of one kind of check: **Engine**, **openEHR path**, **Structure**, **FHIR validation** and so on. A problem [3]{.callout} : The mapping it concerns (`emptyReason`), the message, the kind of check (**Structure**), and where clicking it takes you (**FHIRConnect**: the mapping editor). Pointing at a row shows a **?** at its end (framed): it opens the problem's explanation in this guide. 2. Under `SECTION.adhoc.v1_problem_list`, read the warning: "2 sibling mappings are named 'emptyReason'; highlighting and the resolved paths can only tell them apart by name." The model has two mappings called `emptyReason`, one for an *absence of information* entry and one for an *exclusion* entry. 3. Click the warning. Atlas opens `SECTION.adhoc.v1_problem_list`, selects the first `emptyReason` and puts the cursor in its name (framed): ```{figure} ../images/start/problem-opened.png :class: screenshot :alt: The mapping editor of SECTION.adhoc.v1_problem_list with emptyReason selected and its name field focused The mapping the warning is about, with its name ready to edit. ``` 4. Type a name of its own, `emptyReasonAbsence`. After the auto-save the warning is gone, and the model's group in the dock, now marked **Open in the editor**, lists only its two remaining errors: ```{figure} ../images/start/problem-fixed.png :class: screenshot :alt: The Problems dock after the rename, with the group of SECTION.adhoc.v1_problem_list framed and no warning in it The problem list section's problems after the rename (framed). ``` While you type, the dock checks your unsaved edit and marks the problems it finds **unsaved**. ### 7. Check coverage 1. In the top bar, open the model menu (**▾** next to the model name) and choose `EVALUATION.problem_diagnosis.v1`. 2. Click the coverage percentage in the top bar. The openEHR pane switches to its **Template** tab: the template's tree, with what is mapped. ```{figure} ../images/start/coverage.png :class: screenshot :alt: The Template tab of the openEHR pane for EVALUATION.problem_diagnosis.v1, with Body site mapped and + Map next to Impact Coverage of the problem/diagnosis model. ``` The totals [1]{.callout} : `9 / 10 in Problem/Diagnosis`: this model maps 9 of the archetype's 10 elements. **template 12%** is the share of the whole template. **Unmapped only** [2]{.callout} : Hides everything that is mapped. **Required only** next to it keeps only what must be present. The legend [3]{.callout} : Point at the **?** to read the marks: **✓** mapped, a light **✓** covered by its cluster's mapping, **◐** partly mapped, **○** not mapped, **↗** mapped by its own model, **–** empty in this template. *Body site* [4]{.callout} : Mapped now (**✓**), and marked **EDITING** because `bodySite` is the selected mapping. **+ Map** [5]{.callout} : Point at an element that isn't mapped, such as *Impact*, to add a mapping for it. ## Check it worked - The `bodySite` mapping has no status in the editing sheet, and the `EVALUATION.problem_diagnosis.v1` card on the overview has no error. - The FHIR example's Condition has `bodySite`. - The Problems dock has no `mapping-name-duplicate` warning for `SECTION.adhoc.v1_problem_list`. - The Template tab shows *Body site* as mapped, and the model's count went from 8 to 9 of 10. ## Tips :::{tip} Point at a mapping's status, a problem or a coverage mark before you click: the tooltip usually says what is wrong and what a click will do. ::: :::{tip} Clicking a problem selects the mapping and puts the cursor in the field it is about: the name for a duplicate name, the openEHR path for a path that isn't in the template. Fix it there and the auto-save does the rest. ::: :::{tip} The other errors of the demo are good practice. The `emptyReason › reason › code` mappings, for example, point at `data[at0001]/items[at0005]`, which isn't in the template; the suggestions show what is. ::: ## Watch out :::{warning} Every edit is saved to the engine a moment after you stop typing, and from then on every conversion of the engine uses it. To try something without saving it, clear **Auto save** at the bottom of the middle pane first; Atlas turns it on again each time you open the Workspace. ::: :::{warning} To start over with the original demo data, delete the three demo templates on **Engine state** (select a template, **⋯**, **Delete template…**) with **Also delete all archetypes (model mappers) in the context mapper tied to this template.** checked. When the engine has no templates left, **Load demo mappings** is offered again. ::: ## If something goes wrong The welcome card stays after **Load demo mappings** : The engine didn't take the demo data, or Atlas couldn't read the engine. Reload the page; if the card is still there, check that the engine is running. See {ref}`the welcome message `. "Couldn't load the engine state" : The Workspace couldn't read the engine. Click **Retry** ({ref}`explained here `). "Open the Workspace on a larger screen" : Your window is narrower than 768 pixels ({ref}`explained here `). **Save failed** in the top bar : The engine refused the edit; the message under the editor says why ({ref}`explained here `). "Exception trying to convert due to: …" above a pane : The engine couldn't convert the example ({ref}`explained here `). The problems of this tutorial : {ref}`openehr-not-in-template ` (the body site path), {ref}`mapping-name-duplicate ` (the two `emptyReason` mappings), and {ref}`FHIR validation ` (the wavy underlines in the FHIR pane). ## Related - {doc}`/map/edit-in-workspace`: everything the outline and the editing sheet can do. - {doc}`/map/paths`: how FHIR and openEHR paths are written, and their suggestions. - {doc}`/check/see-in-action`: the example panes, highlights and example values. - {doc}`/check/fix-problems`: the Problems dock in detail. - {doc}`/check/coverage`: the Template and Profile tabs. - {doc}`/map/start-mapping`: map a template of your own.