# Connect models: slots, links, references ## What you'll do You make sure the engine reaches every model of a template: you slot a model in where its archetype sits, pick slot targets from suggestions, follow a slot into the slotted model and back, remove a model from a template, and edit the template's context mapper. ```{figure} ../images/map/unlinked-card.png :class: screenshot :alt: A model card flagged Not linked with a Slot it in button A model nothing slots in: it never runs until you link it. ``` ## Before you start - The template is open in the Workspace ({doc}`start-mapping`). ### How models reach each other A conversion begins with the template's start model. From there the engine follows: **Slots** : A mapping with a **Slot archetype** hands the openEHR node at its path over to another model (named by its `metadata.name`), and places that model's FHIR resource or element at the mapping's FHIR path. This is how a COMPOSITION model reaches the models of the archetypes inside it. **Followed by** : Child mappings inside one model, continuing from their parent's FHIR element and openEHR node. **References** : A mapping with a **Reference** continues in another FHIR resource (its **into** resource type), for example from a Bundle entry into the Observation it holds. Its openEHR path is usually `$reference`, and its child mappings (the **+ mapping** chips) run inside that resource. A model that no chain of slots reaches from the start model is never run. ## Steps ### Slot in a model nothing links to 1. On the template's overview, a model nothing slots in has a dashed amber card with **Not linked · nothing slots it in from the start, so it never runs** [1]{.callout}. Hover it for the full explanation. ```{figure} ../images/map/unlinked-card.png :class: screenshot :alt: The Not linked strip on a model card The **Not linked** strip [1]{.callout} and **Slot it in…** [2]{.callout}. ``` An extension model whose core isn't linked says **Not linked · runs only with , which nothing slots in**. It has no button: slot in the core model instead. 2. Click **Slot it in…** [2]{.callout}. The dialog **Slot in** lists, under **Slot into**, every place in the template where the model's archetype occurs, with the model that will hold the slot mapping and its openEHR path [1]{.callout}. Under **FHIR resource** it asks whether the model maps the same resource or enters a new one; see [Slot a model that maps another resource](#slot-another-resource). ```{figure} ../images/map/link-dialog.png :class: screenshot :alt: The Slot in dialog with one place to slot the model into The place [1]{.callout} and **Add slot** [2]{.callout}. ``` 3. Choose the place and click **Add slot** [2]{.callout}. Atlas adds a slot mapping, named after the place, to the enclosing model and opens that model on it, with the **FHIR** path focused (or, for a model of another resource, the mapping that needs a path). 4. Fill in the **FHIR** path: where the slotted model's resource or element goes. See {doc}`paths`. The same **Slot into** list appears when you add a model from **NOT YET MAPPED** or reuse one ({doc}`start-mapping`); there it also offers **Don't slot it now** (*The model is added to the context, but nothing runs it until a slot links it.*). A place can't be chosen when the archetype around it has no model yet. It says ` has no model to hold the slot — choose a start / map it first`. Nor when the enclosing model already maps elements inside it (an archetype mapped inline through `$composition/…`, say): ` already maps elements inside — a model slotted in would map them twice`. The coverage tree offers no **+ Slot** there either. A mapping that only leads into a slot there (a reference + slot, see [Slot a model that maps another resource](#slot-another-resource)) doesn't count: it maps nothing of the occurrence itself. (slot-another-resource)= ### Slot a model that maps another resource A slot only runs when the FHIR value reaching it has the slotted model's type. A model that maps another resource than the holder (an Organization model slotted from a Bundle, a Practitioner model from a MedicationRequest) needs a **Reference** around the slot: the engine follows it into that resource, and building FHIR it creates the resource and the Reference to it. Every way of slotting a model in asks this under **FHIR resource**: **Slot in** (from **Slot it in…**), **Use an existing mapping?** (from **+ Slot** in the template coverage and from **NOT YET MAPPED**), and the create wizard once you pick the model's resource type. **Same resource** : *Slot it in: one mapping naming the model.* One mapping with the **Slot archetype**. Right for a model of the holder's resource, a data type (a Dosage, an Identifier) or a BackboneElement. **Enters a new \ resource** : *Reference + slot.* Atlas writes the structure the engine needs. The default when the model maps another resource than the holder. When the model's type isn't known yet (its profile's package isn't loaded), pick the resource type in the list. If you pick **Same resource** for a model of another resource, the dialog says *The engine only applies a slot whose model maps \; this one maps \.* It lets you go ahead (a hand-written follow-up is fine), and the Problems dock reports [slot-resource-mismatch](problem-slot-resource-mismatch) until the slot sits inside a reference. From a **Bundle** (*From Bundle entries of type \*), every path is filled in and the slot mapping inside is selected: ```yaml - name: vardgivare with: fhir: $resource.entry openehr: $composition/content[openEHR-EHR-CLUSTER.organisation.v1] fhirCondition: targetRoot: $resource.entry targetAttributes: [resource] operator: type criterias: [Organization] followedBy: mappings: - name: iterateOrganization with: { fhir: resource, openehr: $reference } reference: resourceType: Organization mappings: - name: vardgivareSlot with: { fhir: $fhirRoot, openehr: $composition/content[openEHR-EHR-CLUSTER.organisation.v1] } slotArchetype: CLUSTER.organisation.v1_vårdgivare ``` From **any other resource** (*through a Reference element you name next*), the mapping follows a Reference element of the holder's resource. Atlas focuses its **FHIR** path; fill in the element, for example `$resource.requester`: ```yaml - name: prescriber with: fhir: $resource.requester openehr: $reference reference: resourceType: Practitioner mappings: - name: prescriberSlot with: { fhir: $fhirRoot, openehr: $archetype/protocol[at0005] } slotArchetype: CLUSTER.person.v1-eha ``` A slot mapping you already have (typed in, or picked in **Slot archetype**) gets the same offer: when its model maps another resource, the field says *\ maps \, not \.* with **Wrap in a reference to \**. That rewrites the mapping into the structure above as one edit, keeping its openEHR path for the slot inside; **Undo** in the toast puts it back. ### Pick a slot target from suggestions To point an existing mapping at a model yourself, select the mapping, add **Slot archetype** with **+ Property** if it has none, and click into the **Slot archetype** field. Press {kbd}`Ctrl+Space` to see the suggestions. ```{figure} ../images/map/slot-suggestions.png :class: screenshot :alt: Slot archetype suggestions with a model marked not in context, then New model A model of the right archetype that exists in the engine but not in this template, then a new one. ``` The suggestions are the models of the archetypes that occur at or below the mapping's openEHR path, most relevant first. For each archetype: In this context : The template's own models of that archetype, with the place it occurs (its name and path). Elsewhere : Models of that archetype from other templates, marked **not in context**, with the hint `… — picking it adds it to this context`. Picking one adds it to this template's context (`Adding to this context…`) and fills it in. New model : After the existing ones: **New model for …** (marked **new**). Picking it opens the **New model mapping** wizard ({doc}`start-mapping`); the new model becomes this mapping's slot target. If you type a name nothing matches, the suggestion is **Create “” for …**. These are the same choices, in the same order, as **+ Slot** in the template coverage offers. After them come the context's other models, with the hint `Not below this mapping’s openEHR path`. A model suggestion is accepted with {kbd}`Enter`, {kbd}`Tab` or a click; a create suggestion only with {kbd}`Enter` or a click, so tabbing out of the field never starts the wizard. ### Follow a slot, and come back 5. Select a mapping that has a **Slot archetype**. When it names a model of this template, the **↗** button next to the field (**Open this slot's model**) [1]{.callout} opens that model. ```{figure} ../images/map/slot-goto.png :class: screenshot :alt: The Slot archetype field with its open button **Open this slot's model** [1]{.callout}. ``` 6. In the slotted model, the header of the middle pane shows a back button with **←** and the name of the model you came from [1]{.callout}. Its tooltip names the mapping too (`Back to › `). Click it to return to that model with the same mapping selected. The browser's back and forward buttons move between the models the same way. ```{figure} ../images/map/slot-back.png :class: screenshot :alt: The header of the slotted model with the back button The back button [1]{.callout} to the model you came from. ``` ### Remove a model from a template 7. Open the model and click the bin button (**Delete or unreference this model**) at the right of the middle pane's header. The **Delete model** dialog offers: **Remove from this template only** [1]{.callout} : Unreference the model from this context. The model itself is kept and stays usable elsewhere. **Delete the model permanently** [2]{.callout} : Delete the model from the engine and unreference it here. This cannot be undone. ```{figure} ../images/map/delete-model.png :class: screenshot :alt: The Delete model dialog Remove it from this template [1]{.callout}, or delete it for good [2]{.callout}. ``` **Cancel** closes the dialog without changing anything. ### Edit the context mapper The context mapper lists the template's models (`archetypes`), its extension models, its start and its FHIR profile. Atlas keeps it up to date when you add, reuse or remove models; edit it by hand only for what the dialogs don't cover. 8. On the template's overview (no model open), click **<>** (**Edit the context mapper YAML**) [1]{.callout} in the middle pane's header. The pane shows **Context mapper** and the template id, with the YAML in an editor. ```{figure} ../images/map/context-mapper.png :class: screenshot :alt: The context mapper of the Blood Pressure template as YAML The context mapper button [1]{.callout} and **Save** [2]{.callout}. ``` 9. Edit the YAML and click **Save** [2]{.callout}, or **Cancel** to go back to the overview without saving. Clicking **<>** again (**Back to mapping overview**) also closes it. ## Check it worked - The model's card no longer shows **Not linked**, and its coverage bar fills as the engine reaches its mappings. - With the slot mapping selected, the side panes highlight the slotted part of the example ({doc}`/check/see-in-action`). - The [model-unreached](problem-model-unreached) problem is gone from the Problems dock. ## Tips :::{tip} **A model that isn't linked never runs.** Check the overview for **Not linked** cards after adding models with **Don't slot it now** or editing slot mappings. ::: :::{tip} When an archetype occurs inside another one, add the slot rather than mapping the same elements a second time in the enclosing model. One model per archetype keeps the mapping in one place. ::: :::{tip} Picking a model from **Elsewhere** in the slot suggestions adds it to the context: you don't need to reference it first. ::: ## Watch out :::{warning} **Delete the model permanently** deletes it from the engine, so every other template that uses it loses it too. Use **Remove from this template only** unless you are sure. ::: :::{warning} Saving the context mapper by hand replaces it as a whole. A model name that doesn't exist, or a start that names no model, breaks the template's conversions until fixed. ::: ## If something goes wrong | What you see | What it means and what to do | |---|---| | `The template has no occurrence of to slot it into.` | The template doesn't contain the model's archetype anywhere, so nothing can slot it in. Remove the model from this template. | | `Failed to slot in` (or the engine's reason) | The slot mapping couldn't be added; nothing changed. Try again; see {doc}`/reference/messages`. | | `Failed to reference model` (or the engine's reason) in **Use an existing mapping?** after **+ Slot** | Referencing a model from another template into this one failed; nothing changed. Try again, or pick another model. | | `Failed to add to the context` under **Slot archetype** | Referencing the picked model into the template failed. The field still names it; the slot only works once the model is in the context. | | `Delete failed` in **Delete model** | The engine refused the delete or unreference. The rest of the message is its reason. | | `Failed to load context mapper` | The context mapper couldn't be read. Close it with **<>** and try again. | | `Save failed` (or the engine's reason) under the context mapper | The YAML wasn't accepted. Fix it and save again. | Problems about slots and links show in the Problems dock ({doc}`/check/fix-problems`): [model-unreached](problem-model-unreached), [slot-target-missing](problem-slot-target-missing), [slot-resource-mismatch](problem-slot-resource-mismatch), [slot-context](problem-slot-context), [slot-conflict](problem-slot-conflict), [context-model-missing](problem-context-model-missing), [start-model-missing](problem-start-model-missing) and [reference-type-missing](problem-reference-type-missing). ## Related - {doc}`start-mapping`: add models, with the same **Slot into** choice. - {doc}`edit-in-workspace`: the editor the slot mappings live in. - {doc}`/check/coverage`: **+ Slot** and **+ model** on the template's coverage tree. - {doc}`/reference/deep-links`: links that open a model and mapping directly.