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.