Driver Service Configuration

About 5 mindriver

Due to distributed IOTA Vue architecture - each on-premise data driver installation requires 3 steps:

Install the on-premise driver service
Register the data driver in IOTA Vue user interface.
Configure server connections per each registered data driver

This section covers the on-premise driver service configuration.

Tips

The CONNECT data services (CDS) Driver comes with a preset configuration file. Manual configuration is not required.

On every startup - CDS (ADH) Driver reads its configuration from the file named the same as executable: iota.adhdrv.json. For secure NATs bus communication, the NKey private key file named as privatekey.nk must reside next to iota.adhdrv.json configuration file.

During the first CDS (ADH) Driver installation, the installer copies an auto generated configuration (.json) file and private key file to ProgramData folder:

{ProgramData}\IOTA\Drivers\ADH-Driver_{Region Name}_{Site Name}

Warning

Any subsequent CDS (ADH) Driver updates will not affect the configuration and private key files in ProgramData folder.

Configuration File parameters

Parameter name	Required	Default Value	Data Type	Description
driverid	⚫	`null`	string	Driver Id - used for logging purposes only
debug	⚫	`0`	int	Debug verbose level: 0 - errors only, 1 - warnings, 2 - information, 3 - debug
natsurl	🟢	`null`	string	NATs server url with port
publickey	🟢	`null`	string	NATs NKey public key string. Private key must be defined in file: "privatekey.nk" and located in the same folder as iota.adhdrv.json
reqtopic	🟢	`null`	string	NATs topic on which driver listens for requests
statstopic	⚫	`null`	string	NATs topic for sending driver's stats
logstopic	⚫	`null`	string	NATs topic for sending driver's logs
metricstopic	⚫	`null`	string	NATs topic for sending driver's metrics
metricsmsec	⚫	`30000`	int	How often in milliseconds to send metrics data. Default: 30000 = 30 sec
enablemetrics	⚫	`true`	bool	Enables metrics reporting
healthtopic	🟢	`iota.health`	string	NATs topic for sending driver's health
healthmsec	⚫	`10000`	int	How often in milliseconds to send health data. Default: 10000 = 10 sec
logfilecount	⚫	`10`	int	Number of rolling log files
logfilesize	⚫	`2097152`	int	Number of bytes per each log file. Default: 2097152 bytes = 2 Mb
logscanmsec	⚫	`30000`	int	How often in milliseconds to append data to log files. Default: 30000 = 30 sec
settings	⚫	`30000`	object	Driver side configuration for CDS (ADH) type mapping into IOTA types.

Example

{
  "driverid": "adh-demo",
  "natsurl": "mon.iota-demo.com:443",
  "reqtopic": "us-east-1.site-demo.adh.request",
  "statstopic": "us-east-1.site-demo.stats",
  "logstopic": "us-east-1.site-demo.adh.logs",
  "publickey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "metricstopic": "us-east-1.site-demo.metrics",
  "metricsmsec": 30000,
  "healthtopic": "iota.health",
  "healthmsec": 10000,
  "enablemetrics": true,
  "debug": 2,
  "logfilecount": 10,
  "logfilesize": 2097152,
  "logscanmsec": 10000,
  "settings": null
}

Custom CDS (ADH) Types Mapping to IOTA Types

CONNECT data services is a versatile platform which is designed to aggregate and store high-fidelity operations data and contextual information from multiple sites and assets in a single, secure location in the cloud.
With versatility comes complication in relation to data type schemas. The CDS (ADH) allows to store data based on user defined data type schemas which means that in order to use such data - any client application should be able to map user defined data types to specific application data types.

IOTA Vue internally uses strong data types for tags, assets and timeframes.
By default, IOTA CDS (ADH) Driver works with generic CDS (ADH) data types without the need to provide type mappings.
In case of custom CDS (ADH) data type visualization IN IOTA, type mappings should be provided in configuration file via settings section.

Driver Settings

The settings section is organized as key-value pair collection, where Key is the user defined connection instance name.

Note

