Merge pull request #245703 from baanders/7-20-adtex-v3

v-shils · web-flow · commit 9b0fbe24215f · 2023-07-21T12:13:53.000-07:00
ADT: Update ADT Ex DTDL version guidance
diff --git a/articles/digital-twins/concepts-azure-digital-twins-explorer.md b/articles/digital-twins/concepts-azure-digital-twins-explorer.md
@@ -37,8 +37,6 @@ Developers may find this tool especially useful in the following scenarios:
 
 The explorer's main purpose is to help you visualize and understand your graph, and update your graph as needed. For large-scale solutions and for work that should be repeated or automated, consider using the [APIs and SDKs](./concepts-apis-sdks.md) to interact with your instance through code instead.
 
-[!INCLUDE [digital-twins-explorer-dtdl](../../includes/digital-twins-explorer-dtdl.md)]
-
 ## How to access
 
 The main way to access Azure Digital Twins Explorer is through the [Azure portal](https://portal.azure.com).
@@ -51,8 +49,6 @@ To open Azure Digital Twins Explorer for an Azure Digital Twins instance, first
 
 Azure Digital Twins Explorer is organized into panels, each with a different set of capabilities for exploring and managing your models, twins, and relationships.
 
-[!INCLUDE [digital-twins-explorer-dtdl](../../includes/digital-twins-explorer-dtdl.md)]
-
 The sections of the explorer are as follows:
 * **Query Explorer**: Run queries against the twin graph and see the visual results in the **Twin Graph** panel.
 * **Models**: View a list of your models and perform model actions such as add, remove, and view model details.
@@ -64,6 +60,8 @@ The sections of the explorer are as follows:
 
 For detailed instructions on how to use each feature, see [Use Azure Digital Twins Explorer](how-to-use-azure-digital-twins-explorer.md). 
 
+[!INCLUDE [digital-twins-explorer-dtdl](../../includes/digital-twins-explorer-dtdl.md)]
+
 ## How to contribute
 
 Azure Digital Twins Explorer is an open-source tool that welcomes contributions to the code and documentation. The hosted application is deployed regularly from a source code repository in GitHub.
diff --git a/articles/digital-twins/how-to-use-azure-digital-twins-explorer.md b/articles/digital-twins/how-to-use-azure-digital-twins-explorer.md
@@ -98,8 +98,6 @@ 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)
 
-[!INCLUDE [digital-twins-explorer-dtdl](../../includes/digital-twins-explorer-dtdl.md)]
-
 ### 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.
