# Datastream Template Description

# Datastream: Template Object

See details
  • # identifier

    • Mandatory: Yes
    • Description: Identifier of the template. It is unique by organization (not by datamodel). It can not start with device or provision.device. It can not contain the character "underline".
  • # name

    • Mandatory: Yes
    • Description: Name of the template.
  • # description

    • Mandatory: Yes
    • Description: Description of the template
  • # period

    • Mandatory: No
    • Description: String enumeration:
      • PULSE
      • CUMULATIVE
      • INSTANT. This is the default value
  • # access

    • Mandatory: No
    • Description: Only used when you want to determinate if a datastream is writeable. The access field can take three values
      • READ. This is the default value
      • WRITE
      • READ,WRITE All the datastreams are by default read, I mean, all datastreams can be readen, the devices or third parties can send the value of a datastream and this value processed by the platform, read. But, If you want to send a datastream value to a specific device, e.g. you want to change the value of a specific configuration parameter in one device, you can do it with a set operation and only datastreams with access type WRITE can be part of a set operation, so if you want use datastreams for changing values in configuration parameters you have to set the access value to WRITE.
  • # schema

    • Mandatory: Yes
    • Description: Used for defining the format of the datastream value. It must have a correct jsonSchema format. See see schema object
  • # storage

    • Mandatory: No
    • Description: Only used when you want to determinate the time to life of the collected datastream values. See IoT Datastream Storage Object, The default value is the organization’s plan storage value.
  • # unit

    • Mandatory: No
    • Description:
      • type: String describing the type of unit you want
      • label: String with the label you want for your unit
      • symbol: String with the symbol you want for your unit

      This fields are not mandatory and its default value is empty


  • # modifiable

    • Mandatory: No
    • Description: Boolean value to indicate if it is modifiable this datastream. The default value is true.
  • # calculated

    • Mandatory: No
    • Description: Boolean value to indicate if it is a datastream internally calculated by the platform. The default value is false.
  • # required

    • Mandatory: No
    • Description: Boolean value to indicate if it is required for this datastream. The default value is false.
  • # qrating

    • Mandatory: No
    • Description: Only used when you want to quantify the collected datapoints and datastreams. If it exists, it must be complete. See IoT Datastream Qrating Object.
  • # tags

    • Mandatory: No
    • Description: Array of strings used to tag the datastream, 50 characters max. per tag.
  • # views

    • Mandatory: No
    • Description: To be used in the future.
  • # icon

Datamodel example

{
  "identifier": "health",
  "name": "health name",
  "description": "health description",
  "version": "1.2",
  "allowedResourceTypes":[
    "entity.device"
  ],
  "categories": [
    {
      "identifier": "heart",
      "name": "heart name",
      "datastreams": [
        {
          "identifier": "health.heart.rate",
          "name": "health.heart.rate name",
          "description": "health.heart.rate description",
          "period": "INSTANT",
          "schema": {
            "type": "string"
          },
          "unit": {
            "type": "SI",
            "label": "beats/second",
            "symbol": "bpm"
          },
          "access": "READ",
          "storage": {</details>
            "period": "DAYS",
            "total": 30
          },
          "tags": [
            "health",
            "heart"
          ],
          "modifiable": true,
          "required": false
        }
      ]
    }
  ]
}

# Datastream Schema field description

See details

It allows to define a valid schema json. There are some predefined types than can be used.

# Datastream Qrating field description

See details

QRating ponders all the data streams giving more importance to some over others based on their results giving a more reliable picture of the value collected and device status.

QRating show for each data point / datastream based on the configuration provided for each datastream the next outputs:

  • Scoring
  • Performance
  • Data quality.

