Cosmos DB Connector

The Azure Cosmos DB connector can be used to connect your Digital Twin instances to a Cosmos database in Microsoft Azure. This enables digital twin instances (both real-time and simulation) to persist and retrieve state properties from corresponding CosmosDB JSON documents.

To connect to a Cosmos DB database, supply a set of credentials for an Azure Cosmos DB account that has permissions to create/access/modify tables and create/read/update/delete items. The Azure credentials are provided through the UI when you create a new Cosmos DB connector and consist of:

Account URI: the URI to the Azure Cosmos DB account where the containers will be added.
Primary key: the primary Read-Write key for the Cosmos DB account.

Values for these properties can be found in the Keys section of the Cosmos DB account:

cosmosDbCreds

To configure the connection to Cosmos DB, open the ScaleOut Digital Twins™ UI in your web browser and create a new connection:

cosmosdb_connector_image

In addition to the Azure credentials, you can supply the following parameters for the connection:

Update Interval: The minimum period in seconds between successive updates to a persisted instance after updates to its corresponding digital twins instance. This parameter allows digital twin deployments with high message rates and/or many data sources to coalesce their database updates avoid hitting its resource limits.
Retrieve State on Create: Specifies whether to retrieve properties from DynamoDB when creating a digital twin instance.

The connector can be deployed immediately upon creation, or it can be deployed later. The connector authenticates with Azure and the Cosmos DB table when deployed.

Note

Instances are persisted in a table named DigitalTwinInstances in a ScaleOutSoftware container. This table will be created when the connector is deployed.

Enable Persistence for a Digital Twin Model

Java Models

A Java digital twin model can enable persistence by adding enablePersistence to the model definition file and setting it to true. The model will use the default, configured persistence provider, which is the last persistence provider that was configured. If more than one persistence provider has been configured, the value persistenceProvider can be added to the model definition file and set to one of the following strings: “CosmosDB”, “DynamoDB”, “SQLServer”, “SQLite”, “AzureDigitalTwinsService”, or “Default”.

.NET Core Models

A .NET Core digital twin model can enable persistence by adding EnablePersistence to the appsettings.json and setting it to true. The model will use the default, configured persistence provider, which is the last persistence provider that was configured. If more than one persistence provider has been configured, the value PersistenceProvider can be added to the model definition file and set to one of the following strings: “CosmosDB”, “DynamoDB”, “SQLServer”, “SQLite”, “AzureDigitalTwinsService”, or “Default”.

Here is an example:

 {
     "StartupDll": "WindTurbine.dll",
     "ModelName": "WindTurbine",
     "ModelType": "WindTurbine.dll, WindTurbine.WindTurbineDigitalTwin",
     "MessageType": "WindTurbineMessages.dll, WindTurbineMessages.DeviceTelemetry",
     "EnablePersistence": true
 }

Rule-based Models

To enable persistence in a rule-based model, set the EnablePersistence property in the model definition file. This can be done directly in the ScaleOut Model Development Tool:

persistence_dev_tool