# Write FHIR and openEHR paths ## What you'll do You fill in a mapping's **FHIR** and **openEHR** paths with the help of suggestions from the FHIR definitions and the template, and check what each path really resolves to in the engine. ```{figure} ../images/map/openehr-by-name.png :class: screenshot :alt: openEHR path suggestions found by the node name systolic Typing a node's name finds its whole path in the template. ``` ## Before you start - Open the model and select a mapping ({doc}`edit-in-workspace`). - For profile-aware FHIR suggestions, load the profile's IG package ({doc}`/codes-and-profiles/fhir-packages`) and give the model the profile ({doc}`start-mapping`). Without it, suggestions follow the base FHIR definitions. ## Steps ### Start a path with a token Every path starts either with a token or, inside a child mapping, relative to the parent. Click into an empty field and the tokens are offered straight away. | Field | Token | Means | |---|---|---| | FHIR | `$resource` | The resource this model maps. In a slotted model, the resource it is slotted into. | | FHIR | `$fhirRoot` | The parent mapping's element (only in a child mapping). | | FHIR | *(no token)* | Relative to the parent mapping's element, for example `coding` under `$resource.code`. | | openEHR | `$archetype` | This model's archetype root. | | openEHR | `$openehrRoot` | The parent mapping's node (`$openEHRRoot` is accepted too). | | openEHR | `$composition` | The composition root. Paths below it keep the name predicates that tell same-archetype sections apart, such as `content[openEHR-EHR-SECTION.adhoc.v1 and name/value='Problem List']`. | | openEHR | `$reference` | Delegate to the referenced resource's mapping ({doc}`connect-models`). | | openEHR | *(no token)* | Relative to the parent mapping's node, for example `items[at0004]`. | {doc}`/reference/paths-cheat-sheet` lists all tokens and forms on one page. ### Use the suggestions 1. Type in the field. Suggestions open as you type; {kbd}`Ctrl+Space` opens them at any time. 2. Move with {kbd}`↑` / {kbd}`↓` and accept with {kbd}`Enter` or {kbd}`Tab`, or click one. {kbd}`Esc` closes the list. 3. After accepting, type `.` (FHIR) or `/` (openEHR) to go on to the next level. #### FHIR suggestions ```{figure} ../images/map/fhir-suggestions.png :class: screenshot :alt: FHIR suggestions for $resource. on an Observation model The elements of Observation, with their type, cardinality and definition. ``` Each suggestion shows the element, its type and cardinality, and its short definition. With a profile loaded, badges show what the profile says: | Badge | Means | |---|---| | **MS** | Must support in the profile. | | **ext** | An extension the profile defines. | | **slice: ** | A slice of the element. The hint names what selects it, such as `url = ` or `system = `. | | ** profile** | The profile changes the cardinality from the base definition. | | **binding: required** / **binding: extensible** | The element's codes are bound to a value set. | Elements the profile forbids aren't offered. Rarely mapped elements (`id`, `extension`, `modifierExtension`, `implicitRules`, `language`, `contained`, `text`) come last unless you type their name. On a choice element such as `value[x]`, the suggestions are the casts, **as(Quantity)**, **as(CodeableConcept)** …: *Narrow the choice element to this type*. ```{figure} ../images/map/fhir-choice.png :class: screenshot :alt: The as(Type) suggestions for Observation.value The types `Observation.value` can take. ``` On a Reference, **resolve()** follows the reference into the resource it points at (the hint names the possible targets). From the second segment on, **where(…)** is offered (*Filter, e.g. where(system = …)*); accepting it leaves the caret between the parentheses. ```{figure} ../images/map/fhir-resolve.png :class: screenshot :alt: Suggestions for Observation.subject including resolve() `resolve()` on `Observation.subject`. ``` **Picking a slice or an extension also writes the matching condition.** FHIR Connect addresses a slice or an extension as the element plus a condition that selects it, so when you accept such a suggestion Atlas adds a **FHIR condition** to the mapping: **Where** the path up to the picked element, **field** the selecting attribute (`url`, `system` or `code`), **is one of** the value. It does so only when the mapping has no FHIR condition yet. See {doc}`conditions`. #### openEHR suggestions openEHR suggestions offer whole paths from the template, not just the next segment, and match what you type against the node **names** as well as the path. Typing `$archetype/systolic` finds every node called *Systolic*, however deep it sits. ```{figure} ../images/map/openehr-by-name.png :class: screenshot :alt: openEHR suggestions matching systolic Each suggestion shows the path, its RM type and cardinality, and the node's name. ``` ### Pin one attribute of a data value When the path reaches an ELEMENT, or a node that is a data value itself (`null_flavour`), the suggestions start with the attributes of its data value, spelled as strict AQL in **openEHR** paths (`with.openehr`). ```{figure} ../images/map/leaf-attributes.png :class: screenshot :alt: Data value attributes offered below the Systolic element The attributes of a DV_QUANTITY, with the flat-format attribute each becomes. ``` | Data value | Attributes you can pin | |---|---| | DV_QUANTITY | `value/magnitude`, `value/units`, `value/precision`, `value/units_system`, `value/units_display_name` | | DV_CODED_TEXT | `value/defining_code/code_string`, `value/defining_code/terminology_id`, `value/value`, `value/formatting` | | DV_TEXT | `value/value`, `value/formatting`, and the DV_CODED_TEXT ones (a text element may hold a coded text) | | DV_COUNT | `value/magnitude` | | DV_PROPORTION | `value/numerator`, `value/denominator`, `value/type`, `value/precision` | | DV_ORDINAL | `value/value`, `value/symbol/value`, `value/symbol/defining_code/code_string` | | DV_IDENTIFIER | `value/id`, `value/type`, `value/issuer`, `value/assigner` | | DV_PARSABLE | `value/value`, `value/formalism` | | DV_MULTIMEDIA | `value/uri/value`, `value/media_type/code_string`, `value/size`, `value/alternate_text` | | DV_BOOLEAN, DV_DATE_TIME, DV_DATE, DV_TIME, DV_DURATION, DV_URI, DV_EHR_URI | `value/value` | An element that can hold several types lists the attributes of all of them; the hint says `also : set with.type to pick` when an attribute exists in more than one. The engine reads every spelling of an attribute the same way in every field: `value/magnitude`, `magnitude` and `|magnitude` all address the magnitude. Manual values and openEHR conditions suggest the RM name (`magnitude`); see {doc}`fixed-values`, {doc}`conditions` and {doc}`/reference/paths-cheat-sheet`. Pinning an attribute through `value` that none of the element's types has (`value/magnitude` on a coded text) is reported as {ref}`openehr-not-in-template `. ### Check what a path resolves to Under each path field, a line starting with **→** shows what the path resolves to in the engine: for FHIR the full path and its type (`Observation.code.coding.display` `string`), for openEHR the flat path, the node's name and RM type. Hover it to see every place the model is used. While you edit, that line is Atlas's own estimate and carries an **unsaved** chip (*Estimated from the edited YAML — Save to let the engine resolve it.*) until you save. ```{figure} ../images/map/resolved-unsaved.png :class: screenshot :alt: A changed FHIR path with its resolved path marked unsaved The estimate for an edited path [1]{.callout}. ``` For the whole picture, open the **Resolved paths** tab [1]{.callout} at the bottom of the sheet. ```{figure} ../images/map/resolved-paths.png :class: screenshot :alt: The Resolved paths tab of the value mapping The engine's paths for the `severity` mapping of the IPS problem/diagnosis model, reached through the problem list section. ``` - When the model runs in several places (several slots lead to it), each gets its own **CONTEXT** box. - **FHIR**: the resource hops from the root (an arrow is a `resolve()` into the next resource), the conditions applied on the way with the mapping they come from, and the **engine** path. - **OPENEHR**: the **flat** path (as the openEHR pane shows it) and the **aql** path, the RM types at that node. - **via** names the mappings the model is reached through. Each path has a copy button; it turns into a check mark when copied. Before the first save, the tab says `Not in the engine tree yet — Save to resolve it.`; after an edit, `The engine data reflects the last save — Save to resolve the edited path.` ## Check it worked - The **→** line under the field shows the element or node you meant, without **unsaved** once saved. - No red or amber line appears under the field, and the row's status dot stays clear. - The side panes highlight the value the path maps ({doc}`/check/see-in-action`). ## Tips :::{tip} In openEHR fields, search by what the node is called (`systolic`, `comment`, `substance`) rather than by its at-code. ::: :::{tip} `value` alone maps the whole data value (all its parts). Pin `value/magnitude`, `value/units` or `value/defining_code/code_string` when the FHIR side holds only one part. ::: :::{tip} Accept the slice or extension suggestion instead of typing the element name: you get the selecting condition for free. ::: ## Watch out :::{warning} **Choice casts are capitalised**: `value.as(Quantity)`, `abatement.as(DateTime)`, `value.as(String)`. The engine builds FHIR from the type name, so `as(string)` builds nothing. Accept the suggestion to get it right. ::: :::{warning} **Picking a slice or extension writes a condition only when the mapping has none.** If it already has a FHIR condition, Atlas leaves it as it is: check that it still selects the slice. ::: :::{warning} The copy buttons need a secure page. On Atlas served over plain `http` (other than `localhost`), the browser blocks the clipboard and nothing is copied. ::: ## If something goes wrong Path problems show as a line under the field, as the row's status dot and in the Problems dock ({doc}`/check/fix-problems`): - [fhir-path-unknown](problem-fhir-path-unknown): the FHIR path names an element the type or profile doesn't have. - [fhir-path-prohibited](problem-fhir-path-prohibited): the profile forbids the element. - [fhir-slice-unknown](problem-fhir-slice-unknown): no slice of the profile matches the path's `where(…)`. - [openehr-not-in-template](problem-openehr-not-in-template): the openEHR path isn't in the template. - [profile-not-loaded](problem-profile-not-loaded): the model's profile isn't loaded, so paths are checked against base FHIR only. - [hierarchy-unresolved](problem-hierarchy-unresolved): the engine couldn't resolve the path of the model's `preprocessor` hierarchy. Other notices are in {doc}`/reference/messages`. ## Related - {doc}`/reference/paths-cheat-sheet`: tokens, attribute spellings and FHIRPath forms on one page. - {doc}`conditions`: the conditions slices and extensions rely on. - {doc}`/codes-and-profiles/add-extension`: map a FHIR extension end to end. - Engine: {external+openfhir:doc}`fhirconnect`.