The set of all qRating parameters values allow calculate the overall performance of the device.

  • # version

    • Mandatory: Yes
    • Type: String
    • Description: Version of the configurated Qrating.
  • # max_score

    • Mandatory: Yes
    • Type: Number
    • Description: Datastream weight within the datastream.
  • # ideal

    • Mandatory: Yes
    • Type: Number
    • Description: The best value that can be collected for the datastream.
  • # min_required

    • Mandatory: Yes
    • Type: Number
    • Description: Minimum value accepted by the datastream (indicates when a data point collected is critical below the ideal).
  • # min_desired

    • Mandatory: Yes
    • Type: Number
    • Description: Datastream desired minimum value (the datapoint collected is not critical but is below the ideal).
  • # max_desired

    • Mandatory: Yes
    • Type: Number
    • Description: Datastream desired maximum value (the datapoint collected is not critical but is above the ideal).
  • # max_allowed

    • Mandatory: Yes
    • Type: Number
    • Description: Maximum value accepted by the datastream (indicates when a data point collected is critical above ideal).
  • # conversion_matrix

    • Mandatory: No
    • Type: Object
    • Description: It only applies if the collected datapoints are text typed, give a number for each allowed text value for calculate the qRating.
      • expectd value: Value translated for the expected value.
  • # cumulative_period_divisor

    • Mandatory: No
    • Type: Number, Seconds
    • Description: Allows calculate the median velocity of collection against the previous value collected taking this parameter as divisor

Datamodel example with typical number datastream qRating object

{
  "identifier": "datamodel",
  "name": "datamodel.health",
  "version": "1.2",
  "categories": [
    {
      "identifier": "category",
      "name": "heart",
      "datastreams": [
        {
          "schema": {
            "type": "string"
          },
          "identifier": "health.heart.rate",
          "period": "INSTANT",
          "unit": {
            "type": "SI",
            "label": "beats/second",
            "symbol": "bpm"
          },
          "access": "READ",
          "name": "health.heart.rate",
          "storage": {
            "period": "DAYS",
            "total": 30
          },
          "tags": ["health", "heart"],
          "qrating": {
            "version": "1.0.0",
            "min_required": {
              "value": -5,
              "label": "FROZEN"
            },
            "min_desired": {
              "value": 5,
              "label": "COLD"
            },
            "ideal": {
              "value": 25,
              "label": "NORMAL/IDEAL"
            },
            "max_desired": {
              "value": 35,
              "label": "HIGH"
            },
            "max_allowed": {
              "value": 60,
              "label": "HOT"
            },
            "max_score": 1000,
            "conversion_matrix": {
              "FROZEN": -5,
              "COLD": 5,
              "NORMAL": 36,
              "IDEAL": 36,
              "HIGH": 38,
              "HOT": 40
            }
          },
          "modifiable": true,
          "required": false
        }
      ]
    }
  ]
}

Pay attention to the conversion matrix field, with this option when for example the datapoint collect a value of Frozen, the value is changed by -100 for allowing the qRating calculation.


Pay attention to the cumulative period divisor field, without this option you receive a calculation of the datastream qrating comparing the last collected datapoint with the last one. With this option, qrating algorithm considers this value as a period divisor calculating the increment or decreasing median speed of the datastream cumulative value. For example, if you collect a total connection value of 60 in 1 hour and previous value was 0, the qrating value calculated is the increment (final value): 1 per minute (60 seconds divisor configured).

Final value = (Difference since last datapoint * Time Divisor) / (Total time in seconds between datapoints)


# Datastream Storage field description

See details

This field is oriented to save just only the datastream’s datapoints collected since a specific period of time, allowing the platform for deleting automatically the older datapoints.

In other words, the time a data point will be stored into OpenGate depends on the conjunction of this complex field period plus total and the value of the date field of the data point.

  • # period

    • Description: Specify the units of time that OpenGate have to consider for deleting historical datapoints, the available values are:
      • DAYS
      • MONTHS
      • **YEARS
      • NEVER: if you select this value, no one datapoint will be storaged, the information of the last one could be got in datastream’s
  • # total

    • Description: Amount of period units for considering in the deleting process.

    It is impossible to have total without period If the period is NEVER, the total field is empty The storage can not be greater than the one defined in the organization


# Datastream Icon field description

See details

This field is oriented to asociate an icon in the web datastream visualitation

  • # class

    • Description: Specify the class to represent icon’s name

Datamodel example with icon object

{
  "icon": {
    "class": "fas fa-hourglass-end"
  }
}

The name of the icon class is defined in https://fontawesome.com/icons?d=gallery (opens new window)