| Product(s): | WaterSight |
| Version(s): | 10.00. |
| Area: | Documentation |
Overview
WaterSight consists on a cloud application which heavily relies on integration with real time data from sensors (from SCADA systems, dataloggers or any other telemetry system). To automatically integrate this data there are two main methods:
- Using Data Pusher tool, which can directly connect to the sensors databases
- Through a Rest API connection
Below it is presented a summary with the main types of connection.
For more complete detail on how to setup the connections, please ask your Bentley point of contact for the OFOSC and RestAPI Detailed Guide.
1. Data Pusher (OFOSC) - Types of connection
WaterSight consists of the cloud application and includes also an on-premise software tool called the “Sensor data pusher.” The WaterSight Sensor Data Pusher collects and pushes the raw Sensor values periodically to the WaterSight cloud database at a predefined interval. The sensor data pusher can connect to the following data sources:
- ODBC
- OLEDB
- OPC HDA / OPC DA
- SQL Server Source
- Oracle Connection
- Access / Excel
The data pusher should be installed in a on-premise machine or server that has the right access to the defined data sources, in order to ingest raw Sensor data into WaterSight in the Azure cloud. The installation of this pusher tool will only be done after the utility provides all the access and permission to the on-premise machine and data sources.
Information that the utility needs to prepare (if database connection):
- Machine/Server: will need temporary access to a machine or server that has direct access to the sensors database. This machine or server needs to be turned on 24 hours/7 days:
-
- Connection could be made, for example VPN connection (preferred way) or trough other remote-control tools (for example, Teamviewer or other) – username and password for that VPN connection and the credentials for remote desktop connection
- Need the credentials (username and pass) to enter in the machine or server
- Database connection access
- Server name (or IP)
- Login (user)
- Password
- Database information
- Name of the database
- Name of the table or view
- Table needs to have at least the following columns: Sensor ID/tag, value and Timestamp
- ID of the sensors and the units in the database
If sensors and smart meters are both available, it is required to set up two instances of the OFOSC, one for sensors and the other one for the smart meters.
Data Pusher General Architecture
Minimum data requirements for the server where the Sensor data pusher gets installed:
- The machine must always be running 24 hours/7 days a week
- Minimum RAM recommended for operating system
- Minimum 4 Core CPU
- Disk space (3 GB initially) for OFOSC files and historical data back-fill
- Windows 10 or a recent Windows Server
- Windows Service User account with Administrator privileges
- .NET Framework installed (ideally)
- Allow the following connections through firewall:
-
- connect-watersight.bentley.com
- (connect-watersight-weu.bentley.com if hosted on Western European site)
- Port 443
- Having WaterGEMS installed
RestAPI Connection
As an alternative to the data pusher, an existing REST API connection can be used if available. In this case, there is no need to install any on-premise component and all the work is done by WaterSight.For this case, the requirements are the following:
- The water utility must provide an API which Bentley will connect to.
- The API must be publicly accessible (i.e. anyone can connect if they are authenticated, see below)
- Authentication credentials must be provided. These can be in the form of or 1) a permanent Personal Access Token (PAT) (using Bearer Authentication), or 2) a permanent user and password (using Basic Authentication), or 3) short-lived access tokens via OAuth client credentials flow. The PAT, user/password or access tokens are by default sent in the “Authentication” header of the request. The PAT or user/password must be valid for the full duration of the project (cannot expire sooner).
- The API must allow requesting data for a sensor (via a sensor id) and for a start instant and an end instant (these are the 3 minimum URL parameters you must have).
- The result of the response body must have, anywhere in the object tree, a list with pairs of instants and values (for the requested sensor and for the requested time range).
- Any timestamps (in the url or response body) are assumed to be in the sensor time zone configured in WaterSight.
Below is an example:
Request:
URL:
GET https://api.mycompany.com?tagId=MySensorTag&startInstant=20230101010000&endInstant=20230201020000
Header:
Authenthication: Bearer MyPersonalAccessTokenHere
Response:
Body:
[
{
“timestamp”: “2023-01-01 00:00:00”,
“value”: 20.0,
},
{
“timestamp”: “2023-01-01 01:00:00”,
“value”: 30.0,
},
{
“timestamp”: “2023-01-01 02:00:00”,
“value”: 15.2,
},
]
In the request url above, “tagId”, “startInstant” and “endInstant” are just examples of the 3 minimum parameters required, and can be replaced by aby naming convention. They can also exist in any part of the URL (e.g. in the base url route or as query parameters).
In the response body above, “timestamp” and “value” can be replaced by any naming convention.For other structures not described above, some additional customization may be required and should be discussed with the Bentley team.
FAQ
1 - Does the Data Pusher needs to be installed in the same machine where database is stored?
No, it is not required. The only requirement is that the database needs to be accessible from the machine where the data pusher will be installed.
2 - How to assure the connection is secure?
Once datapusher is installed, data will start to automatically flow from the utility server to WaterSight cloud following an unidirectional communication. Nothing can flow in the opposite direction (from outside to inside the utility server). Besides this the connection is done via an HTTPs encrypted and secure API, and the utility can still restrict which connections are allowed through firewall.
3 - Is the Data pusher tool compatible with any SCADA or telemetry vendor?
Yes, the only requirement is that the utility needs to provide a temporary access to the database where time series values are being stored. Ideally those databases should be accessible and possible to query using typical GUI (graphical user interface) such as SQL Server Management Studio, Oracle SQL Developer or DBeaver. Some specific SCADA vendors might require the installation of their own driver to be able to read their databases, and in this case the driver should be installed first (it is recommended to reach to the SCADA vendor if that is the case).
4 - Is it required a WaterGEMS licence?
WaterGEMS will be required to install the DataPusher, however the utility can't provide a WaterGEMS license, please reach to your Bentley point of contact for support. For the restAPI configuration, WaterGEMS is not used.
5 - Where is the REST API connection configured?
It is configured in WaterSight, by Bentley team. The user just needs to provide the APU definition (such as the url, how do we define the sensor tag in the request, what are the dates parameters and format of the url and the format of the response; see above for more information). It is also required to fill the sensors list under Admin >> Sensors and have the "Provider" filled with a specific name, which Bentley will use to distinguish the url source.
6- Is any Bentley provisioning or project setup required to enable REST API integration?
As mentioned above, Bentley team will configure that internally in WaterSight.
7- For our project the connection to some sensors will be done via database (Data Pusher) and others via API. Is this supported?
Yes, WaterSight supports some sensors connected via restAPi and others using SCADA pusher.
See Also
OpenFlows WaterSight TechNotes and FAQ's
WaterSight Learning Resources Guide