@@ -271,8 +269,6 @@ This section describes how to perform the following management activities:
 
 For information about the viewing experience for twins and relationships, see [Explore twins and the Twin Graph](#explore-the-twin-graph).
 
-[!INCLUDE [digital-twins-explorer-dtdl](../../includes/digital-twins-explorer-dtdl.md)]
-
 ### View flat list of twins and relationships
 
 The **Twins** panel shows a flat list of your twins and their associated relationships. You can search for twins by name, and expand them for details about their incoming and outgoing relationships.
@@ -283,8 +279,6 @@ The **Twins** panel shows a flat list of your twins and their associated relatio
 
 You can create a new digital twin from its model definition in the **Models** panel.
 
-[!INCLUDE [digital-twins-explorer-dtdl](../../includes/digital-twins-explorer-dtdl.md)]
-
 To create a twin from a model, find that model in the list and choose the menu dots next to the model name. Then, select **Create a Twin**. You'll be asked to enter a **name** for the new twin, which must be unique. Then save the twin, which will add it to your graph.
 
 :::image type="content" source="media/how-to-use-azure-digital-twins-explorer/models-panel-create-a-twin.png" alt-text="Screenshot of Azure Digital Twins Explorer Models panel. The menu dots for a single model are highlighted, and the menu option to Create a Twin is also highlighted." lightbox="media/how-to-use-azure-digital-twins-explorer/models-panel-create-a-twin-large.png":::
@@ -328,8 +322,6 @@ You can also choose to delete all of the twins in your instance at the same time
 
 ## Explore models and the Model Graph
 
-[!INCLUDE [digital-twins-explorer-dtdl](../../includes/digital-twins-explorer-dtdl.md)]
-
 Models can be viewed both in the **Models** panel on the left side of the Azure Digital Twins Explorer screen, and in the **Model Graph** panel in the middle of the screen.
 
 The **Models** panel:
@@ -338,6 +330,8 @@ The **Models** panel:
 The **Model Graph** panel:
 :::image type="content" source="media/how-to-use-azure-digital-twins-explorer/model-graph-panel.png" alt-text="Screenshot of Azure Digital Twins Explorer. The Model Graph panel is highlighted." lightbox="media/how-to-use-azure-digital-twins-explorer/model-graph-panel.png":::
 
+[!INCLUDE [digital-twins-explorer-dtdl](../../includes/digital-twins-explorer-dtdl.md)]
+
 You can use these panels to [view your models](#view-models).
 
 The Model Graph panel also provides several abilities to customize your graph viewing experience:
@@ -351,6 +345,8 @@ You can view a flat list of the models in your instance in the **Models** panel.
 
 You can use the **Model Graph** panel to view a graphical representation of the models in your instance, along with the relationships, inheritance, and components that connect them to each other.
 
+[!INCLUDE [digital-twins-explorer-dtdl](../../includes/digital-twins-explorer-dtdl.md)]
+
 #### View model definition
 
 To see the full definition of a model, find that model in the **Models** pane and select the menu dots next to the model name. Then, select **View Model**. Doing so will display a **Model Information** modal showing the raw DTDL definition of the model.
@@ -411,8 +407,6 @@ Then, to upload the images at the same time, use the **Upload Model Images** ico
 
 ## Manage models
 
-[!INCLUDE [digital-twins-explorer-dtdl](../../includes/digital-twins-explorer-dtdl.md)]
-
 You can use the **Models** panel on the left side of the Azure Digital Twins Explorer screen to perform management activities on the entire set of models, or on individual models. 
 
 :::image type="content" source="media/how-to-use-azure-digital-twins-explorer/models-panel.png" alt-text="Screenshot of Azure Digital Twins Explorer. The Models panel is highlighted." lightbox="media/how-to-use-azure-digital-twins-explorer/models-panel.png":::
@@ -428,6 +422,8 @@ For information about the viewing experience for models, see [Explore models and
 
 You can upload models from your machine by selecting model files individually, or by uploading an entire folder of model files at once. If you're uploading one JSON file that contains the code for many models, be sure to review the [bulk model upload limitations](#limitations-of-bulk-model-upload).
 
+[!INCLUDE [digital-twins-explorer-dtdl](../../includes/digital-twins-explorer-dtdl.md)]
+
 To upload one or more models that are individually selected, select the **Upload a model** icon showing an upwards arrow.
 
 :::image type="content" source="media/how-to-use-azure-digital-twins-explorer/models-panel-upload.png" alt-text="Screenshot of Azure Digital Twins Explorer Models panel. The Upload a model icon is highlighted.":::
diff --git a/includes/digital-twins-explorer-dtdl.md b/includes/digital-twins-explorer-dtdl.md
@@ -3,9 +3,9 @@ author: baanders
 description: include file noting DTDL version requirements for Azure Digital Twins Explorer
 ms.service: digital-twins
 ms.topic: include
-ms.date: 06/29/2023
+ms.date: 07/20/2023
 ms.author: baanders
 ---
 
 >[!NOTE]
->Currently, Azure Digital Twins Explorer only works with twins and models that are compatible with [version 2 of DTDL](../articles/digital-twins/concepts-models.md#supported-dtdl-versions).
+>Currently, Azure Digital Twins Explorer fully supports DTDL v2 models and supports limited functionality for DTDL v3 models, including viewing DTDL v3 models in the Models panel and viewing/editing twins created with DTDL v3 models (including those with array properties). However, DTDL v3 models won't show up in the Model Graph panel, and they can't be imported using Azure Digital Twins Explorer. To import DTDL v3 models to your instance, use another developer interface like the [APIs and SDKs](../articles/digital-twins/concepts-apis-sdks.md) or the [Azure CLI](../articles/digital-twins/concepts-cli.md).
