LoadTwinsFromCsv Utility

The LoadTwinsFromCsv utility is a command-line utility that uses a CSV file to initialize Digital Twin instances. For every line in a CSV file, the tool sends a message to ScaleOut Digital Twins™ using the service’s REST APIs.

Download:

Usage:

LoadTwinsFromCsv /payload json|columns /csv PathToCsvFile /restUrl https://realtimetwinapi.scaleoutsoftware.com /apiKey 1234567890ABCDEF [/colTypes snbe...]
/payload

[json|columns] Specifies whether each row in the CSV file contains either a single JSON message payload or multiple property columns.

/csv

Path to the CSV file.

/restUrl

Address of the server hosting the service’s REST APIs.

/apiKey

The API key used to access the service.

/colTypes

Required if /payload is set to columns. Specifies the data type for each column (see below).

Any of the parameters can optionally be set in the utility’s appsettings.json file instead of the command line. For example:

{
  "csv": "PathToCsvFile",
  "restUrl": "https://realtimetwinapi.scaleoutsoftware.com",
  "apiKey": "1234567890ABCDEF",
  "payload": "json"
}

If parameters are supplied to both locations then the command line will take precedence.

Selecting a Payload Type

The first two columns in your CSV file must be called ModelName and InstanceId. After those two columns, your CSV file can be formatted in one of two ways:

  • /payload json: A three-column CSV file, where the third column is a JSON object that is passed directly to your model’s message processor.

  • /payload columns: A CSV with an arbitrary number of columns. Columns that follow the first two required fields (ModelName & InstanceId) are called “property columns”. For each CSV row, the LoadTwinsFromCsv utility combines these columns into a single JSON payload that is sent to the message processor.

An example of each type of CSV file is provided below.

JSON Payloads

When uploading a JSON string (/payload json), the CSV file should have three columns with the following form:

ModelName,InstanceId,InitPayload
WindTurbine,Turbine001,"[{""State"": ""NV"", ""MaxTemp"": 200}]"
WindTurbine,Turbine002,"[{""State"": ""NV"", ""MaxTemp"": 200}]"
WindTurbine,Turbine003,"[{""State"": ""NV"", ""MaxTemp"": 200}]"

Multiple Property Columns

If the message properties are expressed as individual columns in the CSV (/payload columns), the the CSV file should have the following form:

ModelName,InstanceId,State,MaxTemp
WindTurbine,Turbine001,NV,200
WindTurbine,Turbine002,NV,200
WindTurbine,Turbine003,NV,200

An addional argument, colTypes, must be supplied to provide type information about each property field. The tool uses this information when constructing a JSON message. The number of characters supplied as a colTypes argument should match the number of property fields.

The example CSV above would specify /colTypes sn, indicating that the first property field (“State”) contains string values, and the second property field (MaxTemp) is a numeric value.

The following characters may be specified in the colTypes argument string to specify field types during JSON conversion:

  • s - String. Empty fields in the CSV should be sent as null in the JSON message.

  • e - String. Empty fields in the CSV should be sent as an empty string in the JSON message.

  • b - Boolean

  • n - Number