.. _tut_inlineterminology:

Inline terminology
==================

.. note::
    A whole tutorial referenced here is available in the following Postman collection: https://documenter.getpostman.com/view/1515623/2sAYdimoej
.. note::
    If running against a public sandbox.open-fhir.com, don't forget to include Authorization header of type Basic.


An important aspect to successful mappings between FHIR and openEHR is a service able to translate codings, enums, terminologies from one to the other.

In this specific example, within openEHR template, ``growth_chart/body_weight/any_event:0/state_of_dress``` is coded in a ``local``` terminology with values ``at0013``` (Naked) and others. Something unknown to FHIR. An implementation
guide in FHIR may restrict you to snomed or loinc coding, which is why you need a mapping from one to the other.

A simple terminology mapping is to provide the mapping inline, within a specific model.yaml.

Adding mapping of this data point & inline terminology
------------------------------------------------------

Mapping of the ``state_of_dress`` data point wasn't included in the original mappings. Let's add it, following a similar approach as in the previous step when we added Observation.note.text.

Get an ID and trigger a PUT of the body weight mapper. You need to add the following mapping within mappings:

::

  - name: "state of dress"
    with:
      fhir: "$resource.component.value"
      openehr: "$archetype/data[at0002]/events[at0003]/state[at0008]/items[at0009]"
      type: "CODEABLECONCEPT"
    fhirCondition:
      targetRoot: "$resource.component"
      targetAttribute: "code.coding.code"
      operator: "one of"
      criteria: "[$loinc.9999-9]"
    terminology:
        type: "inline"
        mappings:
            - openehr:
                code: "at0013"
                system: "local"
              fhir:
                code: "fhirNakedIsh"

This will add value from ``growth_chart/body_weight/any_event/state_of_dress`` (``data[at0002]/events[at0026]/state[at0008]/items[at0009]``) to an ``Observation.component.value`` and code that component with component.coding.code=9999-9, and vice-versa.

Additionally, with the inline terminology, anything in openEHR coded as at0013 in system local will be mapped to fhirNakedIsh when creating a FHIR Resource.

In the other direction, something in FHIR Coded as fhirNakedIsh will result in openEHR code of at0013.

Full payload you need to use when updating this specific model mapper should look like:

.. http:put:: http://localhost:8080/fc/model/(id of the model mapper)

   .. sourcecode:: http

      PUT http://localhost:8080/fc/model/(id) HTTP/1.1
      Body: <yaml below>

::

    grammar: FHIRConnect/v0.0.1
    type: model
    metadata:
      name: "openEHR-EHR-OBSERVATION.body_weight.v2"
      version: 1.0.0
    spec:
      system: FHIR
      version: R4
      openEhrConfig:
        archetype: "openEHR-EHR-OBSERVATION.body_weight.v2"
      fhirConfig:
        structureDefinition: http://hl7.org/fhir/StructureDefinition/Observation
    preprocessor:
      fhirCondition:
        targetRoot: "$resource"
        targetAttribute: "category.coding.code"
        operator: "one of"
        criteria: "weight"


    mappings:
      - name: "weight"
        with:
          fhir: "$resource.value"
          openehr: "$archetype/data[at0002]/events[at0003]/data[at0001]/items[at0004]"
          type: "QUANTITY"
        fhirCondition:
          targetRoot: "$resource"
          targetAttribute: "code.coding.code"
          operator: "one of"
          criteria: "[$loinc.29463-7, $snomed.27113001]"

      - name: "time"
        with:
          fhir: "$resource.effective"
          openehr: "$archetype/data[at0002]/events[at0003]/time"
          type: "DATETIME"
      - name: "state of dress"
        with:
          fhir: "$resource.component.value"
          openehr: "$archetype/data[at0002]/events[at0003]/state[at0008]/items[at0009]"
          type: "CODEABLECONCEPT"
        fhirCondition:
          targetRoot: "$resource.component"
          targetAttribute: "code.coding.code"
          operator: "one of"
          criteria: "[$loinc.9999-9]"
        terminology:
            type: "inline"
            mappings:
                - openehr:
                    code: "at0013"
                    system: "local"
                  fhir:
                    code: "fhirNakedIsh"

Validating behavior of the inline terminology
---------------------------------------------

Use the same example of openEHR as in previous steps:

.. http:post:: http://localhost:8080/openfhir/tofhir?templateId=Growth chart

   .. sourcecode:: http

      POST http://localhost:8080/openfhir/tofhir?templateId=Growth%2Cchart HTTP/1.1
      Content-Type: application/json
      Body: <json below>

:download:`growth_chart_flat.json </tutorial/files/growth_chart_flat.json>`

Within the result, you should see a new FHIR element mapped from openEHR:

::

     "component": [
        {
            "code": {
                "coding": [
                    {
                        "code": "9999-9"
                    }
                ]
            },
            "valueCodeableConcept": {
                "coding": [
                    {
                        "code": "fhirNakedIsh"
                    }
                ]
            }
        }
    ]

Going in the other direction, you should see a properly openEHR coded at0013 in the resulting Composition.

::

    "growth_chart/body_weight/any_event:0/state_of_dress|code": "at0013",
    "growth_chart/body_weight/any_event:0/state_of_dress|terminology": "local",