FEWS Web Services

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-XML REST Web Service: The PI-XML REST Service provides a REST based interface using the REST protocol.
PI-XML SOAP Web Service: The PI-XML SOAP Service can be accessed by the SOAP protocol.
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.
Umaquo Web Service: The Umaquo Web Service can be accessed by the SOAP protocol.

Tomcat Installation

To install the FEWS Web Services at least the Tomcat 7 application server is required. See: https://tomcat.apache.org/download-70.cgi. The requirements of the Java version to be used for Tomcat is the same as for the FEWS version that is being used.

This installation guide assumes a newly installed Tomcat 7 or Tomcat 8 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.

FEWS Installation

If Tomcat is succesfully installed, the FEWS configuration installation can be done. FEWS itself is packaged inside the FewsWebServices.war.

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.

FEWS should 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 a stand alone or direct database access client. In the following code snippet the configuration of a Stand alone client can be seen.

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

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 hte FewsPiService.properties overrules the default filter in the Filters.xml.

FILTER_ID=All

N.B.: In version 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 restart tomcat after deployment.

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.

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

PI-XML 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-XML 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 FewsPiServices.war.

PI-XML REST Web Service

For the PI-XML 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

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!

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.

Page tree