The user defined connection instance name must match the UI connection dialog Name definition

Server object parameters

Parameter Name	Default Value	Data Type	Description
`streamtypemap`	`null`	object	Provides mapping for CDS (ADH) user defined stream types.
`assettypemap`	`null`	object	Provides mapping for CDS (ADH) user defined asset types.
`eventquerymap`	`null`	object	Provides mapping for CDS (ADH) user defined event types.

Note

The server configuration requires only one of the two parameters defined: name or host. If both parameters are defined, the driver will search on name first then on host second.

Example

In this example, the CDS (ADH) Connection instance is named in IOTA Vue UI as ADH-DEMO1

{
  "driverid": "adh-demo",
  "natsurl": "mon.iota-demo.com:443",
  "reqtopic": "us-east-1.site-demo.adh.request",
  "statstopic": "us-east-1.site-demo.stats",
  "logstopic": "us-east-1.site-demo.adh.logs",
  "publickey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "metricstopic": "us-east-1.site-demo.metrics",
  "metricsmsec": 30000,
  "healthtopic": "iota.health",
  "healthmsec": 10000,
  "enablemetrics": true,
  "debug": 2,
  "logfilecount": 10,
  "logfilesize": 2097152,
  "logscanmsec": 10000,
  "settings": {
     "ADH-DEMO1": {
        "streamtypemap": null,
        "assettypemap": null,
        "eventtypemap" : null
      }
  }
}

Stream Type Map

The streamtypemap section is organized as key-value pair collection and provides mapping between CONNECT data services custom stream schema and IOTA tag schema.
The key of each pair is the name of CDS (ADH) stream schema and the value is the mapping object which is also a key-value collection where the keys are now the IOTA
tag property names, and the values are CDS (ADH) stream schema property names.

 "<CDS (ADH) Stream Schema Name>":
  {
      "<IOTA Tag Property>": "CDS (ADH) Stream Schema Property"
  }

IOTA Tag Mapping Schema

IOTA Tag Property	Default Value	Data Type	Description
`id`	"id"	string	The tag id property. Default: "id"
`name`	`null`	string	The tag name property.
`description`	`null`	string	The tag description property.
`step`	`null`	string	The tag step property.
`events`	`null`	string	The name of events collection.
`event`	`null`	object	The CDS (ADH) event schema mapping to IOTA event schema.

IOTA Tag Event Mapping Schema

IOTA Event Property	Default Value	Data Type	Description
`timestamp`	`null`	string	The attribute timestamp property.
`value`	`null`	string	The attribute value property.

Example

"settings": {
   "ADH-DEMO1" : {
       "streamtypemap": {
           "test": {
               "id": "id",
               "name": "name",
               "description": null,
               "step": null,
               "events": "events",
               "event": {
                  "timestamp": "timestamp",
                  "value": "value"
               }
           }
       }
   }
}

Asset Type Map

The assettypemap section is organized as key-value pair collection and provides mapping between CONNECT data services custom asset schema and IOTA asset schema.
The key of each pair is the name of CDS (ADH) asset schema and the value is the mapping object which is also a key-value collection where the keys are now the IOTA
asset property names, and the values are CDS (ADH) asset schema property names.

 "<CDS (ADH) Asset Schema Name>":
  {
      "<IOTA Asset Property>": "CDS (ADH) Asset Schema Property"
  }

IOTA Asset Mapping Schema

IOTA Asset Property	Default Value	Data Type	Description
`id`	"id"	string	The asset id property.
`name`	`null`	string	The asset name property.
`description`	`null`	string	The asset description property.
`typeid`	"assetTypeId"	string	The asset step property.
`attributes`	`null`	string	The name of attributes collection.
`attribute`	`null`	object	The CDS (ADH) attribute schema mapping to IOTA attribute schema.

IOTA Attribute Mapping Schema

IOTA Attribute Property	Default Value	Data Type	Description
`id`	"id"	string	The attribute id property.
`name`	`null`	string	The attribute name property.
`description`	`null`	string	The attribute description property.
`timestamp`	`null`	string	The attribute timestamp property.
`value`	`null`	string	The attribute value property.
`uom`	`null`	string	The attribute uom property.

