1. Home
  2. How To Dev - The Dictionary via entity identification: physical, virtual and modules/tools

How To Dev - The Dictionary via entity identification: physical, virtual and modules/tools

 

The Analysis via the Innovation Matrix allows to perform the identification of Entities (or better of the Entity Models), and from Entity Models one should be capable to create a Dictionary to develop scenarios, use cases, requirements and some sequence diagram. We suggest “Some” since to develop all of them may not be needed since the beginning, we are in the agile model. Please identify only those that are the most relevant as: data ingestion, system integration, user registration, data analytics, etc.

For example: Let us now to suppose that we have to develop a solution for monitoring Vehicles and Drivers. Each Vehicle has a profile description and can be driven by a number of drivers over time. Each Vehicle can experience some maintenance and performs trips in the city area. A trip has an official start/end and over time is described by its velocity, acceleration, brakes, charging level, or thank level, etc. Each Driver has a profile and can use a number of Vehicles to perform trips. During the trip also the Driver is monitored for its healthiness, attention, etc., and before, during and after the driving, periodically or sporadically may experience some Analysis to certify its capability to drive in that moment and for the next days. The Driver may experience some warning cases for healthiness, some tickets from policeman, some warning for high-speed velocity or generically bad driving, some problems from the vehicle’s status, etc.

We identified Entities Models such as: Vehicle, Driver, DriverHealthiness, VehicleEvent, DriverEvent, DriverAnalysis.  

The phase of Analysis has identified entities/models classified into

  • Physical Entities / Devices (token, on board unit on the vehicle, device for assessing the drive attention, etc.). All Physical Entities are sending data on the platform on server via some IoT Broker or other data ingestion process, for example via some local application, third party service, IoT Edge solution, etc.
  • Virtual Entities / Devices (Vehicle, Driver, DriverHealthiness, VehicleEvent, DriverEvent, DriverAnalysis). Virtual Physical Entities are managed on server side for managing data and providing a set of user interface views for data entry (registering data) and for data rendering visualization.

See the figure here below for example. All of them, in Snap4City, can be managed as Entity Models, and implemented as Entity Models / IoT Device Models for their definition. Once defined they need to be actually created/instantiated via registration. Once registered they (the device/entity instance: user45driveranalysis) can be used to collect data into the storage by sending messages to the Device instance (for example on: user45driveranalysis).

 


Figure: Example of relationships among Entity Model (IoT Device Model), Entity Instance (IoT Device),
Entity Messages (IoT Device Messages), according to the Snap4City terminology of 2023

Another example: The solution has to provide a User’s interface for registering: Vehicles, Drivers, and Driver Healthiness, and when produced also result of computed Analysis for driver healthiness on some period of time. In the moment in which a Driver is registered (e.g., user45), one should also register the personal DriverAnalysis Entity Instance (IoT device) to be prepared to collect user45 analysis (Entity Messages) performed in many situations over time. For example, as in the figure here above. Monitoring data for real time assessment are performed by Entity Instances (IoT Devices), special Data Analytic performs the Driver Healthiness assessment and provides the assessed score to the Driver Healthiness of the specific Driver. The Analyses may change the status of the Driver confirming that it is enabled to drive or should be pushed to take a rest. Driver Events of start of a Vehicle usage, and of end of Vehicle usage are registered by the Driver which passes its token on the Vehicle. Critical events (e.g., DriverEvent such as a ticket to the Driver, VehicleEvent a Ticket for maintenance of the vehicle, the detection of critical conditions, etc.), are registered as events sent to the systems, from some Entity Instance (IoT Device) or via some operator user interface or computed by some Data Analytics. Monitoring and interacting on the view regarding Vehicle and Driver evolutions and status on the basis of integrated views taking into account Physical and Virtual Entities have to be possible. Please note that, according to the sequence of messages (see the image above), it can be observed that the user45 has changed its status over time. This is what is going to be reported on dashboards and also used in the analysis.

The analysis of the above description allowed us also to identify a number of Entity Models which are neither Physical or Virtual Entities, which would be realized as major entity modules/tools in the solution (which in turn are realized as: Processing Logic / IoT App on cloud or on Edge, Dashboards, Data Analytics processes, and eventually Mobile Apps and Web App using Smart City API). For example:

We suggest, to provide them a name as soon as possible and to enter all Entities in a Dictionary organized as a table. The dictionary should collect both the Data Models and the Modules / Tools you are going to develop in your solution.

 

Dictionary

Term

Entity Model or Module

Kind

Responsible

Status

Spec where

 

 

 

 

 

 

 Driver Healthiness

 DriverHealthiness

 Entity Model

 Dr. Rick Ross

 To be done 

 To be defined 

 User profile A

 DriverA

 Entity Instance

 

 

 

 Vehicle Event

 VehicleEvent

 Entity Model

 

 

 

 Remote Consolle

 MyOperation

 Application

 J.T. Kirk

 To be done 

 lost

 

The columns in green are related to the design phase, which may be not fully specified/filled in the analysis phase.

The legenda for the columns is:

  • Terms for example in Capital Case for the first letter, or CamelCase as you prefer (we suggest not use spaces and neither special characters since most of the programming languages and brokers do not like those characters). For example: Vehicle, Driver, DriverHealthiness, VehicleEvent, DriverEvent, DriverAnalysis
  • Entity Models or Module:
    • Data Model: FIWARE Data Model, IoT Device Model, custom model, smart data models, etc.
    • Modules could be specific, for example:
  • Kind: Entity Model, Entity Instance, Processing Logic / IoT App on cloud or on Edge, Dashboards, Data Analytics processes, Mobile Apps and Web App, third party tools, etc.;
  • Responsible: who has to develop and/or maintain
  • Status: inherited, already accessible, to be customized, to be finalized, to be done, in cloud, on edge, etc.
  • Spec Where: location of the description, of the specification. It can be a document or a link.

External API: have to be identified and listed to allow to interoperate with the platform and among partners/developers.

Each external API should be:

 

External API

 API name

 API url and shape

 Kind

 parameter

 Credentials approach

 Status

 Description, Swagger  link, Postman, …

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The columns in green are related to the design phase, which may be not fully specified in the analysis phase.

In Snap4City, External API of third-party services can be:

In Snap4City, dedicated custom API could be created from Processing Logic /  IoT App.

This practice is strongly discouraged for a number of reasons reported as follows:

  1. Custom made APIs from Processing Logic / IoT APP should be avoided,
    1. They are not secured. they are not authenticated and neither support the authorization control for their access. API provided from Processing Logic / IoT App, would not to be easily secured, and very difficult controlled into the general SSO of the system.
    2. The interpretation of the REST call parameters should be performed into the Processing Logic / IoT App and also the search of entities and filtering.
    3. They are not scalable in terms of multitasking support. 
  2. Most of the API that you are going to create in Processing Logic are typically created to provide data results may be requesting them to the storage. So that, the same data can be easily obtained by using Snap4City Smart City API, which are in place, authenticated, controlled in access and scalable.

Moreover:

Any API call that you need to access at Data Time Series, data collections, and data instance status (on the basis of some variable and filters) can be easily implemented by using Snap4City Smart City API. 

  • See for smart city API call and filters in Section IV.C.4.
  • See for authentication before calling API in snap4city in Section IV.C.5

Please use Smart City APIs which provide:

  • a large set of facilities to get data filtering them by area, path, GPS locations, distance; date and time interval; value of the variable of the models; IDs of the entities, etc. They are authenticated and provide data according to the authorization accesses of the user. So that, they are very useful for implementing services from Mobile App, etc. Thus, increasing flexibility and simplifying the solution. 
  • Authentication and authorization mechanism, see Section IV.C.5  
  • Robustness to the cybersecurity attacks, reliability
  • documented in swagger, see Section IV.C.4  
  • Support for scalability

Please note that mobile app and third-party tools accessing to Snap4City API need to have a ClientID (which is going to identify the kind of client is approaching the platform, for safety reason) registered on KeyCloak, please ask, see Section IV.C.5.

External Services can be used to insert into the user interface and Dashboards elements coming from third party applications. They have to be listed as:

  • URL, parameters, size of the screen
  • IFRAME constraints

Please note that in Snap4City they can be easily listed and, in a click, integrated into Dashboards.

External Services

 URL

 parameter

 Description

 Nature

Subnature

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

  • Share