diff --git a/docs/private/npm/img.png b/docs/private/npm/img.png new file mode 100644 index 000000000..7fe30c8c5 Binary files /dev/null and b/docs/private/npm/img.png differ diff --git a/docs/private/npm/release-process-npm-packages.md b/docs/private/npm/release-process-npm-packages.md new file mode 100644 index 000000000..24c4d41fe --- /dev/null +++ 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 new file mode 100644 index 000000000..8f004e506 --- /dev/null +++ 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 new file mode 100644 index 000000000..d349653a1 --- /dev/null +++ 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 new file mode 100644 index 000000000..dfff546ae --- /dev/null +++ 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 new file mode 100644 index 000000000..2f39f2b8b Binary files /dev/null and b/docs/public/architecture/web_oc_diagram.png differ diff --git a/docs/public/configuration/README.md b/docs/public/configuration/README.md new file mode 100644 index 000000000..bb7f42ace --- /dev/null +++ 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 `` 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 `` 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 `` 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 `` element for a DisplayGroup in DisplayGroups.xml. No additional configuration required in Topology.xml. +2. Configure a `` 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. diff --git a/docs/public/deployments/README.md b/docs/public/deployments/README.md new file mode 100644 index 000000000..b83744c1a --- /dev/null +++ b/docs/public/deployments/README.md @@ -0,0 +1,111 @@ +# Delft-FEWS Web OC Deployments + +The Delft-FEWS Web OC is distributed as a single page web application. +When deployed to a server like Nginx or Tomcat it is required to make sure that all requests are mapped to the index.html page of the web oc. +This means that the server will have to redirect all HTTP 404 errors to the index.html. How this can be done is explained per deployment option. + +## Tomcat + +The Delft-FEWS Web OC can be deployed in Tomcat as follows: + +In the webapps folder of tomcat, create a directory named: "ROOT". +Unzip the Delft-FEWS Web OC distribution into that folder. +Create a subfolder "WEB-INF" in the ROOT folder. +Create the file "[web.xml](tomcat/ROOT/WEB-INF/web.xml)" in the WEB-INF folder. + +```xml + + +Delft-FEWS Web OC + + +404 +/index.html + + +``` + +Customize the app-config.json file. + +After starting tomcat the Delft-FEWS Web OC is available at: http://localhost:8080 + +## Azure Static Web App using Azure DevOps + +Using Azure DevOps a pipeline can be created to build and deploy the Delft-FEWS Web OC. +The following is an example of a pipeline: [azure-pipelines.yml](azure/azure-pipelines.yml). +To make sure all requests are redirected to the index.html, the following [staticwebapp.config.json](azure/staticwebapp.config.json) has to be added to the deployment. + +## Delft-FEWS Standalone + +The Delft-FEWS Web OC can be deployed in a Delft-FEWS Standalone as follows" + +In the "Modules" folder of the Delft-FEWS Region Home folder, create a directory named: "weboc". +Unzip the Delft-FEWS Web OC distribution into that folder. +Create a subfolder "WEB-INF" in the weboc folder. + +Create the file "[web.xml](delftfews-sa/Modules/weboc/WEB-INF/web.xml)" in the WEB-INF folder. + +```xml + + +Delft-FEWS Web OC + + +404 +/index.html + + +``` + +Customize the app-config.json file where appropriate. + +After starting tomcat using F12 in the Standalone the Delft-FEWS Web OC is available at: http://localhost:8080 + +## Nginx + +In Nginx the recommended way is to use try_files. See: https://router.vuejs.org/guide/essentials/history-mode.html#nginx + +An example Nginx configuration looks as follows: + +```xml +server { + listen 80 default_server; + listen [::]:80 default_server; + + root /usr/share/nginx/html; + index index.html index.htm; + + server_name _; + location / { + try_files $uri $uri/ /index.html; + } +} + +``` + +unzip the weboc.zip file into the Nginx html folder: + +/usr/share/nginx/html/ + +the WebOC will be available in the root at port 80: http://mynginxserver/ + +## Access to FewsWebServices + +Please note that every user of Web OC requires direct access to the FewsWebServices endpoints by default. If needed, FewsWebServices requests can be re-directed. Please find an apache example below. + +``` +# Redirect FewsWebServices requests to local server. + + ProxyPass http://fewswebservices_host_name:port + ProxyPassReverse http://fewswebservices_host_name:port + + +``` diff --git a/docs/public/deployments/azure/azure-pipelines-archive.yml b/docs/public/deployments/azure/azure-pipelines-archive.yml new file mode 100644 index 000000000..0c964460f --- /dev/null +++ b/docs/public/deployments/azure/azure-pipelines-archive.yml @@ -0,0 +1,45 @@ +trigger: + branches: + include: + - main + paths: + include: + - src/* + - package.json + +pr: none + +pool: + vmImage: ubuntu-latest + +steps: + - task: NodeTool@0 + inputs: + versionSpec: '18.5.x' + displayName: 'Install Node.js' + - task: Bash@3 + inputs: + targetType: 'inline' + script: | + touch .env + echo 'VITE_PUBLIC_PATH="/"' >> .env + + rm public/app-config.json + cat > public/app-config.json <> .env + + rm public/app-config.json + cat > public/app-config.json <> .env + + rm public/app-config.json + cat > public/app-config.json < + + Delft-FEWS Web OC + + + 404 + /index.html + + diff --git a/docs/public/deployments/tomcat/ROOT/WEB-INF/web.xml b/docs/public/deployments/tomcat/ROOT/WEB-INF/web.xml new file mode 100644 index 000000000..6a29e772b --- /dev/null +++ b/docs/public/deployments/tomcat/ROOT/WEB-INF/web.xml @@ -0,0 +1,58 @@ + + + Delft-FEWS Web OC + + + ExpiresFilter + org.apache.catalina.filters.ExpiresFilter + + ExpiresByType image + access plus 10 minutes + + + ExpiresByType text/css + access plus 10 minutes + + + ExpiresByType application/javascript + access plus 10 minutes + + + + ExpiresDefault + access plus 0 seconds + + + + ExpiresFilter + /resources/* + REQUEST + + + + httpHeaderSecurity + org.apache.catalina.filters.HttpHeaderSecurityFilter + true + + antiClickJackingEnabled + true + + + antiClickJackingOption + SAMEORIGIN + + + + httpHeaderSecurity + /* + + + + 404 + /index.html + + diff --git a/docs/public/oidc/README.md b/docs/public/oidc/README.md new file mode 100644 index 000000000..7dc3f9739 --- /dev/null +++ b/docs/public/oidc/README.md @@ -0,0 +1,51 @@ +# Delft-FEWS Web OC Open ID Connect + +The Delft-FEWS Web OC is distributed as a single page web application. +It is possible to enable OIDC as authentication solution and pass access tokens to the Delft-FEWS Web Service API to apply role based access. + +## Azure AD + +The following example explains how the Delft-FEWS Web OC and Delft-FEWS WebServices can be configured to support OIDC. + +In Azure AD 2 app registrations have to be created. + +App Registration for the Delft-FEWS Web OC. For example: Delft-FEWS Web OC Test +![Web OC App Registration](./app-registration-web-oc.png) +App Registration for the Delft-FEWS Web Services. For example: Delft-FEWS Web OC Web Services API +![Web OC Web Services App Registration](./app-registration-web-services-api.png) + +Now the Delft-FEWS Web OC Web Services API app registration needs to expose permissions. +From the Azure Portal, select the Delft-FEWS Web OC Web Services API app registration. +Select the Expose an API permissions menu. +Select Add a scope +Enter a name for the scope. For example: Delft-FEWSWebServices +A scope URL will be generated, similar to: api://10309c77-251e-4157-a371-49b318d66f11/Delft-FEWSWebServices +![Expose an api](./expose-an-api.png) + +The optional email claim has to be added to the access token. +From the Token configuration menu, select Add optional claim. +When saving the optional claim, the Azure Portal will request to turn on the Microsoft Graph email permission. Allow this. +![Graph email permission](./optional-claim-graph-email-permission.png) + +Now the Delft-FEWS Web OC Test app registration needs API permissions on the Delft-FEWS Web OC Web Services API. +From the Azure Portal, select the Delft-FEWS Web OC Test app registration. +Select the API permissions menu. +Select "My APIs" +Choose the Delft-FEWS Web OC Web Services API. +![Scope](./request-api-permissions.png) + +In the app-config.json file of the Delft-FEWS Web OC, the following OIDC properties have to be set: + +```json +{ + "VITE_AUTH_AUTHORITY": "https://login.microsoftonline.com/MYTENANTID/", + "VITE_AUTH_METADATA_URL": "https://login.microsoftonline.com/MYTENANTID/v2.0/.well-known/openid-configuration" + "VITE_AUTH_ID": "MY-CLIENT_ID", + "VITE_AUTH_SCOPE": "openid email ", + "VITE_REQUEST_HEADER_AUTHORIZATION": "Bearer" +} + +``` + +VITE_AUTH_ID has to be the Application (client) id of the Delft-FEWS Web OC Test app registration. +For the VITE_AUTH_SCOPE, the value should be: "openid profile email Offline_Access api://myclientid/Delft-FEWSWebServices" diff --git a/docs/public/oidc/access_token_optional_claim_email.png b/docs/public/oidc/access_token_optional_claim_email.png new file mode 100644 index 000000000..0d103b2c1 Binary files /dev/null and b/docs/public/oidc/access_token_optional_claim_email.png differ diff --git a/docs/public/oidc/app-registration-web-oc.png b/docs/public/oidc/app-registration-web-oc.png new file mode 100644 index 000000000..2f4adcfe6 Binary files /dev/null and b/docs/public/oidc/app-registration-web-oc.png differ diff --git a/docs/public/oidc/app-registration-web-services-api.png b/docs/public/oidc/app-registration-web-services-api.png new file mode 100644 index 000000000..41ed98829 Binary files /dev/null and b/docs/public/oidc/app-registration-web-services-api.png differ diff --git a/docs/public/oidc/delft-fews-web-oc-api-permissions.png b/docs/public/oidc/delft-fews-web-oc-api-permissions.png new file mode 100644 index 000000000..5f7b7e775 Binary files /dev/null and b/docs/public/oidc/delft-fews-web-oc-api-permissions.png differ diff --git a/docs/public/oidc/expose-an-api.png b/docs/public/oidc/expose-an-api.png new file mode 100644 index 000000000..a96bc5fb0 Binary files /dev/null and b/docs/public/oidc/expose-an-api.png differ diff --git a/docs/public/oidc/optional-claim-graph-email-permission.png b/docs/public/oidc/optional-claim-graph-email-permission.png new file mode 100644 index 000000000..e2b66a438 Binary files /dev/null and b/docs/public/oidc/optional-claim-graph-email-permission.png differ diff --git a/docs/public/oidc/request-api-permissions.png b/docs/public/oidc/request-api-permissions.png new file mode 100644 index 000000000..f76bbfa98 Binary files /dev/null and b/docs/public/oidc/request-api-permissions.png differ diff --git a/docs/public/project/README.md b/docs/public/project/README.md new file mode 100644 index 000000000..03eef8996 --- /dev/null +++ b/docs/public/project/README.md @@ -0,0 +1,131 @@ +# Web OC project + +## Introduction + +At Deltares, we notice an increasing number of requests for web-based user-interfaces connected to Delft-FEWS. Also, we see that there is a broader move ongoing towards online user-interfaces, with many comparable packages used internationally already providing such solutions. As such, the Delft-FEWS 2025 vision (https://oss.deltares.nl/web/delft-fews/vision-2025) also incorporates the development of a Web-based Operator Client (Web OC) (https://oss.deltares.nl/web/delft-fews/-/web-based-oc?redirect=%2Fweb%2Fdelft-fews%2Froadmaps). + +## Development goals + +Considering the use-case for a Web OC, we see the following key benefits: + +- Easier deployment (compared to Desktop OC) +- Increased mobility (fast access through browser, also from mobile devices) +- Increased modularity (possibility to incorporate into existing online environments already in use by clients) +- Increased flexibility (the intention to have further options to customize the interface to user needs) +- Improvements to performance and security of Delft-FEWS web-services in consequence of the development of a secure and performant Web OC +- Technological developments. Benefit from all the technological developments and 3rd party functionality available for the web. + +Furthermore, key overall assumptions are: + +- The Web OC will serve expert users primarily. +- For the foreseeable future, the Web OC and Desktop OC will be developed and used in parallel. In some cases, the web-based UI might serve as an addition to the Desktop OC. In others it might serve as a replacement. +- Web OC will not be a clone of the existing Desktop OC regarding functionality and design. +- The Web OC will be a responsive web application, building on experience gained in prior web applications developed by Deltares +- The Web OC will connect to the Delft-FEWS web services to interact with other Delft-FEWS components. +- The Web OC can be hosted anywhere, dependent on the client’s preference (on-premise, the cloud, …) +- The Web OC will become an integral part of the overall Delft-FEWS product. +- An open source, closed community license model will apply (see REFERENCE). + +## Development process + +Key assumptions regarding the development process are: + +- The development of the Web OC will apply a growth model. Starting from initial requirements and an initial prioritization, relevant functionality will be gradually and iteratively included or enhanced (in line with the current Delft-FEWS business model). +- An initial Minimum Viable Product (MVP) version of the Web OC will likely include functionality to: 1) visualize data (time series, map fields, SCADA displays, also including associated information such as thresholds), 2) dispatching jobs, 3) visualize monitoring information, 4). Aanpassen, link naar presentaties +- Deltares will provide long-term support on the Web OC. + +## Project timeline + +| Time Period | Activities | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 2020 Q4 | International User Days. Presenting Web OC plans: [Vision 2025](https://oss.deltares.nl/web/delft-fews/vision-2025). | +| 2021 | Define use-cases and key assumptions and MVP.
First steps towards technical architecture: Involve both Deltares and external colleagues. | +| | Start development work. | +| | International User Days. Present architecture and 3rd party collaboration.
Interactive sessions on key functionality. | +| 2022 | Third-party testing of reusability Web OC building blocks. | +| | Continuation of development work.
User feedback session during CSB meeting and NL/INT User Days. | +| | International User Days. Demonstration / Plug & Play session Web OC / UI/UX Design session. | +| 2023 | Continuation of development work. | +| | International User Days. Presentation status Web OC Developments.
Dec 2023 **2023.02 Delft-FEWS Web OC MVP Release.** Software available on [GitHub](https://github.com/Deltares/fews-web-oc). | +| 2024 onwards | Web OC Development in line with the current Delft-FEWS business model. | + +## Present status + +As stated in the section “Development process ” the development of Web OC will apply a growth model. Starting from initial requirements and an initial prioritization, relevant functionality will be gradually and iteratively included or enhanced (in line with the current Delft-FEWS business model). The initial requirements for the first release of Web OC have been defined together with the community during sessions organized at the FEWS Sofware days (refer to presentations). The key features were defined as: + +Functional: + +- Visualize data (time series, map fields, SCADA displays, also including associated information such as thresholds) +- Dispatching jobs +- Visualize monitoring information + +Non-functional: + +- Focus on code quality, test and deployement process. +- Adhere present day insights regarding cyber security, authentication and Authorization +- Performance +- Relevant configuration will be part of the existing Delft-FEWS configuration concept. + +In line with the features listed above, the first release of Web OC (Dec 2023, refer to release management section), will include the following: + +| Initial requirements | Web OC release 1.0.0 (Dec 2023)\* | +| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | +| **Functional** | | +| Visualize data (time series, map fields, SCADA displays, also including associated information such as thresholds). | Visualize configured Display Groups when linked to toplogy node (graph/table view).
Visualize timeseries configured in Filters.xml when linked to toplogy node (graph/table view).
Show associated threshold levels in time series graphs.
Show associated quality flags in table view.
Show SCADA displays including support for most click-actions.
Visualize data layers configured in the spatial display.
Ensembles not supported yet. | +| Dispatching jobs | Not supported in this release. However, FewsWebServices toplogy/nodes? Endpoint extended with information on workflows. | +| Visualize monitoring information | “Import status” and “Running Tasks” components of system monitor available in Web OC. | +| **Non-functional** | | +| Focus on code quality, test and deployement process. | Back-end (FewsWebServices):
- Version management: Subversion
- Issue tracking in JIRA
- Development feature and unit tests
- Code Review
- Deploy new FewsWebServices on test server (both open and authorized version). | | +| | Front-end (Libaries and Web OC components):
- Version management: Deltares Github
- Issue tracking in JIRA
- New branch in Git for each issue (manual)
- Review and push to main branch (manual)
- Run tests for Typescript libraries (automated Teamcity)
- Run test for Web OC components (automated Teamcity)
- Test successful, deploy on Azure test environment (artifact on build server) | +| Adhere present day insights regarding cyber security, authentication and authorization | Using OpenID Connect / Oauth2, for both Web OC front-end and FewsWebServices
FEWS permissions as configured in FEWS configuration respected by FewsWebServices
Run automated ZAP scan (OWASP) on Web OC components and demo Web OC.
Web OC will directly connect to FewsWebServices to obtain configuration and relevant data from the FEWS database. | +| Performance | During the development process of Web OC, the FewsWebServices back-end will be enhanced continuously to improve performance and add functionality. It is intended not to introduce any additional software to the Web OC stack to further improve the performance of Web OC. | +| Relevant configuration will be part of the existing Delft-FEWS configuration concept. | All configuration related to what content is being displayed in Web OC, is managed by the Delft-FEWS configuration. Referentie | + +\*Please note that Web OC will not support all functionality available in the Desktop OC regarding the features listed above. In addition, not all configurations might be supported. For questions on this matter, please contact Web OC Team via fews-pm@deltares.nl. + +## Future plans + +Following the December 2023 release of Web OC, the software will be developed further in line with the current Delft-FEWS business model. Currently, the following features are planned for: + +- Support click actions on grid data: show time series of selected location. +- Support click actions on grid data: show vertical profile time series of selected location (3D data). +- Show vertical slider (elevation) for grid data when data layer consists of 3D data. +- FewsWebServices endpoint for static resources (logos, fonts, css etc.) +- FewsWebServices endpoint to better support time series table view. +- Run workflow from Topology node. +- Visualize scada display linked to Topology node. +- Support time series data edits in table view. + +## Architectural principles + +Key assumptions regarding the technical design and requirements are: + +- Existing or prior web applications developed by Deltares will serve as a reference for the technical design of the Web OC. +- The Web OC will connect to the Delft-FEWS web services to interact with other Delft-FEWS components. Where required these web-services will be further improved to enable this (improving performance, adding features) +- The Web OC will retrieve certain configuration data required on-the-fly (based on filters, spatial display, SCADA displays, workflow descriptors, …). +- Web OC configuration will not require expertise in web development, relevant configuration will be XML based and will be part of the existing Delft-FEWS configuration concept. +- The Web OC will be customizable for different user groups and workflows / work processes. User authentication and authorization will be possible. + +- Relevant functionality will be implemented as components, which should be easily replaceable when these components are end-of-life. Components should be easily re-useable in other web applications, and components from existing web applications might be re-used in the Web OC. Modularity between components developed for the Web OC and third-party applications will be explored. +- The following software frameworks will serve as a basis for the further technical design: + +- During design and development, present day insights and requirements regarding cyber security will be adhered to from the start. +- During design and development, present day insights regarding DevOps (continuous integration and deployment) will be adhered to from start. +- During development, tooling to monitor code quality will be applied (SonarQube or comparable). + +## How to use Web OC in your organization? + +Provided that you have a running Delft-FEWS system already, its suggested to follow the steps below to get started with Web OC. + +- Play around with a local Web OC for your FEWS system. + - FewsWebServices developments for the Web OC are available from FEWS 2023.02. + - Ask FEWS Product Management / Deltares Project Lead for a recent Web OC build or download from Github. +- Identify required Web OC developments / modifications. +- Decide on development strategy: use Typescript libraries / Web OC components / Full stack. +- Discuss developments and strategy with Deltares (architecture / timeline / budgets etc.) +- Deltares to coordinate developments and to identify overlap with other Web OC projects +- Developments organized in Sprint sessions (1 to 2 weeks): back-end, front-end, UX/UI. + +## DSD Web OC presentations + +Public presentations on the Delft-FEWS Web OC can be found here: