# Problems Atlas checks a template's mappings and lists everything it finds in the **Problems** dock at the bottom of the Workspace. This page explains every problem it can show: what the message means, what it does to conversions, how to fix it, and where clicking the problem takes you. The question-mark icon at the end of each row (shown on hover, tooltip "What this problem means and how to fix it") opens this page at that problem's section. ```{figure} ../images/reference/problems-dock.png :class: screenshot :alt: The Problems dock of the International Patient Summary template, with problems grouped by model The Problems dock of the demo template "International Patient Summary". ``` [1]{.callout} **Severity toggles.** One button per severity (errors, warnings, infos), each with its count. 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**. The sections below follow the same grouping. [3]{.callout} **A model group.** Problems are grouped by model, in a fixed order (by model name; problems of the context mapper come after the models, and FHIR validation issues that couldn't be traced to a mapping come last). The number after the model name is how many problems the group holds. The list never reorders when you open a model: the open model's group is tinted in place and marked **Open in the editor**. [4]{.callout} **A problem row.** Its severity icon, the mapping it is on (names from the top-level mapping down, joined by `›`; an unnamed mapping shows as `(unnamed)`), the message, and labels below it (see [Reading a row](#problems-row)). Click the row to go to the problem. [5]{.callout} **Where clicking lands.** **FHIRConnect**: the row opens the mapping editor (the middle pane). **FHIR**: the row shows the element in the FHIR example pane. [6]{.callout} **Refresh** ("Re-check the saved mappings"). Runs the saved-state checks again. [7]{.callout} **Minimize to a strip.** Folds the dock into one line (see [The collapsed strip](#problems-strip)). [8]{.callout} **Close.** Hides the dock. The problems button in the top bar opens it again. (problems-summary)= ## All problems at a glance | Code | Severity | Source | In one line | |---|---|---|---| | [`slot-conflict`](#problem-slot-conflict) | {bdg-danger}`error` | Engine | A mapping has both `slotArchetype` and `slotContext`; the slot is not mapped. | | [`slot-context`](#problem-slot-context) | {bdg-danger}`error` | Engine | A `slotContext` can't be entered; the slot is not mapped. | | [`hierarchy-unresolved`](#problem-hierarchy-unresolved) | {bdg-warning}`warning` | Engine | The model's hierarchy path doesn't fully resolve against the template. | | [`engine-issue`](#problem-engine-issue) | {bdg-warning}`warning` | Engine | Any other issue the engine reported while building the mapping tree. | | [`fhir-path-unknown`](#problem-fhir-path-unknown) | {bdg-danger}`error` / {bdg-warning}`warning` | FHIR path | The FHIR path isn't an element of the resource it lands in. | | [`fhir-path-prohibited`](#problem-fhir-path-prohibited) | {bdg-danger}`error` | FHIR path | The profile forbids the element (max 0). | | [`fhir-slice-unknown`](#problem-fhir-slice-unknown) | {bdg-warning}`warning` | FHIR path | No slice of the profile matches what the mapping selects. | | [`profile-not-loaded`](#problem-profile-not-loaded) | {bdg-info}`info` | FHIR path | The model's profile isn't loaded; paths are checked against base FHIR only. | | [`openehr-not-in-template`](#problem-openehr-not-in-template) | {bdg-danger}`error` | openEHR path, Engine | The openEHR path isn't in the template; the mapping is skipped. | | [`with-missing`](#problem-with-missing) | {bdg-danger}`error` | Structure | A mapping has no `with`. | | [`with-empty`](#problem-with-empty) | {bdg-warning}`warning` | Structure | A mapping has neither a FHIR nor an openEHR path. | | [`mapping-name-missing`](#problem-mapping-name-missing) | {bdg-warning}`warning` | Structure | A mapping has no name. | | [`mapping-name-duplicate`](#problem-mapping-name-duplicate) | {bdg-warning}`warning` | Structure | Two or more sibling mappings share a name. | | [`slot-target-missing`](#problem-slot-target-missing) | {bdg-danger}`error` | Structure, Engine | `slotArchetype` names no model in this context. | | [`slot-resource-mismatch`](#problem-slot-resource-mismatch) | {bdg-warning}`warning` | Structure | The slotted model maps another resource; the engine skips the slot. | | [`reference-type-missing`](#problem-reference-type-missing) | {bdg-danger}`error` | Structure | A reference has no `resourceType`. | | [`reference-type-unknown`](#problem-reference-type-unknown) | {bdg-danger}`error` | Structure | A reference's `resourceType` isn't a FHIR resource. | | [`terminology-conceptmap-missing`](#problem-terminology-conceptmap-missing) | {bdg-warning}`warning` | Structure | Local terminology without a ConceptMap. | | [`terminology-conceptmap-unknown`](#problem-terminology-conceptmap-unknown) | {bdg-warning}`warning` | Structure | The ConceptMap isn't known to the engine. | | [`extension-url-not-written`](#problem-extension-url-not-written) | {bdg-warning}`warning` | Structure | openEHR→FHIR won't set the extension's `url`. | | [`model-without-mappings`](#problem-model-without-mappings) | {bdg-warning}`warning` | Structure, Engine | The model has no mappings. | | [`context-model-missing`](#problem-context-model-missing) | {bdg-danger}`error` | Context | The context lists a model that doesn't exist. | | [`start-model-missing`](#problem-start-model-missing) | {bdg-danger}`error` | Context | The context's start names no model. | | [`archetype-not-in-template`](#problem-archetype-not-in-template) | {bdg-warning}`warning` | Context | The model maps an archetype the template doesn't contain. | | [`model-unreached`](#problem-model-unreached) | {bdg-warning}`warning` | Context | Nothing slots the model in from the start; it never runs. | | [`schema`](#problem-schema) | {bdg-danger}`error` | Schema | The model breaks the FHIRConnect schema; the engine would reject it. | | [`yaml-syntax`](#problem-yaml-syntax) | {bdg-danger}`error` | Schema | The model's YAML doesn't parse. | | [FHIR validation](#problem-validation) | any | FHIR validation | The validator's findings on the FHIR example. | ## Using the Problems dock ### Opening it - The **problems button** in the Workspace top bar (tooltip "Problems of this template's mappings") shows the template's error and warning counts. Click it to open or close the dock. Infos are counted in the dock only. - The **validation chip** in the FHIR pane header opens the dock too. - The **status chip** in the editing sheet of a mapping (for example **1 error** or **2 problems**; hover it for the list, ending in "Click to show it in the Problems panel") opens the dock **scoped to that mapping**: a filter chip with the mapping's name path appears next to the source filter, and only that mapping's problems and those of the mappings below it are listed. The **×** on the chip ("Show all problems") removes the scope. Closing the dock or opening another model removes it too. The line above the dock is a resize handle ("Drag to resize · double-click to reset"). Atlas remembers the height in this browser. When the engine keeps a version history, the dock has a second tab, **History**; see {doc}`/ship/history`. (problems-row)= ### Reading a row ```{figure} ../images/reference/problem-row.png :class: screenshot :alt: One problem row with its source label, its occurrence count and the docs link A problem found at both places a model is slotted. ``` [1]{.callout} **Source label**: which check found it (the Source filter names). [2]{.callout} **×N**: the same problem was found at N places, because the model is slotted in more than once (tooltip "Found at N places the model is slotted"). Fixing it once fixes all of them. [3]{.callout} **FHIRConnect** or **FHIR**: which pane clicking the row opens. [4]{.callout} **Docs link**: opens this page at the problem's section. Two more labels can appear after the source label: `unsaved` (orange) : The problem comes from the live check of the model you are editing; your edits aren't saved yet. It disappears or changes as you edit. `from last save` (tooltip "Recomputed on save") : An engine problem of the model you are editing. The engine only checks what is saved, so this one reflects the last save and may already be fixed (or broken differently) by your edits. Validation issues also show the element's location in the produced FHIR (for example `Bundle.entry[0].resource.meta.profile[0]`) and, when Atlas traced the element to a mapping, a **go to mapping** link. (problems-live)= ### Saved checks and live checks Two sets of checks fill the dock: - **Saved-state checks** run in Atlas over what the engine has saved: the context mapper, every model of the template, the engine's mapping tree (its own construction issues), the template (OPT), the engine's ConceptMaps and the loaded FHIR profiles. They run when you open the template, after every save, and when you click **Refresh**. - **Live checks** run in your browser over the model you are editing, shortly after each edit. They cover the Schema, Structure, FHIR path and openEHR path problems of that model. Engine and Context problems can only come from a save. While the open model has unsaved edits, its live problems replace its saved ones, and the dock header says: > Live for \ — the rest reflects the last save. Everything else in the dock (other models, the context mapper, the engine's findings for the open model) still shows the last saved state until you save. The release wizard ({doc}`/ship/release`) checks the same saved-state problems before a release, and the Engine state page's mapping detail lists a mapping's problems under its status chip. (problems-click)= ### What clicking a problem does | Problem | Where it takes you | |---|---| | On a mapping (the row shows a mapping name path) | Opens the model, selects the mapping in the outline, opens its editing sheet and puts the cursor in the field at fault (see each code below). If the problem names no particular field, the cursor goes to the mapping's name. | | On a whole model (no mapping name path: [`profile-not-loaded`](#problem-profile-not-loaded), [`model-without-mappings`](#problem-model-without-mappings), [`archetype-not-in-template`](#problem-archetype-not-in-template), [`model-unreached`](#problem-model-unreached), [`hierarchy-unresolved`](#problem-hierarchy-unresolved), [`yaml-syntax`](#problem-yaml-syntax), a model-level terminology problem) | Opens the model; no mapping is selected. | | On the context mapper (group **Context mapper**) | Goes to the template overview and opens the context mapper's YAML in the middle pane. | | FHIR validation | Scrolls the FHIR example pane to the element and marks it. **go to mapping** opens the mapping that produced it, with the cursor in its **FHIR** path. | With auto-save off, opening another model while the current one has unsaved edits asks first (**Leave without saving?**). With auto-save on, your edits are saved on the way. ```{figure} ../images/reference/problem-opened.png :class: screenshot :alt: The Workspace after clicking a duplicate-name problem, with the mapping selected and its name field focused After clicking the `mapping-name-duplicate` problem of the adverse reaction list. ``` [1]{.callout} The mapping is selected and the field at fault (here the name) has the cursor. [2]{.callout} The model's group in the dock is marked **Open in the editor**; the row of the mapping selected in the editor gets an accent bar. [3]{.callout} The status chip of the mapping shows its problems; click it to scope the dock to this mapping. (problems-actions)= ### Quick actions Quick actions appear when you hover a row. ```{figure} ../images/reference/problem-dismiss.png :class: screenshot :alt: An info problem with its Dismiss icon framed The Dismiss icon of an info. ``` **Dismiss** (eye icon, infos only) : Hides that info for this template. The counts drop with it. A dismissed info comes back only when it changes (another message, another mapping) or when you clear this site's data in your browser; there is no button to bring it back. ```{figure} ../images/reference/problem-validation.png :class: screenshot :alt: A FHIR validation issue with its source label, go to mapping link, FHIR target and Ignore icon A FHIR validation issue traced to the mapping that produced the element. ``` [1]{.callout} The source label **FHIR validation** and the element's location. [2]{.callout} **go to mapping** ("Open the mapping that produces this element"). [3]{.callout} **FHIR**: clicking the row shows the element in the FHIR example pane. **Ignore** (eye icon, framed; FHIR validation issues only, tooltip "Ignore this kind of issue here for this template") : Hides this kind of issue (the same validator message id, at the same element, whatever the index) for this template, now and in later validations. The ignored issues are listed under **Ignored for this template (N)** in the validation settings (the sliders button next to **Validate**); the **×** there ("Stop ignoring") brings them back. :::{warning} **Dismissals and ignores are kept in this browser only.** They aren't saved with the mappings or shared with your team: a colleague, another browser or a private window still shows them. ::: (problems-banners)= ### Banners and empty states > The engine's helper tree couldn't be read, so its checks are missing: \ Shown in amber at the top of the list. Atlas couldn't read the engine's mapping tree for this template, so the **Engine** problems are missing, and so are the saved FHIR path problems (checked on the paths the engine resolved) and [`model-unreached`](#problem-model-unreached) (which needs the engine's tree to see what the start reaches). The list is incomplete, not clean. The models' own Structure, openEHR path and other Context checks still run. Click **Refresh** to try again; if it persists, check that the engine is reachable. > Failed to load problems Shown in red (or the backend's own message) when the problems couldn't be loaded at all. Click **Refresh** to try again. > No problems found. The template has no problems. > No problems match the filters. There are problems, but the severity toggles, the source filter or the mapping scope hide all of them. (problems-strip)= ### The collapsed strip ```{figure} ../images/reference/problems-strip.png :class: screenshot :alt: The collapsed problems strip with the counts and the first error The dock minimized to one line. ``` The strip shows the counts per severity and the first of the most severe problems. Click anywhere on it (**Show all**) to open the dock again. ## Engine The engine reports these while it builds its mapping tree for the saved template (its "helpers"). The message is the engine's own wording. Each one is a place where the engine will not convert what you meant it to. See {external+openfhir:doc}`fhirconnect` for the FHIRConnect format the engine reads. The engine also reports [`openehr-not-in-template`](#problem-openehr-not-in-template), [`slot-target-missing`](#problem-slot-target-missing) and [`model-without-mappings`](#problem-model-without-mappings); those are explained with Atlas's own checks of the same kind. When the engine and an Atlas check find the same problem on the same mapping, the dock shows it once, in the engine's wording. (problem-slot-conflict)= ### `slot-conflict`: slotArchetype and slotContext together {bdg-danger}`error` · Source **Engine** > Mapping '\' of model mapper '\' declares both slotArchetype and slotContext, > which are mutually exclusive; the slot is not mapped. What it means : The mapping says both "continue in this model" (`slotArchetype`) and "continue in this sub-context" (`slotContext`). A slot can only go one way. Why it matters : The engine maps neither: nothing below this slot is converted. How to fix it : 1. Click the problem: the mapping opens with the cursor in **Slot archetype**. 2. Decide which one you mean. To keep the model slot, leave **Slot archetype** and remove `slotContext` in the **Code** view (`slotContext` isn't shown in the visual editor). To keep the sub-context, remove the **Slot archetype** row with its **×**. 3. Save. (problem-slot-context)= ### `slot-context`: a sub-context that can't be entered {bdg-danger}`error` · Source **Engine** > Mapping '\': slotContext '\' is not listed under the context's contexts; the > slot is not mapped. > Mapping '\': no model mapper found for the start archetype of slotContext > '\'; the slot is not mapped. What it means : The mapping continues in another context (`slotContext`), but either the template's context mapper doesn't declare that sub-context, or the sub-context has no model for its start archetype. Why it matters : Nothing below this slot is converted. How to fix it : 1. For the first message: open the context mapper (the code icon "Edit the context mapper YAML" in the middle pane header of the template overview) and add the sub-context to its `contexts` list. Save. 2. For the second: make sure the sub-context's start model exists and is saved. 3. If the name is a typo, fix `slotContext` in the model's **Code** view. Clicking it : Opens the model and selects the mapping (cursor in its name). (problem-hierarchy-unresolved)= ### `hierarchy-unresolved`: hierarchy path not resolved {bdg-warning}`warning` · Source **Engine** > Hierarchy path '\' of model mapper '\' could not be fully resolved against the > template; resolved to '\'. Check that the model mapper matches the uploaded > operational template. What it means : The model's `preprocessor.hierarchy` path points at nodes the template doesn't have, and what is left of it no longer repeats. Why it matters : The engine uses the hierarchy to split repeating entries. When it resolves to a node that doesn't repeat, repeating entries below it can end up sharing one index in the openEHR output. How to fix it : 1. Check that the model was written for this template (the same archetype ids and node ids). 2. Correct the hierarchy path in the model's **Code** view, or bring in the template the model was written for ({doc}`/map/bring-material-in`). 3. Save and check the problem is gone. Clicking it : Opens the model; the problem is about the model as a whole. (problem-engine-issue)= ### `engine-issue`: other engine findings {bdg-warning}`warning` · Source **Engine** > \ What it means : The engine reported something while building its mapping tree that Atlas has no specific code for. The message says what and where. Why it matters : Read the message: it usually says what the engine skipped. How to fix it : Follow the message. Different messages on the same mapping are listed separately. If you can't tell what it means, contact support with the template id, the model name and the message ({doc}`/offer/support`). Clicking it : Opens the model and selects the mapping the engine attached it to. ## FHIR path Atlas checks each mapping's FHIR path where it lands in the resource: against the model's profile when its IG package is loaded ({doc}`/codes-and-profiles/fhir-packages`), otherwise against base FHIR. The saved check uses the paths the engine resolved, once per place the model is slotted in; the live check uses the same estimate the editing sheet shows. Children of a broken path aren't reported again. How to write paths: {doc}`/map/paths`. (problem-fhir-path-unknown)= ### `fhir-path-unknown`: not an element {bdg-danger}`error` (base FHIR or loaded profile) · {bdg-warning}`warning` (the model has a profile that isn't loaded) · Source **FHIR path** > Can't resolve '\': not an element of \ (\.\, base FHIR \) > Can't resolve '\': not an element of \ (\.\, base FHIR \; > the model's profile may allow it, its package isn't loaded) > Can't resolve '\': not an element of \ (\.\, profile \) Example: `Can't resolve 'txt': not an element of CodeableConcept (Condition.code.txt, base FHIR R4)`. What it means : A step of the FHIR path names an element the resource (or data type) doesn't have: usually a typo, a step from another FHIR version, or an element that only a profile or extension adds. The part in brackets is the full path the step landed in. Why it matters : The mapping can't carry data through an element that doesn't exist: reading FHIR, nothing is found there; producing FHIR, the output wouldn't be valid FHIR. Its children build on it, so they are broken too. How to fix it : 1. Click the problem: the mapping opens with the cursor in **FHIR**. 2. Press {kbd}`Ctrl+Space` to see the elements that exist at that point and pick one. 3. If it's the warning variant, the profile may define the element: load its IG package on **FHIR packages** ({doc}`/codes-and-profiles/fhir-packages`). The check then runs against the profile and either passes or becomes an error. 4. Save. (problem-fhir-path-prohibited)= ### `fhir-path-prohibited`: forbidden by the profile {bdg-danger}`error` · Source **FHIR path** > '\' is prohibited by the profile (max 0); the engine output will not conform > (\.\, profile \) What it means : The model's profile sets this element's maximum cardinality to 0: conforming resources must not have it. Why it matters : The engine still writes the element, so the FHIR it produces won't conform to the profile and fails validation against it. How to fix it : 1. Click the problem: the mapping opens with the cursor in **FHIR**. 2. Map the value to an element the profile allows ({kbd}`Ctrl+Space` lists them), or delete the mapping if the profile deliberately leaves the data out. 3. Save. (problem-fhir-slice-unknown)= ### `fhir-slice-unknown`: no matching slice {bdg-warning}`warning` · Source **FHIR path** > No slice of the profile matches \ (\.\, profile \) Example: `No slice of the profile matches url = 'https://example.org/StructureDefinition/not-in-the-profile' (…)`. What it means : The mapping's FHIR condition selects part of a sliced element (an extension url, a coding system…), and none of the profile's slices matches that selection. Why it matters : The engine converts the data, but the element is not one the profile describes: validation against the profile may complain, and readers expecting the profile's slice won't find it. How to fix it : 1. Click the problem: the mapping opens with the cursor in **FHIR**. 2. Pick the slice from the suggestions: choosing a slice or extension suggestion writes both the path and the matching condition ({doc}`/map/conditions`). 3. If the selection is right and the profile is open to it, you can leave the warning. (problem-profile-not-loaded)= ### `profile-not-loaded`: the profile isn't loaded {bdg-info}`info` · Source **FHIR path** > Profile \ isn't loaded, so paths are checked against base FHIR only. Upload the IG > package that defines it (FHIR packages). > Profile \ (declared in meta.profile) isn't loaded, so paths are checked against > base FHIR only. Upload the IG package that defines it (FHIR packages). What it means : The model names a profile (its `structureDefinition`, or a constant it writes into `meta.profile`, the second message), but no loaded IG package defines it. Why it matters : This info is about Atlas's help, not about the conversion itself: path suggestions, the FHIR path checks, profile coverage and FHIR validation all fall back to base FHIR, so elements and slices the profile adds look unknown and its restrictions aren't checked. How to fix it : 1. Find the IG package that defines the profile (the canonical URL tells you which IG). 2. Add it on **FHIR packages** ({doc}`/codes-and-profiles/fhir-packages`). 3. Click **Refresh** in the dock. Or, if you can't load it, **Dismiss** the info. Clicking it : Opens the model. ## openEHR path (problem-openehr-not-in-template)= ### `openehr-not-in-template`: not in the template {bdg-danger}`error` · Source **openEHR path** (Atlas's check) or **Engine** Atlas's check: > Not in the template: \ (under \); the mapping is skipped. The engine's check: > Mapping '\' of model mapper '\': openEHR path '\' does not exist in > the template ('\' not found); the mapping is skipped. Older engines word it: > openEHR path '\' is not in the template; the mapping is skipped. What it means : The mapping's openEHR path, combined with the paths of the mappings above it, names a node the template doesn't have: a wrong node id, a node another template version has, or a node that was left out of this template. Or it pins an attribute through the element's `value` that none of the element's data value types has (`…/value/magnitude` on a coded text; see {ref}`cheat-leaf-attributes`). A manual entry's openEHR path is checked the same way. Atlas's check composes the path itself, so it also covers models the engine never reaches; the engine's check uses the full path from the composition root. Why it matters : The engine skips the mapping, and every mapping below it, in both directions: that data is never converted. How to fix it : 1. Click the problem: the mapping opens with the cursor in **openEHR**. 2. Press {kbd}`Ctrl+Space`: the suggestions list the template's nodes by name and offer whole paths. Pick the node you meant. 3. If the node really isn't in the template, delete the mapping, or bring in the template version that has it. 4. Save. Only the topmost broken mapping is reported, so fixing it may reveal problems below it. ## Structure Structure problems are about how a model is put together. Atlas finds them both live (while you edit) and in the saved state, with the same wording. (problem-with-missing)= ### `with-missing`: mapping without `with` {bdg-danger}`error` · Source **Structure** > Mapping '\' has no \`with\`; the engine needs one on every mapping. What it means : The mapping has no `with` block at all (no FHIR and no openEHR path). Extension models are exempt, since their mappings may only change another model's mapping. Why it matters : The engine needs `with` on every mapping of a model. How to fix it : 1. Click the problem: the mapping opens with the cursor in **FHIR**. 2. Fill in the **FHIR** path, the **openEHR** path or both. 3. Save. (problem-with-empty)= ### `with-empty`: no paths {bdg-warning}`warning` · Source **Structure** > Mapping '\' has neither a FHIR nor an openEHR path; it maps nothing. What it means : The mapping has a `with`, but both paths are empty, and it doesn't hand over to anything else (no slot, reference, child mappings, manual values or mapping code). Why it matters : It converts nothing. How to fix it : 1. Click the problem: the cursor is in **FHIR**. 2. Fill in a path, or delete the mapping if it is left over. (problem-mapping-name-missing)= ### `mapping-name-missing`: unnamed mapping {bdg-warning}`warning` · Source **Structure** > A mapping has no name; it can't be highlighted or matched to the engine's helpers. What it means : The mapping has no `name`. In the dock and the outline it shows as `(unnamed)` / `unnamed`. Why it matters : Atlas links a mapping to the engine's mapping tree by its name. Without one, Atlas can't highlight what it converts, show its resolved paths or example values, or put engine problems on it. How to fix it : 1. Click the problem: the cursor is in the mapping's name. 2. Type a name that is unique among its siblings. 3. Save. (problem-mapping-name-duplicate)= ### `mapping-name-duplicate`: sibling mappings with the same name {bdg-warning}`warning` · Source **Structure** > \ sibling mappings are named '\'; highlighting and the resolved paths can only tell > them apart by name. The demo template "International Patient Summary" has this one three times (`emptyReason`). What it means : Two or more mappings directly under the same parent share a name. It is reported once, on the first of them. Why it matters : Atlas matches mappings to the engine's tree by name, so for two equal names it picks the first: highlights, resolved paths, example values and problems of the second one land on the first. How to fix it : 1. Click the problem: the first mapping with that name opens, with the cursor in its name. 2. Give one of them a different name (for example `emptyReasonText`). 3. Save. (problem-slot-target-missing)= ### `slot-target-missing`: slot to a model that isn't there {bdg-danger}`error` · Source **Structure** or **Engine** > slotArchetype '\' names no model in this context; the slot is not mapped. The engine's wording: > Mapping '\' of model mapper '\': no model mapper found for slot archetype > '\'; the slot is not mapped. What it means : The mapping's **Slot archetype** names a model that isn't one of the template's models (the context mapper's `archetypes` and `extensions`). Often the model was never created, was renamed, or lives in another template. Why it matters : The engine stops at this slot: nothing of the slotted archetype is converted. How to fix it : 1. Click the problem: the mapping opens with the cursor in **Slot archetype**. 2. Pick a model from the suggestions: models of this template, models from elsewhere (picking one adds it to this template), or a new model created on the spot. 3. Save. See {doc}`/map/connect-models`. (problem-slot-resource-mismatch)= ### `slot-resource-mismatch`: slot into a model of another resource {bdg-warning}`warning` · Source **Structure** > slotArchetype '\' maps \, but the resource here is \: the engine skips a slot > into another resource. Fix: … (as + Slot does). The fix in the message depends on the resource in scope: from a Bundle, *map $resource.entry (type \), followed by resource / $reference with reference.resourceType \, and slot it inside*; from any other resource, *map the Reference element with openehr $reference and reference.resourceType \, and slot it inside*. What it means : The slotted model maps a FHIR resource (its structureDefinition or profile) other than the one in scope at the slot mapping: the model's own, or inside a **Reference** its resource type. A model that maps a data type (a Dosage, an Identifier) or a BackboneElement maps an element of the resource in scope, so it isn't reported. Nor is a model whose type isn't known yet (a profile whose package isn't loaded). Why it matters : The engine applies a slot only to a FHIR value of the slotted model's type, and skips this one without an error: nothing of the slotted archetype is converted from FHIR. Building FHIR, only a reference makes the engine create the other resource and the Reference to it. How to fix it : 1. Click the problem: the mapping opens with the cursor in **Slot archetype**. 2. Click **Wrap in a reference to \** under the field. Atlas rewrites the mapping into the reference + slot structure (one edit; **Undo** puts it back). From any other resource than a Bundle, fill in the **FHIR** path of the Reference element it follows (for example `$resource.requester`). 3. Save. See {doc}`/map/connect-models`. (problem-reference-type-missing)= ### `reference-type-missing`: reference without a resource type {bdg-danger}`error` · Source **Structure** > Reference of mapping '\' has no resourceType; its child mappings have no resource to > map. What it means : The mapping has a **Reference**, but no resource type to create or follow. Why it matters : The mappings under the reference have no resource to map into or out of. How to fix it : 1. Click the problem: the cursor is on the **Reference** row's **into** list. 2. Choose the resource type. 3. Save. (problem-reference-type-unknown)= ### `reference-type-unknown`: not a FHIR resource {bdg-danger}`error` · Source **Structure** > Reference resourceType '\' is not a FHIR \ resource. What it means : The reference names a resource type that the model's FHIR version doesn't have: a typo (`Pateint`) or a resource from another FHIR version. Why it matters : The engine can't create or follow such a resource; the mappings under the reference don't convert. How to fix it : 1. Click the problem: the cursor is on the **Reference** row's **into** list. 2. Choose the right resource type (the list holds the resources of the model's FHIR version). 3. Save. (problem-terminology-conceptmap-missing)= ### `terminology-conceptmap-missing`: local terminology without a ConceptMap {bdg-warning}`warning` · Source **Structure** > Local terminology without a conceptmap; no codes are translated. What it means : The model's or the mapping's terminology is set to `local`, which means "translate with a ConceptMap", but no ConceptMap is chosen. Why it matters : Codes pass through untranslated. How to fix it : 1. Click the problem. For a mapping, the cursor is in the **Terminology** row; for the model's own terminology, the model opens. 2. Choose a ConceptMap, or switch the terminology type to inline rows or none. 3. Save. See {doc}`/codes-and-profiles/translate-codes`. (problem-terminology-conceptmap-unknown)= ### `terminology-conceptmap-unknown`: ConceptMap not known to the engine {bdg-warning}`warning` · Source **Structure** > ConceptMap '\' is not known to the engine; codes pass through untranslated. What it means : The terminology points at a ConceptMap URL that none of the engine's ConceptMaps has. Why it matters : The engine finds nothing to translate with, so codes pass through untranslated. How to fix it : 1. Upload the ConceptMap on the **Terminology** page ({doc}`/codes-and-profiles/conceptmaps`), or 2. click the problem and choose an existing ConceptMap in the **Terminology** row. 3. Save (or click **Refresh** after uploading). (problem-extension-url-not-written)= ### `extension-url-not-written`: the extension's url is never set {bdg-warning}`warning` · Source **Structure** > openEHR→FHIR won't set the extension url: nothing writes \. Fix: add a child mapping on > $fhirRoot with a manual writing url (as + Map does). What it means : The mapping's FHIR path ends in `extension` and its FHIR condition picks the extension by `url` (`url` **is one of** one URL). That condition selects the right extension when reading FHIR. But when the engine builds FHIR, it doesn't apply conditions, and nothing in the mapping (or its direct children) writes `url` as a manual value. Why it matters : openEHR→FHIR conversions produce extensions without a `url`, which aren't valid FHIR and that nobody can interpret. FHIR→openEHR is unaffected (the problem doesn't show for mappings that are unidirectional `fhir->openehr`). How to fix it : 1. Click the problem: the mapping opens. 2. Add a child mapping with FHIR path `$fhirRoot` and a **Manual** FHIR value `url` = the extension's URL. 3. Save. The **+ Map** action in the Profile tab adds extensions this way from the start; see {doc}`/codes-and-profiles/add-extension`. (problem-model-without-mappings)= ### `model-without-mappings`: empty model {bdg-warning}`warning` · Source **Structure** or **Engine** > Model '\' has no mappings; nothing is mapped. The engine's wording: > Model mapper '\' (id \) has no mappings where some were expected; nothing is mapped > there. What it means : The model has no mappings. Extension models are exempt. Why it matters : Wherever the model is slotted in, nothing is converted. A model created with the wizard starts like this. How to fix it : Add mappings (**+ Mapping** in the outline, or **+ Map** in the coverage tabs), or remove the model from the template if it isn't needed. Clicking it : Opens the model. ## Context Context problems are about the template's context mapper: which models belong to the template and where mapping starts. See {doc}`/map/start-mapping` and {doc}`/map/connect-models`. (problem-context-model-missing)= ### `context-model-missing`: listed model doesn't exist {bdg-danger}`error` · Source **Context** > The context lists model '\', but no model has that name. What it means : The context mapper's `archetypes` or `extensions` list names a model that the engine doesn't have (deleted, renamed, or never uploaded). Why it matters : Slots that lead to that name don't convert. How to fix it : 1. Click the problem: the template overview opens with the context mapper's YAML. 2. Correct the name, or remove it from the list. 3. **Save**. Or create or upload the missing model. (problem-start-model-missing)= ### `start-model-missing`: start names no model {bdg-danger}`error` · Source **Context** > The context's start '\' names no model in this context; nothing is mapped. What it means : The context mapper's `start` names a model that isn't among the template's models. Why it matters : Conversion begins at the start model. Without it, nothing of the template is converted. How to fix it : 1. Click the problem: the context mapper's YAML opens. 2. Set `start` to the name of the model for the template's root archetype, and make sure it is listed under `archetypes`. 3. **Save**. (problem-archetype-not-in-template)= ### `archetype-not-in-template`: archetype not in the template {bdg-warning}`warning` · Source **Context** > The model maps archetype '\', which the template doesn't contain. What it means : The model's archetype (`spec.openEhrConfig.archetype`, or that of the model it extends) doesn't occur in the template (OPT). Why it matters : There is nothing in compositions of this template for the model to map: it never converts anything here. How to fix it : 1. If the archetype id is wrong (a version suffix like `.v1` vs `.v2`), correct it in the model's **Code** view and save. 2. If the model belongs to another template, remove it from this one ({doc}`/map/connect-models`). Clicking it : Opens the model. (problem-model-unreached)= ### `model-unreached`: never reached from the start {bdg-warning}`warning` · Source **Context** > Model '\' is never reached from the start model '\' (no slotArchetype leads to > it), so it isn't used in conversions. What it means : The model belongs to the template, but no chain of slots leads from the start model to it. An extension counts as reached when the model it extends is. The template overview shows the model card with **Not linked · nothing slots it in from the start, so it never runs**. Why it matters : The engine never runs its mappings. How to fix it : 1. On the template overview, click **Slot it in…** on the model's card. The dialog **Slot \ in** opens. 2. Pick the place in the template where the archetype sits and click **Add slot**: Atlas adds the slot mapping to the model that encloses it. 3. Save (with auto-save on, this happens by itself). See {doc}`/map/connect-models`. Clicking it : Opens the model. ## Schema Schema problems come only from the live check of the model you are editing: they are what the engine would reject on save. (problem-schema)= ### `schema`: breaks the FHIRConnect schema {bdg-danger}`error` · Source **Schema** > \ — the engine rejects the model on save. What it means : The model's YAML doesn't follow the FHIRConnect model schema: a misspelled key, a value of the wrong type, a value outside its allowed list. The message names the key. Up to 25 are listed at once. Why it matters : Saving fails: the engine refuses a model that breaks the schema, so the conversion keeps using the last saved version. How to fix it : 1. Click the problem: the mapping the key belongs to opens (cursor in its name). 2. Correct the key or value; the **Code** view underlines schema errors and suggests keys. 3. Save. (problem-yaml-syntax)= ### `yaml-syntax`: YAML doesn't parse {bdg-danger}`error` · Source **Schema** > The YAML doesn't parse: \ What it means : The model's text isn't valid YAML (wrong indentation, a missing colon, an unclosed quote). Why it matters : Nothing else can be checked, the visual editor can't show the model, and the engine can't accept it. How to fix it : 1. Open the model's **Code** view (the visual editor switches to it by itself when the YAML doesn't parse). 2. Fix the line the parser names. 3. Save. (problem-validation)= ## FHIR validation {bdg-danger}`error` · {bdg-warning}`warning` · {bdg-info}`info` · Source **FHIR validation** These are the findings of the FHIR validator on the FHIR example pane. Atlas validates the produced FHIR against base FHIR and the loaded profiles (after each conversion, or when you click **Validate**); the engine itself doesn't validate. The validator's "fatal" and "error" become errors, "warning" a warning, anything else an info. See {doc}`/check/validate`. The message is the validator's, for example: > Rule cmp-2: 'A section can only have an emptyReason if it is empty' Failed > Profile reference '\' has not been checked because it is unknown > If a date has a time, it must have a timezone When the issue comes from a profile, ` (profile )` is added. The row also shows the element's location (`Bundle.entry[1].resource.onsetDateTime`). The problem code is the validator's message id, so they all share this one section. What it means : The FHIR that the mappings produce for the example doesn't conform to FHIR or to a profile at that element. Why it matters : Real conversions produce the same structure, so receivers that validate will reject or question it. Some issues come from the example data rather than from your mappings (an example date without a time zone, for instance). How to fix it : 1. Click the row: the FHIR pane scrolls to the element and marks it. 2. If the row has **go to mapping**, click it to open the mapping that produced the element (the cursor is in its **FHIR** path). Issues Atlas couldn't trace to a mapping are grouped under **Produced FHIR (no mapping traced)**. 3. Fix the mapping (a missing required element often needs a new mapping or a manual value), save, and let the conversion and validation run again. 4. If the issue is expected for this template (an artefact of the example data), hover the row and click **Ignore**. Ignores are kept in this browser only. :::{tip} "Profile reference … has not been checked because it is unknown" and "N profile(s) not loaded" mean the IG package isn't loaded, so the result covers base FHIR only. Load the package on **FHIR packages** first ({doc}`/codes-and-profiles/fhir-packages`). ::: Validation issues don't depend on saving: each validation replaces the previous list. ## Related - {doc}`/check/fix-problems`: the guide to working through the dock. - {doc}`/check/validate`: validating the FHIR example. - {doc}`/reference/messages`: every other notice and message.