Links
Comment on page

Configuration

This section explains each of the properties in the configuration blade.

General

Property
Description
Collection
This associates the Agent to a specific Collection (default to that of the current Data Stream).
Refer to Collections and Stream Hosts to understand more about Collections.

Authentication

Property
Description
Use Variables
Tick to select saved variables for the authentication credentials; or enter the text manually.
Subscription Id
The Id of the Azure subscription to which the Client has access. This is required if you wish to create or manage an Azure Digital Twins instance through this Agent's configuration blade and requires the Client to have additional administration permissions. This is also required if you want to Integrate to Azure Data Explorer.
Tenant Id
The Id of the tenant to which the Client belongs.
Client Id
The Id of the Azure App Registration the Agent should use to connect to the Azure Digital Twin instance.
Client Secret
The Secret of the Azure App Registration the Agent should use to connect to the Azure Digital Twin instance.

Digital Twin

Property
Description
Host Name
The Host Name of the Azure Digital Twins instance. This can either be the simple name or the full URL in the format "https://***.api.aue.digitaltwins.azure.net"
Model Name
The model of the devices you wish to update. Options are automatically fetched from the Digital Twins instance.
Twin Id
The event property that represents the Digital Twin's Id.

Create New Resource

This link opens a sub-page that allows you to create a new Azure Digital Twins instance. This option will only appear if the Subscription Id value is filled in and Azure resource creation is enabled.
Property
Description
Resource Location
The location the new Digital Twins instance will be created in. The options are filled out from Azure's list of servers.
Resource Group
The resource group the new Digital Twins instance will be assigned to. The options are filled out from existing Resource Groups, but a new Resource Group can be created by inputting a value manually.
Digital Twins Instance Name
The name of the Digital Twins instance to create.
Once these are entered, click Setup Infrastructure.
Once the new Digital Twins instance is created, which may take several minutes, click Apply on this blade to insert the Host Name into the main configuration blade. This can only happen if the Use Variables checkbox is not ticked.
If the details of an existing Digital Twins instance are entered, the required values to connect to the existing instance will be displayed and no new instance created.

Upload New Model

This link opens a sub-page that allows you to upload a new Digital Twin Model (or multiple models) to the Digital Twins instance. The File upload on this page expects either a JSON file containing the DTDL definition of the model, or a ZIP file containing multiple such JSON files.
For more information about the DTDL format expected, please see Azure's documentation.

Relationships Mapping

The Relationships Mapping grid lists the available relationships of the Digital Twin Model and is used to decide if those values should be changed by the Agent.
Property
Description
Relationship
The name of the relationship in the Digital Twin model.
Value
The event property used to update the relationship. If this is not blank, the relationship will be updated every time a non-empty value is received. In addition, any extra properties the relationship might contain will be exposed to updates in the Input Mapping in the format "{relationshipName}-{property}"

Azure Data Explorer (Optional)

This Agent can integrate with a Azure Data Explorer, to create Time Series models based on your Digital Twins, and enable viewing historical data by sending data via an Event Hub configured to forward events to the Azure Data Explorer instance.
Property
Description
Integrate with Azure Data Explorer?
Tick to integrate with Azure Data Explorer. The rest of the properties in this group apply when Integrate with Azure Data Explorer? is ticked.
Event Hub Namespace
The URL of the Event Hub Namespace to which events are sent, normally in the format sb://***.servicebus.windows.net/ .
Access Key Name
The name of the Access Key to authenticate to the Event Hub.
Access Key
The value of the Access Key to authenticate to the Event Hub.
Event Hub Name
The name of the Event Hub within the chosen Namespace to send events.
Event Hub Resource ID
The unique identifier that represents an instance of Azure Event Hubs service within an Azure subscription, in the format /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}/eventhubs/{eventHubName}.
Resource Group
The Resource Group of the ADX instance.
Location
The Location of the ADX Cluster.
Use ADX Secret
Tick to use a different Client ID and Secret Key to that of the Digital Twin.
Client ID
The Client ID of the ADX Cluster (applies when Use ADX Secret is ticked).
Secret Key
The Secret Key of the ADX Cluster (applies when Use ADX Secret is ticked).
Cluster
The Host Name used to create, start, edit, list, terminate, and delete clusters - in the format https://{clusterName}.{location}.kusto.windows.net). You can find the URL on the Azure Portal blade for the Data Explorer Cluster under the "URI" property.
Database
The name of the database to connect to. Once selected, the Table property is populated with the list of available tables in the database.
Table
The name of the table to save the Digital Twin history data. If it's schema is not the same as the Model with the additional columns, you must create a new table or map it manually.
Managed Identity Resource ID
The unique identifier that represents an instance of User-assigned Managed Identity service within an Azure subscription - in the format /subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}.
You need to authorize the User-assigned Identity to access the Event Hub: go to the Azure portal and assign the "Azure Event Hub Data Receiver" role on the Event Hub instance.

