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.

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

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.

The model terminology of the allergy model, type local with the adverse reaction ConceptMap

The allergy model translates through a ConceptMap.

1 Model terminology: the outline row, with a summary of the block (none — add a model-level terminology when there is none).

2 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 ConceptMap: every ConceptMap the engine holds, by canonical url and description.

4 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.

The category mapping with four inline terminology rows

category translates four values with inline rows.

1 The book icon in the outline: this mapping’s codes are translated (“Codes translated via …”).

2 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 Terminology type of this mapping.

4 + Row adds a pair.

5 × (“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 (Suggested systems and codes): 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 1 of 1: codes of the example translated (amber when some weren’t).

2 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 Only example codes: shows only the rows the example used.

4 Filter codes: filters the rows by code or display.

5 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 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 See your mapping in action.

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 (Manage 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.

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 terminology-conceptmap-unknown. Pick an existing ConceptMap, or create one with that url.

The model terminology naming a ConceptMap marked (not found)

The ConceptMap was deleted from the engine; the open button 1 is disabled.

Warning

A local terminology without a ConceptMap translates nothing: 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.

  • terminology-conceptmap-unknown, terminology-conceptmap-missing.