.. _tut_localterminology:

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

A more complex terminology mapping than described in :doc:`inlineterminology` can be provided with ConceptMaps.

openFHIR Engine has a full terminology service built-in. That terminlogy service provides a `$translate` operation as per the FHIR IG of the terminology service (https://build.fhir.org/terminology-service.html).

Add ConceptMap
--------------

.. http:post:: http://localhost:8080/terminology/fhir/ConceptMap

   .. sourcecode:: http

      POST http://localhost:8080/terminology/fhir/ConceptMap HTTP/1.1
      Content-Type: application/json
      Body:
        {
          "resourceType": "ConceptMap",
          "id": "e1a90f56-4773-44a6-8004-0ef178ce85a8",
          "url": "http://open-fhir.com/DemoConceptmap",
          "description": "A test mapping",
          "group": [
            {
              "source": "local",
              "target": "http://loinc.org",
              "element": [
                {
                  "code": "at0013",
                  "display": "Naked",
                  "target": [
                    {
                      "code": "9999-9",
                      "equivalence": "equivalent"
                    }
                  ]
                }
              ],
              "unmapped": {
                "mode": "fixed",
                "code": "hardcodedcode-inloinc"
              }
            },
            {
              "source": "http://loinc.org",
              "target": "local",
              "element": [
                {
                  "code": "9999-9",
                  "target": [
                    {
                      "code": "at0013",
                      "display": "Naked",
                      "equivalence": "equivalent"
                    }
                  ]
                }
              ],
              "unmapped": {
                "mode": "fixed",
                "code": "at0013"
              }
            }
          ]
        }

Reference ConceptMap in the model mapping
-----------------------------------------

ConceptMap created above needs to be referenced from a specific model mapper so the engine picks it up when doing a translation from openEHR<>FHIR.

To do this, we need to add terminology tag within a mapping as such:

::

    terminology:
        type: "local"                                          # local when using the embedded terminology service, could also be 'inline' and 'remote'
        conceptmap: "http://open-fhir.com/DemoConceptmap"      # concept map canonical URL as provided when creating it

Full payload when updating a 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: "local"
            conceptmap: "http://open-fhir.com/DemoConceptmap"

Testing the embedded terminology service
----------------------------------------

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": [
                     {
                         "system": "http://loinc.org",
                         "code": "9999-9"
                     }
                 ]
             }
         }
     ]

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"

You can also test what happens when providing a code that's not within the ConceptMap. A fallback would be used with the "unmapped" entry of the ConceptMap, as per the ConceptMap's purpose.