Main concepts
In BBData, datasources are represented by virtual objects which belong to zero or more object groups. Users belong to one or more user groups. User groups have access to zero or more object groups.
Virtual objects
Virtual objects are the most important abstraction in BBData. A virtual object represents a datasource; it is a container that holds measures of the same type.
Mapping
Real word sensors can be mapped to one or many virtual objects. To better understand the concept, let's see some examples of virtual objects.
- one-to-one mapping: A basic sensor measuring the temperature of the room is mapped to one virtual object.
- one-to-many mapping: A more complex sensor able to measure the temperature as well as the humidity and the number of times the door opens needs three virtual objects. This way, temperature measures won't be mixed with humidity and aggregations will be performed separately for each type of measurements.
- many-to-one mapping: say we have a building with temperature sensors on each room, but we are only interested in the global temperature. As long as the different sensors don't emit measures at exactly the same time, we could use only one virtual object in BBData. This way, aggregations will be automatically performed to reflect the whole temperature in the building.
Metadata
Metadata are associated to each virtual objects:
- id: a unique identified, generated automatically be the system upon creation.
- creation date: when the object has been created.
- name: an arbitrary name, maximum 45 characters long.
- description: an optional description, such as the localisation of the datasource.
- unit: the measure unit, such as
vol,degreesoron/off. The object's unit determines the measure type (string, boolean, float or integer). - tags: a list of user-defined tags. Tagging objects makes tag-based search and lookups possible.
- state: an object can be enabled or disabled. Disabled objects cannot receive new measures.
- owner: as explained below, an object belongs to a usergroup. Only administrators of the owning group can make modification to the object.
Info
Currently, aggregations are performed only on objects with unit lx, m/s, %, A, ppm, V, W or °C.
Object groups
Object groups let user group similar objects together.
An object group has zero or more objects, while objects can be part of zero or more object groups. Furthermore, an object group belongs to a user group and all its objects must have the same owner.
How to group objects is left to the user. Common grouping schemes are location (site 1/level 1, site 1/level 2, etc.) and function (thermostats, electricity, etc.).
Object groups can also be used to share some objects with another user group, either temporarily or permanantly. Indeed, creating or deleting a group won't alter the objects, making them highly flexible.
Users and usergroups
A BBData user can belong to one or more user groups. Users in user groups can be one of two kinds:
- regular user: a regular user has read-only access to objects in object groups that the user group has access to;
- administrator: an administrator can create, edit and modify objects, manage object groups and grant/revoke permissions on behalf of the user group.
User rights and sharing
The notion of ownership is used to determine who can modify or delete a resource (objects, object groups, etc). Only user group administrators are allowed to create, edit or delete resources. A resource belongs to the user group that created it.
Using user groups and administrators instead of user-based ownership avoids troubles when someone quits the system. Indeed, as long as groups have administrators, resources are always editable.
The notion of sharing determines who can access resources in read mode (get metadata, query values, etc). By default, all regular users of the user group owning a resource can access it in read-only mode. Furthermore, an administrator can decide to share an object group with other user groups. The right is transitive: if a user group UG can access the object group OG, any user U in UG can access all the objects in OG.
In the image above,
- U1 can edit O1 and access data (read-only) associated to objects O2 and O3;
- U2 can access data (read-only) associated to objects O2 and O3;
- U3 can edit O2, O3 and O4;
- U4 can access data (read-only) associated to objects O2, O3 and O4;
Given the permission graph, we can also guess that O1 has been created by UG1, and O2-4 by UG3.
Security
REST endpoints need to be secured by an authentication mecanism. To achieve that, we use tokens and apikeys. Both tokens and apikeys are cryptographically secured, randomly generated strings of 32 characters.
Tip
Tokens and apikeys can be managed through the admin webapp.
Tokens
Tokens are associated with objects and are used to submit new measures (input api). Most of the time, tokens are used by applications or middleware, not by humans. For each new measure, the input api checks that the pair <token, objectID> in the body is valid. If not, the measure is simply discarded.
Objects can have multiple tokens. It is the charge of the administrators to ensure they stay secret. In term of rights, only administrators of the usergroups who created an object can view, create and delete its tokens.
Apikeys
Apikeys are associated with users and are used to access the output api.
Apikeys have two extra properties:
- expire: apikeys may have an expiration date;
- read-only: apikeys can be read-only or read-and-write.
To get an apikey, users login to the output api using the /login endpoint. They provide their username and password and the api returns a read-and-write token valid for two hours. To revoke the apikey before its expiration, a /logout endpoint is also available.
If users want to grant access on their behalf to an application, for example to automatise object creation or data retrieval, they can also create apikeys explicitly with the settings they see fit (see the /me/apikeys endpoint).
It is important to stress that an apikey gives access to the api on behalf of the user: it is his responsibility to manage them properly.