Quickstart - Get started with a sample scenario in Azure Digital Twins Explorer

In this quickstart, you'll explore a prebuilt Azure Digital Twins graph using the Azure Digital Twins Explorer. This tool allows you to visualize and interact with your Azure Digital Twins data within the Azure portal.

With Azure Digital Twins, you can create and interact with live models of your real-world environments, which can be part of wider IoT solutions. First, you model individual elements as digital twins. Then you connect them into a knowledge graph that can respond to live events and be queried for information.

You'll complete the following steps:

1. Create an Azure Digital Twins instance, and connect to it in Azure Digital Twins Explorer.
2. Upload prebuilt models and graph data to construct the sample scenario.
3. Explore the scenario graph that's created.
4. Make changes to the graph.
5. Review your learnings from the experience.

The Azure Digital Twins example graph you'll be working with represents a building with two floors and two rooms. Floor0 contains Room0, and Floor1 contains Room1. The graph will look like this image:

Prerequisites

You'll need an Azure subscription to complete this quickstart. If you don't have one already, create one for free now.

You'll also need to download the materials for the sample graph used in the quickstart. Use the links and instructions below to download the three required files from the digital-twins-explorer GitHub repository. Later, you'll follow more instructions to upload them to Azure Digital Twins.

• Room.json: This is a model file representing a room in a building. Navigate to the link, right-click anywhere on the screen, and select Save as in your browser's right-click menu. Use the following Save As window to save the file somewhere on your machine with the name Room.json.

• Floor.json: This is a model file representing a floor in a building. Navigate to the link, right-click anywhere on the screen, and select Save as in your browser's right-click menu. Use the following Save As window to save the file to the same location as Room.json, under the name Floor.json.

• buildingScenario.xlsx: This file contains a graph of room and floor twins, and relationships between them. Navigate to the link and select the Download button. This will download the file to your default download location.

  

Set up Azure Digital Twins

The first step in working with Azure Digital Twins is to create an Azure Digital Twins instance. After you create an instance of the service, you can connect to the instance in Azure Digital Twins Explorer, which you'll use to work with the instance throughout the quickstart.

The rest of this section walks you through these steps.

Create an Azure Digital Twins instance

In this section, you'll create a new instance of Azure Digital Twins using the Azure portal. Navigate to the portal and log in with your credentials.

1. Once in the portal, start by selecting Create a resource in the Azure services home page menu.

   

2. Search for Azure Digital Twins in the search box, and choose the Azure Digital Twins service from the results. Select the Create button to create a new instance of the service.

   

3. Fill in the fields on the Basics tab of setup, including your Subscription, Resource group, Location, and a Resource name for your new instance. Check the Assign Azure Digital Twins Data Owner Role box to give yourself permissions to manage data in the instance.

   Note

   If the Assign Azure Digital Twins Data Owner Role box is greyed out, it means you don't have permissions in your Azure subscription to manage user access to resources. You can continue creating the instance in this section, and then should have someone with the necessary permissions assign you this role on the instance before completing the rest of this quickstart.

   Common roles that meet this requirement are Owner, Account admin, or the combination of User Access Administrator and Contributor.

4. Select Review + Create to finish creating your instance.

   

5. You will see a summary page showing the details you've entered. Confirm and create the instance by selecting Create.

This will take you to an Overview page tracking deployment status of the instance.

Open instance in Azure Digital Twins Explorer

When the instance is finished deploying, use the Go to resource button to navigate to the instance's Overview page in the portal.

Next, select the Open Azure Digital Twins Explorer (preview) button.

This will open an Azure Digital Twins Explorer window connected to your instance.

Upload the sample materials

Next, you'll import the sample models and graph into Azure Digital Twins Explorer. You'll use the model files and the graph file that you downloaded to your machine in the Prerequisites section.

Models

The first step in an Azure Digital Twins solution is to define the vocabulary for your environment. You'll create custom models that describe the types of entity that exist in your environment.

Each model is written in a language like JSON-LD called Digital Twin Definition Language (DTDL). Each model describes a single type of entity in terms of its properties, telemetry, relationships, and components. Later, you'll use these models as the basis for digital twins that represent specific instances of these types.

Typically, when you create a model, you'll complete three steps:

1. Write the model definition. In the quickstart, this step is already done as part of the sample solution.
2. Validate it to make sure the syntax is accurate. In the quickstart, this step is already done as part of the sample solution.
3. Upload it to your Azure Digital Twins instance.

For this quickstart, the model files are already written and validated for you. They're included with the solution you downloaded. In this section, you'll upload two prewritten models to your instance to define these components of a building environment:

• Floor
• Room

Upload the models (.json files)

Follow these steps to upload models (the .json files you downloaded earlier).

1. In the Models panel, select the Upload a Model icon that shows an arrow pointing into a cloud.

   

2. In the Open window that appears, navigate to the folder containing the Room.json and Floor.json files that you downloaded earlier.

3. Select Room.json and Floor.json, and select Open to upload them both.

Azure Digital Twins Explorer will upload these model files to your Azure Digital Twins instance. They should show up in the Models panel and display their friendly names and full model IDs. You can select the View Model information icons to see the DTDL code behind them.

Twins and the twin graph

Now that some models have been uploaded to your Azure Digital Twins instance, you can add digital twins that follow the model definitions.

