Page tree
Skip to end of metadata
Go to start of metadata

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):

Installation

Tomcat Installation

The FEWS Web Services are supported on the Tomcat 7 and Tomcat 8 and 9 application server. See: https://tomcat.apache.org/download-70.cgihttps://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.

This installation guide assumes a newly installed Tomcat 7, 8 or 9 application server. For migrating existing installations from before FEWS 2017.02, see the paragraph on migrating.

The root of the tomcat installation is referred to as "${catalina.home}" and will be used from here. The root of a tomcat installation can be recognized by the webapps and conf directories.

FewsWebServices.war installation

The FEWS Web Services are packaged in a file called the FewsWebServices.war. Before installation, make sure the tomcat server has been shutdown. Inspect the ${catalina.home}/webapps folder and inspect if there is a FewsWebServices folder. If this folder exists, delete the ${catalina.home}/webapps/FewsWebServices folder. The FewsWebServices.war file has to be copied to the ${catalina.home}/webapps folder.

FEWS Installation

If Tomcat is succesfully installed and the FewsWebServices.war deployed, the FEWS configuration installation can be done. FEWS itself (i.e. the bin\ folder) is packaged inside the FewsWebServices.war.

Direct database access

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

In this folder a clientConfig.xml is required to configure a direct database access client. In the following code snippet an example of the configuration of a Direct Database Access client can be seen. The tomcat process should have write permissions to the Region_Home directory. The clientConfig.xml file should be readable by Tomcat.

 

<?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>FEWS_DATABASE_USER</user>
			<encryptedPassword>DATABASE_ENCRYPTED_PASSWORD</encryptedPassword>
        </databaseServer>
    </connection>
</clientConfiguration>

FewsPiService.properties

The FEWS Web Services have a custom property file that can be used to make service specific configurations available. This is a property file that is located in the FEWS configuration in the directory:

%REGION_HOME%/Config/PiClientConfigFiles/FewsPiService.properties

For more information about the possible properties, see FEWS Web Services configuration FewsPiService.properties

Global Properties

In case global properties are needed by the FEWS Web Services, a global.properties file can be put in the Region_Home directory as well. If the same global.properties is available in the RootConfigFile in the FEWS configuration, the properties will be overwritten by the one in the FEWS database

Index Files

Since 2018.02 the FEWS Web Services will not startup before an index file is available in the Database. Index files are created automatically by Forecasting Shells. This means that the FEWS Web Services will only start if a running Forecasting Shell is available on the live system.

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

In this folder a clientConfig.xml is required to configure the stand alone client. In the following code snippet the configuration of a Stand alone client can be seen. The tomcat process should have write permissions to the Region_Home directory. The clientConfig.xml file should be readable by Tomcat.

 

<?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>

Only direct database access should be used for operational use of the FEWS Web Services. A standalone configuration can be used, but only has limited functionality. For example only the Derby local data store is supported and workflows depending on DLL's (or .so files on Linux) are NOT supported.


FEWS Configuration requirements

The only requirement for running the FewsWebServices is that a default filter is configured in FEWS. This can be done in two different ways:

Configure a default filter in the Filters.xml of the FEWS configuration with the name of the filter that should be used for all requested timeSeries: "${catalina.home}/fews/Region_Home/Config/RegionConfig/Filters.xml"

 

<?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>All</defaultFilterId>
...

Alternatively a property file can be used to configure the default filter (and other properties as well). The property file should be located at: "${catalina.home}/fews/Region_Home/Config/PiClientConfigFiles/FewsPiService.properties". In the following code snippet the default filter to be used by the FEWS Web Services is configured using the property key "FILTER_ID" where the filter "All" has been configured. A filter configured in the FewsPiService.properties overrules the default filter in the Filters.xml.

 

FILTER_ID=All

N.B.: In versions before FEWS 2017.02 it was possible to override the FewsPiService.properties with another name or location. This is no longer supported. Only one property file can be used for all services and the name is fixed to FewsPiService.properties.

If the previous configurations have been applied, the FewsWebServices.war can be installed using the standard deployment options of Tomcat. See the tomcat deployment documentation for more information. When installing a new version of the FewsWebServices.war file it is recommended to delete the FewsWebService directory in the webapps directory and restart tomcat after deployment.

Advanced Installation and Configuration

In some cases it may be required to support different FewsPiService.properties on the same database, for example to support different default filters. In this case and advanced installation of the FEWS Web Services is required that is similar to installations before 2017.02. 

 The FewsWebServices.war file should be put in the ${catalina.home}/fews folder, instead of the ${catalina.home}/webapps. 

In the ${catalina.home}/conf/Catalina/localhost folder a context.xml should be created where a specific client config file id can be configured. In this xml file a reference to the FewsWebServices.war file should be made and a reference to the property file to be used.

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

The FewsPiService01.properties is expected to be in:

%REGION_HOME%/Config/PiClientConfigFiles/FewsPiService01.properties

Using this configuration the web service will now be available at http://localhost:8080/FewsWebServices01/For multiple configurations more context xml files can be created.

 

Security

Since 2017.02 it is also possible to run the FEWS Web Services in readOnly mode. The FewsPiService.properties can be configured with the property READONLY_MODE=true to only allow read access. 

Since 2018.02 readOnly mode is enabled by default.


The FEWS Web Services can be protected using the capabilities of the Tomcat Application Server. See FEWS Web Services Tomcat Security for more information.

Testing

The FEWS Web Services come with a testing page that can be accessed at: http://localhost:8080/FewsWebServices/. This leads to an overview page with links to test pages for the different services (SOAP, REST, WaterML, Digitale Delta and UmAquo). You can find more on how to configure the different services on 18 FEWS data exchange interfaces.

See Tomcat Installation as Windows Service usage for running the Web Services as a Windows service.

The default tomcat installation runs at port 8080. Change the port value in case your tomcat installation runs on another port.

Migrating from before 2017.02

In case an existing 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

Before 2017.02 the FEWS PI Services always returned its response in the PI 1.9 version format. Since 2017.02 if no version is specified, the latest pi version format will be used. If it is required to get a specific version of the pi format, the version can be specified in the service call.

URL changes

The example URLs are based on a default tomcat installation with port 8080. Please adjust in case the defaults have been changed where appropriate.


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.


  • No labels