# Fixed values, codes and manual pairs ## What you'll do You write values that aren't in the source data, such as a fixed LOINC code or a document title, with manual pairs. You also limit a mapping to one direction, call a programmed mapping with a mapping code, and use the mappings of an extension model to add to, extend or replace the mappings of the model it extends. ```{figure} ../images/map/manual-pairs.png :class: screenshot :alt: The manual entries of the type mapping, code, system and display The `type` mapping of the IPS composition writes a fixed LOINC coding. ``` ## Before you start - Open the model and select the mapping ({doc}`edit-in-workspace`). Its paths say where the values go ({doc}`paths`). ## Steps ### Write fixed values with manual pairs 1. Click **+ Property** and pick **Manual** (under **VALUES**). A **Manual** entry appears in the **Values** group. ```{figure} ../images/map/manual-pairs.png :class: screenshot :alt: A manual entry with its name, a FHIR path and value The entry's name [1]{.callout}, a path [2]{.callout} and its value [3]{.callout}, and **+ Pair** [4]{.callout}. ``` 2. Give the entry a name [1]{.callout}. 3. Under **FHIR** or **openEHR**, click **+ Pair** [4]{.callout} and fill in the **path** [2]{.callout} and the **value** [3]{.callout}. Add as many pairs as you need; the **×** next to a pair removes it. 4. **+ Add another** adds a second entry to the same mapping; the **×** next to an entry's name removes it. How the pairs are read: - **Paths are relative to the mapping.** A FHIR path continues from the mapping's own FHIR element: under `$resource.type.coding`, the paths `code`, `system` and `display` write `type.coding.code`, `type.coding.system` and `type.coding.display`. `$fhirRoot` is the element itself. An openEHR path continues from the mapping's own node; `$openehrRoot` is the node itself. The path suggestions follow that. - **FHIR pairs are written when converting openEHR → FHIR**; openEHR pairs when converting FHIR → openEHR. The engine turns each FHIR pair into a child mapping of its own. - **openEHR pairs** below an element take the attributes of its data value, by their RM name: `defining_code/code_string`, `defining_code/terminology_id` and `value/value` (or `value`) for a coded text, `magnitude` and `units` for a quantity. The engine reads every spelling the same way, so the flat attribute (`|magnitude`, `|unit`) and strict AQL (`value/magnitude`) work too; see {doc}`/reference/paths-cheat-sheet`. ### Limit a mapping to one direction 5. Open the **Advanced** group at the bottom of the sheet (it is folded unless one of its properties is set) and click **+ Unidirectional**, or pick **Unidirectional** from **+ Property**. 6. Choose the direction the mapping runs in: `openehr->fhir` or `fhir->openehr`. To make it run both ways again, click the **×** next to **Unidirectional**. ```{figure} ../images/map/advanced.png :class: screenshot :alt: The Advanced group with Unidirectional and Mapping code A mapping that runs only from openEHR to FHIR, with a mapping code being added. ``` ### Call a programmed mapping 7. In **Advanced**, click **+ Mapping code** and type the function, for example `generateNarrative(entry)`. A mapping code calls one of the engine's programmed mappings instead of copying values; see {external+openfhir:doc}`programmedmappings` for the functions and their arguments. ### Use an extension model's mappings An extension model (made with **Extends** in the wizard, {doc}`start-mapping`) changes the model it extends. On the overview it sits under that model, marked **EXTENSION**. Each of its mappings says in **Advanced** › **Extension** what it does to the extended model: ```{figure} ../images/map/extension-mapping.png :class: screenshot :alt: A mapping of the IPS_problem_diagnose extension model with Extension add **Extension** [1]{.callout} and **+ Append to** [2]{.callout} in an extension model's mapping. ``` **add** : The mapping is added to the extended model's mappings. **overwrite** : The mapping replaces the extended model's mapping of the same name. **append** : The mapping adds to the extended model's mapping named in **Append to** [2]{.callout}: its conditions are set on that mapping and its child mappings are added after the existing ones. For a nested mapping, write the names joined by dots (`parent.child`). Its own paths are not used. **Append to** and **Extension** are offered only in extension models. A model-level terminology in the extension model replaces the extended model's. ## Check it worked - With an example loaded, the **Example values** tab of the mapping ({doc}`/check/see-in-action`) and the FHIR pane show the fixed values in the converted resource. ## Tips :::{tip} Put pairs that build one element into one entry, with paths that share their start (`code.coding.code`, `code.coding.system`): the engine creates the shared `code.coding` once, so both values land on the same coding. ::: :::{tip} A fixed value that only exists on the FHIR side (a profile URL, a LOINC code, a status) is a manual pair on a mapping whose openEHR path is the parent node, such as `$composition` or `$archetype`. ::: :::{tip} Set `openehr->fhir` on a mapping that only makes sense when building FHIR, such as a narrative or a fixed coding, so it isn't applied when reading FHIR. ::: ## Watch out :::{warning} **Extension mappings need a manual `url` writer when converting openEHR → FHIR.** A FHIR extension is addressed as `extension` plus a condition on its `url`. That condition selects the extension when reading FHIR, but when building FHIR nothing writes the `url` unless a child mapping on `$fhirRoot` has a manual FHIR pair `url` = the extension's canonical. Without it you get [extension-url-not-written](problem-extension-url-not-written). {doc}`/codes-and-profiles/add-extension` builds both for you. ::: :::{warning} An **append** mapping's own **FHIR** and **openEHR** paths are ignored by the engine. To change a mapping's paths, use **overwrite**. ::: ## If something goes wrong | What you see | What it means and what to do | |---|---| | [extension-url-not-written](problem-extension-url-not-written) | See *Watch out*. | | [with-empty](problem-with-empty) | The mapping has neither a FHIR nor an openEHR path. A mapping with manual pairs still needs the path they continue from. | | [terminology-conceptmap-missing](problem-terminology-conceptmap-missing) / [terminology-conceptmap-unknown](problem-terminology-conceptmap-unknown) | A terminology on the mapping or model names no ConceptMap, or one that isn't loaded. See {doc}`/codes-and-profiles/translate-codes`. | Other notices are in {doc}`/reference/messages`. ## Related - {doc}`/codes-and-profiles/translate-codes`: translate codes instead of fixing them. - {doc}`/codes-and-profiles/add-extension`: map a FHIR extension end to end. - {doc}`paths`: the paths manual pairs continue from. - Engine: {external+openfhir:doc}`fhirconnect`, {external+openfhir:doc}`programmedmappings`.