# Start mapping a template ## What you'll do You open a template in the Workspace, choose the archetype where every conversion starts, and add a model for each archetype the template contains, either by reusing a model that already exists or by creating a new one with the **New model mapping** wizard. ```{figure} ../images/map/template-overview.png :class: screenshot :alt: The Workspace showing the overview of the International Patient Summary template The overview of the International Patient Summary template in the Workspace. ``` ## Before you start - The template's OPT is in the engine ({doc}`bring-material-in`). - If the FHIR side follows a profile (for example the IPS), load its IG package first ({doc}`/codes-and-profiles/fhir-packages`), so you can pick the profile in the wizard. You can also add a profile from inside the wizard. - {doc}`/start/key-ideas` explains template, context mapper, start archetype, model and slot. ## Steps ### Open the template 1. Click **Open Workspace** in the sidebar, then the template's card under **Select a template to start mapping**. From **Engine state** you can also select the template and click **Open in workspace**. 2. The middle pane shows the template's overview: ```{figure} ../images/map/template-overview.png :class: screenshot :alt: The template overview with numbered callouts The start model [1]{.callout}, a model of an archetype [2]{.callout}, an extension model [3]{.callout}, a model's problem count [4]{.callout}, and the context mapper button [5]{.callout}. ``` **START** [1]{.callout} : The start model, marked **START**: the model the engine begins every conversion with. Its card names the archetype and the FHIR type it maps. **ARCHETYPE MAPPINGS** [2]{.callout} : Every other model of the template, with its archetype. The bar at the bottom of each card shows how many of the archetype's elements it maps (`8 / 10`). Extension models [3]{.callout} : An extension model sits under the model it extends, marked **↳**, **EXTENSION** and `extends `. Problem count [4]{.callout} : The model's errors and warnings. See {doc}`/check/fix-problems`. **<>** [5]{.callout} : Opens the template's context mapper as YAML ({doc}`connect-models`). **NOT YET MAPPED** : The template's archetypes no model maps yet, one **Add mapping** card each. This section only shows while there are some. Click a model's card to open it in the editor ({doc}`edit-in-workspace`). The model crumb in the top bar (**Select a model** with its **▾**) switches between the template's models too. ### Create the context mapper A template you uploaded without a context mapper (the OPT alone) can't be mapped yet. Instead of the overview, the middle pane shows **New context mapper**: ```{figure} ../images/map/context-wizard.png :class: screenshot :alt: The New context mapper wizard on its profile step, with Bundle selected The loaded profiles [1]{.callout}, adding one [2]{.callout}, a base resource [3]{.callout} and **Create context mapper** [4]{.callout}. ``` - **1 · Select the FHIR version** the template maps to (**R4** unless you change it), then click **Next**. - **2 · Which FHIR profile does the template map to?** Pick a profile from the loaded FHIR packages [1]{.callout}, add one by uploading a StructureDefinition or package or fetching one from the registry [2]{.callout}, or pick a base resource such as **Bundle** [3]{.callout}. Only profiles on resources are offered. The engine picks this context for an incoming FHIR resource whose `meta.profile` names the profile; a base resource fits when every conversion names the template. - Click **Create context mapper** [4]{.callout}. Atlas names the context mapper after the template and fills in the template id. It lists no models and has no start yet: the overview appears, and the next steps add both. ### Choose the start archetype A freshly uploaded template has no start. The **START** section then shows **Choose a start archetype for this template** [1]{.callout}. ```{figure} ../images/map/start-placeholder.png :class: screenshot :alt: The overview with no start and one archetype not yet mapped No start yet [1]{.callout}; one archetype is not yet mapped [2]{.callout}. ``` 3. Click **Choose a start archetype for this template**. The **Choose a start archetype** dialog lists: - **Mapped**: the template's models. Click one to make it the start. - **Not yet mapped**: the archetypes no model maps. Click one to add a model for it, which becomes the start (the steps below, without a slot: nothing slots in the start). ```{figure} ../images/map/start-picker.png :class: screenshot :alt: The Choose a start archetype dialog One mapped model and one archetype not yet mapped. ``` Usually the start is the template's COMPOSITION archetype. Atlas writes your choice into `context.start` of the context mapper and keeps the rest of the file as written. ### Add a model for an archetype 4. Under **NOT YET MAPPED**, click the **Add mapping** card of the archetype. ```{figure} ../images/map/not-yet-mapped.png :class: screenshot :alt: An Add mapping card under Not yet mapped The observation archetype has no model in this template yet. ``` 5. **If a model for this archetype already exists in the engine** (in another template), Atlas asks **Use an existing mapping?** **+ Slot** in the template coverage opens the same dialog, with its occurrence chosen; it also lists this template's own models of the archetype, under **In this template**, before those **In other templates**. ```{figure} ../images/map/reuse-dialog.png :class: screenshot :alt: The Use an existing mapping dialog Where it is slotted in [1]{.callout}, or not yet [2]{.callout}; a model to reuse [3]{.callout}; or **New model…** [4]{.callout}. ``` - **Slot into** [1]{.callout} lists every place in the template where this archetype occurs, with the model that will hold the slot mapping and its openEHR path. The first usable place is chosen for you; see {doc}`connect-models` for how slotting works. - **Don't slot it now** [2]{.callout} adds the model to the context only. - With a place chosen, **FHIR resource** asks whether the model maps the same resource as the enclosing model or enters a new one ({ref}`slot-another-resource`). The default follows each model's type. - Click a model [3]{.callout} to reference it into this template. With a place chosen, Atlas also adds the slot mapping to the enclosing model and opens that model on the new mapping. Without one, it opens the reused model. - **New model…** [4]{.callout} goes on to the next step. While you slot the model in, extension models aren't offered: an extension merges into its core model, so nothing can slot it. 6. **Name the new model.** The dialog (titled **Add mapping** when it offers a place to slot the model in, **Name the mapping** otherwise) asks for the **Model name (metadata.name)**. ```{figure} ../images/map/name-prompt.png :class: screenshot :alt: The Add mapping dialog with Slot into and the model name Where it is slotted in [1]{.callout} and the model's name [2]{.callout}. ``` The name is filled in from the chosen place (made unique if a model of that name exists), or from the archetype id. It follows your choice of place until you type your own. Click **Continue** (or press {kbd}`Enter`). ### Create the model with the wizard The **New model mapping** wizard opens in the middle pane. Its header names the archetype and, when the model will be slotted in, where: `Will be slotted into at ` [1]{.callout}. Once you pick what the model maps (step 2), the header also asks under **FHIR resource** whether it maps the same resource as that model or enters a new one; the default follows the two types ({ref}`slot-another-resource`). 7. **1 · Select the FHIR version**: **STU3**, **R4** (the default) or **R5** [2]{.callout}. Click **Next**. ```{figure} ../images/map/wizard-version.png :class: screenshot :alt: Step 1 of the wizard, the FHIR version Where the model will be slotted in [1]{.callout}, and the FHIR version [2]{.callout}. ``` 8. **2 · What does this model map to?** Choose a profile, a base resource or a data type. ```{figure} ../images/map/wizard-type.png :class: screenshot :alt: Step 2 of the wizard, profiles, base resources and data types Search [1]{.callout}, profiles of the loaded packages [2]{.callout}, add a profile [3]{.callout}, base resources [4]{.callout}, and the choice [5]{.callout}. ``` - Type in **Search profiles, resources and data types…** [1]{.callout} to narrow all three lists. - **Profiles (loaded FHIR packages)** [2]{.callout} lists the profiles of the packages loaded for this FHIR version. Picking a profile also picks its type (shown next to it). With none loaded, the list says `No profiles loaded for FHIR yet — add one below.` - To add a profile on the spot [3]{.callout}, click **Upload profiles / packages**, pick one or more files (StructureDefinition `.json`, `.tgz` packages up to 15 MB, or a `.zip` of them) and click **Upload N files**, the same as on **FHIR packages** ({doc}`/codes-and-profiles/fhir-packages`). Or type a package as `name#version` in **or fetch: hl7.fhir.uv.ips#1.1.0** and click **Fetch**. Atlas loads it into the FHIR packages and, when the added packages hold a single profile (or a single resource profile), selects it for you: `Added #: selected ().` - **Base resources (no profile)** [4]{.callout} and **Other data types** map the plain FHIR type. - The line at the bottom [5]{.callout} says what you picked: `Selected: (profile on )` or `Selected: (base, no profile)`. Click **Next**. 9. **3 · Extends (optional)**: to make an extension model, pick the model it extends. The list holds the engine's models for the same archetype. Leave **None** to start fresh. ```{figure} ../images/map/wizard-extends.png :class: screenshot :alt: Step 3 of the wizard, Extends **Extends** [1]{.callout}: **None**, or a model of the same archetype. ``` 10. Click **Create model**. **Back** returns to the previous step; on the first step it is **Cancel**. Atlas creates the model and adds it to the template's context (and sets it as the start when you came from **Choose a start archetype**). With a place chosen, it adds the slot mapping to the enclosing model and opens that model on it, with the **FHIR** path focused: fill in where the slotted resource goes in FHIR. Otherwise the new, empty model opens. ```{figure} ../images/map/created-slot.png :class: screenshot :alt: The enclosing model with the new slot mapping selected The new slot mapping in the enclosing model: its **Slot archetype** [1]{.callout} names the new model; the FHIR path is still to fill in. ``` ## Check it worked - The overview shows the new model under **ARCHETYPE MAPPINGS** (or as **START**), and its archetype is gone from **NOT YET MAPPED**. - A model you slotted in has no **Not linked** strip on its card ({doc}`connect-models`). - The coverage chip in the top bar and the **Template** tab show what is still unmapped ({doc}`/check/coverage`). ## Tips :::{tip} **Pick the profile rather than the base type when you have one.** The model then keeps the base type as its `structureDefinition` and gets a `meta` mapping that writes the profile into `meta.profile`. That profile drives the path suggestions, the checks, profile coverage and validation ({doc}`/check/validate`). ::: :::{tip} Reuse a model when the same archetype is mapped the same way in another template. Reusing keeps one model for both, so a fix applies to both. ::: :::{tip} To map a slightly different variant of an existing model, create an extension model (step 9) rather than a copy. See {doc}`fixed-values` for what an extension model's mappings can do. ::: ## Watch out :::{warning} A model you add with **Don't slot it now** is in the context, but no conversion runs it until a slot links it. Its card shows **Not linked**; see {doc}`connect-models`. ::: :::{warning} Reusing a model shares it: editing it later changes it for every template that uses it. ::: ## If something goes wrong | What you see | What it means and what to do | |---|---| | `Failed to create the context mapper` (or the engine's reason) under **New context mapper** | The engine didn't store the context mapper. ``Template '' already has a context mapper`` means one was added meanwhile (an upload, another user): reload the page. | | `Failed to set start` or `The context YAML doesn't parse: …` in the start dialog | The context mapper couldn't be read or saved. Open it with **<>** and fix the YAML ({doc}`connect-models`). | | ``Context YAML has no `context` block to set `start` on`` | The context mapper lacks its `context:` block. Add it with **<>**. | | `Failed to reference model` in **Use an existing mapping?** | The engine refused to add the model to this context. The rest of the message is its reason. | | ` has no model to hold the slot — choose a start / map it first` under a place in **Slot into** | The archetype that encloses this place has no model yet. Choose a start, or map the enclosing archetype first. | | ` already maps elements inside — a model slotted in would map them twice` under a place in **Slot into** | The enclosing model maps this occurrence inline. Keep those mappings and choose **Don't slot it now** or another place, or remove the inline mappings first. | | `Reading the template structure…` in **Slot into** | Atlas is still reading the template; the places appear once it is done. | | `Failed to load FHIR types` in step 2 | The FHIR type list couldn't be loaded. Go back to step 1, pick another FHIR version and then yours again: the list is loaded again. | | `Packages are limited to 15 MB` | The file is too big to add here. | | `Failed to add the profile` (or the engine's reason) | The StructureDefinition or package couldn't be stored or fetched. See {doc}`/codes-and-profiles/fhir-packages`. | | `Added #; its profiles are still loading or it has none for FHIR .` | The package is stored but no profile of it shows yet. Wait a moment and search again, or check the package's FHIR version. | | `Failed to create model` (or the engine's reason) | The model couldn't be created, for example because its name is taken. Go **Back** to step 1, click **Cancel**, and add the mapping again with another name. | After the model exists, the Problems dock may show [the start names no model](problem-start-model-missing), [a model nothing reaches](problem-model-unreached) or [a model without mappings](problem-model-without-mappings). Other notices are listed in {doc}`/reference/messages`. ## Related - {doc}`connect-models`: slots, links and references between models. - {doc}`edit-in-workspace`: add the mappings of the new model. - {doc}`/codes-and-profiles/fhir-packages`: load IG packages and profiles. - {doc}`/reference/screens/index`: the Workspace, control by control.