Digital twins represent the actual entities within your business environment. They can be things like sensors on a farm, lights in a car, or—in this quickstart—rooms on a building floor. You can create many twins of any given model type, such as multiple rooms that all use the Room model. You connect them with relationships into a twin graph that represents the full environment.

In this section, you'll upload pre-created twins that are connected into a pre-created graph. The graph contains two floors and two rooms, connected in the following layout:

• Floor0
  • Contains Room0
• Floor1
  • Contains Room1

Import the graph (.xlsx file)

Follow these steps to import the graph (the .xlsx file you downloaded earlier).

1. In the Twin Graph panel, select the Import Graph icon that shows an arrow pointing into a cloud.

   

2. In the Open window, navigate to the buildingScenario.xlsx file you downloaded earlier. This file contains a description of the sample graph. Select Open.

   After a few seconds, Azure Digital Twins Explorer opens an Import view that shows a preview of the graph to be loaded.

3. To confirm the graph upload, select the Save icon in the upper-right corner of the graph preview panel.

   

4. Azure Digital Twins Explorer will use the uploaded file to create the requested twins and relationships between them. A dialog box appears when it's finished. Select Close.

   

5. The graph has now been uploaded to Azure Digital Twins Explorer. Switch back to the Twin Graph panel.

   

6. To see the graph, select the Run Query button in the Query Explorer panel, near the top of the Azure Digital Twins Explorer window.

   

This action runs the default query to select and display all digital twins. Azure Digital Twins Explorer retrieves all twins and relationships from the service. It draws the graph defined by them in the Twin Graph panel.

Explore the graph

Now you can see the uploaded graph of the sample scenario.

The circles (graph "nodes") represent digital twins. The lines represent relationships. The Floor0 twin contains Room0, and the Floor1 twin contains Room1.

If you're using a mouse, you can drag pieces of the graph to move them around.

View twin properties

You can select a twin to see a list of its properties and their values in the Properties panel.

Here are the properties of Room0:

Room0 has a temperature of 70.

Here are the properties of Room1:

Room1 has a temperature of 80.

Query the graph

A main feature of Azure Digital Twins is the ability to query your twin graph easily and efficiently to answer questions about your environment.

One way to query the twins in your graph is by their properties. Querying based on properties can help answer a variety of questions. For example, you can find outliers in your environment that might need attention.

In this section, you'll run a query to answer the question of how many twins in your environment have a temperature above 75.

To see the answer, run the following query in the Query Explorer panel.

SELECT * FROM DIGITALTWINS T WHERE T.Temperature > 75

Recall from viewing the twin properties earlier that Room0 has a temperature of 70, and Room1 has a temperature of 80. For this reason, only Room1 shows up in the results here.

Edit data in the graph

You can use Azure Digital Twins Explorer to edit the properties of the twins represented in your graph. In this section, we'll raise the temperature of Room0 to 76.

To start, rerun the following query to select all digital twins. This will display the full graph once more in the Twin Graph panel.

SELECT * FROM DIGITALTWINS

Select Room0 to bring up its property list in the Properties panel.

The properties in this list are editable. Select the temperature value of 70 to enable entering a new value. Enter 76, and select the Save icon to update the temperature to 76.

Now, you'll see a Patch Information window where the patch code appears that was used behind the scenes with the Azure Digital Twins APIs to make the update. Select Close.

Query to see the result

To verify that the graph successfully registered your update to the temperature for Room0, rerun the query from earlier to get all the twins in the environment with a temperature above 75.

SELECT * FROM DIGITALTWINS T WHERE T.Temperature > 75

Now that the temperature of Room0 has been changed from 70 to 76, both twins should show up in the result.

Review and contextualize learnings

In this quickstart, you created an Azure Digital Twins instance and used Azure Digital Twins Explorer to populate it with a sample scenario.

You then explored the graph, by:

• Using a query to answer a question about the scenario.
• Editing a property on a digital twin.
• Running the query again to see how the answer changed as a result of your update.

The intent of this exercise is to demonstrate how you can use the Azure Digital Twins graph to answer questions about your environment, even as the environment continues to change.

In this quickstart, you made the temperature update manually. It's common in Azure Digital Twins to connect digital twins to real IoT devices so that they receive updates automatically, based on telemetry data. In this way, you can build a live graph that always reflects the real state of your environment. You can use queries to get information about what's happening in your environment in real time.

Clean up resources

To clean up after this quickstart, choose which resources you want to remove based on what you want to do next.

• If you plan to continue to the Azure Digital Twins tutorials, you can reuse the instance in this quickstart for those articles, and you don't need to remove it.

• If you want to continue using the Azure Digital Twins instance you set up in this article, but clear out some or all of its models, twins, and relationships, you can use the az dt CLI commands in an Azure Cloud Shell window to delete the elements you want to remove.

• If you do not need any of the resources you created in this tutorial, you can delete the Azure Digital Twins instance and all other resources from this article with the az group delete command. This deletes all Azure resources in a resource group, as well as the resource group itself.

  Important

  Deleting a resource group is irreversible. The resource group and all the resources contained in it are permanently deleted. Make sure that you don't accidentally delete the wrong resource group or resources.

  Open Azure Cloud Shell, and run the following command to delete the resource group and everything it contains.

  az group delete --name <your-resource-group>
  

You may also want to delete the sample project folder from your local machine.

Next steps

Next, continue on to the Azure Digital Twins tutorials to build out your own Azure Digital Twins scenario and interaction tools.