Merge pull request #228200 from baanders/2-22-adtex-data-validation

ADT: Add Explorer data history validation

Author: Court72

articles/digital-twins/how-to-create-data-history-connection.md

@@ -5,7 +5,7 @@ titleSuffix: Azure Digital Twins
 description: See how to set up a data history connection for historizing Azure Digital Twins updates into Azure Data Explorer.
 author: baanders
 ms.author: baanders # Microsoft employees only
-ms.date: 02/23/2023
+ms.date: 03/02/2023
 ms.topic: how-to
 ms.service: digital-twins
 ms.custom: event-tier1-build-2022
@@ -257,13 +257,25 @@ You'll see confirmation messages on the screen as models, twins, and relationshi
 
 When the simulation is ready, the **Start simulation** button will become enabled. Scroll down and select **Start simulation** to push simulated data to your Azure Digital Twins instance. To continuously update the twins in your Azure Digital Twins instance, keep this browser window in the foreground on your desktop and complete other browser actions in a separate window. This will continuously generate twin property updates events that will be historized to Azure Data Explorer.
 
-To verify that data is flowing through the data history pipeline, navigate to the [Azure portal](https://portal.azure.com) and open the Event Hubs namespace resource you created. You should see charts showing the flow of messages into and out of the namespace, indicating the flow of incoming messages from Azure Digital Twins and outgoing messages to Azure Data Explorer. The image below shows what these charts might look like after an hour of running the simulator (but you should start to see some data after only a few minutes).
+#### Verify data flow
+
+To verify that data is flowing through the data history pipeline, you can use the [data history validation in Azure Digital Twins Explorer](how-to-use-azure-digital-twins-explorer.md#validate-and-explore-historized-properties). 
+
+1. Navigate to the [Azure Digital Twins Explorer](https://explorer.digitaltwins.azure.net/) and ensure it's [connected to the right instance](how-to-use-azure-digital-twins-explorer.md#switch-contexts-within-the-app).
+
+1. Use the instructions in [Validate and explore historized properties](how-to-use-azure-digital-twins-explorer.md#validate-and-explore-historized-properties) to choose a historized twin property to visualize in the chart.
+
+If you see data being populated in the chart, this means that Azure Digital Twins update events are being successfully stored in Azure Data Explorer.
+
+:::image type="content" source="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-chart.png" alt-text="Screenshot of the Data history explorer showing a chart of historized values for a property." lightbox="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-chart.png":::
+
+If you *don't* see data in the chart, the historization data flow isn't working properly. You can investigate the issue by viewing your Event Hubs namespace in the [Azure portal](https://portal.azure.com), which displays charts showing the flow of messages into and out of the namespace. This will allow you to verify both the flow of incoming messages from Azure Digital Twins and the outgoing messages to Azure Data Explorer, to help you identify which part of the flow isn't working.
 
 :::image type="content"  source="media/how-to-create-data-history-connection/simulated-environment-portal.png" alt-text="Screenshot of the Azure portal showing an Event Hubs namespace for the simulated environment." lightbox="media/how-to-create-data-history-connection/simulated-environment-portal.png":::
 
 ### View the historized updates in Azure Data Explorer
 
-In this section, you'll view all three types of historized updates that were generated by the simulator and stored in Azure Data Explorer tables.
+Now that you've verified the data history flow is sending data to Azure Data Explorer, this section will show you how to view all three types of historized updates that were generated by the simulator and stored in Azure Data Explorer tables.
 
 Start in the [Azure portal](https://portal.azure.com) and navigate to the Azure Data Explorer cluster you created earlier. Choose the **Databases** pane from the left menu to open the database view. Find the database you created for this article and select the checkbox next to it, then select **Query**.
 

articles/digital-twins/how-to-use-3d-scenes-studio.md

@@ -5,7 +5,7 @@ titleSuffix: Azure Digital Twins
 description: Learn how to use all the features of 3D Scenes Studio (preview) for Azure Digital Twins.
 author: baanders
 ms.author: baanders # Microsoft employees only
-ms.date: 02/22/2023
+ms.date: 02/27/2023
 ms.topic: how-to
 ms.service: digital-twins
 ms.custom: event-tier1-build-2022
@@ -109,6 +109,14 @@ You can switch to **View** mode to enable filtering on specific elements and vis
 
 :::image type="content" source="media/how-to-use-3d-scenes-studio/scene-view.png" alt-text="Screenshot of 3D Scenes Studio, showing a scene in the viewer." lightbox="media/how-to-use-3d-scenes-studio/scene-view.png":::
 
+You can view **All properties** of an element from here, as well as their values over time if [data history](concepts-data-history.md) is enabled on your instance. To view property history, select the **Open data history explorer** icon.
+
+:::image type="content" source="media/how-to-use-3d-scenes-studio/scene-view-data-history.png" alt-text="Screenshot of 3D Scenes Studio, showing the icon to open the data history explorer." lightbox="media/how-to-use-3d-scenes-studio/scene-view-data-history.png":::
+
+This will open the **Data history explorer** for the property. For more information about using the data history explorer, see [Validate and explore historized properties](how-to-use-azure-digital-twins-explorer.md#validate-and-explore-historized-properties). 
+
+:::image type="content" source="media/how-to-use-3d-scenes-studio/data-history-explorer.png" alt-text="Screenshot of data history explorer for 3D Scenes Studio." lightbox="media/how-to-use-3d-scenes-studio/data-history-explorer.png":::
+
 ### Embed scenes in custom applications
 
 The viewer component can also be embedded into custom applications outside of 3D Scenes Studio, and can work in conjunction with 3rd party components.

articles/digital-twins/how-to-use-azure-digital-twins-explorer.md

@@ -5,7 +5,7 @@ titleSuffix: Azure Digital Twins
 description: Learn how to use all the features of Azure Digital Twins Explorer (preview)
 author: baanders
 ms.author: baanders # Microsoft employees only
-ms.date: 12/2/2022
+ms.date: 02/27/2023
 ms.topic: how-to
 ms.service: digital-twins
 ms.custom: event-tier1-build-2022
@@ -89,7 +89,7 @@ The **Twin Graph** panel allows you to explore the twins and relationships in yo
 
 :::image type="content" source="media/how-to-use-azure-digital-twins-explorer/twin-graph-panel.png" alt-text="Screenshot of Azure Digital Twins Explorer. The Twin Graph panel is highlighted." lightbox="media/how-to-use-azure-digital-twins-explorer/twin-graph-panel.png":::
 
-You can use this panel to [view your twins and relationships](#view-twins-and-relationships).
+You can use this panel to [explore twin data](#explore-twin-data).
 
 The Twin Graph panel also provides several abilities to customize your graph viewing experience:
 * [Change twin display property](#change-twin-display-property)
@@ -98,7 +98,7 @@ The Twin Graph panel also provides several abilities to customize your graph vie
 * [Show and hide twin graph elements](#show-and-hide-twin-graph-elements)
 * [Filter and highlight twin graph elements](#filter-and-highlight-twin-graph-elements)
 
-### View twins and relationships
+### Explore twin data
 
 Run a query using the [Query Explorer](#query-your-digital-twin-graph) to see the twins and relationships in the query result displayed in the **Twin Graph** panel.
 
@@ -143,6 +143,57 @@ Both of these error messages are shown in the screenshot below:
 
 :::image type="content" source="media/how-to-use-azure-digital-twins-explorer/properties-errors.png" alt-text="Screenshot of Azure Digital Twins Explorer Twin Properties panel, showing two error messages. One error indicates that models are missing, and the other indicates that properties are missing a model." lightbox="media/how-to-use-azure-digital-twins-explorer/properties-errors-large.png":::
 
+#### Validate and explore historized properties
+
+If your Azure Digital Twins instance has [data history](concepts-data-history.md) enabled, you can validate and explore its historized data in Azure Digital Twins Explorer. Follow the steps below to visualize historized data in a chart, or view raw values in a table.
+
+1. From the **Twin Graph** viewer, select a twin whose historized properties you want to view to open it in the **Twin Properties** panel. In the top right corner of the panel, select the **Time series** icon to open the **Data history explorer**. 
+
+    :::image type="content" source="media/how-to-use-azure-digital-twins-explorer/open-data-history.png" alt-text="Screenshot of Azure Digital Twins Explorer Twin Properties panel, highlighting the icon to open the data history explorer." lightbox="media/how-to-use-azure-digital-twins-explorer/open-data-history.png":::
+
+1. Select the twin name from the left to bring up the options for choosing which historical properties of the twin to view. The **Twin ID** field will be pre-populated with the twin selection. Next to this field, you can select the **Inspect properties** icon to view the twin data, or the **Advanced twin search** icon to find other twins by querying property values.
+
+    :::image type="content" source="media/how-to-use-azure-digital-twins-explorer/data-history-explorer.png" alt-text="Screenshot of the Data history explorer and a modal asking for twin and property details." lightbox="media/how-to-use-azure-digital-twins-explorer/data-history-explorer.png":::    
+
+1. In the **Property** field, select the property whose historized data you'd like to view. If the property is not numeric, but it consists of numeric values, use the **Cast property value to number** option to attempt to cast this data to numbers so it can be visualized on the chart.
+
+    :::image type="content" source="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-property.png" alt-text="Screenshot of the Data history explorer with the property details highlighted." lightbox="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-property.png":::
+
+1. Choose a **Label** for the time series and select **Update**.  
+
+This will load the chart view of the historized values for the chosen property. You can use the tabs above the chart to toggle between the [chart view](#view-history-in-chart) and [table view](#view-history-in-table).
+
+To add more properties to the visualization, use the **Add time series** button on the left.
+
+:::image type="content" source="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-add-time-series.png" alt-text="Screenshot of the Data history explorer highlighting the option to add another time series." lightbox="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-add-time-series.png":::
+
+To exit the data history explorer and return to the main Azure Digital Twins Explorer, select **Close**.
+
+##### View history in chart
+
+The **Chart** view of historized properties shows property values as points on a line graph over time.
+
+:::image type="content" source="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-chart.png" alt-text="Screenshot of the Data history explorer showing a chart of historized values for a property." lightbox="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-chart.png":::
+
+You can use the icons above the chart to control the chart settings, including...
+* changing the time range for the data that's included in the chart.
+* selecting whether multiple time series are shown independently or on a shared y-axis. Selecting **Independent** for the axes means that each time series will scale to the chart and maintain their own axis for scale. Selecting **Shared** axes means that all time series data will be scaled to the same axis. 
+* choosing the aggregation logic for the chart. When the property has more data points than can be shown on the chart, the data will be aggregated into a finite amount of data points using either average, minimum or maximum functions.
+
+There's also a button to **Open query in Azure Data Explorer**, where you can view and modify the current query to further explore the time series data.
+
+:::image type="content" source="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-azure-data-explorer.png" alt-text="Screenshot of the button to open query in Azure Data Explorer." lightbox="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-azure-data-explorer.png":::  
+
+##### View history in table
+
+The **Table** view of historized properties shows property values and their timestamps in a table.
+
+:::image type="content" source="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-table.png" alt-text="Screenshot of the Data history explorer showing a table of historized values for a property." lightbox="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-table.png":::
+
+You can use the icons above the table to control the table settings, including...
+* changing the time range for the data that's included in the table.
+* downloading the table data for independent analysis.
+
 #### View a twin's relationships
 
 You can also quickly view the code of all relationships that involve a certain twin (including incoming and outgoing relationships).