Overview of the MedTech service FHIR destination mapping

Article
11/06/2023

This article provides an overview of the MedTech service FHIR® destination mapping.

The MedTech service requires two types of JSON mappings that are added to your MedTech service through the Azure portal or Azure Resource Manager API. The device mapping is the first type and controls mapping values in the device data sent to the MedTech service to an internal, normalized data object. The device mapping contains expressions that the MedTech service uses to extract types, device identifiers, measurement date time, and measurement value(s). The FHIR destination mapping is the second type and controls how the normalized data is mapped to FHIR Observations.

Note

The device and FHIR destination mappings are re-evaluated each time a device message is processed. Any updates to either mapping will take effect immediately.

FHIR destination mapping basics

The FHIR destination mapping controls how the normalized data extracted from a device message is mapped into a FHIR Observation.

Should an observation be created for a point in time or over a period of an hour?
What codes should be added to the observation?
Should the value be represented as SampledData or a Quantity?

These data types are all options the FHIR destination mapping configuration controls.

Once device data is transformed into a normalized data model, the normalized data is collected for transformation to a FHIR Observation. If the Observation type is SampledData, the data is grouped according to device identifier, measurement type, and time period (time period can be either 1 hour or 24 hours). The output of this grouping is sent for conversion into a single FHIR Observation that represents the time period for that data type. For other Observation types (Quantity, CodeableConcept and String) data isn't grouped, but instead each measurement is transformed into a single Observation representing a point in time.

Tip

For more information about how the MedTech service processes device message data into FHIR Observations for persistence on the FHIR service, see Overview of the MedTech service device message processing stages.

This diagram provides an illustration of what happens during the transformation stage within the MedTech service.

Note

The FHIR Observation in this diagram is not the complete resource. See Example in this overview for the entire FHIR Observation.

CollectionFhir

CollectionFhir is the root template type used by the MedTech service FHIR destination mapping. CollectionFhir is a list of all templates that are used during the transformation stage. You can define one or more templates within CollectionFhir, with each normalized message evaluated against all templates.

CodeValueFhir

CodeValueFhir is currently the only template supported in the FHIR destination mapping. It allows you to define codes, the effective period, and the value of the observation. Multiple value types are supported: SampledData, CodeableConcept, Quantity, and String. Along with these configurable values, the identifier for the Observation resource and linking to the proper Device and Patient resources are handled automatically.

Important

The Resolution type specifies how the MedTech service associates device data with Device resources and Patient resources. The MedTech service reads Device and Patient resources from the FHIR service using device identifiers and patient identifiers. If an encounter identifier is specified and extracted from the device data payload, it's linked to the observation if an encounter exists on the FHIR service with that identifier. If the encounter identifier is successfully normalized, but no FHIR Encounter exists with that encounter identifier, a FhirResourceNotFound exception is thrown. For more information on configuring the MedTech service Resolution type, see Configure the Destination tab.