Example

"settings": {
   "ADH-DEMO1" : {  
       "assettypemap": {
          "Well": {
            "id": "id",
            "name": "name",
            "description": "description",
            "attributes": "metadata",
            "attribute": {
               "id": "id",
               "name": "name",
               "timestamp": "timestamp",
               "value": "value",
               "uom": "uom"
            }
         }
      }
   }
}

Event Query Map

The eventquerymap section is organized as key-value pair collection and provides mapping between CONNECT data services custom event schema and IOTA timeframe schema.
The key of each pair is the name of CDS (ADH) event schema and the value is the mapping object which is also a key-value collection where the keys are now the IOTA
timeframe property names, and the values are CDS (ADH) event schema property names.

 "<CDS (ADH) Event Schema Name>":
  {
      "<IOTA TimeFrame Property>": "CDS (ADH) Event Schema Property"
  }

IOTA TimeFrame Mapping Schema

IOTA TimeFrame Property	Default Value	Data Type	Description
`id`	"id"	string	The timeframe id property.
`name`	`null`	string	The timeframe name property.
`description`	`null`	string	The timeframe description property.
`default`	false	boolean	The timeframe default property.
`count`	`null`	string	The timeframe count property.
`starttime`	"eventStartTime"	string	The timeframe start time property.
`endtime`	"eventEndTime"	string	The timeframe end time property.
`refassets`	`null`	string	The timeframe referenced asset collection name.
`asset`	`null`	object	The CDS (ADH) asset schema mapping to IOTA asset schema.

Example

"settings": {
   "ADH-DEMO1" : {  
       "eventquerymap": {
           "queryEventDemo": {
              "default": true,
               "count": "count",
               "id": "id",
               "name": null,
               "starttime": "eventStartTime",
               "endtime": "eventEndTime",
               "refassets": "referenceAssets",
               "asset": {
                  "id": "id",
                  "name": "name",
                  "typeid": "assetTypeId"
              }
           }
       }
   }
}

Full Example

{
  "driverid": "adh-demo",
  "natsurl": "mon.iota-demo.com:443",
  "reqtopic": "us-east-1.site-demo.adh.request",
  "statstopic": "us-east-1.site-demo.stats",
  "logstopic": "us-east-1.site-demo.adh.logs",
  "publickey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "metricstopic": "us-east-1.site-demo.metrics",
  "metricsmsec": 30000,
  "healthtopic": "iota.health",
  "healthmsec": 10000,
  "enablemetrics": true,
  "debug": 2,
  "logfilecount": 10,
  "logfilesize": 2097152,
  "logscanmsec": 10000,
  "settings": {
    "ADH-DEMO1": {
       "streamtypemap": {
          "test": {
             "id": "id",
             "name": "name",
             "description": null,
             "step": null,
             "events": "events",
             "event": {
                "timestamp": "timestamp",
                "value": "value"
             }
          }
      },
      "assettypemap": {
         "Well": {
            "id": "id",
            "name": "name",
            "description": "description",
            "attributes": "metadata",
            "attribute": {
               "id": "id",
               "name": "name",
               "timestamp": "timestamp",
               "value": "value",
               "uom": "uom"
            }
         }
      },
      "eventtypemap": {
         "Test_events": {
            "count": "count",
            "id": "id",
            "name": null,
            "starttime": "eventStartTime",
            "endtime": "eventEndTime",
            "refassets": "referenceAssets",
            "asset": {
               "id": "id",
               "name": null,
               "typeid": null
           }
        },
        "queryEventDemo": {
           "count": "count",
           "id": "id",
           "name": null,
           "starttime": "eventStartTime",
           "endtime": "eventEndTime",
           "refassets": "referenceAssets",
           "asset": {
              "id": "id",
              "name": "name",
              "typeid": "assetTypeId"
          }
        }
      }
    }
  }
}