# Map only when… (conditions) ## What you'll do You make a mapping apply only to some data: only the blood pressure component with the systolic LOINC code, only a coded value with a certain code, or only when an element has a value. You read what the condition resolves to and how many elements of the example it keeps. ```{figure} ../images/map/condition-filter.png :class: screenshot :alt: The FHIR condition of the systolic mapping with its FHIRPath preview and tally The `systolic` mapping keeps only the components coded `8480-6`. ``` ## Before you start - Open the model and select the mapping ({doc}`edit-in-workspace`). - Its paths are set ({doc}`paths`): a condition narrows what the paths select. ## Steps ### Add a condition 1. On the mapping's sheet, click **+ Property** [1]{.callout} and pick **FHIR condition** or **openEHR condition** under **ONLY WHEN**. ```{figure} ../images/map/add-property.png :class: screenshot :alt: The + Property menu with FHIR condition and openEHR condition **+ Property** [1]{.callout}: the conditions are under **ONLY WHEN**. ``` The condition appears in the **Only when** group, with **is one of** chosen. A mapping can have one FHIR condition and one openEHR condition. **remove** next to the condition's label (shown on hover) deletes it. ### Fill it in 2. Fill in the four parts: ```{figure} ../images/map/condition-filter.png :class: screenshot :alt: The parts of a FHIR condition **Where** [1]{.callout}, **field** [2]{.callout}, the operator [3]{.callout}, the criteria [4]{.callout}, the FHIRPath it is equivalent to [5]{.callout}, and what it keeps [6]{.callout}. ``` **Where** [1]{.callout} : The target root: the element whose items are tested, for example `$resource.component`. It is written like the mapping's own paths and has the same suggestions. **field** [2]{.callout} : The attribute of each item that is tested, relative to **Where**, such as `code.coding.code`. Separate several with commas: any of them may match. Suggestions offer the children of **Where**. Operator [3]{.callout} : One of five: | In the list | Keeps or applies when | |---|---| | **is one of** | the field equals one of the criteria | | **is none of** | the field equals none of the criteria | | **is of type** | the field holds one of the named types | | **is empty** | the field has no value | | **has a value** | the field has a value | Criteria [4]{.callout} : The values to compare with, comma-separated: any may match, for example `8480-6, 8462-4`. **is empty** and **has a value** take none, and the criteria field disappears. ### Read what it does 3. Below the condition, Atlas shows what it resolves to. A condition works in one of two ways. **Filter** (**is one of**, **is none of**, **is of type**) : It picks elements. The preview [5]{.callout} is the FHIRPath the condition is equivalent to, with the `where(…)` where the engine applies it: `Bundle.entry.resource.as(Reference).resolve().component.where(code.coding.code = '8480-6')`. **is none of** wraps the test in `.not()`; **is of type** tests the value's type. With an example loaded, the line under it [6]{.callout} counts what the condition keeps: **keeps 3 of 9 component in the example**. When it keeps none, the line turns amber and adds *— check the criteria*. **Gate** (**is empty**, **has a value**) : It picks nothing; it decides whether the whole mapping applies: `mapping only applies when has a value`. ```{figure} ../images/map/condition-gate.png :class: screenshot :alt: A FHIR condition with has a value, shown as a gate A gate [1]{.callout}: the mapping applies only when `bodySite.text` has a value. ``` While you edit, the preview is Atlas's own estimate and carries an **unsaved** chip; save to let the engine resolve it. After an edit the count is dimmed: it reflects the last save until the conversion runs again. An **openEHR condition** reads as one line: the node it tests, the operator and the criteria, for example `$archetype/data[at0001]/items[at0073]/defining_code/code_string is one of at0076`. ```{figure} ../images/map/condition-openehr.png :class: screenshot :alt: The openEHR condition of the certainty mapping An openEHR condition: only the certainty coded `at0076`. ``` ### Match by type 4. Choose **is of type** and click into the criteria field ({kbd}`Ctrl+Space`). Suggestions list first the types the **field** can hold (*value can hold this*), then every resource and data type (FHIR) or every data value type such as `DV_CODED_TEXT` (openEHR). ```{figure} ../images/map/condition-type.png :class: screenshot :alt: Type suggestions for the field value of an Observation component The types `component.value` can hold come first. ``` ## Check it worked - The preview shows the `where(…)` (or the gate) you meant, without **unsaved** after saving. - **keeps k of n** shows a sensible share of the example, not 0. - The side panes highlight only the kept elements ({doc}`/check/see-in-action`). ## Tips :::{tip} **A comma means "any may match"**, in **field** and in the criteria alike. `8480-6, 8462-4` keeps both systolic and diastolic components. ::: :::{tip} If the preview says *The target root isn't on this mapping's path, so the condition tests the whole resource rather than picking elements.*, **Where** doesn't lie on the mapping's FHIR path. The condition then tests the resource as a whole: it keeps all of the mapping's elements or none. To pick elements, start **Where** with the same path as the mapping. ::: :::{tip} Accepting a slice or an extension in a FHIR path suggestion writes its selecting condition for you ({doc}`paths`). ::: :::{tip} Atlas writes **field** and the criteria as lists (`targetAttributes`, `criterias`). Older files with the single forms (`targetAttribute`, `criteria`) still work; editing the field rewrites them as lists. In the YAML, a single `criteria: "a, b"` is one criterion, not two. ::: ## Watch out :::{warning} After moving a mapping, its FHIR condition is kept as written. Check that **Where** still names the right element; the undo toast says `FHIR condition kept as written: check it still applies.` ({doc}`edit-in-workspace`). ::: :::{warning} **is empty** and **has a value** drop any criteria you had typed: they aren't kept hidden in the YAML. ::: ## If something goes wrong | What you see | What it means and what to do | |---|---| | **keeps 0 of n … in the example — check the criteria** | No element of the example matches. Check the codes, the **field** and **Where**. | | No preview under the condition | The condition isn't complete yet: **field**, an operator, and (except for the gates) criteria are needed. | | *The target root isn't on this mapping's path, …* | See *Tips*. | Problems in the paths of a condition show in the Problems dock like any path problem ([fhir-path-unknown](problem-fhir-path-unknown), [openehr-not-in-template](problem-openehr-not-in-template)). Other notices are in {doc}`/reference/messages`. ## Related - {doc}`paths`: the paths a condition narrows. - {doc}`/reference/paths-cheat-sheet`: operators and FHIRPath equivalents on one page. - {doc}`/check/see-in-action`: the example the count is taken from. - Engine: {external+openfhir:doc}`fhirconnect` (selecting a coding with `fhirCondition`).