Links

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 Subscription Id, Tenant Id, Client Id, Client Secret, Host Name, Event Hub Namespace, Access Key Name, Access Key, Event Hub Name, and Time Series Environment properties; 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.
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.
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}"

Time Series

This Agent is additionally able to integrate with a Time Series Insights instance, to create Time Series models and instances based on your Digital Twins, and enable viewing historical data by sending data via an Event Hub configured to forward events to the Time Series instance.
Property
Description
Event Hub Namespace
The URL of the Event Hub Namespace to send events to, 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.
Time Series Environment
The FQID of the Time Series instance to integrate. This is a GUID.

Create new resource

This link opens a sub-page that allows you to create a new Event Hub to connect to an Azure Time Series Instance. Azure Time Series instances cannot be managed this way, so creating the Time Series instance and connecting it to the Event Hub 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.
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 will be made available on this endpoint, in a format identical to how the parent Stream Object sent them.
Error
If errors are encountered during the execution of this Agent they will be published on this endpoint.