# Add a FHIR extension ## What you'll do You map an openEHR element to a FHIR extension the profile doesn't define, for example the `allergyintolerance-assertedDate` extension on an AllergyIntolerance. You pick the extension in the **Profile** tab, and **+ Map** writes a mapping that works both ways: it reads the extension by its url, maps its value, and writes the url back when FHIR is built. ```{figure} ../images/codes-and-profiles/ext-mapping.png :class: screenshot :alt: The new assertedDate mapping with its FHIR condition and the value and url child mappings The mapping **+ Map** writes for the asserted date extension. ``` ## Before you start - Open the model in the Workspace and click **Profile** in the FHIR pane ({doc}`/check/coverage`). - Extensions from IG packages are offered only when the package is loaded ({doc}`fhir-packages`). The core FHIR extensions are always offered. - Know where the value comes from in the template: the openEHR path you will map it from. ## Steps ### 1. Open the extension picker In the profile's entry, click **+ Ext** in its header for an extension on the resource itself, or hover an element and click its **+ Ext** for an extension on that element. The picker opens under it, with the cursor in the search. ```{figure} ../images/codes-and-profiles/ext-picker.png :class: screenshot :alt: The extension picker on the AllergyIntolerance resource, searching allergyintolerance The picker for an extension on the resource. ``` [1]{.callout} **Search extensions, or type any url…**: filters by title, name or url. {kbd}`↑` / {kbd}`↓` move, {kbd}`Enter` picks, {kbd}`Esc` closes (or **Cancel**). [2]{.callout} **An extension**: its title, the url's tail, its value type (or `complex`) and the package it comes from (`core` for the FHIR core extensions). Extensions already on the element are greyed out and marked **added**. [3]{.callout} **Show all (N with another context)**: the list first shows the extensions whose context allows this element, and those whose context can't be told (**context?**). This shows the others too, marked **other context**; **Only fitting ones** goes back. To use an extension no loaded package defines, type its url: the picker offers **Use as the extension url:** , "exactly as typed; no loaded package defines it, so it isn't checked". ```{figure} ../images/codes-and-profiles/ext-free-url.png :class: screenshot :alt: The picker offering a typed url as the extension url A url of your own. ``` ### 2. Pick it Click the extension (or press {kbd}`Enter`). The picker closes and the extension appears in the profile's list, with its `value` below it. ```{figure} ../images/codes-and-profiles/ext-draft.png :class: screenshot :alt: The added asserted date extension in the Profile tab, not mapped yet The added extension, not mapped yet. ``` [1]{.callout} **added**: not part of the profile. Hover it: "Not in the profile: added here, not mapped yet (kept for this browser session). Not counted." [2]{.callout} **value**: the extension's value. [3]{.callout} **+ Map**: maps it (step 3). [4]{.callout} **×** ("Remove the added extension"): drops it again. Added extensions never count towards the profile's coverage. ### 3. Map it with + Map Hover the extension's row and click **+ Map**. Atlas adds a top-level mapping to the model, named after the extension, and selects it (see the screenshot at the top): [1]{.callout} **FHIR**: `$resource.extension` (or the element's `extension`). [2]{.callout} **openEHR**: empty, with the cursor in it. Enter the openEHR path the value comes from ({doc}`/map/paths`). [3]{.callout} **FHIR condition**: `url` **is one of** the extension's url, so that reading FHIR picks this extension and no other. [4]{.callout} **value**: a child mapping from the extension's `value` to `$openehrRoot`, the openEHR node of the parent mapping. When the extension allows one value type, the path is narrowed to it (`value.as(DateTime)`); with several, the cursor goes to the child's FHIR path for you to narrow it. A complex extension gets no value child. [5]{.callout} **url**: a child mapping on `$fhirRoot` with a manual entry that writes the url. If the model already maps that extension at the top level, **+ Map** adds only the missing children to it (or selects it when nothing is missing). Save the model. Once a mapping produces the extension, the row turns ✓ and stays listed, now from the mapping instead of the draft. ## Check it worked - In the **Profile** tab, the extension's row is ✓ and its **added** badge says "produced by a mapping". - Convert openEHR to FHIR: the FHIR pane holds the extension with its `url` and value. - The Problems dock has no {ref}`extension-url-not-written ` for the mapping. ## Tips :::{tip} On an element inside a slice, **+ Ext** is disabled: "Inside the slice : an extension mapped here couldn't be told apart from the other slices' yet". Map the extension from a mapping of that slice instead. ::: :::{tip} A profile that closes its extension slicing on an element allows only its own extensions there; the picker says "The profile closes the extension slicing here: only its own extensions are allowed." ::: ## Watch out :::{warning} The extension's condition (`url` is one of …) only selects the extension when reading FHIR. When the engine builds FHIR from openEHR, it ignores the condition: the url is written only by the **url** child mapping. Delete that child and the extension is built without its url; Atlas warns with {ref}`extension-url-not-written `: ```{figure} ../images/codes-and-profiles/ext-url-problem.png :class: screenshot :alt: The warning extension-url-not-written in the Problems dock The warning after deleting the `url` child. ``` ::: :::{warning} An extension you added but haven't mapped is a draft kept for this browser session only. Map it (and save) before you close the session, or it is gone. ::: ## If something goes wrong - "The FHIR packages are still loading; try again in a moment." Close the picker and open it again shortly. - "Could not load the extensions." The profile couldn't be read; check {doc}`fhir-packages`. - "No extension fits this element" / "No extension matches": try **Show all**, or type the url. - {ref}`extension-url-not-written ` ## Related - {doc}`/check/coverage` - {doc}`/map/fixed-values`: manual entries and extension models. - {doc}`/map/conditions` - {doc}`fhir-packages`