add location tag to device twin in message enrichments tutorial

Author: JimacoMS4

articles/iot-hub/iot-hub-message-enrichments-overview.md

@@ -6,7 +6,7 @@ author: kgremban
 ms.service: iot-hub
 services: iot-hub
 ms.topic: conceptual
-ms.date: 05/10/2019
+ms.date: 03/16/2022
 ms.author: kgremban
 #Customer intent: As a developer, I want to be able to add information to messages sent from a device to my IoT Hub, based on the destination endpoint.   
 ---
@@ -69,13 +69,15 @@ To try out message enrichments, see the [message enrichments tutorial](tutorial-
 
 * You can add up to 10 enrichments per IoT Hub for those hubs in the standard or basic tier. For IoT Hubs in the free tier, you can add up to 2 enrichments.
 
-* In some cases, if you are applying an enrichment with a value set to a tag or property in the device twin, the value will be stamped as a string value. For example, if an enrichment value is set to $twin.tags.field, the messages will be stamped with the string "$twin.tags.field" rather than the value of that field from the twin. This happens in the following cases:
+* In some cases, if you're applying an enrichment with a value set to a tag or property in the device twin, the value will be stamped with the specified device twin path. For example, if an enrichment value is set to $twin.tags.field, the messages will be stamped with the string "$twin.tags.field", rather than the value of that field from the twin. This happens in the following cases:
 
    * Your IoT Hub is in the basic tier. Basic tier IoT hubs do not support device twins.
 
    * Your IoT Hub is in the standard tier, but the device sending the message has no device twin.
 
-   * Your IoT Hub is in the standard tier, but the device twin path used for the value of the enrichment does not exist. For example, if the enrichment value is set to $twin.tags.location, and the device twin does not have a location property under tags, the message is stamped with the string "$twin.tags.location". 
+   * Your IoT Hub is in the standard tier, but the device twin path used for the value of the enrichment does not exist. For example, if the enrichment value is set to $twin.tags.location, and the device twin does not have a location property under tags, the message is stamped with the string "$twin.tags.location".
+
+   * Your IoT Hub is in the standard tier, but the device twin path used for the value of the enrichment resolves to an object, rather than a simple property. For example, if the enrichment value is set to $twin.tags.location, and the location property under tags is an object that contains child properties like `{"building": 43, "room": 503}`, the message is stamped with the string "$twin.tags.location".
 
 * Updates to a device twin can take up to five minutes to be reflected in the corresponding enrichment value.
 

articles/iot-hub/media/tutorial-message-enrichments/add-location-tag-to-device-twin.png

@@ -5,7 +5,7 @@ author: kgremban
 ms.service: iot-hub
 services: iot-hub
 ms.topic: tutorial
-ms.date: 12/20/2019
+ms.date: 03/16/2022
 ms.author: kgremban
 ms.custom: "mqtt, devx-track-azurecli, devx-track-csharp"
 # Customer intent: As a customer using Azure IoT Hub, I want to add information to the messages that come through my IoT hub and are sent to another endpoint. For example, I'd like to pass the IoT hub name to the application that reads the messages from the final endpoint, such as Azure Storage.
@@ -260,18 +260,14 @@ At this point, the resources are all set up and the message routing is configure
    | DeviceLocation | $twin.tags.location (assumes that the device twin has a location tag) | AzureStorageContainers > ContosoStorageEndpointEnriched |
    |customerID | 6ce345b8-1e4a-411e-9398-d34587459a3a | AzureStorageContainers > ContosoStorageEndpointEnriched |
 
-   > [!NOTE]
-   > If your device doesn't have a twin, the value you put in here will be stamped as a string for the value in the message enrichments. To see the device twin information, go to your hub in the portal and select **IoT devices**. Select your device, and then select **Device twin** at the top of the page.
-   >
-   > You can edit the twin information to add tags, such as location, and set it to a specific value. For more information, see [Understand and use device twins in IoT Hub](iot-hub-devguide-device-twins.md).
-
 3. When you're finished, your pane should look similar to this image:
 
    ![Table with all enrichments added](./media/tutorial-message-enrichments/all-message-enrichments.png)
 
 4. Select **Apply** to save the changes. Skip to the [Test message enrichments](#test-message-enrichments) section.
 
 ## Create and configure by using a Resource Manager template
+
 You can use a Resource Manager template to create and configure the resources, message routing, and message enrichments.
 
 1. Sign in to the Azure portal. Select **+ Create a Resource** to bring up a search box. Enter *template deployment*, and search for it. In the results pane, select **Template deployment (deploy using custom template)**.
@@ -319,6 +315,25 @@ You can use a Resource Manager template to create and configure the resources, m
 
 1. Wait for the template to be fully deployed. Select the bell icon at the top of the screen to check on the progress. When it's finished, continue to the [Test message enrichments](#test-message-enrichments) section.
 
+## Add location tag to the device twin
+
+One of the message enrichments configured on your IoT hub specifies a key of DeviceLocation with its value determined by the following device twin path: `$twin.tags.location`. If your device twin doesn't have a location tag, the twin path,`$twin.tags.location`, will be stamped as a string for the DeviceLocation value in the message enrichments.
+
+Follow these steps to add a location tag to your device's twin with the portal.
+
+1. Go to your IoT hub by selecting **Resource groups**. Then select the resource group set up for this tutorial (**ContosoResourcesMsgEn**). Find the IoT hub in the list, and select it. Select **Devices** on the left-pane of your IoT hub, then select your device (**Contoso-Test-Device**).
+
+1. Select the **Device twin** tab at the top of the device page and add the following line just before the closing brace at the bottom of the device twin. Then select **Save**.
+
+  ```json
+  		, "tags": {"location": "Plant 43"}
+
+  ```
+  
+  :::image type="content" source="./media/tutorial-message-enrichments/add-location-tag-to-device-twin.png" alt-text="Screenshot of adding location tag to device twin in Azure portal":::
+
+To learn more about how device twin paths are handled with message enrichments, see [Message enrichments limitations](iot-hub-message-enrichments-overview.md#limitations). To learn more about device twins, see [Understand and use device twins in IoT Hub](iot-hub-devguide-device-twins.md).
+
 ## Test message enrichments
 
 To view the message enrichments, select **Resource groups**. Then select the resource group you're using for this tutorial. Select the IoT hub from the list of resources, and go to **Messaging**. The message routing configuration and the configured enrichments appear.