Merge pull request #212580 from msjasteppe/iot-hub-updates

jborsecnik · web-flow · commit 8975a792c86c · 2022-09-29T15:14:30.000-07:00
Updating to address customer feedback.
diff --git a/articles/healthcare-apis/iot/device-data-through-iot-hub.md b/articles/healthcare-apis/iot/device-data-through-iot-hub.md
@@ -6,7 +6,7 @@ author: msjasteppe
 ms.service: healthcare-apis
 ms.subservice: iomt
 ms.topic: tutorial 
-ms.date: 03/25/2022
+ms.date: 09/29/2022
 ms.author: jasteppe
 ---
 
@@ -39,17 +39,24 @@ For more information on Azure role-based access control, see [Azure role-based a
 
 ## Connect IoT Hub with the MedTech service
 
-Azure IoT Hub supports a feature called [message routing](../../iot-hub/iot-hub-devguide-messages-d2c.md). Message routing provides the capability to send device data to various Azure services (for example: event hub, Storage Accounts, and Service Buses). MedTech service uses this feature to allow an IoT Hub to connect and send device messages to the MedTech service device message event hub endpoint.
+Azure IoT Hub supports a feature called [message routing](/azure/iot-hub/iot-hub-devguide-messages-d2c.md). Message routing provides the capability to send device data to various Azure services (for example: event hub, Storage Accounts, and Service Buses). MedTech service uses this feature to allow an IoT Hub to connect and send device messages to the MedTech service device message event hub endpoint.
 
-Follow these directions to grant access to the IoT Hub user-assigned managed identity to your MedTech service device message event hub and set up message routing: [Configure message routing with managed identities](../../iot-hub/iot-hub-managed-identity.md#egress-connectivity-from-iot-hub-to-other-azure-resources). 
+Follow these directions to grant access to the IoT Hub system-assigned managed identity to your MedTech service device message event hub and set up message routing: [Configure message routing with managed identities](/azure-pipelines.yml/iot-hub/iot-hub-managed-identitymd#egress-connectivity-from-iot-hub-to-other-azure-resources)
 
 ## Send device message to IoT Hub
 
 Use your device (real or simulated) to send the sample heart rate message shown below to the IoT Hub. 
 
 This message will get routed to MedTech service, where the message will be transformed into a FHIR Observation resource and stored into FHIR service.
 
+> [!IMPORTANT]
+> To avoid device spoofing in device-to-cloud messages, Azure IoT Hub enriches all messages with additional properties. To learn more about these properties, see [Anti-spoofing properties](/azure/iot-hub/iot-hub-devguide-messages-construct#anti-spoofing-properties)
+
+> [!TIP]
+> To learn about IoT Hub device message enrichment and IotJsonPathContentTemplate mappings usage with the MedTech service device mapping, see [How to use IotJsonPathContentTemplate mappings](how-to-use-iot-jsonpath-content-mappings.md) 
+
 ```json
+
 {
   "HeartRate": 80,
   "RespiratoryRate": 12,
@@ -61,7 +68,9 @@ This message will get routed to MedTech service, where the message will be trans
   },
   "Activity": "walking"
 }
+
 ```
+
 > [!IMPORTANT]
 > Make sure to send the device message that conforms to the [Device mappings](how-to-use-device-mappings.md) and [FHIR destinations mappings](how-to-use-fhir-mappings.md) configured with your MedTech service.
 
@@ -81,4 +90,4 @@ To learn about the different stages of data flow within MedTech service, see
 >[!div class="nextstepaction"]
 >[MedTech service data flow](iot-data-flow.md)
 
-(FHIR&#174;) is a registered trademark of HL7 and is used with the permission of HL7.
+FHIR&#174; is a registered trademark of Health Level Seven International, registered in the U.S. Trademark Office and is used with their permission.
diff --git a/articles/healthcare-apis/iot/how-to-use-iot-jsonpath-content-mappings.md b/articles/healthcare-apis/iot/how-to-use-iot-jsonpath-content-mappings.md
@@ -5,17 +5,14 @@ author: msjasteppe
 ms.service: healthcare-apis
 ms.subservice: fhir
 ms.topic: how-to
-ms.date: 09/06/2022
+ms.date: 09/26/2022
 ms.author: jasteppe
 ---
 
 # How to use IotJsonPathContentTemplate mappings
 
 This article describes how to use IoTJsonPathContentTemplate mappings with the MedTech service [device mapping](how-to-use-device-mappings.md).
 
-> [!TIP]
-> Check out the [IoMT Connector Data Mapper](https://github.com/microsoft/iomt-fhir/tree/master/tools/data-mapper) tool for editing, testing, and troubleshooting the MedTech service Device and FHIR destination mappings. Export mappings for uploading to the MedTech service in the Azure portal or use with the [open-source version](https://github.com/microsoft/iomt-fhir) of the MedTech service.
-
 ## IotJsonPathContentTemplate
 
 The IotJsonPathContentTemplate is similar to the JsonPathContentTemplate except the `DeviceIdExpression` and `TimestampExpression` aren't required.
@@ -25,7 +22,7 @@ The assumption, when using this template, is the messages being evaluated were s
 When you're using these SDKs, the device identity and the timestamp of the message are known.
 
 >[!IMPORTANT]
->Make sure that you're using a device identifier from Azure Iot Hub or Azure IoT Central that is registered as an identifier for a device resource on the destination FHIR service.
+>Make sure that you're using a device identifier from Azure Iot Hub or Azure IoT Central that is registered as an identifier for a device resource on the destination Fast Healthcare Interoperability Resource (FHIR&#174;) service.
 
 If you're using Azure IoT Hub Device SDKs, you can still use the JsonPathContentTemplate, assuming that you're using custom properties in the message body for the device identity or measurement timestamp.
 
@@ -34,9 +31,29 @@ If you're using Azure IoT Hub Device SDKs, you can still use the JsonPathContent
 
 ### Examples
 
+With each of these examples, you're provided with:
+ * A valid IoT device message.
+ * An example of what the IoT device message will look like after being received and processed by the IoT Hub.
+ * A valid MedTech service device mapping for normalizing the IoT device message after IoT Hub processing.
+ * An example of what the MedTech service device message will look like after normalization.
+
+> [!IMPORTANT]
+> To avoid device spoofing in device-to-cloud messages, Azure IoT Hub enriches all messages with additional properties. To learn more about these properties, see [Anti-spoofing properties](/azure/iot-hub/iot-hub-devguide-messages-construct#anti-spoofing-properties)
+
 **Heart rate**
 
-*Message*
+**A valid IoT device message.**
+
+```json
+
+{“heartrate” : “78”}
+
+```
+
+**An example of what the IoT device message will look like after being received and processed by the IoT Hub.**
+
+> [!NOTE]
+> The IoT Hub enriches the device message before sending it to the MedTech service device event hub with all properties starting with **iothub**. For example: **iothub-creation-time-utc**.
 
 ```json
 
@@ -49,12 +66,12 @@ If you're using Azure IoT Hub Device SDKs, you can still use the JsonPathContent
     },
     "SystemProperties": {
         "iothub-connection-device-id" : "device123"
-    }
-}
+   }
+}     
 
 ```
 
-*Template*
+**A valid MedTech service device mapping for normalizing the IoT device message after IoT Hub processing.**
 
 ```json
 
@@ -80,28 +97,60 @@ If you're using Azure IoT Hub Device SDKs, you can still use the JsonPathContent
 
 ```
 
+**An example of what the MedTech service device message will look like after the normalization process.**
+
+```json
+
+{
+   "type": "heartrate",
+   "occurrenceTimeUtc": "2021-02-01T22:46:01.875Z",
+   "deviceId": "device123",
+   "properties": [
+      {
+         "name": "hr",
+         "value": "78"
+      }
+   ]
+}
+
+```
+
 **Blood pressure**
 
-*Message*
+**A valid IoT device message.**
+
+```json
+
+{
+  "systolic": "123",
+  "diastolic": "87"
+}
+
+```
+
+**An example of what the IoT device message will look like after being received and processed by the IoT Hub.**
+
+> [!NOTE]
+> The IoT Hub enriches the device message before sending it to the MedTech service device event hub with all properties starting with **iothub**. For example: **iothub-creation-time-utc**.
 
 ```json
 
 {
    "Body": {
    "systolic": "123",
    "diastolic" : "87"
-      },
-      "Properties": {
-         "iothub-creation-time-utc" : "2021-02-01T22:46:01.8750000Z"
-      },
-      "SystemProperties": {
-         "iothub-connection-device-id" : "device123"
-    }
+    },
+     "Properties": {
+       "iothub-creation-time-utc" : "2021-02-01T22:46:01.8750000Z"
+    },
+     "SystemProperties": {
+        "iothub-connection-device-id" : "device123"
+   }
 }   
 
 ```
 
-*Template*
+**A valid MedTech service device mapping for normalizing the IoT device message after IoT Hub processing.**
 
 ```json
 
@@ -132,50 +181,74 @@ If you're using Azure IoT Hub Device SDKs, you can still use the JsonPathContent
 
 ```
 
+**An example of what the MedTech service device message will look like after the normalization process.**
+
+```json
+
+{
+   "type": "bloodpressure",
+   "occurrenceTimeUtc": "2021-02-01T22:46:01.875Z",
+   "deviceId": "device123",
+   "properties": [
+      {
+         "name": "systolic",
+         "value": "123"
+      },
+      {  
+         "name": "diastolic",
+         "value": "87"
+      }
+   ]
+}
+
+```
+
 > [!TIP]
-> The above IotJsonPathTemplate examples will work separately with your MedTech service device mapping or you can combine them into a single MedTech service device mapping as shown below. Additionally, the IotJasonPathTemplates can also be combined with with other template types such as [JasonPathContentTemplate mappings](how-to-use-jsonpath-content-mappings.md) to create and tune your MedTech service device mapping to meet your individual needs and scenarios. 
+> The IotJsonPathTemplate device mapping examples provided in this article may be combined into a single MedTech service device mapping as shown below.
+>
+> Additionally, the IotJasonPathTemplates can also be combined with with other template types such as [JasonPathContentTemplate mappings](how-to-use-jsonpath-content-mappings.md) to further expand your MedTech service device mapping. 
 
-*Template*
+**Combined heart rate and blood pressure MedTech service device mapping example.**
 
 ```json
 
 {
-    "templateType": "CollectionContent",
-    "template": [
-    {
-       "templateType": "IotJsonPathContentTemplate",
-       "template": {
-       "typeName": "heartrate",
-       "typeMatchExpression": "$..[?(@Body.heartRate)]",
-       "values": [
-           {
-             "required": "true",
-             "valueExpression": "$.Body.heartRate",
-             "valueName": "hr"
-           }
-         ]  
-      }
+   "templateType": "CollectionContent",
+   "template": [
+     {  
+        "templateType": "IotJsonPathContentTemplate",
+        "template": {
+        "typeName": "heartrate",
+        "typeMatchExpression": "$..[?(@Body.heartRate)]",
+        "values": [
+             {
+               "required": "true",
+               "valueExpression": "$.Body.heartRate",
+               "valueName": "hr"
+             }
+          ]  
+       }  
     },
     {
-       "templateType": "IotJsonPathContentTemplate",
-       "template": {
-       "typeName": "bloodpressure",
-       "typeMatchExpression": "$..[?(@Body.systolic && @Body.diastolic)]",
-       "values": [
-          {  
-            "required": "true",
-            "valueExpression": "$.Body.systolic",
-            "valueName": "systolic"
-          },
-          {
-            "required": "true",
-            "valueExpression": "$.Body.diastolic",
-            "valueName": "diastolic"
-          }
-        ]
-      }
-    }
-  ]
+        "templateType": "IotJsonPathContentTemplate",
+        "template": {
+        "typeName": "bloodpressure",
+        "typeMatchExpression": "$..[?(@Body.systolic && @Body.diastolic)]",
+        "values": [
+             {  
+               "required": "true",
+               "valueExpression": "$.Body.systolic",
+               "valueName": "systolic"
+             },
+             {
+               "required": "true",
+               "valueExpression": "$.Body.diastolic",
+               "valueName": "diastolic"
+             }
+         ]
+       }
+     }
+   ]
 }
 
 ```
