# Translate codes ## What you'll do openEHR and FHIR often code the same thing differently: `at0102` in the archetype is `low` in FHIR. You tell the engine how to translate such codes, either with a few code pairs written into the mapping (**inline**) or with a FHIR ConceptMap the engine holds (**local**), for one mapping or for the whole model. Then you check in the example what each code turned into. ```{figure} ../images/codes-and-profiles/translation-tab.png :class: screenshot :alt: The Translation tab of the criticality mapping, tracing at0102 to low through the ConceptMap The **Translation** tab of `criticality`: the example's `at0102` became `low`. ``` ## Before you start - Open the model in the Workspace ({doc}`/map/edit-in-workspace`). - For a ConceptMap, it must exist in the engine: create or upload it on the Terminology page ({doc}`conceptmaps`). - How the engine applies terminology is described in the engine's {external+openfhir:doc}`terminology` documentation. ## Choose where the translation lives | Use | When | Where you set it | |---|---|---| | **inline** rows | A handful of code pairs that belong to one mapping, for example four category values. | The mapping's **Terminology** property, or the model terminology. | | **local** (a ConceptMap) | Longer lists, codes shared by several mappings or models, or a map you maintain on its own. | The mapping's **Terminology** property, or the model terminology. | | **none** | The model translates nothing; the mappings' own blocks still apply. | Model terminology only. | | **external** | A terminology server translates the codes (enter its **Server**, for example `https://tx.fhir.org/…`). | Model terminology only. | A mapping uses its own terminology; without one, the model's; without that, its parent mapping's. A top-level mapping of a model that is slotted into another one can also get the terminology of the mapping that slots it in. ## Steps ### 1. Set the model terminology Select **Model terminology**, the first row of the outline. The editing sheet shows the model's terminology block. ```{figure} ../images/codes-and-profiles/model-terminology.png :class: screenshot :alt: The model terminology of the allergy model, type local with the adverse reaction ConceptMap The allergy model translates through a ConceptMap. ``` [1]{.callout} **Model terminology**: the outline row, with a summary of the block (`none — add a model-level terminology` when there is none). [2]{.callout} **Type**: **none**, **inline**, **local** or **external**. Changing the type drops the other types' fields, so no stale value stays in the YAML; a new **inline** block starts with an empty row. [3]{.callout} **ConceptMap**: every ConceptMap the engine holds, by canonical url and description. [4]{.callout} Open the ConceptMap on the Terminology page, in a new tab ("Open this ConceptMap in the Terminology view (new tab)"). Without a block, the sheet offers **Add terminology** (it starts as **local**). **Remove** deletes the block. ### 2. Or give one mapping its own codes Select the mapping and add the **Terminology** property (**+ Property** › **Terminology**). A mapping's own block knows **inline** and **local**. ```{figure} ../images/codes-and-profiles/inline-rows.png :class: screenshot :alt: The category mapping with four inline terminology rows `category` translates four values with inline rows. ``` [1]{.callout} The book icon in the outline: this mapping's codes are translated ("Codes translated via …"). [2]{.callout} **Translates codes**: the terminology that applies, wherever it comes from (`inline · 4 rows`, `ConceptMap …/adverse-reaction_list-fhirconnect`), and from where (**this mapping**, **model terminology**, **from **, **from the model that slots this one**). Click it for the **Translation** tab. [3]{.callout} **Terminology** type of this mapping. [4]{.callout} **+ Row** adds a pair. [5]{.callout} **×** ("Remove row") deletes a pair. Each row pairs an **openEHR** side with a **FHIR** side, each with **system**, **code**, **display** and **ordinal**. Leave a field empty when it doesn't matter; empty fields are not written to the YAML. On the FHIR side, **system**, **code** and **display** suggest what the model's FHIR packages and core FHIR know, as in the ConceptMap editor ({ref}`conceptmap-suggestions`): the systems first that the mapped element's ValueSet binding lists codes of (`binding`), then those the other rows use (`in use`); then the codes of the row's system. A line under **system** says where it comes from. The openEHR side's codes come from the template and aren't suggested. ### 3. Check what the codes turned into Select the mapping and click **Translates codes** (or the **Translation** tab at the bottom of the sheet, or **View map** / **View rows** on the **Example values** tab). The tab shows the map with what the example did to it. Its badge `N of M` says how many of the example's codes were translated. The numbers match the screenshot at the top of this page. [1]{.callout} `1 of 1`: codes of the example translated (amber when some weren't). [2]{.callout} **In this example**: each code of the source pane, with the direction (`openEHR → FHIR`), what it became and how: the equivalence (`equivalent` …), **fixed** (the group's code for unlisted codes), **other map**, or **not in map** ("not in the map: kept as is"). Click a code to mark its row in the map. [3]{.callout} **Only example codes**: shows only the rows the example used. [4]{.callout} **Filter codes**: filters the rows by code or display. [5]{.callout} A row the example used, tinted. Under each group, the group's rule for unlisted codes: "Codes not listed are kept as they are.", "Codes not listed become ." or "Codes not listed are looked up in ." [6]{.callout} **Open in ConceptMap editor**: opens the map on the Terminology page in a new tab. For inline rows, **Edit rows** takes you to the rows instead. The pane popovers show the same: in the source pane's values, each code has a chip such as `→ low`; click it to open the map at that code. See {doc}`/check/see-in-action`. ```{figure} ../images/check/values-popover.png :class: screenshot :alt: The openEHR values popover with the translation chip → low The openEHR values of `criticality`, with the translation chip. ``` ## Check it worked The **Translation** tab counts every code as translated, and the FHIR pane shows the target code. If a code says **not in map**, add a row for it, or set the group's unmapped rule ({doc}`conceptmaps`). ## Tips :::{tip} Edits to the terminology apply to the example only after a save. Until then **Translates codes** carries a marker: **not applied yet** (added), **changed**, or **removed**, and the example values still went through the saved terminology. Save to apply it. ```{figure} ../images/codes-and-profiles/pending-edit.png :class: screenshot :alt: Translates codes with the marker changed An inline row edited, not saved yet. ``` ::: :::{tip} The map in the tab is read again each time you open it, so edits you saved on the Terminology page in the other tab show up. ::: ## Watch out :::{warning} A ConceptMap that the model names but the engine doesn't have is kept, marked **(not found)**, and can't be opened. The engine then translates nothing: codes are kept as they are, and the Problems dock reports {ref}`terminology-conceptmap-unknown `. Pick an existing ConceptMap, or create one with that url. ```{figure} ../images/codes-and-profiles/conceptmap-not-found.png :class: screenshot :alt: The model terminology naming a ConceptMap marked (not found) The ConceptMap was deleted from the engine; the open button [1]{.callout} is disabled. ``` ::: :::{warning} A **local** terminology without a ConceptMap translates nothing: {ref}`terminology-conceptmap-missing `. ::: ## If something goes wrong - "The engine has no ConceptMap with this url, so it can't translate anything: codes are kept as they are." The peek can't find the map; see the warning above. - "Not saved yet, so the example didn't go through it." Save the model. - "The example has no codes for this mapping." The example holds no coded value at the mapping's path. - {ref}`terminology-conceptmap-unknown `, {ref}`terminology-conceptmap-missing `. ## Related - {doc}`conceptmaps` - {doc}`/check/see-in-action` - {external+openfhir:doc}`terminology`