Element	Description	Required
typeName	The type of measurement this template should bind to. Note: There should be at least one device mapping template that has this same `typeName`. The `typeName` element is used to link a FHIR destination mapping template to one or more device mapping templates. Device mapping templates with the same `typeName` element generate normalized data that is evaluated with a FHIR destination mapping template that has the same `typeName`.	True
periodInterval	The period of time the observation created should represent. Supported values are 0 (an instance), 60 (an hour), 1440 (a day).	True when the Observation type is SampledData; Ignored for other Observation types.
category	Any number of CodeableConcepts to classify the type of observation created.	False
codes	One or more Codings to apply to the observation created.	True
codes[].code	The code for a Coding in the `codes` element.	True
codes[].system	The system for a Coding in the `codes` element.	False
codes[].display	The display for a Coding in the `codes` element.	False
value	The value to extract and represent in the observation. For more information on the elements that the `value` element contains, see Value types.	True when the `components` element isn't used (unless the Observation type is CodebleConcept, in which case this element isn't only 'not required' but also ignored).
components	One or more components to create on the observation.	True when the `value` element isn't used instead.
components[].codes	One or more Codings to apply to the component.	False
components[].value	The value to extract and represent in the component. For more information on the elements that the `components[].value` element contains, see Value types.	True when the `components` element is used (unless the Observation type is CodebleConcept, in which case this element isn't only 'not required' but also ignored).

Value types

All CodeValueFhir templates' value element contains these elements:

Element	Description	Required
valueType	Type of the value. This value would be "SampledData", "Quantity", "CodeableConcept", or "String" depending on the value type.	True
valueName	Name of the value.	True unless `valueType` is CodeableConcept.

These value types are supported in the MedTech service FHIR destination mapping:

SampledData

Represents the SampledData FHIR data type. Observation measurements are written to a value stream starting at a point in time and incrementing forward using the period defined. If no value is present, an E is written into the data stream. If the period is such that two or more values occupy the same position in the data stream, the latest value is used. The same logic is applied when an observation using the SampledData is updated. For a CodeValueFhir template with the SampledData value type, the template's value element contains the following elements:

Element	Description	Required
defaultPeriod	The default period in milliseconds to use.	True
unit	The unit to set on the origin of the SampledData.	True

Quantity

Represents the Quantity FHIR data type. This type creates a single, point in time, Observation. If a new value arrives that contains the same device identifier, measurement type, and timestamp, the previous Observation is updated to the new value. For a CodeValueFhir template with the Quantity value type, the template's value element contains the following elements:

Element	Description	Required
unit	Unit representation.	False
code	Coded form of the unit.	False
system	System that defines the coded unit form.	False

CodeableConcept

Represents the CodeableConcept FHIR data type. The value in the normalized data model isn't used, and instead when this type of data is received, an Observation is created with a specific code representing that an observation was recorded at a specific point in time. For a CodeValueFhir template with the CodeableConcept value type, the template's value element contains the following elements:

Element	Description	Required
text	Plain text representation.	False
codes	One or more Codings to apply to the observation created.	True
codes[].code	The code for a Coding in the `codes` element.	True
codes[].system	The system for a Coding in the `codes` element.	False
codes[].display	The display for a Coding in the `codes` element.	False

String

Represents the String FHIR data type. This type creates a single, point in time, Observation. If a new value arrives that contains the same device identifier, measurement type, and timestamp, the previous Observation is updated to the new value. No other elements are defined.

Example

Tip

You can use the MedTech service Mapping debugger for assistance creating, updating, and troubleshooting the MedTech service device and FHIR destination mappings. The Mapping debugger enables you to easily view and make inline adjustments in real-time, without ever having to leave the Azure portal. The Mapping debugger can also be used for uploading test device messages to see how they'll look after being processed into normalized messages and transformed into FHIR Observations.

Note

This example and normalized message is a continuation from Overview of the MedTech service device mapping.

In this example, we're using a normalized message capturing heartRate data:

[
  {
    "type": "heartrate",
    "occurrenceTimeUtc": "2023-03-13T22:46:01.875Z",
    "deviceId": "device01",
    "properties": [
      {
        "name": "hr",
        "value": "78"
      }
    ]
  }
]

We're using this FHIR destination mapping for the transformation stage:

{
  "templateType": "CollectionFhir",
  "template": [
    {
      "templateType": "CodeValueFhir",
      "template": {
        "codes": [
          {
            "code": "8867-4",
            "system": "http://loinc.org",
            "display": "Heart rate"
          }
        ],
        "typeName": "heartrate",
        "value": {
          "system": "http://unitsofmeasure.org",
          "code": "count/min",
          "unit": "count/min",
          "valueName": "hr",
          "valueType": "Quantity"
        }
      }
    }
  ]
}

The resulting FHIR Observation will look like this after the transformation stage:

[
  {
    "code": {
      "coding": [
        {
          "system": {
            "value": "http://loinc.org"
          },
          "code": {
            "value": "8867-4"
          },
          "display": {
            "value": "Heart rate"
          }
        }
      ],
      "text": {
        "value": "heartrate"
      }
    },
    "effective": {
      "start": {
        "value": "2023-03-13T22:46:01.8750000Z"
      },
      "end": {
        "value": "2023-03-13T22:46:01.8750000Z"
      }
    },
    "issued": {
      "value": "2023-04-05T21:02:59.1650841+00:00"
    },
    "value": {
      "value": {
        "value": 78
      },
      "unit": {
        "value": "count/min"
      },
      "system": {
        "value": "http://unitsofmeasure.org"
      },
      "code": {
        "value": "count/min"
      }
    }
  }
]

Tip

For assistance fixing common MedTech service deployment errors, see Troubleshoot MedTech service deployment errors.

For assistance fixing MedTech service errors, see Troubleshoot errors using the MedTech service logs.