Deltares · ekkelenkamp · Dec 12, 2023 · Dec 12, 2023 · Dec 12, 2023
diff --git a/docs/private/npm/img.png b/docs/private/npm/img.png
diff --git a/docs/private/npm/release-process-npm-packages.md b/docs/private/npm/release-process-npm-packages.md
@@ -0,0 +1,35 @@
+# Publish npm packages with lerna and NPM
+
+To build a new release of one of the npm packages, follow the following steps. Either use lerna or npm, depending on the package.
+
+For the SSD Requests library use:
+
+    lerna version prerelease (will create a tag a push a tag automatically)
+
+for the other libraries use:
+
+    npm version 0.2.7.alpha.0
+    git push origin v0.2.7.alpha.0
+    git push
+
+The following steps are performed with git:
+
+Update the version in package.json and create a tag:
+
+    npm version 0.5.17-alpha.0
+
+Push the tag (N.B. the tag is prefixed with a v)
+
+    git push origin v0.5.17-alpha.0
+
+Push the commit
+
+    git push
+
+GitHub steps:
+
+Create a new release in GitHub: v0.2.7.alpha.0 and chose the correct tag. A GitHub action will test this release and deploy to NPM if successful.
+
+If the release was build successfully, test with this release in the web oc.
+
+If the tests are successful, create a final release
diff --git a/docs/public/README.md b/docs/public/README.md
@@ -0,0 +1,52 @@
+# The Delft-FEWS Web OC documentation
+
+Landing page for Delft-FEWS Web OC documentation
+
+## Web OC Project
+
+See [Web OC Project](project/). This page includes background information on the Web OC project such as:
+
+- Introduction (link to Delft-FEWS vision and roadmap)
+- Development goals
+- Development process
+- Project time line
+- Present software status
+- Future development plans
+- How to use Web OC in your organization?
+- Delft Software Days presentations on Web OC
+
+## Technical Architecture
+
+See [Technical Architecture](architecture/). This page includes information on the technical architecture of Web OC and in addtion covers the folowing:
+
+- Licensing and Software distribution
+- Release management
+- Support and Maintanance
+
+## Web OC Delft-FEWS configuration
+
+See [Web OC Delft-FEWS configuration ](configuration/). This page includes information on the Delft-FEWS configration for Web OC and in addtion covers the folowing:
+
+- Web OC navigation using Topology
+- Other WEB OC functional components
+- Permissions
+
+## Web OC Application configuration
+
+See [Web OC Application configuration ](app_configuration/). This page includes information on the application configuration for Web OC.
+
+## Web OC Deployment
+
+The Web OC can be built with npm:
+
+```
+npm run build
+```
+
+A dist folder is created that can be used to deploy the web oc to different platforms, like Azure, Tomcat and Nginx.
+
+See [Deployments](deployments/) for more information on how to run Web OC stand-alone and/or from a webserver.
+
+## Authentication and Authorization with Open ID Connect
+
+See [OIDC](oidc/) for more information.
diff --git a/docs/public/app_configuration/README.md b/docs/public/app_configuration/README.md
@@ -0,0 +1,17 @@
+## Application Configuration
+
+The application configuration is stored in the `.env` or the `public/app-config.json` file. All settings are provided as a key-value pair.
+Settings in the `.env` file are parsed on build time, while settings in the `app-config.json` are handled on run-time.
+The following settings can be provided:
+
+| Key                                 | Description                                                                                                           |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `VITE_FEWS_WEBSERVICES_URL`         | Url of the FewsWebServices, e.g. "https://rwsos-dataservices-ont.avi.deltares.nl/iwp/FewsWebServices"                 |
+| `VITE_REQUEST_HEADER_AUTHORIZATION` | 'Bearer': pass OIDC `id_token` as bearer for request to the FewsWebServices                                           |
+|                                     | 'Off': no Authorization request header                                                                                |
+| `VITE_AUTH_AUTHORITY`               | Url of the OIDC authority, e.g. "https://login.microsoftonline.com/MYTENANTID/".                                      |
+|                                     | If not configured the web oc can be accessed without authentication.                                                  |
+| `VITE_AUTH_METADATA_URL`            | Url of the OIDC meta data, e.g. "https://login.microsoftonline.com/MYTENANTID/v2.0/.well-known/openid-configuration". |
+| `VITE_AUTH_SCOPE`                   | Scope, e.g. "openid profile email Offline_Access api://myclientid/Delft-FEWSWebServices".                             |
+| `VITE_REQUEST_HEADER_AUTHORIZATION` | Url of the OIDC meta data, e.g. "https://login.microsoftonline.com/MYTENANTID/v2.0/.well-known/openid-configuration". |
+| `VITE_MAPBOX_TOKEN`                 | Mapbox token. Can be retrieved from: https://account.mapbox.com/access-tokens.                                        |
diff --git a/docs/public/architecture/README.md b/docs/public/architecture/README.md
@@ -0,0 +1,78 @@
+# Technical Architecture
+
+The Delft-FEWS Web Operator Client (Web OC) will interact with the Delft-FEWS database by means of the FewsWebServices API. However, by using the FewsWebservices API, organizations are not limited to front-end applications developed by Deltares. There are various levels to interact with our software components (fig.1):
+
+- Develop your own web applications on top of FewsWebServices, without using any further front-end components developed by Deltares.
+- Make use of Typescript libraries (to interpret FewsWebServices API calls) developed by Deltares in your own web applications connected to Delft-FEWS.
+- Re-use Web OC front-end components (HTML5) as well as Typescript libraries in your own web applications connected to FEWS. Or use components as a reference for your own implementation in a JavaScript framework.
+- Use the entire Web OC stack including back-end and front-end components as developed by Deltares
+
+Diagram below shows the software architecture of the Web OC in relation to Delft-FEWS.
+
+![Web OC diagram](./web_oc_diagram.png)
+
+## Technical framework
+
+The following software frameworks are used to develop Web OC
+
+|              | Delft-FEWS Web OC         |
+| ------------ | ------------------------- |
+| Language     | Typescript and Javascript |
+| Framework    | Vue.js (Vue 3)            |
+| UI Framework | Vuetify3 + Vite           |
+| Maps         | Mapbox                    |
+| Charts       | d3js + custom, eCharts    |
+
+_Please note that we are currently in the proces of migrating Web OC from the Vue 2 to Vue 3 framework_.
+
+## Licensing and Software distribution
+
+Components 1 (Delft-FEWS database) and 2 (FewsWebServices API) in the diagram above are already part of the Delft-FEWS software suite. The license under which these components are made available and the manner in which they are provided will not change with introduction of the Web OC. Additionally, Deltares intends to offer new components 3 to 6 as in addition to the current Delft-FEWS software:
+
+#### Web OC Typescript libraries:
+
+1. fews-pi-requests
+2. fews-ssd-requests
+3. fews-wms-requests
+
+#### Web OC HTML 5 components (currently available)
+
+1. Schematic status display component
+
+#### Web OC Vue components (currently available)
+
+1. Topology component
+2. SSD component
+3. Spatial display component
+4. System monitor component
+
+#### Web OC Application
+
+1. Web OC application
+
+The idea behind the above architecture is that different consumers (existing or new FEWS end-users/intermediaries/consultants) of the Web OC software can connect at their relevant level of the architecture. A few examples:
+
+1. A customer of Deltares needs a web interface for their Delft-FEWS environment. The customer acquires the complete Web OC application from Deltares. Any software development is carried out by Deltares.
+2. Similar to (1), except the customer (or a customer consultant) wants to make modifications to the Web OC code for their own use. The customer acquires the complete Web OC application from Deltares and makes modifications to the underlying Vue components, HTML components, and libraries.
+3. A consumer intends to present information from FEWS in a web environment not developed or to be developed by Deltares (i.e., not a Web OC application). When consumers want to present the data in a similar way to one of the Web OC components, they can use Web OC HTML 5 components. These components are JavaScript-platform independent and can thus be reused in platforms other than Vue.js.
+4. Similar to (3), except consumers want to present data in their own unique way and do not want to use Web OC HTML 5 components. A consumer can then utilize the Web OC TypeScript libraries and develop their own web components based on them.
+
+Based on the described usage above, the Web OC TypeScript libraries and HTML5 components are available under the Permissive MIT license. This allows the use of Web OC libraries and components in packages developed by third parties with a different licensing model.
+Components 5 (Vue components) and 6 (Web OC application) are made available under the "Copyleft/protective" GNU AGPL license. With this license, it is prohibited for consumers to include the Vue components and/or the Web OC application as-is in their own software without also making the source code of such software available under the AGPL license, thus preventing it from becoming proprietary software.
+
+### Software distributions:
+
+- Web OC Application and components: https://github.com/Deltares/fews-web-oc
+- PI REST libraries: https://github.com/Deltares/fews-pi-requests
+- SSD libraries : https://github.com/Deltares/fews-ssd-requests
+- WMS libraries : https://github.com/Deltares/fews-wms-requests
+
+In the case of Deltares customer-specific orders for one or more of the software components 1 to 6 (Figure 1: Delft-FEWS Web OC Architecture), the existing FEWS executable License Agreement will be used. In the specific customer contract, a product will be delivered based on specific requirements, and within this customer contract, we will extract the product (IP, liability, warranties) from the customer contract terms and apply the FEWS License Agreement terms, including the customer's indemnification for the use of the FEWS component(s).
+
+## Release management
+
+Information to be added.
+
+## Support
+
+The Delft-FEWS Web OC will become an integral part of the overall Delft-FEWS product (see section Development goals) for which Deltares provides dedicated S&M packages: https://oss.deltares.nl/web/delft-fews/services .
diff --git a/docs/public/architecture/web_oc_diagram.png b/docs/public/architecture/web_oc_diagram.png
diff --git a/docs/public/configuration/README.md b/docs/public/configuration/README.md
@@ -0,0 +1,78 @@
+# Web OC Delft-FEWS configuration
+
+## Introduction
+
+In order to connect Web OC to a FewsWebServices instance, some basic configuration is required in app-config.json. Please refer to: https://github.com/Deltares/fews-web-oc/blob/main/README.md.
+All configuration related to what content is being displayed in Web OC, is managed by the Delft-FEWS configuration. For general documentation on this matter please refer to: https://publicwiki.deltares.nl/display/FEWSDOC/Configuring+Delft-FEWS+-+Configuration+Guide
+
+Key files in the FEWS Configuration to get started with Web OC are:
+
+- WebOperatorClient.xml (SystemConfigFiles). Configure available Web OC components as well as general items like title and logo: https://publicwiki.deltares.nl/display/FEWSDOC/11+Web+Operator+Client
+- WebServices.xml (PiServiceConfigFiles). Web OC highly depends on what data is made available through FewsWebServices, Use this configuration file to configure a filterId, permissions etc.: https://publicwiki.deltares.nl/pages/viewpage.action?pageId=220266993
+
+Although Web OC will run without any further adjustments to the Delft-FEWS configuration, its strongly recommended to spend some time on your Topology configuration in relation to Web OC (see below).
+
+### System time
+
+Please note that Web OC will always use the system time of the Web OC users device as Web OC system time. This time setting can not be modified by Web OC configuration.
+
+## Web OC navigation using Topology
+
+- While the Web OC does not aim to become a copy of the "thick" client, it is explicitly built based on the underlying FEWS configuration. Think of items such as display groups, SSD, filters, grid plots, etc.
+- The current FEWS Client has a multitude of tree/folder structures (Filters, Spatial Display, Topology, Display Groups, Manual Forecast) that we prefer not to duplicate in Web OC. Ideally, we want to use a single menu/folder structure from which various data displays can be accessed, and actions can be taken.
+- The architecture of the Web OC lends itself to the development of different functional components and displays for specific use. Nonetheless, we want to offer basic components that provide an excellent starting point for many users.
+
+When we want to limit ourselves to a single menu/folder structure configured in FEWS for navigation in Web OC, it is logical to base this on Topology.xml. In Web OC, the entire Topology structure is displayed, to which the Web OC user has access via FewsWebServices.
+
+For the general configuration of Topology.xml, please refer to https://publicwiki.deltares.nl/display/FEWSDOC/24+Topology.
+
+Topology nodes in the Web OC component TopologyDisplay can be linked using Topology.xml as described below.
+
+| **Link topology node to** | **Config item** | **Back-end support** | **Web OC Support** |
+| ------------------------- | --------------- | -------------------- | ------------------ |
+| Spatial Display           | PlotId          | Yes                  | Yes                |
+| Filters                   | FilterId        | Yes                  | Yes                |
+| Web Browser               | url             | Yes                  | Yes                |
+| DisplayGroup              | DisplayGroupId  | Yes                  | Yes                |
+| Run Task                  | WorkFlowId      | Yes                  | Not yet            |
+| SchematicStatusDisplay    | PanelId         | 2024.01              | Not yet            |
+| System Monitor            | TabId           | 2024.01              | Not yet            |
+
+**Spatial Display**
+
+Web OC will show a map, displaying the configured plotId linked to the selected topology node. Use the `<gridDisplaySelection>` item in Toplogy.xml to configure a plotId. A time slider will show up for navigation in time. The period covered by the time slider is based on the configured relative view period of the time series in the GridDisplay.xml with reference to the system time of Web OC (system time of users device).
+
+**Filters**
+
+Web OC will show a map, displaying all locations configured in the filterId linked to the selected topology node. Locations are also listed in a drop down menu. Use the `<filterId>` item in Toplogy.xml to configure a filterId. By selecting a location on the map or from the list, time series graphs will be displayed for all parameters configured in Filters.xml for the linked filterId. Time series graphs are grouped by parameterGroup. The period shown in the graph corresponds to the configured relative view period (relative to Web OC system time) of the time series in the Filters.xml
+
+**Web Browser**
+
+When a `<url>` element is configured in the selected topology node, Web OC will open a new browser window for the url configured.
+
+**DisplayGroup**
+
+Web OC will show a time series graph and a drop down menu for selection of displays within the configured displayGroup. Currently, two configuration options are supported by Web OC to link DisplayGroups to Topology nodes:
+
+1. Configure a `<nodeId>` element for a DisplayGroup in DisplayGroups.xml. No additional configuration required in Topology.xml.
+2. Configure a `<displayGroupId>` element for a Topology node in Topology.xml
+
+The period shown in the graph corresponds to the configured relative view period in DisplayGroups.xml
+
+### Permissions
+
+By assigning viewPermissions in Topology.xml, it is possible to configure nodes for Web OC users that do not affect usage in the "thick" client. If authentication is not used for Web OC, permissions can still be utilized by configuring "defaultUser" in WebServices.xml (https://publicwiki.deltares.nl/pages/viewpage.action?pageId=220266993). The Web OC component that utilizes Topology.xml is TopologyDisplay.
+
+## Other WEB OC functional components
+
+Next to the Topology Display, three additional components can be configured in WebOperatorClient.xml: spatialDisplay, systemMonitor and schematicStatusDisplay.
+
+**spatialDisplay**: A tree view will list all gridPlots (configured permissions respected) from the Spatial Display. Selected dataLayer will be displayed on the map.
+
+**systemMonitor**: “Import status” and “Running Tasks” components of system monitor will be displayed in Web OC.
+
+**schematicStatusDisplay**: A tree view will list all SSD displayGroups including all displayPanels (configured permissions respected) available to FewsWebServices. Most click-actions on displayPanels are supported: https://publicwiki.deltares.nl/display/FEWSDOC/FEWS+Schematic+Status+Display+%28SSD%29+Web+Service
+
+## Known issues
+
+- The FewsWebServices _thinning_ option is used (https://publicwiki.deltares.nl/display/FEWSDOC/FEWS+PI+REST+Web+Service#FEWSPIRESTWebService-GETtimeseries) while retreiving data for Web OC timeseries graphs and tables. This function tries to keep the peaks and gaps and minimizes the number of time steps that have to be retrieved. Eventually, _thinning_ should not be used for timeseries tables. In future releases of Web OC _thinning_ will only be used for timeseries graphs.