Introduction
The goal in this workshop is to know onesait Platform's main tools to integrate IoT solutions.
To do this, we will model a case to integrate a connected sensor, which reports atmospheric values to the platform. Starting in the data model and device's connection, data will be remotely inserted in the platform. After these steps, exploitation tools will be used on this data, to transform it, visualize it or share it with other systems.
Defining an ontology in the Platform
Onesait Platform is a data-centric platform, inasmuch all the entities in the platform refer to the agreed data model to model the elements in a solution. When we talk about an ontology, we refer to that data model chosen to exchange information between involved devices and systems. Through the ontology, we can model and define what data, and in what format, the platform accepts for my device.
There are several ways to create ontologies in the Platform (https://lab.onesaitplatform.com/controlpanel/ontologies/create):
For this workshop, we will create an ontology step by step. An example could be the following ontology:
Among the provided templates, in the creation wizard's left side, we can start with Empty Base, under the General category, that starts with an empty schema. When the sensor fields are added, it will look like this:
For every field in the ontology, we can select the type of the data to be stored, whether it is required by the platform in the message exchange or not, and whether we want to encrypt the information on it. At the end, if we click on the Update Schema button, we will see the JSON Schema that's appropriate for the defined categories. Besides, if we click on Generate Instance, we will see an instance of the defined ontology:
If everything is OK, when we click New, the ontology is created. Just after that, the platform guides us and suggests several choices to continue defining our solution. Following this example's flow line, we will click on: 'Create new Digital Client for this ontology'.
Creating an Digital Client in the Platform
The Digital Client entity is a record in the platform used as an interface with the different ontologies to which it can access. In a typical case, an Digital Client is defined for a device type that will insert or consume a subset of ontologies.
Accessing from the screen in previous image or from this URL: https://lab.onesaitplatform.com/controlpanel/devices/create , we can define the Digital Client by filling in the required fields and by selecting the involved ontologies. For this workshop, we will select the ontology we have just created in the previous step.
And, once we click on New, it is created.
Digital Broker – Practical example using Node-RED client
With the ontology and with the Digital Client, we already have the platform elements we need to start receiving information from IoT devices. In this case, we will use the platform's Digital Broker component to perform the data insert.
For the sake of practicality and speed, we have selected to use a platform client developed with Node-RED, a visual IoT business flow developed system, based on programmable boxes (https://nodered.org/).
You can follow its installation guide for Windows systems in the following URL: https://nodered.org/docs/platforms/windows.
After installing and executing Node-RED, we proceed to install the onesait Platform client package. We can do this graphically, using the palette and searching "onesait" as a keyword:
Or inserting the following command in the console, then rebooting Node-RED:
npm i node-red-contrib-onesait-platform
After the import/install process, there is a pre-configured example on the onesait Platform CloudLab environment, on which we will start the exercise, at: https://flows.nodered.org/flow/989c8da7c08465f132882f24740c835f
Import the URL flow on the Node-RED local instance:
You will see the example flow, with several example cases on an already created public ontology, with its associated Digital Client.
By clicking on any node in the Platform, then editing the Server field, we can see how the Digital Client, with its definition and token, is placed to get the platform's authentication when inserting the data:
Testing with the client's example, we can try and insert a sample by clicking on any insertion flow's trigger. As a result, in the Node-RED console, we will see the id in the Real Time Database (BDTR), where the ontology instance has been inserted:
And consecutively we can explore the different flows and operations that the example implements.
Once we are familiar with the client, we can adapt it to the ontology and the Digital Client we created for this example. To do this, and focusing in the insertion flow, we must perform the following operations:
- Modify the pre-set ontology name to the one we created in the workshop.
- Adapt the ontology instance (JSON) to the one we defined in the JSON-Schema.
- Adapt the server's settings with information on our Digital Client.
To access the Digital Client information, we must open it in this URL: https://lab.onesaitplatform.com/controlpanel/devices/list. By clicking on the one we had been using, we will view both its id and the associated token.
If the editions were executed correctly, when we insert, we will get a new BDTR id, this time for our ontology.
To check this insertion, we can explore it using the platform's query engine, or Query Tool, at: https://lab.onesaitplatform.com/controlpanel/querytool/show
And we will check that we have inserted the first real data on our ontology.
Flow Engine – Creating business rules
Onesait Platform provides a customized environment for each user, on which we can develop visual logic following the Node-Red paradigm. You can find it in this link: https://lab.onesaitplatform.com/controlpanel/flows/list
After creating and booting the environment, we will test one of the most used cases in the platform, due to its ability to act as the main entity in an IoT solution: Subscription to message insertion.
To do this, we will create an easy flow with the onesaitplatform-notification-endpoint node, followed by a Debug node:
After configuring the node with the ontology we want to listen and the operations we want it to react to, we deploy with by clicking on Deploy.
After this, to simulate a real flow, we must go back to our PC's Node-RED environment and insert a new value. Then, if we go to the Platform's Flow Engine console, we should be able to see an event triggered by that remote insert: 
With this, we can now consider this insertion to be the trigger event for different business rules using Node-RED's pre-configured nodes or the function nodes where we can insert logic in JS. For instance, I can use Twitter to report an alert depending on the insertion value, using a flow like this one:
API Manager – Interact with your data or with other systems
Onesait Platform has an API Manager allowing for the creation of interfaces on the platform's ontologies, either to perform data inserts through it, or to consume them from other systems.
This component is particularly interesting to integrate other systems in the platform, because many solutions, such as device ones, have a provider-supplied system that performs PUSH inserts to a client's endpoint. From this component in the Platform, we can provision such end-point.
To create an API, simply browse to this URL:
https://lab.onesaitplatform.com/controlpanel/apimanager/create
In this workshop, we will use an API for our ontology and fill in the fields in this form:
We will also define an Insert operation and a Custom Query operation that will return the last 5 inserted values:
After the creation, we must pass it to Development, in the API list page:
https://lab.onesaitplatform.com/controlpanel/apimanager/list 
After this, using any REST client, we can invoke the Query we had defined, simulating an external system. To do this, we need to invoke the created URL and add these HEADERS to the GET call:
You need to get a user token to fill in the HEADER X-OP-APIKey. It is in the following URL:
https://lab.onesaitplatform.com/controlpanel/apimanager/token/list
Then you will get the values provided by the query, now in our remote system:
