FewsPiService.properties

Introduction

Since FEWS 2017.02 all FEWS Web Services have been unified into one installation package (FewsWebServices.war). The following WebServices are available with this installation using HTTP(s):

• PI REST Web Service: The PI REST Service can be accessed using the REST protocol. See also: https://fewsdocs.deltares.nl/webservices/rest-api/v1
• WMS-T Web Mapping Service: The Web Mapping Service with time support can be accessed using the OGC-WMS protocol. See also: https://fewsdocs.deltares.nl/webservices/rest-api/v1
• FEWS Schematic Status Display Web Services: The SSD Web service can by access by the REST protocol. See also: https://fewsdocs.deltares.nl/webservices/ssd
• PI SOAP Web Service: The PI SOAP Service can be accessed by the SOAP protocol. The Delft-FEWS PI SOAP Web Services has been removed in Delft-FEWS 2022.01. See: Delft-FEWS End of Life Modules and Displays#FEWSEndofLifeModulesandDisplays-FEWSWebServicesAPIsthatwillberemoved
• WaterML Web Service: The WaterML2 Web Service can be accessed by the WaterML protocol.
• Digitale Delta Web Service: The Digitale Delta Web Service can be accessed by the REST protocol.
• Operating Request Web Service: The Operating Request Web Service can be accessed by the REST protocol. See also: https://fewsdocs.deltares.nl/webservices/operatingrequest/
• Umaquo Web Service: The Umaquo Web Service can be accessed by the SOAP protocol. Was removed in the 2022.02 release.

The different service are available at the following endpoints:

