# Edit mappings in the Workspace ## What you'll do You edit a model's mappings in the Workspace's visual editor: find a mapping in the outline, change it on the editing sheet, add, rename, move, duplicate and delete mappings, switch to the YAML when you need it, and decide when your edits are saved. ```{figure} ../images/map/editor.png :class: screenshot :alt: The visual editor, the outline above the editing sheet of the systolic mapping The outline of the blood pressure observation model, with `systolic` on the editing sheet. ``` ## Before you start - Open the template and the model in the Workspace ({doc}`start-mapping`): click the model's card on the overview, or pick it from the model crumb in the top bar. - {doc}`paths` and {doc}`conditions` explain the fields on the sheet. ## Steps ### Find your way around The middle pane shows the model in the visual editor: the outline (grey) on top, the editing sheet (white) below it while a mapping is selected. ```{figure} ../images/map/editor.png :class: screenshot :alt: The visual editor with numbered callouts The editor's controls. ``` [1]{.callout} **Filter by name or path** : Shows only the mappings whose name or path matches, with their parents for context; matches are highlighted. {kbd}`Esc` clears it, {kbd}`↓` moves into the outline. [2]{.callout} **Expand all** / **Collapse all** : Opens or folds every mapping that has children. The chevron on a row does it for one. [3]{.callout} **+ Mapping** : Adds a top-level mapping (see below). [4]{.callout} **Model terminology** : The model's own terminology block, always first. See *Set the model terminology* below. [5]{.callout} The selected row : Turns white with an orange bar and **EDITING**; its parents' names turn bold. Each row shows the mapping's name and the ends of its FHIR (red) and openEHR (blue) paths; hover a row for the full paths. A book icon means the mapping's codes are translated. The dot at the end is the mapping's worst problem (red error, amber warning, blue info); a ring on a folded row means a problem somewhere below it. [6]{.callout} The grab handle : Drag it to give the outline or the sheet more room; double-click resets it. Atlas remembers the split in this browser. [7]{.callout} **+ Property** : Adds a property the mapping doesn't have yet: **FHIR condition**, **openEHR condition**, **Manual**, **Terminology**, **Followed by**, **Reference**, **Slot archetype**, **Unidirectional**, **Mapping code** (and, in extension models, **Append to** and **Extension**). [8]{.callout} Delete : Deletes the mapping (see below). [9]{.callout} Close : Closes the sheet ({kbd}`Esc` does the same). The outline takes the full height and the side panes stop highlighting. [10]{.callout} **Auto save** : Whether edits are saved to the engine by themselves (see *Save your edits*). The sheet shows the mapping's name in large type (click it to rename) and its properties in groups: **Maps** (the FHIR and openEHR paths), **Only when** (conditions), **Values** (manual values and terminology), **Continues into** (child mappings as chips, a reference, a slot), **Advanced** (folded unless set), then the tabs **Resolved paths** and **Example values**. A status chip such as `1 error` next to **+ Property** shows the mapping's problems; click it to see them in the Problems dock. Use the keyboard in the outline (click a row first): | Key | Does | |---|---| | {kbd}`↑` / {kbd}`↓` | Select the previous / next row | | {kbd}`←` / {kbd}`→` | Fold / unfold the row, or go to its parent / first child | | {kbd}`Home` / {kbd}`End` | Select the first / last row | | {kbd}`Enter` | Edit the selected mapping's name | | {kbd}`Delete` or {kbd}`Backspace` | Delete the selected mapping | | {kbd}`Ctrl+D` ({kbd}`Cmd+D` on a Mac) | Duplicate the selected mapping | | {kbd}`Alt+↑` / {kbd}`Alt+↓` | Move it up / down among its siblings | | {kbd}`Alt+→` | Move it into the mapping above it, as its last child | | {kbd}`Alt+←` | Move it out of its parent, right after it | ### Add a mapping 1. Click **+ Mapping** for a top-level mapping. For a child, open the parent's **⋯** menu and click **Add child mapping**, or click **+ Add child mapping** (or **+ child**) on the parent's sheet. 2. The new mapping is selected with its name field focused. Type the name, then fill in the **FHIR** and **openEHR** paths ({doc}`paths`). A model without mappings shows **No mappings yet.** and an **+ Add mapping** button. ### Rename a mapping Select the row and press {kbd}`Enter`, or open its **⋯** menu and click **Rename**. The name field on the sheet is focused with the name selected; type the new one. ### Use the row menu Hover a row to see its buttons. ```{figure} ../images/map/row-menu.png :class: screenshot :alt: The menu of a mapping row The grip for dragging [1]{.callout}, **Duplicate (Ctrl+D)** [2]{.callout}, and the **⋯** menu [3]{.callout}. ``` The **⋯** menu holds **Rename**, **Add child mapping**, **Duplicate**, **Move to…**, **Move up**, **Move down** and **Delete**. ### Move a mapping Moving changes where a mapping sits: its order, or its parent. Atlas rewrites the mapping's relative paths for the new parent where it can. **Drag and drop.** Drag a row by its grip (the dotted handle at its left edge) and hold it over another row: - over the middle of a row: the row gets an orange frame and **→ followed by**. Dropping makes the mapping that row's last child. ```{figure} ../images/map/drag-into.png :class: screenshot :alt: A row being dragged over the middle of the location row `description` held over the middle of `location`: it would become its child. ``` - near the top or bottom edge of a row: an orange line shows where it lands, before or after that row. Where several levels end at the same spot, move the pointer left or right to choose the depth: the line's indent follows it. ```{figure} ../images/map/drag-before.png :class: screenshot :alt: The drop line above the location row Held near the top edge of `location`: it would land just before it. ``` Holding a dragged row over the middle of a folded row opens it after a moment, so you can drop deeper. **Keyboard.** Select the row and use {kbd}`Alt` with the arrow keys (see the table above), or **Move up** / **Move down** in the **⋯** menu. **Move to….** Open the row's **⋯** menu and click **Move to…**. Type in **Filter by name or path** [1]{.callout} to find the destination: **Top level** or another mapping (the moved mapping becomes its last child). Destinations that can't take it are greyed out; hover one for the reason. The line at the bottom [2]{.callout} previews how the paths change. Use {kbd}`↑` / {kbd}`↓` and {kbd}`Enter`, or click; {kbd}`Esc` goes back to the menu. ```{figure} ../images/map/move-to.png :class: screenshot :alt: The Move to picker filtered to systolic Moving `clinicalInterpretation` under `systolic`: its FHIR path becomes relative. ``` ### Duplicate or delete a mapping **Duplicate** (the copy button on the row, {kbd}`Ctrl+D`, or **⋯** › **Duplicate**) puts a copy of the mapping, with all its children, right after it, and selects the copy's name so you can rename it. **Delete** (the bin on the sheet, {kbd}`Delete` in the outline, or **⋯** › **Delete**) removes the mapping with all its children. There is no confirmation: undo it instead. ### Undo the last change After a delete, a move or a duplicate, a dark toast at the bottom of the editor says what happened (`Deleted “”`, `Moved “” under “”`, `Moved “” to the top level`, `Duplicated “”` …) with **Undo** [1]{.callout}. It disappears after a few seconds, and stays a little longer when it carries notes. ```{figure} ../images/map/undo-toast.png :class: screenshot :alt: The undo toast after moving a mapping, with two notes A move whose paths couldn't follow the new parent, and **Undo** [1]{.callout}. ``` The notes tell you what to check after a move: | Note | What to do | |---|---| | `FHIR path kept as written: it now resolves from .` | The relative FHIR path couldn't be rewritten for the new parent and now means something else there. Check it. | | `openEHR path kept as written: it now resolves from .` | The same for the openEHR path. | | `openEHR path made absolute: it isn’t under the new parent’s node.` | Atlas rewrote the openEHR path from the archetype root, because the new parent's node doesn't contain it. | | `FHIR condition kept as written: check it still applies.` | The mapping's FHIR condition still names the old place. See {doc}`conditions`. | | `Another mapping here is also named “”.` | Two siblings share a name now. Rename one: problems and highlights pick the first. | ### Work in the YAML (Code view) The two buttons in the middle pane's header switch views: the tree button (**Visual mapping editor**) [1]{.callout} and **<>** (**Raw YAML editor**) [2]{.callout}. ```{figure} ../images/map/code-view.png :class: screenshot :alt: The model as YAML in the Code view The same model in the Code view. ``` The Code view is the model's FHIR Connect YAML. It suggests keys and values from the FHIR Connect schema as you type ({kbd}`Ctrl+Space` asks for them), marks schema errors in the gutter, and indents with spaces when you press {kbd}`Tab`. The caret selects the mapping it is in: the side panes highlight it, and the visual editor opens on it when you switch back. Saving works the same in both views. If the YAML doesn't parse, the visual editor can't show it. The pane switches to the code and says `Couldn't parse the YAML for the visual editor — showing raw code.` with the parser's message. Fix the YAML there. ### Save your edits **Auto save** (on by default) saves the model to the engine shortly after you stop editing, then re-runs the example conversion, so the side panes follow your edits. The footer says *Auto-saves to the engine shortly after you stop editing, then re-runs.* To collect several edits before they reach the engine, untick **Auto save** in the footer [4]{.callout}. Then: ```{figure} ../images/map/manual-save.png :class: screenshot :alt: The Workspace with unsaved edits, the Save button, the Unsaved changes status and the stale panes Saving by hand: **Save** [1]{.callout}, the save status [2]{.callout}, a stale pane's **Save & refresh** [3]{.callout}, and **Auto save** switched off [4]{.callout}. ``` - Edits stay in the browser. The top bar shows **Unsaved changes** [2]{.callout} and a **Save** button [1]{.callout}. - Both example panes are dimmed with **Out of date with your edits** — *This pane won't reflect your mapping changes until you save.* Their **Save & refresh** [3]{.callout} saves and re-runs. - Click **Save** or press {kbd}`Ctrl+S` ({kbd}`Cmd+S`) to save. The status shows **Saving & running…**, then **Saved**. With **Auto save** on, {kbd}`Ctrl+S` saves a pending edit right away and briefly says **Auto-save is on — edits save automatically**. With it off and nothing to save, it says **No unsaved changes**. Ticking **Auto save** again saves any unsaved edits at once. **Leaving with unsaved edits.** Switching template or model, going back, or leaving the Workspace with unsaved edits asks **Leave without saving?** — *You have unsaved changes to this mapping. If you leave now they will be lost. Leave anyway?* Click **Stay** to keep editing, **Leave** to drop the edits. Closing or reloading the browser tab asks through the browser's own prompt. ```{figure} ../images/map/leave-prompt.png :class: screenshot :alt: The Leave without saving dialog The prompt before unsaved edits are dropped. ``` ### Set the model terminology Click **Model terminology** [1]{.callout} at the top of the outline. The sheet shows **EDITING · model header** and the model's **Terminology** block: its **Type** [2]{.callout} (`none`, `inline`, `local` or `external`) and, by type, the ConceptMap, the server or the inline rows. A model without one shows **Add terminology**. The row itself summarises the block, or says `none — add a model-level terminology`. ```{figure} ../images/map/model-terminology.png :class: screenshot :alt: The model terminology of IPS_problem_diagnose, local, with the IPS ConceptMap The model terminology row [1]{.callout} and its type [2]{.callout}. ``` {doc}`/codes-and-profiles/translate-codes` explains which setting to use. ## Check it worked - The top bar's save status shows **Saved** (or nothing) and no **Unsaved changes**. - The side panes show the example converted with your mapping ({doc}`/check/see-in-action`). - The row's status dot and the Problems dock show no new problems ({doc}`/check/fix-problems`). ## Tips :::{tip} Press {kbd}`Esc` to close the sheet and get the whole outline back; {kbd}`↑` / {kbd}`↓` open it again on the next mapping. ::: :::{tip} Filter, then click: the filter finds a mapping by any part of its name or paths (`loinc`, `bodySite`, `at0004`). ```{figure} ../images/map/filter.png :class: screenshot :alt: The outline filtered by "loinc", showing the matching mappings and their parents The Blood Pressure outline filtered by `loinc`. ``` ::: :::{tip} Duplicate a mapping to start a similar one, such as `diastolic` from `systolic`: the copy keeps the conditions and children, so you only change what differs. ::: ## Watch out :::{warning} **Auto save turns back on every time you open the Workspace.** Atlas doesn't remember that you switched it off. If you rely on saving by hand, untick **Auto save** again at the start of each visit. ::: :::{warning} **Moving is off while the outline is filtered.** Rows can't be dragged, and {kbd}`Alt` + arrows and the move items of the **⋯** menu do nothing. Clear the filter to move mappings. ::: :::{warning} **Undo covers only the last delete, move or duplicate**, and only while its toast shows. Text you typed into fields isn't part of it. ::: :::{warning} {kbd}`Esc` closes the sheet only when no field has the focus. In a path field it closes the field's suggestions instead; click a row of the outline first. ::: ## If something goes wrong | What you see | What it means and what to do | |---|---| | **Save failed** in the top bar, with the reason in red in the footer | The engine didn't accept the model. Your edits stay in the editor; fix what the message says and save again. Leaving now asks **Leave without saving?**. | | `This model has no id and can't be edited live.` in the footer | The engine returned the model without an id, so Atlas can't save changes to it. | | `Couldn't parse the YAML for the visual editor — showing raw code.` | See *Work in the YAML* above. | | `No mapping matches “”.` | Nothing matches the filter. Clear it with {kbd}`Esc`. | Problems about single mappings, such as [a mapping without a name](problem-mapping-name-missing), [two mappings with the same name](problem-mapping-name-duplicate), [a mapping without `with`](problem-with-missing) or [a mapping without paths](problem-with-empty), show on the row and in the Problems dock. Every other notice is in {doc}`/reference/messages`. ## Related - {doc}`paths`, {doc}`conditions` and {doc}`fixed-values`: the fields on the sheet. - {doc}`/check/see-in-action`: what the side panes show while you edit. - {doc}`/reference/shortcuts`: every keyboard shortcut. - {doc}`/reference/remembers`: what Atlas keeps in your browser.