Quickstart - Explore a sample Azure Digital Twins scenario using ADT Explorer

With Azure Digital Twins, you can create and interact with live models of your real-world environments. This is done by modeling individual elements as digital twins, then connecting them into a knowledge graph that can respond to live events and be queried for information.

In this quickstart, you will explore a pre-built Azure Digital Twins graph, with the help of a sample application called Azure Digital Twins (ADT) Explorer. ADT Explorer lets you upload a digital representation of an environment, view visual images of the twins and graph that are created to represent the environment in Azure Digital Twins, and perform other management activities through a browser-based, visual experience.

The quickstart contains the following major steps:

  1. Set up an Azure Digital Twins instance and ADT Explorer
  2. Upload pre-built models and graph data to construct the sample scenario
  3. Explore the scenario graph that is created
  4. Make changes to the graph

The sample graph you will be working with represents a building with two floors and two rooms. The graph will look like this:

View of a graph made of 4 circular nodes connected by arrows. A circle labeled 'Floor1' is connected by a arrow labeled 'contains' to a circle labeled 'Room1'; a circle labeled 'Floor0' is connected by an arrow labeled 'contains' to a circle labeled 'Room0'. 'Floor1' and 'Floor0' are not connected.

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 Node.js on your machine. You can get the latest version at this link: Node.js.

Finally, you will also need to download the sample to use during the quickstart: the ADT Explorer sample application. This sample contains the app you use in the quickstart to load and explore an Azure Digital Twins scenario, as well as the sample scenario files. To get the sample, navigate here: Azure Digital Twins (ADT) explorer. Hit the Download ZIP button to download a .ZIP file of this sample code to your machine. This will download a .ZIP folder to your machine as Azure_Digital_Twins__ADT__explorer.zip. Unzip the folder and extract the files.

Set up Azure Digital Twins and ADT Explorer

The first step in working with Azure Digital Twins is to set up an Azure Digital Twins instance. After you create an instance of the service, you'll be able to populate it with the example data later in the quickstart.

You'll also set up permissions for ADT Explorer to run on your computer and access your Azure Digital Twins instance, including setting up an Azure Active Directory (Azure AD) app registration for it to use. After this, you can use the sample app to explore your instance and its data.

Set up Azure Digital Twins instance and app registration

To work with Azure Digital Twins in this article, you first need to set up an Azure Digital Twins instance and the required permissions for using it. If you already have an Azure Digital Twins instance set up from previous work, you can use that instance.

Otherwise, follow the instructions in How-to: Set up an instance and authentication. The instructions also contain steps to verify that you have completed each step successfully and are ready to move on to using your new instance.

After setting up your Azure Digital Twins instance, you'll need the instance's host name (find in the Azure portal). Take note of this value so you can use it later to connect to the instance.

To authenticate all the resources used in this article, you'll need to set up an Azure Active Directory (Azure AD) app registration. Follow the instructions in How-to: Create an app registration to set this up.

Once you have an app registration, you'll need the registration's Application (client) ID and Directory (tenant) ID (find in the Azure portal). Take note of these values to use them later to grant access to the Azure Digital Twins APIs.

Set ADT Explorer permissions

Next, prepare the Azure Digital Twins instance you created to work with ADT Explorer, which is a locally-hosted web application. Visit the App registrations page in the Azure portal and select the name of your app registration that you created in the previous section from the list.

Select Authentication from the registration's menu, and hit + Add a platform.

Azure portal page of the Authentication details for an app registration. There is a highlight around an 'Add a platform' button

In the Configure platforms page that follows, select Web. Fill the configuration details as follows:

  • Redirect URIs: Add a redirect URI of http://localhost:3000.
  • Implicit grant: Check the box for Access tokens.

Hit Configure to finish.

The Configure platforms page, highlighting the info described above onscreen

Now you have a web configuration configured that ADT Explorer will use. The Authentication tab in the Azure portal should reflect this. After verifying the sections below, hit Save.

Azure portal page of the Authentication details for an app registration. There are highlights around a Web platform section with a redirect URI of http://localhost:3000, and Implicit Grant being enabled for access tokens. The Save button is also highlighted.

Run and configure ADT Explorer

Next, run the ADT Explorer application and configure it for your Azure Digital Twins instance.

Navigate to the downloaded and unzipped Azure_Digital_Twins__ADT__explorer folder. Open a command prompt at the folder location Azure_Digital_Twins__ADT__explorer/client/src.

Run npm install to download all the required dependencies.

Then, start the app by running npm run start.

After a few seconds, a browser window will open and the app will appear in the browser.

Browser window showing an app running at localhost:3000. The app is called ADT Explorer and contains boxes for a Query Explorer, Model View, Graph View, and Property Explorer. There is no onscreen data yet.

Hit the Sign in button at the top of the window (shown in image below) to configure ADT Explorer to work with the instance you've set up.

ADT Explorer highlighting the Sign In icon near the top of the window. The icon shows a simple silhouette of a person overlaid with a silhouette of a key.

Enter the important information you gathered earlier in the Prerequisites section:

  • Application (client) ID
  • Directory (tenant) ID
  • Azure Digital Twins instance URL, in the format https://{instance host name}

Note

You can revisit/edit this information at any time by selecting the same icon to pull up the Sign In box again. It will keep the values that you passed in.

