How to use the FHIR destination mappings

Important

Azure Healthcare APIs is currently in PREVIEW. The Supplemental Terms of Use for Microsoft Azure Previews include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

This article describes how to configure IoT connector using the Fast Healthcare Interoperability Resources (FHIR®) destination mappings.

Tip

Check out the IoMT Connector Data Mapper tool for editing, testing, and troubleshooting IoT connector Device and FHIR destination mappings. Export mappings for uploading to IoT connector in the Azure portal or use with the open-source version of IoT connector.

Below is a conceptual example of what happens during the normalization and transformation process within IoT connector:

IoT data normalization flow example1

FHIR destination mappings

Once the device content is extracted into a normalized model, the data is collected and grouped according to device identifier, measurement type, and time period. The output of this grouping is sent for conversion into a FHIR resource (Observation currently). The FHIR destination mapping template controls how the data 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 mappings configuration controls.

Note

Mappings are stored in an underlying blob storage and loaded from blob per compute execution. Once updated they should take effect immediately.

CodeValueFhirTemplate

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

Property Description
TypeName The type of measurement this template should bind to. There should be at least one Device mapping template that outputs this type.
PeriodInterval The period of time the observation created should represent. Supported values are 0 (an instance), 60 (an hour), 1440 (a day).
Category Any number of CodeableConcepts to classify the type of observation created.
Codes One or more Codings to apply to the observation created.
Codes[].Code The code for the Coding.
Codes[].System The system for the Coding.
Codes[].Display The display for the Coding.
Value The value to extract and represent in the observation. For more information, see Value Type Templates.
Components Optional: One or more components to create on the observation.
Components[].Codes One or more Codings to apply to the component.
Components[].Value The value to extract and represent in the component. For more information, see Value Type Templates.

Value type templates

Below are the currently supported value type templates:

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 will be written into the data stream. If the period is such that two 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.

Property Description
DefaultPeriod The default period in milliseconds to use.
Unit The unit to set on the origin of the SampledData.

Quantity

Represents the Quantity FHIR data type. If more than one value is present in the grouping, only the first value is used. When new value arrives that maps to the same observation it will overwrite the old value.

Property Description
Unit Unit representation.
Code Coded form of the unit.
System System that defines the coded unit form.

CodeableConcept

Represents the CodeableConcept FHIR data type. The actual value isn't used.

Property Description
Text Plain text representation.
Codes One or more Codings to apply to the observation created.
Codes[].Code The code for the Coding.
Codes[].System The system for the Coding.
Codes[].Display The display for the Coding.

Examples

Heart rate - SampledData

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

Steps - SampledData

{
    "templateType": "CodeValueFhir",
    "template": {
        "codes": [
            {
                "code": "55423-8",
                "system": "http://loinc.org",
                "display": "Number of steps"
            }
        ],        
        "periodInterval": 60,
        "typeName": "stepsCount",
        "value": {
            "defaultPeriod": 5000,
            "unit": "",
            "valueName": "steps",
            "valueType": "SampledData"
        }
    }
}

Blood pressure - SampledData

{
    "templateType": "CodeValueFhir",
    "template": {
        "codes": [
            {
                "code": "85354-9",
                "display": "Blood pressure panel with all children optional",
                "system": "http://loinc.org"
            }
        ],
        "periodInterval": 60,
        "typeName": "bloodpressure",
        "components": [
            {
                "codes": [
                    {
                        "code": "8867-4",
                        "display": "Diastolic blood pressure",
                        "system": "http://loinc.org"
                    }
                ],
                "value": {
                    "defaultPeriod": 5000,
                    "unit": "mmHg",
                    "valueName": "diastolic",
                    "valueType": "SampledData"
                }
            },
            {
                "codes": [
                    {
                        "code": "8480-6",
                        "display": "Systolic blood pressure",
                        "system": "http://loinc.org"
                    }
                ],
                "value": {
                    "defaultPeriod": 5000,
                    "unit": "mmHg",
                    "valueName": "systolic",
                    "valueType": "SampledData"
                }
            }
        ]
    }
}

Blood pressure - Quantity

{
    "templateType": "CodeValueFhir",
    "template": {
        "codes": [
            {
                "code": "85354-9",
                "display": "Blood pressure panel with all children optional",
                "system": "http://loinc.org"
            }
        ],
        "periodInterval": 0,
        "typeName": "bloodpressure",
        "components": [
            {
                "codes": [
                    {
                        "code": "8867-4",
                        "display": "Diastolic blood pressure",
                        "system": "http://loinc.org"
                    }
                ],
                "value": {
                    "unit": "mmHg",
                    "valueName": "diastolic",
                    "valueType": "Quantity"
                }
            },
            {
                "codes": [
                    {
                        "code": "8480-6",
                        "display": "Systolic blood pressure",
                        "system": "http://loinc.org"
                    }
                ],
                "value": {
                    "unit": "mmHg",
                    "valueName": "systolic",
                    "valueType": "Quantity"
                }
            }
        ]
    }
}

Device removed - CodeableConcept

{
    "templateType": "CodeValueFhir",
    "template": {
        "codes": [
            {
                "code": "deviceEvent",
                "system": "https://www.mydevice.com/v1",
                "display": "Device Event"
            }
        ],
        "periodInterval": 0,
        "typeName": "deviceRemoved",
        "value": {
            "text": "Device Removed",
            "codes": [
                {
                    "code": "deviceRemoved",
                    "system": "https://www.mydevice.com/v1",
                    "display": "Device Removed"
                }
            ],
            "valueName": "deviceRemoved",
            "valueType": "CodeableConcept"
        }
    }
}

Tip

See IoT connector troubleshooting guide for assistance fixing common errors and issues.

Next steps

In this article, you learned how to use FHIR destination mappings. To learn how to use Device mappings, see

(FHIR®) is a registered trademark of HL7 and is used with the permission of HL7.