Create new resource

This link opens a sub-page that allows you to create a new Event Hub to connect to an Azure Data Explorer instance. Azure Data Explorer instances cannot be managed this way, so creating the Azure Data Explorer instance must be done manually.
This option will only appear if the Subscription Id value is filled in and Azure resource creation is enabled.
Property
Description
Resource Location
The location the new Digital Twins instance will be created in. The options are filled out from Azure's list of servers.
Resource Group
The resource group the new Digital Twins instance will be assigned to. The options are filled out from existing Resource Groups, but a new Resource Group can be created by inputting a value manually.
Event Hub Namespace
The name of the Event Hub Namespace to connect to. If this namespace does not exist, it will be created.
Event Hub Name
The name of the Event Hub to connect to. If this event hub does not exist, it will be created.
Once these are entered, click Setup Infrastructure.
Once the new Event Hub objects are created, which may take several minutes, several additional textboxes will appear with the information required to connect to the new service. Make sure to note these, then click Apply on this blade and input these values into the corresponding options in the main configuration blade.
If the details of an existing Event Hub are entered, the values that are required to connect to the existing instance will be displayed and no new instance will be created.

Create new table

This link opens a sub-page that allows you to create a new Table on the selected ADX Database. It will copy the schema of the Digital Twin Model and add the following columns:
Column
Datatype
Description
TimeStamp
datetime
The time the Digital Twin properties reflected to ADX
SourceTimeStamp
datetime
The time the Digital Twin properties gets updated
ServiceId
string
The agent that update the Digital Twin
ModelId
string
The Model Id of the Digital Twin
dtId
string
The Id of the Digital Twin
etag
string
The standard HTTP field assigned by the web server
Property
Description
Table Name
The name of the new Table (default to 'AdtPropertyEvents'). Special characters allowed are (_) Underscore, (-) Dash, (.) Period and, ( ) Space.
Once this is entered, click Create Table.

Use Manual Mapping

This link opens a sub-page that allows you to manually map the Digital Twin properties to corresponding ADX columns. This applies if the selected table columns do not match the property names of the Digital Twin.
Property
Description
Digital Twin Property
Text field pre-populated with the Digital Twin properties and the additional fields.
ADX Column
Dropdown of the available columns on the ADX Table. It will only show the columns with same datatype as the corresponding Digital Twin property.
Once all fields are filled, click Apply.
Before configuring the Action Agent, please ensure that its input endpoint is connected to a parent Agent which will be sending data to it.

Input Mapping

All input mapping attributes are generated based on the definition of the Model Name selected. There are two types of properties - properties of the Digital Twin model itself, and properties of its relationships. Digital Twin properties are named as they are found in the Model, while relationship properties are in the format "{relationshipName}-{propertyName}" and only appear if the Relationship has a value in the Relationships Mapping grid.
Refer to Setup Input Mappings for step-by-step instructions.

Endpoints

Name
Description
Input
Receives the events to send to the Azure Digital Twins instance.
Output
Events received from the parent Agent are made available to this endpoint with unchanged attributes and data.
Error
If errors are encountered during the execution of this Agent they will be published on this endpoint.