Tutorial: Receive device messages through Azure IoT Hub


Fast Healthcare Interoperability Resources (FHIR®) is an open healthcare specification.

The MedTech service can receive messages from devices you create and manage through an IoT hub in Azure IoT Hub. This tutorial uses an Azure Resource Manager template (ARM template) and a Deploy to Azure button to deploy a MedTech service. The template also deploys an IoT hub to create and manage devices, and message routes device messages to an event hub for the MedTech service to read and process. After device data processing, the FHIR resources are persisted into a FHIR service, which is also included in the template.

Diagram of the IoT device message flow through an IoT hub and event hub, and then into the MedTech service.


To learn how the MedTech service transforms and persists device data into the FHIR service as FHIR resources, see Overview of the MedTech service device data processing stages.

In this tutorial, learn how to:

  • Open an ARM template in the Azure portal.
  • Configure the template for your deployment.
  • Create a device.
  • Send a test message.
  • Review metrics for the test message.


To learn about ARM templates, see What are ARM templates?


To begin your deployment and complete the tutorial, you must have the following prerequisites:

  • An active Azure subscription account. If you don't have an Azure subscription, see the subscription decision guide.

  • Owner or Contributor and User Access Administrator role assignments in the Azure subscription. For more information, see What is Azure role-based access control (Azure RBAC)?

  • Microsoft.HealthcareApis, Microsoft.EventHub, and Microsoft.Devices resource providers registered with your Azure subscription. To learn more, see Azure resource providers and types.

  • Visual Studio Code installed locally.

  • Azure IoT Tools installed in Visual Studio Code. Azure IoT Tools is a collection of extensions that makes it easy to connect to IoT hubs, create devices, and send messages. In this tutorial, you use the Azure IoT Hub extension in Visual Studio Code to connect to your deployed IoT hub, create a device, and send a test message from the device to your IoT hub.

When you have these prerequisites, you're ready to configure the ARM template by using the Deploy to Azure button.

Review the ARM template

The ARM template used to deploy the resources in this tutorial is available at Azure Quickstart Templates by using the azuredeploy.json file on GitHub.

Use the Deploy to Azure button

To begin deployment in the Azure portal, select the Deploy to Azure button:

Deploy to Azure

Configure the deployment

  1. In the Azure portal, on the Basics tab of the Azure Quickstart Template, select or enter the following information for your deployment:

    • Subscription: The Azure subscription to use for the deployment.

    • Resource group: An existing resource group, or you can create a new resource group.

    • Region: The Azure region of the resource group that's used for the deployment. Region autofills by using the resource group region.

    • Basename: A value that's appended to the name of the Azure resources and services that are deployed. The examples in this tutorial use the basename azuredocsdemo. You can choose your own basename value.

    • Location: A supported Azure region for Azure Health Data Services (the value can be the same as or different from the region your resource group is in). For a list of Azure regions where Health Data Services is available, see Products available by regions.

    • Fhir Contributor Principal Id (optional): An Azure Active Directory (Azure AD) user object ID to provide FHIR service read/write permissions.

      You can use this account to give access to the FHIR service to view the FHIR Observations that are generated in this tutorial. We recommend that you use your own Azure AD user object ID so you can access the messages in the FHIR service. If you choose not to use the Fhir Contributor Principal Id option, clear the text box.

      To learn how to get an Azure AD user object ID, see Find the user object ID. The user object ID that's used in this tutorial is only an example. If you use this option, use your own user object ID or the object ID of another person who you want to be able to access the FHIR service.

    • Device mapping: Leave the default values for this tutorial.

    • Destination mapping: Leave the default values for this tutorial.

    Screenshot that shows deployment options for the MedTech service for Health Data Services in the Azure portal.

  2. To validate your configuration, select Review + create.

    Screenshot that shows the Review + create button selected in the Azure portal.

  3. In Review + create, check the template validation status. If validation is successful, the template displays Validation Passed. If validation fails, fix the issue that's indicated in the error message, and then select Review + create again.

    Screenshot that shows the Review + create pane displaying the Validation Passed message.

  4. After a successful validation, to begin the deployment, select Create.

    Screenshot that shows the highlighted Create button.

  5. In a few minutes, the Azure portal displays the message that your deployment is completed.

    Screenshot that shows a green checkmark and the message Your deployment is complete.


    If you're going to allow access from multiple services to the event hub, it's required that each service has its own event hub consumer group.

    Consumer groups enable multiple consuming applications to have a separate view of the event stream, and to read the stream independently at their own pace and with their own offsets. For more information, see Consumer groups.


    • Two MedTech services accessing the same event hub.

    • A MedTech service and a storage writer application accessing the same event hub.

Review deployed resources and access permissions

When the deployment completes, the following resources and access roles are created:

  • Event Hubs namespace and event hub. In this deployment, the event hub is named devicedata.

    • Event hub consumer group. In this deployment, the consumer group is named $Default.

    • Azure Event Hubs Data Sender role. In this deployment, the sender role is named devicedatasender and can be used to provide access to the event hub using a shared access signature (SAS). To learn more about authorizing access using a SAS, see Authorizing access to Event Hubs resources using Shared Access Signatures. The Azure Event Hubs Data Sender role isn't used in this tutorial.

  • IoT hub with message routing configured to route device messages to the event hub.

  • User-assigned managed identity, which provides send access from the IoT hub to the event hub. The managed identity has the Azure Event Hubs Data Sender role in the Access control section (IAM) of the event hub.

  • Health Data Services workspace.

  • Health Data Services FHIR service.

  • Health Data Services MedTech service with the system-assigned managed identity enabled and granted the following access roles:

  • Conforming and valid MedTech service device and FHIR destination mappings. Resolution type is set to Create.


