# Engine state **Engine state** (`/state`) lists what the openFHIR engine holds: the operational templates (OPTs), their context mappers, the model mappers with their mappings, and counts of ConceptMaps and FHIR packages. From here you upload material, open a template in the Workspace, export it, replace or delete it, and read or edit a single mapping without leaving the page. The page has three levels. Each level is a URL, so the browser's back button and a shared link return to the same place (see {doc}`/reference/deep-links`): 1. The overview: every template and every model mapper. 2. A template selected: its actions and only its model mappers. 3. A model mapper opened: its mappings, with the selected mapping in a detail panel. ## The overview ```{figure} ../../images/screens/engine-state-overview.png :class: screenshot :alt: Engine state with three templates and the list of model mappers The overview after **Load demo mappings**. ``` [1]{.callout} **Engine State** : The page title. When the engine holds no template yet, the page shows a **Welcome** card instead of the lists, with **Load demo mappings** (see {doc}`/start/first-mapping`). When versioning is set up and the git remote has commits the engine hasn't pulled, a notice above it offers **Import from the remote** ({ref}`msg-remote-content`), and loading the demo asks first. [2]{.callout} Help : Opens this page. [3]{.callout} **Upload** : Opens and closes the **Upload mappings** panel (see [Upload panel](#engine-state-upload) below). [4]{.callout} **Operational templates** : How many templates the engine holds, how many have a context mapper ("**3** with context"), and, in amber, how many have none ("**1** without"). [5]{.callout} **Model mappers** : All model mappers, split into core models and extensions ("17 core · 2 extensions"). [6]{.callout} **Mappings** : The number of top-level mappings across all model mappers. Nested mappings (followed-by, reference) aren't counted. [7]{.callout} **ConceptMaps** : The ConceptMaps in the terminology store and how many of them a model uses. Click the tile to open {doc}`terminology`. [8]{.callout} **FHIR packages** : The loaded IG packages ("none loaded", or the first package with "+N" more). Click the tile to open {doc}`fhir-packages`. A tile shows **—** when its count couldn't be read. [9]{.callout} Search : Filters both lists at once by template id, model mapper name, archetype or extended model. Press {kbd}`Esc` or the **✕** to clear it. [10]{.callout} Template : The template's name and id, and its status: - **Mapped**: a context mapper exists and every archetype of the template has a model. - **Partially mapped**: some archetypes have no model yet. - **No context**: the template has no context mapper. A **Start mapping →** link opens it in the Workspace, which creates the context mapper first (see {doc}`/map/start-mapping`). Click the row (or press {kbd}`Enter` on it) to select the template. [11]{.callout} **FHIR profile · start** : The FHIR profile of the context mapper (the resource type as a chip, then **core** for a core FHIR profile or the profile's canonical URL) and, below it, the start archetype. A template without a context mapper shows **No context mapper yet**. [12]{.callout} **Archetypes mapped** : How many of the template's archetypes a model maps, out of all archetypes in the OPT. The bar is green when every archetype is mapped, amber otherwise. [13]{.callout} Open in workspace : Shows when you point at a template that has a context mapper; opens the template in the Workspace. [14]{.callout} **Model mappers** : The list of model mappers with their count. While you search, the count reads "*N* of *M*". [15]{.callout} **Core** and **Extensions** : With more than one template, the list is split into core models and extension models. [16]{.callout} Model mapper row : The model's name and version, its openEHR RM class and the FHIR type it produces ("OBSERVATION · → Observation"); an extension shows "extends *core model*" instead. On the right, the number of mappings. Click the row to open the model mapper. [17]{.callout} Template tag : Which template uses the model (with "+N" when several do). Shown when the list is wide enough. When some templates have no context mapper, a filter appears next to the search: **All**, **With context** and **No context**, each with its count. (engine-state-template)= ## A template selected ```{figure} ../../images/screens/engine-state-template.png :class: screenshot :alt: The Blood Pressure template selected, with its actions and the More actions menu open Blood Pressure selected, with the **⋯** menu open. ``` [1]{.callout} Selected template : Marked with an orange bar. The row below it holds the template's actions. [2]{.callout} **Open in workspace** : Opens the template in the Workspace. [3]{.callout} **Export** : Opens **Export template**: download the template's FHIR Connect mappings, the OPT, the linked FHIR packages and ConceptMaps as one ZIP. See {doc}`/ship/export`. [4]{.callout} More actions (**⋯**) : The rarely used and destructive actions. [5]{.callout} **Replace OPT…** : Upload a new `.opt` file for this template (**Update operational template**). See {doc}`/map/bring-material-in`. [6]{.callout} **Delete template…** : Asks **Delete operational template?** and can delete the template's model mappers with it. See {doc}`/map/bring-material-in`. [7]{.callout} Scope : The model mapper list shows only this template's models ("of Blood Pressure"). The search doesn't filter this list. [8]{.callout} **✕** (Show all model mappers) : Clears the selection and returns to the overview. ### With versioning When the engine versions the mappings, the page has three more entry points (see {ref}`When is versioning available `): ```{figure} ../../images/screens/engine-state-versioning.png :class: screenshot :alt: The Versions button, the History action and the Versions group of the More actions menu The versioning entry points on the Engine state page. ``` [1]{.callout} **Versions** : Opens {doc}`versioning`. [2]{.callout} **History** : Opens **History · *template***: what changed in the template's OPT, context and models, by whom. See {doc}`/ship/history`. [3]{.callout} **Release…** : Tags a release of the template. See {doc}`/ship/release`. [4]{.callout} **Restore from revision…** : Brings the template back as it was in a release, commit or branch. See {doc}`/ship/history`. (engine-state-mapping)= ## A model mapper opened Click a model mapper to see its mappings. Click a mapping row to open it in the detail panel on the right. ```{figure} ../../images/screens/engine-state-mapping.png :class: screenshot :alt: The OBSERVATION.blood_pressure.v2 model with the systolic mapping open in the detail panel The `systolic` mapping of the blood pressure model. ``` [1]{.callout} **Engine State** (breadcrumb) : Back to the template (or to the overview, when you opened the model from the overview). [2]{.callout} Current model : The model you are looking at. When you follow a slot into another model, the breadcrumb grows by one level per model; click an earlier name to go back to it. [3]{.callout} Model summary : **Name** (the model name and its archetype), **FHIR** (its structure definition) and **Condition** (the model's own FHIR conditions, when it has any). [4]{.callout} **Edit in workspace** : Opens the template in the Workspace with this model open. Shown when you came through a template. [5]{.callout} Raw editing : Opens **Raw editing — *model***: the whole model as YAML, saved in one go. [6]{.callout} Mapping row : The mapping's name and type, its FHIR path and its openEHR path. Child mappings are indented under their parent with **↳**. The selected row is shaded. [7]{.callout} Model name : The model the detail panel edits. [8]{.callout} **Save** : Writes the whole model to the engine. It is enabled once you have changed something; then **Unsaved changes** and a **Discard** button appear next to it. If the save fails, the reason shows in red in the same place. [9]{.callout} Mapping inspector : The same editor as the Workspace's editing sheet: **Maps**, **Only when**, **Values**, **Continues into**, **Advanced** and the resolved paths, with path suggestions and live checks. Every part is explained in {ref}`the Workspace's editing sheet `. Its status chip opens a **Problems** list at the top of the panel. Your edits are kept per model while you click through rows and models, until you save or discard them. Leaving the page with unsaved edits asks **Leave without saving?**: "You have unsaved mapping changes to *models*. If you leave now they will be lost. Leave anyway?" (**Leave** / **Stay**). The detail panel can also say: - "“*name*” comes from the core model ***core***; this extension doesn't override it." with an **Open *core*** button. - "“*name*” isn't in this model's YAML." (or "isn't in the edited YAML (renamed or deleted in unsaved changes?)"). - "Couldn't parse the model's YAML — use raw editing to fix it." followed by the parser's message. A mapping that hands over to another model through a slot shows that model's name as a link in its row. Click it to open that model: ```{figure} ../../images/screens/engine-state-slot.png :class: screenshot :alt: The sectionActiveProblems row with its slot link SECTION.adhoc.v1_problem_list [1]{.callout} The slot link of `sectionActiveProblems`. ``` See {doc}`/map/connect-models` for slots, and {doc}`/map/edit-in-workspace` for editing mappings. (engine-state-upload)= ## Upload panel ```{figure} ../../images/screens/engine-state-upload.png :class: screenshot :alt: The Upload mappings panel with its drop zone **Upload mappings**, opened with **Upload**. ``` Drop files on the panel or click **browse**. It accepts a ZIP archive and `.opt`, `.yaml`, `.yml`, `.json` and `.tgz` files: OPTs go to the engine's template store, FHIR Connect files are recognised as a model or context, a `.json` ConceptMap goes to the terminology store and a `.tgz` IG package to the FHIR packages. On engines that can import atomically, Atlas shows a **Preview** first, with **Merge** or **Mirror** and **Apply**. The results read "*N* uploaded · *N* skipped · *N* failed". The whole flow, with the traps of **Mirror**, is in {doc}`/map/bring-material-in`. ## Related - {doc}`/map/bring-material-in` - {doc}`/map/start-mapping` - {doc}`/ship/export` - {doc}`workspace` - {doc}`/reference/deep-links`