Tip

If a SignalRService.subscribe error message is shown when you connect, make sure that your Azure Digital Twins URL begins with https://.

If you see a Permissions requested pop-up window from Microsoft, grant consent for this application and accept to continue.

Add the sample data

Next, you will import the sample scenario and graph into ADT Explorer. The sample scenario is also located in the Azure_Digital_Twins__ADT__explorer folder you downloaded earlier.

Models

The first step in an Azure Digital Twins solution is defining the vocabulary for your environment. This is done by creating custom models, which describe the types of entity that exist in your environment.

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

Typically when creating a model, you will complete three steps:

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

For this quickstart, the model files have already been written and validated for you, and are included with the solution you downloaded. In this section, you will upload two pre-written models to your instance to define these components of a building environment:

  • Floor
  • Room

Upload models

In the MODEL VIEW box, hit the Upload a Model icon.

In the Model View box, the middle icon is highlighted. It shows an arrow pointing into a cloud.

  1. In the file selector box that appears, navigate to the Azure_Digital_Twins__ADT__explorer/client/examples folder in the downloaded repository.
  2. Select Room.json and Floor.json, and hit OK. (You can upload additional models if you'd like, but they won't be used in this quickstart.)
  3. Follow the popup dialog asking you to sign into your Azure account.

Note

If you see the following error message: A popup reading 'Error: Error fetching models: ClientAuthError: Error opening popup window. This can happen if you are using IE or if popups are blocked in the browser.' with a Close button at the bottom Try disabling your popup blocker or using a different browser.

ADT Explorer will now upload these model files to your Azure Digital Twins instance. They should show up in the MODEL VIEW box, displaying their friendly names and full model IDs. You can click the View Model information bubbles 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: 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 (like multiple rooms that all use the Room model), and connect them with relationships into a twin graph that represents the full environment.

In this section, you will 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

In the GRAPH VIEW box, hit the Import Graph icon.

In the Graph View box, an icon is highlighted. It shows an arrow pointing into a cloud.

In the file selector box, navigate to theAzure_Digital_Twins__ADT__explorer/client/examples folder and choose the buildingScenario.xlsx spreadsheet file. This file contains a description of the sample graph. Hit OK.

After a few seconds, ADT Explorer will open an Import view displaying a preview of the graph that is going to be loaded.

To confirm the graph upload, hit the Save icon in the upper right corner of the GRAPH VIEW:

ADT Explorer will now use the uploaded file to create the requested twins and relationships between them. A dialog will appear to show that it is finished. Hit Close.

The graph has now been uploaded to ADT Explorer. To see the graph, hit the Run Query button in the GRAPH EXPLORER box, near the top of the ADT Explorer window.

A button reading 'Run Query' near the top of the window is highlighted

This will run the default query to select and display all digital twins. ADT Explorer will retrieve all twins and relationships from the service, and draw the graph defined by them in the GRAPH VIEW box.

Explore the graph

Now, you can see the uploaded graph of the sample scenario:

View of the 'Graph View' box with a twin graph inside. A circle labeled 'floor1' is connected by a arrow labeled 'contains' to a circle labeled 'room1'; a circle labeled 'floor0' is connected by an arrow labeled 'contains' to a circle labeled 'room0'.

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

If you're using a mouse, you can click and 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 PROPERTY EXPLORER box.

Here are the properties of Room0:

Note that Room0 has a temperature of 70.

Here are the properties of Room1:

Note that 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, including finding outliers in your environment that might need attention.

In this section, you will run a query to answer the following question: What are all the twins in my environment with a temperature above 75?

To see the answer, run the following query in the QUERY EXPLORER box:

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. As a result, only Room1 shows up in the results here.

Results of property query, showing only Room1

Tip

Other comparison operators (<,>, =, or !=) are also supported within the query above. You can try plugging these, different values, or different twin properties into the query to try out answering your own questions.

Edit data in the graph

You can use ADT Explorer to edit the properties of the twins represented in your graph. In this section, we will raise the temperature of Room0 to 76.

To do this, select Room0, bringing up its property list in the PROPERTY EXPLORER box.

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

Upon successful save, you will see a Patch Information window displaying the patch code that was used behind the scenes with the Azure Digital Twins APIs to make the update. Hit Close.

Query to see the result

To verify that the graph successfully registered your update to Room0's temperature, re-run 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.

Results of property query, showing both Room0 and Room1

Review and contextualize learnings

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

You then explored the graph, by...

  1. Using a query to answer a question about the scenario.
  2. Editing a property on a digital twin.
  3. 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.

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

Clean up resources

To wrap up the work for this quickstart, first end the running console app. This will shut off the connection to the ADT Explorer app in the browser, and you will no longer be able to view live data in the browser. You can close the browser tab.

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

If you no longer need the resources created in this tutorial, follow these steps to delete them.

Using the Azure Cloud Shell, you can delete all Azure resources in a resource group with the az group delete command. This removes the resource group and the Azure Digital Twins instance.

Important

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

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

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

Next, delete the Azure Active Directory app registration you created for your client app with this command:

az ad app delete --id <your-application-ID>

Finally, delete the project sample folder you downloaded to your local machine (Azure_Digital_Twins__ADT__explorer). You may have to delete both the zipped and unzipped versions.

Next steps

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