# Fix problems ## What you'll do You work through the **Problems** dock of a template: narrow it down to what matters, click a problem to land on the field that causes it, fix it, and see it go away. Every problem code is explained, with how to fix it, in {doc}`/reference/problems`. ```{figure} ../images/check/dock.png :class: screenshot :alt: The Problems dock of the International Patient Summary template The Problems dock of the demo template "International Patient Summary". ``` ## Before you start - Open a template in the Workspace. The problems button in the top bar shows its error and warning counts; click it to open the dock under the three panes. Click it again to close the dock. - Atlas checks the template in two ways (see [Live and saved checks](#fix-problems-live)): the saved state on the server, and the open model's unsaved edits in your browser. ## Steps ### 1. Narrow the list down The numbers match the screenshot above. [1]{.callout} **Severity toggles** : One per severity with its count: errors, warnings, infos. Click one to hide that severity (it shows struck through); click again to show it. [2]{.callout} **Source filter** : **All sources**, or one of **Engine**, **FHIR path**, **openEHR path**, **Structure**, **Context**, **Schema**, **FHIR validation**. [3]{.callout} **Refresh** : "Re-check the saved mappings". Saving a model re-checks by itself; use it after changes made elsewhere (another user, an upload). [4]{.callout} **Minimize to a strip** : Folds the dock into one line with the counts and the worst problem; click the strip ("Show all") to open it again. **×** next to it closes the dock. ```{figure} ../images/check/strip.png :class: screenshot :alt: The Problems dock minimized to one line with the counts, the worst problem and Show all The dock minimized to a strip. ``` [5]{.callout} **A model group** : Problems are grouped by model, in a fixed order that never changes when you open a model. The open model's group is tinted and marked **Open in the editor**. [6]{.callout} **Where a click lands** : **FHIRConnect**: the mapping editor. **FHIR**: the element in the FHIR example pane. Drag the gutter above the dock to make it taller (double-click resets it). ### 2. Scope the dock to one mapping On the editing sheet, a mapping with problems shows a status chip next to **+ Property**, for example `1 error` or `3 problems`. Click it: the dock opens with only that mapping's problems and those of the mappings below it. The filter chip shows the mapping; its **×** ("Show all problems") removes the scope. Opening another model removes it too. ```{figure} ../images/check/scoped.png :class: screenshot :alt: The Problems dock scoped to the comment mapping Scoped to `comment` [1]{.callout} from its status chip. ``` ### 3. Read a row Each row shows the mapping (names from the top-level mapping down, joined by `›`), the message and labels below it: - the source (**Engine**, **FHIR path**, …); - `×N`: found at N places, because the model is slotted in N times; - `unsaved`: found in your unsaved edits; - `from last save`: an engine check of the open model, from its last save; it is re-run when you save; - for FHIR validation issues, the element's location and **go to mapping** ({doc}`validate`). Hover a row for the **?** icon, "What this problem means and how to fix it": it opens the problem's section in {doc}`/reference/problems`. ### 4. Click the problem Clicking a row takes you to the cause: - **A problem of a mapping**: Atlas opens its model (asking first if another model has unsaved edits), selects the mapping in the visual editor and puts the cursor in the field at fault: the FHIR path, the openEHR path, the name, **Slot archetype**, the **Reference** type or the **Terminology** type. The row stays marked until you select another mapping. - **A problem of a model as a whole** (no mapping named): Atlas opens the model. - **A problem of the context** (group **Context mapper**): Atlas opens the context mapper of the template. - **A FHIR validation issue**: the FHIR pane switches to **Example** and selects the element. The rows of the mapping selected in the editor carry a blue bar, so you see at a glance which problems belong to what you are editing. ### 5. Fix it and check Fix the field, then save (or let auto-save do it). The open model's problems update while you type; the rest update after the save. A fixed problem disappears from the dock and from the mapping's status chip. | Code | Source | What it is about | |---|---|---| | {ref}`slot-conflict ` | Engine | `slotArchetype` and `slotContext` on one mapping | | {ref}`slot-context ` | Engine | A slot context that can't be entered | | {ref}`hierarchy-unresolved ` | Engine | The model's hierarchy path | | {ref}`engine-issue ` | Engine | Any other engine message | | {ref}`fhir-path-unknown ` | FHIR path | A FHIR path that isn't an element | | {ref}`fhir-path-prohibited ` | FHIR path | An element the profile forbids | | {ref}`fhir-slice-unknown ` | FHIR path | No slice matches | | {ref}`profile-not-loaded ` | FHIR path | The model's profile isn't loaded | | {ref}`openehr-not-in-template ` | openEHR path, Engine | An openEHR path the template doesn't have | | {ref}`with-missing ` | Structure | No `with` | | {ref}`with-empty ` | Structure | No path at all | | {ref}`mapping-name-missing ` | Structure | A mapping without a name | | {ref}`mapping-name-duplicate ` | Structure | Siblings with the same name | | {ref}`slot-target-missing ` | Structure, Engine | A slot naming no model of the context | | {ref}`reference-type-missing ` | Structure | A reference without a resource type | | {ref}`reference-type-unknown ` | Structure | A reference type FHIR doesn't know | | {ref}`terminology-conceptmap-missing ` | Structure | A `local` terminology without a ConceptMap | | {ref}`terminology-conceptmap-unknown ` | Structure | A ConceptMap the engine doesn't have | | {ref}`extension-url-not-written ` | Structure | An extension built without its url | | {ref}`model-without-mappings ` | Structure, Engine | A model with no mappings | | {ref}`context-model-missing ` | Context | The context names a model that doesn't exist | | {ref}`start-model-missing ` | Context | The start model doesn't exist | | {ref}`archetype-not-in-template ` | Context | A model's archetype isn't in the template | | {ref}`model-unreached ` | Context | A model nothing slots in | | {ref}`schema ` | Schema | The YAML breaks the FhirConnect schema | | {ref}`yaml-syntax ` | Schema | The YAML doesn't parse | | {ref}`FHIR validation ` | FHIR validation | Issues of the FHIR example ({doc}`validate`) | (fix-problems-live)= ## Live and saved checks The server checks the **saved** state of the whole template: every model, the context and the engine's resolved mapping tree. While the open model has unsaved edits, your browser re-checks its YAML as you type (schema, structure, FHIR paths, openEHR paths) and these live results replace the saved ones of that model. The dock then says "Live for — the rest reflects the last save.", live rows are marked `unsaved`, and the open model's engine checks are marked `from last save`. ```{figure} ../images/check/live.png :class: screenshot :alt: The Problems dock with live problems of the allergy model `category` renamed to `substance` without saving: the duplicate name is found live. ``` [1]{.callout} The live note. [2]{.callout} A live problem. [3]{.callout} An engine check of the open model from its last save. ## Tips :::{tip} Infos can be dismissed: hover an {bdg-info}`info` row and click the eye icon ("Dismiss"). It stays hidden for this template. Errors and warnings can't be dismissed; fix them. ```{figure} ../images/check/dismiss.png :class: screenshot :alt: Dismissing the profile-not-loaded info **Dismiss** on an info. ``` ::: :::{tip} Fix errors first: an error usually means the engine skips the mapping, and problems below it often come from the same cause. ::: ## Watch out :::{warning} Live checks cover only the open model. Everything else in the dock reflects the last save: a fix in another model shows once that model is saved. ::: :::{warning} Dismissed infos and ignored validation issues are kept **in this browser**. Your teammates still see them, and so do you in another browser. ::: ## If something goes wrong - "The engine's helper tree couldn't be read, so its checks are missing: ": the dock shows only the checks Atlas could run itself. See {ref}`Banners `. - "Failed to load problems": the saved checks couldn't be loaded; **Refresh**. - "No problems match the filters.": show the hidden severities or pick **All sources**. ## Related - {doc}`/reference/problems`: every code, with its fix. - {doc}`validate` - {doc}`see-in-action`, {doc}`coverage` - {doc}`/map/edit-in-workspace`