Since version 3.1.0-KickOff, Ontologies have been referred to as "Entities" in the Control Panel. This does not alter any functionality; the nomenclature has simply been changed for a better understanding of the concept.

Introduction

Onesait Platform's architecture is Data-Centric based, the data is the main and permanent asset. In this type of architectures data models precedes the implementation of any given application and will be valid long after they are replaced.

Onesait Platform supports this type of architecture through the concept of Entity (previously called Ontologies), and all the Platform's functionalities are based on this concept.

In the simplest case, an Entity can be compared to a table in a relational database, but an Entity can contain a complete domain model, which in a relational database would require a set of related tables.

This article details the reasons why it is advisable to implement the data model using Entities.

Definition and structure

In the Platform, a JSON-Schema format schema is used to define the Entities. This schema defines the structure of the information that the Entity will store, allowing semantic validations on the data received.

An example of an Entity definition schema would be similar to this example:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "SensorTemp",
  "type": "object",
  "required": [
    "SensorTemp"
  ],
  "properties": {
    "SensorTemp": {
      "type": "string",
      "$ref": "#/datos"
    }
  },
  "datos": {
    "description": "Properties for DataModel SensorTemp",
    "type": "object",
    "required": [
      "measure",
      "units",
      "timestamp",
      "geoposition"
    ],
    "properties": {
      "measure": {
        "type": "number"
      },
      "units": {
        "type": "string"
      },
      "timestamp": {
        "type": "string",
        "format": "date-time"
      },
      "geoposition": {
        "type": "object",
        "required": [
          "coordinates",
          "type"
        ],
        "properties": {
          "coordinates": {
            "type": "array",
            "items": [
              {
                "type": "number",
                "maximum": 180,
                "minimum": -180
              },
              {
                "type": "number",
                "maximum": 90,
                "minimum": -90
              }
            ],
            "minItems": 2,
            "maxItems": 2
          },
          "type": {
            "type": "string",
            "enum": [
              "Point"
            ]
          }
        },
        "additionalProperties": false
      }
    }
  },
  "description": "Temperature ontology",
  "additionalProperties": true
}

The information sent to the Platform using the Entity must comply with this definition scheme.

The unit of information in the Platform is called an instance. An instance of an Entity would be the equivalent of a record in a relational database table.

For the above example, a valid Entity instance would be:

{
  "SensorTemp": {
    "measure": 28.6,
    "units": "C",
    "timestamp": "2014-01-30T17:14:00Z",
    "geoposition": {
      "coordinates": [
        4,
        28.6
      ],
      "type": "Point"
    }
  }
}

Any instance that does not semantically comply with the target Entity definition schema will be rejected by the Platform, thus ensuring the correctness of the information.

Whenever an instance is inserted into the Platform, additional audit information is added to it within a property called "ContextData":

"contextData": {
    "deviceTemplate": "clientSensor",
    "device": "sensorTemperatura01",
    "clientConnection": "53643241-1497-17ea-436e-ba74618f7322 ",
    "clientSession": "64376481-4139-48cb-ad6e-dc7bdd8f73ca",
    "user": "user_developer",
    "timezoneId": "GMT",
    "timestamp": "Thu May 31 14:51:31 GMT 2018",
    "timestampMillis": 1527778291886
  }

This contextual data includes information regarding the source or device that sent the information, the session that was used, the time zone and the time at which it was received, etc.

Properties of an Entity

In addition to the structure of the ontology, another set of behavior defining characteristics can be defined:

Name: Identifier of the ontology that will allow to refer to it, make queries, insertions, etc. The elements that are inserted in the ontology must have this identifier as a root element (as seen in the previous example).
Metainformation: Additional information (tags) that allow categorizing the ontology for filtering, etc ...
Description: It details any aspect of the ontology that its owner considers appropriate.
Active: Indicates if an ontology is active. Otherwise, it will not be available for use.
Publish: A public ontology is an ontology to which all users have access. If an ontology is not public (private), each user must be given explicit access so that they can use it. In addition, it is necessary to detail the access level for each user:
- Query: Allows queries over the information stored in the ontology.
- Insert: Allows the user to insert information in the ontology.
- All: Allows total control over the ontology.
Encryption of fields: To add an additional security level, encryption of the attributes of the ontology instances is allowed.

As advanced options:

Kafka topic generation: For ontologies designed to receive massive data ingests.
Automatic Data remove: An automatic deletion of the stored information can be defined as well as the period of time the data will be kept in the DB.
Data history: Instead of deleting the data, it can be migrated either to a file system or to a historical database.

Types of Entities and how to create them

To make the Entity creation process easier, the Platform offers different options:

Creation Step by step: Through an assistant the JSON-Schema of the Ontology can be generated simply by adding the attributes to include. In addition, a series of basic templates are provided from which to start for the construction of the ontology.

For more information: IoT Workshop

Creation from file: From a file with data to be stored, the ontology's JSON schema is extrapolated. It offers the possibility of loading the records that are included on the file.

Creation from an external relational database: Using a defined connection to an external DB, it allows to select tables to generate its representation as ontologies (JSON-Schema). The platform will act as a connector with the external DB when operations are performed on the ontology.

For more information: Creating an ontology from a relational database and showing it in a dashboard

Creation from a Rest API: It makes available an Rest API as an ontology. For this, it will be necessary to define the mapping of the API Rest methods with the operations that can be performed on the ontology.

For more information: Creating an ontology from a REST API and use examples with FlowEngine and Dashboards

KPI creation: It allows defining an ontology whose values are KPIs generated using stored information.

For more information: (Ontologies) Creating a KPI to measure my business outcomes

Creation of Timeseries: An ontology of type TimeSeries is characterized in that its scheme describes the structure of the instances that the IoTBroker receives, but not the structure of the instances stored in the Database engine, that is, and as we will see later , the platform makes an internal management of the received data, to build a more efficient grouping of the different signals.

For more information: TimeSeries Support on Ontologies

Once the Entity has been defined, the data model has been defined, you can proceed to implement functionalities on it.

platform-doc-en

Introduction to Entities

Introduction

Definition and structure

Properties of an Entity

Types of Entities and how to create them