# Understand a conversion (Insights) ## What you'll do You look up a conversion the engine made for one of your systems, read what came in and what went out, and see mapping by mapping which values were taken from where and where they were written. That is how you answer "why is this field empty?" for a real message. ```{figure} ../images/operate/insight-detail.png :class: screenshot :alt: The detail of a conversion — direction FHIR to openEHR, template Blood Pressure, status OK, the request (a FHIR Bundle) and the response (a flat openEHR composition) A blood pressure Observation converted to openEHR: the request and the response side by side. ``` ## Before you start - The engine records insights only when it is set up to: `openfhir.insights.enabled` turns the recording on, `openfhir.insights.store-payload` also keeps the request and the response. See {external+openfhir:doc}`insights`. - Insights cover every conversion the engine makes: REST calls from your systems and messages from a queue (see {external+openfhir:doc}`messaging`). :::{warning} With `store-payload` on, the engine keeps the request and the response as they are, which means clinical data. The engine documentation advises against it in production. ::: ## Steps ### Find the conversion 1. In the sidebar, under *Track*, click **Insights**. 2. The list shows the newest conversions first, ten per page: ```{figure} ../images/operate/insights-list.png :class: screenshot :alt: The Insights list with ten conversions of the demo templates, one of them with status ERROR The Insights list. ``` | | Column | | |---|---|---| | [1]{.callout} | **Insight ID** | The engine's id of this record. | | [2]{.callout} | **Request ID / Date** | The id of the request the engine recorded, and when it converted it. For queue messages it is the `openfhir-request-id` header, or the subscription, topic, partition and offset. | | [3]{.callout} | **Template** | *Template:* the template the conversion used, *Context name:* its context mapper. | | [4]{.callout} | **Direction** | **FHIR › openEHR** (`$toopenehr`) or **openEHR › FHIR** (`$tofhir`). | | [5]{.callout} | **Status** | **OK**, or **ERROR** when the conversion failed. | | [6]{.callout} | Pages | **<**, the page numbers and **>** step through older conversions. | 3. Click a row to open it. The address of the page says which page and which conversion is open (`/insights?page=2&insightId=…`; pages count from 0). Send it to a colleague, or use the browser's back and forward buttons. See {doc}`/reference/deep-links`. ### Read the conversion The detail view shows: - **Mapping direction** [2]{.callout}, **Template id**, **Request id**, **Context name** and **Mapping date**; - **Mapping status** [3]{.callout}: **OK** or **ERROR**; for an error, **Message:** with the engine's reason; - the request [4]{.callout} and the response [5]{.callout}. Click **Load request** and **Load response** to fetch them; JSON is shown indented. *No request* or *No response* means the engine didn't keep it (payloads aren't stored, or a failed conversion has no response). To go back to the list, click the insight id in the breadcrumb at the top [1]{.callout}, or use the browser's back button. ### Read the applied mappings Below, **Applied mappings** lists every mapping of the template's models, model by model, children indented under their parent with **↳**. Each mapping row names the mapping and its **Model:**. Under a mapping that was applied, one row per value it carried: ```{figure} ../images/operate/insight-applied-mappings.png :class: screenshot :alt: The applied mappings table — greyed parent mappings, value rows under the systolic and diastolic value mappings, and a greyed clinicalInterpretation mapping The applied mappings of the blood pressure conversion. ``` | | | |---|---| | [1]{.callout} | The columns follow the direction. For FHIR › openEHR: **From FHIR path**, **Value (FHIR)**, **To openEHR path**, **Result value (openEHR)**; for openEHR › FHIR the other way round. | | [2]{.callout} | A greyed mapping: *Greyed out means a mapping was not applied.* No value was carried by this mapping itself. | | [3]{.callout} | A value the mapping carried. The FHIR path reads as the mapping's own path, then the full path in brackets (`value (Bundle.entry.resource.as(Reference).resolve().component.value)`). The value is the FHIR element as JSON; the openEHR side lists the flat paths written, and their values separated by commas. | | [4]{.callout} | `clinicalInterpretation` is greyed: the Observation had no `component.interpretation.text`, so nothing was written to *Clinical interpretation*. | Fixed values of a mapping (its `manual` entries) appear as rows without a "from" side: the full paths they write and the values. A failed conversion has no applied mappings: the table stays empty. ```{figure} ../images/operate/insight-error.png :class: screenshot :alt: A failed openEHR to FHIR conversion of the Growth chart template — status ERROR, the message "Could not consume Parts [...]", the request loaded and "No response" A blood pressure composition sent with the Growth chart template: the engine couldn't use its parts. ``` ### Find out why a field is empty 1. Find the conversion by its date, template and request id, and open it. 2. If the status is **ERROR**, read the **Message**: the conversion stopped, nothing was written. Typical causes are the wrong template for the input (as in the screenshot above) or an input that doesn't parse. 3. Load the request and check that the data is there at all, at the place your mapping expects it. 4. Find the mapping of the field in **Applied mappings**: - **Greyed**: the mapping didn't carry a value. Either the input had nothing at its path, or a condition of the mapping (or of its parent) didn't match. Compare the path and the condition with the request. - **Applied, but the result is wrong**: compare **From … path** and the value with what you expected; then check the target path and the result value. 5. Reproduce it in the Workspace: open the template, paste the request into the example pane of its side and watch the other side (see {doc}`/check/see-in-action`). Fix the mapping there and check again. ## Check it worked After your fix is saved, send the message again. The new conversion is at the top of the list, and the mapping that was greyed now carries a value. ## Tips :::{tip} The response pane holds exactly what the engine returned, so you can copy it as a test input for the opposite direction. ::: ## Watch out :::{warning} The **Applied mappings** table is built from the template's models as they are now, not as they were when the message was converted. If someone changed the mappings since, rows can be missing, extra, or named differently. Compare with the history of the model if in doubt (see {doc}`/ship/history`). ::: :::{warning} Values are matched to mappings by the mapping's name within its model. Two mappings with the same name in one model (like the two `value` mappings under `systolic` and `diastolic` above) both list the values of both. Read the paths to tell them apart. ::: ## If something goes wrong | What you see | What to do | |---|---| | The list is empty | The engine records no insights, or none were made yet. Ask whoever runs the engine whether `openfhir.insights.enabled` is set. | | *No request* / *No response* | Payloads aren't kept (`openfhir.insights.store-payload` is off), or the conversion failed before a response. | | **ERROR** with a **Message** | The conversion failed; the message is the engine's. See {external+openfhir:doc}`restful_apis` for the conversion endpoints and their errors. | ## Related - {doc}`connect-api`: let your system call the engine. - {doc}`/check/see-in-action`: reproduce a conversion in the Workspace. - {doc}`/reference/screens/insights`: the Insights page, control by control. - The engine's insights: {external+openfhir:doc}`insights`.