In this tutorial, the ARM template configures the MedTech service to operate in Create mode. A Patient resource and a Device resource are created for each device that sends data to your FHIR service.

To learn about the MedTech service resolution types Create and Lookup, see Configure the Destination tab.

Create a device and send a test message

With your resources successfully deployed, you next connect to your IoT hub, create a device, and send a test message to the IoT hub. After you complete these steps, your MedTech service can:

  • Read the IoT hub-routed test message from the event hub.
  • Transform the test message into five FHIR Observations.
  • Persist the FHIR Observations into your FHIR service.

You complete the steps by using Visual Studio Code with the Azure IoT Hub extension:

  1. Open Visual Studio Code with Azure IoT Tools installed.

  2. In Explorer, under Azure IoT Hub, select and choose Select IoT Hub.

    Screenshot of Visual Studio Code with the Azure IoT Hub extension with the deployed IoT hub selected.

  3. Select the Azure subscription where your IoT hub was provisioned.

  4. Select your IoT hub. The name of your IoT hub is the basename you provided when you provisioned the resources prefixed with ih-. An example hub name is ih-azuredocsdemo.

  5. In Explorer, in Azure IoT Hub, select and choose Create Device. An example device name is iot-001.

    Screenshot that shows Visual Studio Code with the Azure IoT Hub extension with Create device selected.

  6. To send a test message from the device to your IoT hub, right-click the device and select Send D2C Message to IoT Hub.


    In this device-to-cloud (D2C) example, cloud is the IoT hub in the Azure IoT Hub that receives the device message. Azure IoT Hub supports two-way communications. To set up a cloud-to-device (C2D) scenario, select Send C2D Message to Device Cloud.

    Screenshot that shows Visual Studio Code with the Azure IoT Hub extension and the Send D2C Message to IoT Hub option selected.

  7. In Send D2C Messages, select or enter the following values:

    • Device(s) to send messages from: The name of the device you created.

    • Message(s) per device: 1.

    • Interval between two messages: 1 second(s).

    • Message: Plain Text.

    • Edit: Clear any existing text, and then copy/paste the following test message JSON.


      You can use the Copy option in in the right corner of the below test message, and then paste it within the Edit window.

          "PatientId": "patient1",
          "HeartRate": 78,
          "RespiratoryRate": 12,
          "HeartRateVariability": 30,
          "BodyTemperature": 98.6,
          "BloodPressure": {
             "Systolic": 120,
             "Diastolic": 80
  8. To begin the process of sending a test message to your IoT hub, select Send.

    Screenshot that shows Visual Studio Code with the Azure IoT Hub extension with the device message options selected.

    After you select Send, it might take up to five minutes for the FHIR resources to be available in the FHIR service.


    To avoid device spoofing in device-to-cloud (D2C) messages, Azure IoT Hub enriches all device messages with additional properties before routing them to the event hub. For example: SystemProperties: iothub-connection-device-id and Properties: iothub-creation-time-utc. For more information, see Anti-spoofing properties and How to use IotJsonPathContent templates with the MedTech service device mapping.

    You do not want to send this example device message to your IoT hub as the enrichments will be duplicated by the IoT hub and cause an error with your MedTech service. This is only an example of how your device messages are enriched by the IoT hub.


    Screenshot of an Azure IoT Hub enriched device message.

    patientIdExpression is only required for MedTech services in the Create mode, however, if Lookup is being used, a Device resource with a matching Device Identifier must exist in the FHIR service. This example assumes your MedTech service is in a Create mode. The Resolution type for this tutorial set to Create. For more information on the Destination properties: Create and Lookup, see Configure the Destination tab.

Review metrics from the test message

Now that you have successfully sent a test message to your IoT hub, you can now review your MedTech service metrics. Review metrics to verify that your MedTech service received, grouped, transformed, and persisted the test message into your FHIR service. To learn more, see How to use the MedTech service monitoring and health checks tabs.

For your MedTech service metrics, you can see that your MedTech service completed the following steps for the test message:

  • Number of Incoming Messages: Received the incoming test message from the event hub.
  • Number of Normalized Messages: Created five normalized messages.
  • Number of Measurements: Created five measurements.
  • Number of FHIR resources: Created five FHIR resources that are persisted into your FHIR service.

Screenshot that shows a MedTech service metrics tile and test data metrics.

Screenshot that shows a second MedTech service metrics tile and test data metrics.

View test data in the FHIR service

If you provided your own Azure AD user object ID as the optional value for Fhir Contributor Principal ID in the deployment template, you can query FHIR resources in your FHIR service.

To learn how to get an Azure AD access token and view FHIR resources in your FHIR service, see Access by using Postman.

Next steps

In this tutorial, you deployed an ARM template in the Azure portal, connected to your IoT hub, created a device, sent a test message, and reviewed your MedTech service metrics.

To learn about methods of deploying the MedTech service, see

For an overview of the MedTech service device data processing stages, see

For frequently asked questions (FAQs) about the MedTech service, see

FHIR® is a registered trademark of Health Level Seven International, registered in the U.S. Trademark Office and is used with their permission.