• FEWS PI Rest Web Services: /rest/fewspiservice/*
• FEWS WMS-T Web Mapping Services: /wms
  
• FEWS Schematic Status Display Web Services: /ssd
  
• FEWS PI SOAP Web Services: /fewspiservice Was removed in the  2022.01 release.
• FEWS WaterML Web Services: /waterml
  
• FEWS Digitale Delta Web Services: /rest/digitaledelta/*
• FEWS Operating Request Web Services: /rest/operatingrequest/*
• FEWS Umaquo Web Services: /umaquo  Was removed in the 2022.02 release.

Embedded tomcat

Since FEWS 2022.02 the Delft-FEWS Web Services can be started from a standalone or operator client with the F12 menu option: "start embedded tomcat web services" which will try to start the FewsWebServices on port 8080 which makes it available on your local machine at: http://localhost:8080/FewsWebServices/. It is also possible with a configuration option in the explorer.xml from the SystemConfigFiles folder. See: 01 FEWS Explorer#01FEWSExplorer-fewsWebServicesPortRange

Installation

Tomcat Installation

The FEWS Web Services are supported on the Tomcat application server, check Tomcat requirements for the required version (depends on the Delft-FEWS version you use). You can download Tomcat here: https://tomcat.apache.org/download-70.cgi, https://tomcat.apache.org/download-80.cgi  and https://tomcat.apache.org/download-90.cgi.
The requirements of the Java version to be used for Tomcat is the same as for the FEWS version that is being used. It is strongly advised to use same Java JRE for tomcat as is used for a FEWS OC when installing tomcat. For 2018.02 the java version should be java 11.

Delft-FEWS Web Services configuration

If Tomcat is successfully installed and the FewsWebServices.war deployed, the Delf-FEWS Web Services configuration can be done. FEWS itself (i.e. the bin\ folder) is packaged inside the FewsWebServices.war. Please see below for notes regarding a Stand Alone Delft-FEWS application used in combination with the FEWS Web Services.

Direct database access using ENV variables (since 2020.02)

Since 2020.02 it is possible to install the Delft-FEWS Web Services by only providing Environment variables. This is the recommended way of configuration.

The environment variables can be set with SETX /M for windows or in the systemd configuration file for Linux. Run SETX /M makes variables available for all (service) user accounts.

jdbc:vjdbc:servlet:https://<host>:<port>/FewsDatabaseHttpsProxy

jdbc:postgresql://<host>:<port>/<databaseName>

jdbc:oracle:thin:@<host>:<port>:<sid> or 

jdbc:sqlserver://<host>:<port>;DatabaseName=<databaseName>

An example of configured environment variables.

FEWS_WS_DATABASE_URL=jdbc:postgresql://dummy_hostname:6001/dummy_databasename
FEWS_WS_DATABASE_USER=dummy_username
FEWS_WS_DATABASE_ENCRYPTED_PASSWORD=dummy_password_encrypted
FEWS_WS_CLIENT_CONFIG_FILE_NAME=ws_clientConfig.xml
FEWS_WS_HOME=d:\fews-ws\region-home
FEWS_WS_WEB_SERVICES_CONFIG_FILE_NAME=WebServices.xml
#FEWS_WS_CLIENTCONFIGFILEID is deprecated since 2022.02. Use FEWS_WS_WEB_SERVICES_CONFIG_FILE_NAME instead:
#FEWS_WS_CLIENTCONFIGFILEID=CustomFewsPiService.properties

The clientConfiguration of type "Web Services".

Take note in the following example that the clientType is set to "Web Services". Also a global.properties file is required. The configurated property file will be used by the Delft_FEWS configuration.

<?xml version="1.0" encoding="UTF-8"?>
<clientConfiguration xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/clientConfig.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews">
<title>My WebServices Client</title>
<clientType>Web Services</clientType>
   <otherRootConfigFiles>
      <name>ws_global.properties</name>
   </otherRootConfigFiles>
</clientConfiguration>

Since 2023.02 the autoExportModuleDataSet in the clientConfig is recognized on startup of the webservice. A restart of tomcat is required to update the module datasets if changed

Migrating from 2020.01 and before

Before 2020.02 the FewsWebServices required a local clientConfig.xml file and global.properties in the ${catalina.home}/fews/Region_Home folder. N.B.: this folder still needs to exist if no FEWS_WS_HOME env variable is used.

When migrating to 2020.02 all files in this folder have to be deleted. Please follow the configuration steps in DirectdatabaseaccessusingENVvariables(since2020.02) to complete the migration. 

Direct database access using clientConfig.xml (before 2020.02)

clientConfig.xml

Direct database access has to be configured in the "${catalina.home}/fews/Region_Home" directory. Make sure the exact folder names are use (case sensitive on linux): /fews/Region_Home

<?xml version="1.0" encoding="UTF-8"?>
<clientConfiguration xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/clientConfig.xsd">
    <connection id="Database" name="Database">
        <databaseServer>
            <url>FEWS_DATABASE_URL</url>
            <user>dummy_username</user>
			<encryptedPassword>dummy_password_encrypted</encryptedPassword>
        </databaseServer>
    </connection>
</clientConfiguration>

<?xml version="1.0" encoding="UTF-8"?>
<clientConfiguration xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/clientConfig.xsd">
    <connection id="Database" name="Database">
        <databaseServer>
            <url>FEWS_DATABASE_URL;integratedSecurity=true</url>
        </databaseServer>
    </connection>
</clientConfiguration>

Stand alone

When using a stand alone configuration with an existing local data store, note that only the Derby database datastore is supported for the Fews Web Services. Existing firebird datastores can be converted into a derby datastore using FEWS F12/Database/Replicate Central Database option. In the context of this Web Service, you can use the replica directly as (and where) it is created with this method. Update the localDatastoreFormat in your global properties file if needed.

If installation fails, please check the webservice.log and catalina.log files in the ${catalina.home}/logs directory.

Since 2018.02 there is no longer a webservices.log file. The FEWS Web Services log files are written to the /fews/Region_Home folder with the name log.1.txt etc.. use the environment variable LOG4J_DEBUG=true to enable debug logging.

FEWS has to be installed in the root folder of tomcat in the directory "${catalina.home}/fews/Region_Home". Make sure the exact folder names are use (case sensitive on linux): /fews/Region_Home

<?xml version="1.0" encoding="UTF-8"?>
<clientConfiguration xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/clientConfig.xsd">
	<clientType>Stand alone</clientType>
</clientConfiguration>

<?xml version="1.0" encoding="UTF-8"?>
<filters version="1.1" xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/filters.xsd">
<defaultFilterId>some_defined_filter</defaultFilterId>
...

FILTER_ID=some_defined_filter

<?xml version="1.0" encoding="UTF-8"?>
<Context docBase="${catalina.home}/fews/FewsWebServices.war">
    <Parameter name="ENV_PREFIX" value="FEWS_WS_01_" override="false"/>
</Context>

FEWS_WS_01_DATABASE_URL=jdbc:postgresql://dummy_hostname:6001/dummy_databasename
FEWS_WS_01_DATABASE_USER=dummy_username
FEWS_WS_01_DATABASE_ENCRYPTED_PASSWORD=dummy_password_encrypted
FEWS_WS_01_CLIENT_CONFIG_FILE_NAME=ws_clientConfig.xml
FEWS_WS_01_HOME=d:\fews-ws\region-home-01
FEWS_WS_01_WEB_SERVICES_CONFIG_FILE_NAME=FewsWebServices01.xml

FEWS_WS_01_HOME=d:\fews-ws\region-home-01
FEWS_WS_01_WEB_SERVICES_CONFIG_FILE_NAME=FewsWebServices01.xml

<?xml version="1.0" encoding="UTF-8"?>
<Context docBase="${catalina.home}/fews/FewsWebServices.war">
    <Parameter name="ENV_PREFIX" value="FEWS_WS_01_" override="false"/>
</Context>

FEWS_WS_01_DATABASE_URL=jdbc:postgresql://dummy_hostname:6001/dummy_databasename
FEWS_WS_01_DATABASE_USER=dummy_username
FEWS_WS_01_DATABASE_ENCRYPTED_PASSWORD=dummy_password_encrypted
FEWS_WS_01_CLIENT_CONFIG_FILE_NAME=ws_clientConfig.xml
FEWS_WS_01_HOME=d:\fews-ws\region-home-01
FEWS_WS_01_CLIENTCONFIGFILEID=FewsPiService01.properties

<?xml version="1.0" encoding="UTF-8"?>
<Context docBase="${catalina.home}/fews/FewsWebServices.war">
    <Parameter name="clientConfigFileId" value="FewsPiService01.properties" override="false"/>
    <Parameter name="regionHome" value="${catalina.home}/fews/Region_Home01" override="false"/>
</Context>

%REGION_HOME%/Config/PiClientConfigFiles/FewsPiService01.properties

In case an existing Delft-FEWS web service has to be migrated to the 2017.02 or later version, the following changes should be taken into account.

Installation directory

The FewsWebServices.war file is installed in the ${catalina.home}/webapps folder instead of the ${catalina.home}/fews folder.

Derby Local datastore

Running the FEWS Web Services in standalone mode is only supported for the Derby local datastore with limited functionality. Please see the previous Installation section if an existing non-Derby local datastore needs to be converted to Derby using the Database replication functionality of FEWS. For full functionality configure a clientConfig.xml file with a direct database connection.

Default PI Version

URL changes

PI SOAP Web Service

The change that has the largest impact on the URLs of the Web services is the changed context path (the URL part after the servername + port). Before 2017.02 every FEWS Web service has its own context path. Since 2017.02 all webservices have the same context path, which is FewsWebServices by default.

For example before 2017.02 the URL endpoint of the FEWS PI SOAP Web Service would be: http://localhost:8080/FewsPiServices/fewspiservice

Since 2017.02 it is: http://localhost:8080/FewsWebServices/fewspiservice

If it is required to keep the endpoints backwards compatible, the FewsWebServices.war can be renamed into FewsPiService.war.

PI REST Web Service

For the PI REST Web Service it is not possible to keep the endpoints backwards compatible since the "rest" path is now a required part of the endpoint.

http://localhost:8080/FewsWebServices/rest/fewspiservice

Tomcat installation changes

N.B.: It is highly recommended to install a clean version of tomcat.

Cleanup

It is advisable to cleanup the ${catalina.home}/temp and ${catalina.home}/work folder. N.B. Don't delete the folders themselves, only their content! 

In case there is an old FewsPIService.war in the fews folder, please remove the old FewsPIService.war.

If there is a FewsPIService folder in the ${catalina.home}/webapps folder, please remove this folder.

DAC

Previously the FEWS Web services required a DAC.jar to be installed. Since 2017.02 this component is obsolete and should be removed from existing tomcat installations. See also the tomcat installation guide.

To uninstall the DAC.jar it should be removed from  ${catalina.home}/lib directory. Also the ${catalina.home}/conf/server.xml should be cleaned up. The reference to the DacLifecycleListener should be removed from the server.xml:

<Listener className="nl.wldelft.fews.system.data.dac.DacLifecycleListener" />

Also a reference to the fews_dac resource should be removed:

<Resource name="fews_dac" auth="Container"
            type="nl.wldelft.fews.system.data.dac.DataAccessComponent"
            factory="nl.wldelft.fews.system.data.dac.DacBeanFactory"
            regionHome="${catalina.home}/fews/Region_Home"  
            binPath="${catalina.home}/fews/bin/"
            closeMethod="stop"
            />

From the ${catalina.home}/conf/Catalina/localhost old xml configurations with references to the old services should be removed as well.