Skip to content

3.1 Workflow

Stroomversnelling edited this page May 24, 2019 · 2 revisions

Installing a monitoring system (before using the API)

  1. The identity provider creates - through the UDB - a new "connection_id" that is unique together with the UDB Resource Server url.
  • The connection_id is added to the UDB Resource Server.
  • The connection_id is coupled with the connection address in the UDB Resource Server.
  • The connection_id is coupled to a PDB Resource Server url with a start and end date.
  1. The identity provider describes the contract situation for the connection. These determine access rights.
  • The "contract" object identifies the relationship between a connection_id, role, start and end date for a user with a valid token. A single user can have an array of associated connections.
  1. An assignment is given to place a monitoring system at the specified address with the corresponding connection_id for the device(s) in the building. The url of the UDB authentication server and the UDB resource server are also provided. These urls are added to the PDB database as trusted UDB urls for the specific connection_id.

  2. The contractor installs the devices and links within PDB the data from the device to the correct connection_id.

  3. When no longer required for this task, the address information is destroyed everywhere except for in the UDB Resource Server or in the owners internal database.

Changing a monitoring system

For the simple addition or replacement of devices with the same contractor, the corresponding data object coupled with the connection_id must be correctly adjusted in the PDB (in the "config" object).

Changing a component of a monitoring system

There is more than one good way to change a component or device of a monitoring system and the Monitoring API does not prescribe how to do it. Good practice is:

  1. Deactivate the old device ("data_object"). Do not remove the data from the device. This means that every data_object should have a status. (It does not have this yet in version 0.5.)

  2. Add data, do not manipulate data.

  3. Beware of the difference between cumulative and pulse sensors. Data loss for pulse sensors is more problematic than for cumulative sensors.

Creating a new user

  1. The Identity provider can register / create new users with the UDB Authentication Server. The specific details of user management (activation, emails, password changes, password resets) are outside the scope of this document.

  2. The Identity provider can register / create new contracts for each users in the UDB Resource Server. A contract includes one connection_id, a start and end time, and a role.

Logging in

  1. The user may log in with APP specific user credentials.

  2. The APP will have a (list of) UDB urls for the user.

  3. The user is redirected to the UDB and logs in. The UDB authorization server verifies the login information. The APP can do this in the background.

  4. Recommended OAuth2 flows: the Authorization Code Flow for Single Page Apps (SPA) and the Authorization Code with PKCE Flow for Native Apps.

Renter leaves their home owned by a housing corporation

  1. Identity provider changes the UDB Resource Server contract table to reflect the actual end date for the tenants' old home.

  2. The APP will then still be allowed to query historical data from the timeperiod of each contract from the PDB. The APP must be able to support both historical and current contracts.

  3. In case there is a display in the home with energy performance data: home owner resets the display either physically or remotely.

Renter moves to a new home owned by the same housing corporation

  1. See use case above regarding data from the old home.

  2. A new contract is added with the new connection_id for the users new home and accompanying role, start and end date.

User buys a (new) house

  1. The monitoring provider may recommend an identity provider to the user. The user registers with the Identity provider.

User wants to receive an alarm when the installations are not performing as expected

  1. The APP may be setup to provide an alarm under certain conditions. This may be logic within the APP itself or may be errors queried from the PDB on periodic basis.