How To Dev - Analysis: Scenarios formalization


Warning message

You can't delete this newsletter because it has not been sent to all its subscribers.


The scenarios are formalized by using tables. A UML Activity diagram graphically represents a process (or Scenario).

According to the above example, the Main Scenarios to be described may include:

  • The operator registers the driver into the system (the driver is requested to register on the platform before the actual registration on the monitoring activities, thus including the signed consent for GDPR).
  • The Driver takes the Vehicles for day trip: starts, drives (while being monitored), ends.
  • The Driver is assessed in the analysis center, and results are saved and processed allowing or blocking him to drive.
  • The Driver may be monitored on its activity of driving to provide direct real time feedback.
  • The operator analyses the last 3 months of a Driver.
  • The operator analyses the usage of Vehicle.
  • Etc.

The Server/platform has to communicate some notification to the Mobile/Web App in real time. For some cases it could be done with some Web Socket as provided from Snap4City platform and Dashboards, otherwise in most of the cases the communication with third party applications and/or special purpose mobile apps should not need to be in real time. Thus, messages from Operator/client mobile to Platform could be performed by sending messages modelled with some Entity Model but on a specific Entity Instance by sending an Entity Message to a platform broker. Notifications can be internally performed with some changes into the Entity Instance status.

Please note that Mobile App cannot be easily pushed, they have a dynamic changing IP and they do not have web server of APIs to be called easily. The Mobile Applications cannot have a process listener active in real time since the IP address on mobile is going to change, some of the operating system does not allow to have a process active on the mobile phone to reduce the power consumption and the user security. Both Apple and Samsung provide some service to send message in push on the basis of the mobile phone number/id. See for example, APNS (Apple Push Notification Service) of Apple, Airship, Firebase messaging, wonder push, etc.

A simple solution is to develop the mobile app to make periodic polling on the server (dashed lines) to get notifications. If this approach is not viable, there are some services of Apple, Samsung, or third party which use the services of the mobile operator. Another possibility is to send a message to the Driver via SMS, or Telegram. SMS is passing from the mobile operator.

Therefore, since most of the clients are on mobile App. This means that if the data analytics or decision support is taking time and thus the communication back has to be performed Asynchronously from the mobile to the server à that is Asynchronous interaction among elements, or using some services, or a developing platform using an external service.
So that, the Server/platform can change the status of some IoT Device (for example, for remaking that a notification is ready, variable: “NotificationXXYYReady”), and the Mobile App can periodically call the IoT Device via Smart City API (authenticated and authorized) to understand and get the instructions to be performed according to the NotificationXXYYReady, for example a questionnaire. Once the action on mobile app has been done, the Mobile App can patch/post on IoT Device via NGSI V2 patch/post API a new message including the resulting data of the action.
If you have hundreds or thousands of users and actions we suggest staying on Asynchronous interaction, which is more scalable.


Figure: Example of Activity Diagram

The typical interaction from some Web or Mobile App can be based on sending messages to the platform via IoT Orion Broker in NGSI V2 and collecting results asynchronously requesting them via Smart City APIs. In both cases the access to the API (of IoT broker and of the Smart City API), has to be performed by using open id connect. This means that the Web or Mobile App has to get the token and then connect. The Smart City API can also be acted without authentication to get public data.

In the figure here above, the mobile app or the car is notifying to the platform that is starting or beginning is driving turn with a message to the IoT Orion Broker (the message on the Orion Broker will be automatically feed into the storage). If the message is not sent to the Orion Broker but on MQTT, the message needs to be decoded (in most cases) and remapped to an NGSI V2 format. This can be performed in an IoT App on platform.

The Mobile App can immediately ask to the platform server to get the status by using the Smart City API (to verify if the start state has been registered) and may be to get destination or other travel trip information, among those, also the ALERT if the driver cannot drive for example.

Once the mobile app received the authorization to start, the mobile is starting monitoring (position, moving velocity, assessment of the driver, etc.). This is information is provided in push on IoT broker. The Platform will register all of them. A process on the platform, running on IoT App and/or on Python, can analyze the data collected and decide to continue support the driver in driving or informing him to stop or to be more careful. The Mobile App should be in foreground to continuously get information by polling (dashed line) from the direct reading of some device status using Smart City API.

A variant of the above figure can be the figure here below as follows.

Every time a data is entered into the Storage an event occurs into the broker. The server «Inform» can be subscribed from an IoT App to receive in push these changes (red dashed line). To this end, the Snap4City Library of microservices provide a node for subscription on broker.

Figure: Variant of Activity Diagram of the previous Figure


In the image here above, an example of Sequence/Activity Diagram is reported. The driver on its Mobile App, he/she marks the start of the driving section, and the App notifies the change of status to the platform via some broker, once performed all the needed verifications (taking some minutes, may be). The effective change and authorization to start is made accessible by the platform to the mobile app which is requesting the status in pull (dashed line). Then the mobile app starts to monitor the drive status continuously, and send new data (e.g., the level of attention, the road taken, etc.) to the platform via some broker every minute. The arrival of new data may activate some data analytics to perform some analysis of the collected data (red dots) and producing results on the platform data. In the case in which the process detected critical conditions for the driver, the assessment procedure on platform may decide to send an event/message (dashed red, in push from platform to clients) to the operator and driver via a Broker to warning the driving of the lack of attention or for some wrong path. The event in push from platform to client could be a viable approach on some platforms and may have some limitation on Mobile App in which the interaction paradigm can be changed in a periodic REST call from the Mobile to the Platform.

For instance, as explained in the training slides, according to the figure right above:

  • the black continuous line (push) will be used to send some data on the platform broker with a REST call which has to be Authenticated and Authorized according to the OpenId Connect as explained in Section IV.C.5, and would be in the form of:
  • the black dashed line (pull) will be used to request some data from the platform by using a REST call to smart city API (Authenticated and Authorized according to the OpenId Connect as explained in Section IV.C.8), in the forms:
  • the red dashed line (push) will be used to send some data from the platform (from an Orion broker) to some stable IP client or other machine for machine-to-machine communication
  • As a first step the client has to subscribe to some entity on the Orion Broker passing its IP where the broker will have to send the data in push
    • This example refers to NGSI V1 which is deprecated and substituted by V2
      • NGSI V2 examples are reported in Section IV.C.6.
    • The POST will be in the form of /v1/subscribeContext passing as parameters: elementid (the device ID, and K1, K2 (please note that the approach with K1/K2 is mainly deprecated)) or TSL approach
    • curl -X POST "" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"entities\":[{\"type\":\"Ambiental\",\"isPattern\":false,\"id\":\"mypersonaldatatester-device\"}],\"attributes\":[\"temperature\"],\"reference\":\"http://prova/\",\"duration\":\"P1M\",\"notifyConditions\":[{\"type\":\"ONCHANGE\",\"condValues\":\"temperature\"}],\"throttling\":\"PT10S\"}"
    • Please note that
      • the use of K1, K2 is discouraged in favor of more secure solutions see Section IV.C.8),
      • each platform and organization may have different endpoints for this API
  • Then the broker will send the messages to the subscribed client
  • it could be possible to have this kind of push also by using Kafka and/or WebSocket, but this is possible with simple and direct exposed API to all Snap4City platforms.

The external APIs of Snap4City are documented in Swagger

In alternative, for creating some Synchronous user interaction, it could be possible to: