Page History

...

DAC installation guide (final).doc (DAC installation is obsolete since FEWS 2017.02)

Table of Contents

Introduction

The Tomcat Fews PI service is hosted in a Tomcat service container. This service allows SOAP clients to interact with a FewsPiService that is connected to a FEWS system through the FEWS DataAccessComponent. With this API the SOAP client can retrieve data from the FEWS system. Before a client application can access the FEWS system there is some configuration work that needs to be done.

For some examples on how to connect to the service, see: FEWS PI-XML SOAP Examples. For some sample SOAP request please see FEWS PI SOAP Web Service Request examples.

PI SOAP Web Service API

Description of the methods provided by the PI SOAP Service API.

Getter methods

getTimeZoneId

Code Block
String getTimeZoneId(String piVersion);

...

clientId: <id not used>
returns: String representation of time zone.

getFilters

Code Block
String getFilters(String filterId, String piVersion);

...

filterid: Subset filter id. (optional).
piVersion: File format version (optional).
returns: PiFilters xml file content.

getLocations

Code Block
String getLocations(String clientId, String filterId, String piVersion);

...

clientId <id not used>.
filterId Filter id (optional).
piVersion File format version (optional)
returns PiLocations XML file content.

getLocationsAsStream

Code Block
DataHandler getLocationsAsStream(String filterId, String piVersion);

...

filterId Filter id (optional).
piVersion File format version (optional)
returns javax.activation.DataHandler that allows client to stream response. The response is returned following the MTOM protocol.

getParameters

Code Block
String getParameters(String clientId, String filterId, String piVersion);

...

clientId <id not used>.
filterId Filter id (optional).
piVersion File format version (optional)
returns PiTimeSeriesParameters XML file content.

getParametersAsStream

Code Block
DataHandler getParametersAsStream(String filterId, String piVersion);

...

filterId Filter id (optional).
piVersion File format version (optional)
returns javax.activation.DataHandler that allows client to stream response.

getTimeSeriesHeadersForFilter

Code Block

String getTimeSeriesHeadersForFilter(String clientId, Date startTime, Date timeZero, Date endTime, String filterId, String[] locationIds, String[] parameterIds, boolean useDisplayUnits, String piVersion);

...

clientId <id not used>.
startTime start date/time of run.
timeZero Forecast time zero. If missing System time is used (optional)
endTime end date/time of run.
filterId Filter id (optional).
locationIds Subset of locations for which to retrieve timeseries (optional).
parameterIds Subset of parameters for which to retrieve timeseries (optional).
useDisplayUnits Export values using display units (optional).
piVersion File format version (optional)
return PiTimeseries xml file content.

getTimeSeriesHeadersForFilter2

Code Block

String getTimeSeriesHeadersForFilter2(String clientId, Date startTime, Date timeZero, Date endTime, String filterId, String[] locationIds, String[] parameterIds, boolean useDisplayUnits, String ensembleId, String piVersion);

...

clientId <id not used>.
startTime start date/time of run.
timeZero Forecast time zero. If missing System time is used (optional)
endTime end date/time of run.
filterId Filter id (optional).
locationIds Subset of locations for which to retrieve timeseries (optional).
parameterIds Subset of parameters for which to retrieve timeseries (optional).
useDisplayUnits Export values using display units (optional).
ensembleId Ensemble id (optional)
piVersion File format version (optional)
return PiTimeseries xml file content.

getTimeSeriesForFilter

Code Block

String getTimeSeriesForFilter(String clientId, Date startTime, Date timeZero, Date endTime, String filterId, String[] locationIds, String[] parameterIds, boolean convertDatum, boolean useDisplayUnits, String piVersion);

...

clientId <id not used>.
startTime start date/time of run.
timeZero Forecast time zero. If missing System time is used (optional)
endTime end date/time of run.
filterId Filter id (optional).
locationIds Subset of locations for which to retrieve timeseries (optional).
parameterIds Subset of parameters for which to retrieve timeseries (optional).
convertDatum Convert values from relative location height to absolute height values (optional).
useDisplayUnits Export values using display units (optional).
piVersion File format version (optional)
return PiTimeseries xml file content.

getTimeSeriesForFilter2

Code Block

String getTimeSeriesForFilter2(String clientId, Date startTime, Date timeZero, Date endTime, String filterId, String[] locationIds, String[] parameterIds, boolean convertDatum, boolean useDisplayUnits, String ensembleId, String piVersion);

...

clientId <id not used>.
startTime start date/time of run.
timeZero Forecast time zero. If missing System time is used (optional)
endTime end date/time of run.
filterId Filter id (optional).
locationIds Subset of locations for which to retrieve timeseries (optional).
parameterIds Subset of parameters for which to retrieve timeseries (optional).
convertDatum Convert values from relative location height to absolute height values (optional).
useDisplayUnits Export values using display units (optional).
ensembleId Ensemble id (optional)
piVersion File format version (optional)
return PiTimeseries xml file content.

getTimeSeries

Code Block

language	java

String getTimeSeries(QueryParams queryParameters);

...

convertDatum Convert values from relative location height to absolute height values.
endCreationTime End time of search period that looks for creation time of timeseries. Note: creation time of timeseries is actually the creation time of the task that produced/imported these timeseries.
endForecastTime End time of search period that looks for timeseries produced by forecasts that have their forecast time within this period.
endTime End time of search period that looks for timeseries values that lie within this period.
ensembleId Ensemble identifier of for timeseries
externalForecastTime Time value of for external forecast time.
filterId Filter id.
forecastSearchCount Number of forecast runs to return when using start- and end- forecast time. Default is 1.
importFromExternalDataSource Option to look data up in a linked external data source (eg. archive) or not.
locationIds Subset of locations for which to retrieve timeseries.
omitMissing Toggle omitting or returning of missing values in response
onlyHeaders Toggle to return only header information or also data
parameterIds Subset of parameters for which to retrieve timeseries.
piVersion File format version
showStatistics Toggle to return statistics information about timeseries. Use in combination with 'onlyHeaders=true'. Returns additional information about data availability of timeseries (available from 2015.01)
showThresholds Option to toggle the returning of threshold information in the headers
startCreationTime Start time of search period that looks for creation time of timeseries. Note: creation time of timeseries is actually the creation time of the task that produced/imported these timeseries.
startForecastTime Start time of search period that looks for timeseries produced by forecasts that have their forecast time within this period.
startTime Start time of search period that looks for timeseries values that lie within this period..
useDisplayUnits Export values using display units.
return PiTimeseries xml file content.

getTimeSeriesAsStream

Code Block

language	java

DataHandler getTimeSeriesAsStream(QueryParams queryParameters);

Same as getTimeSeries method except this method returns a DataHandler using the MTOM protocol.

getWorkflows

Code Block
String getWorkflows(String piVersion);

...

piVersion File format version (optional)
return PiWorkflows xml file content.

getSamplesAsStream

Code Block

language	java

DataHandler getSamplesAsStream(SampleQueryParams sampleQueryParams);

...

If no startCreationTime and endCreationTime have been set, the startTime and endTime are used to determine the search period.
If no startTime and endTime have been specified, the search period will be set to the current system time minus one day and one hour until the current system time plus one day and one hour.

getModifiers

Code Block
String getModifiers(Date startTime, Date endTime, String modifierTypeId);

...

If no startTime and endTime are given, the search period is any time.

getTimeSeriesModifiers

Code Block
String getTimeSeriesModifiers(Date startTime, Date endTime, String userId, boolean active, String[] locationIds, String[] moduleInstanceIds, String[] userDefinedDescriptions, String modifierTypeId);

...

startTime Start of the search period
endTime end of the search period
userId if this option is used only the modifiers of this user will be returned
active if this option is set to true only the enabled modifiers will be returned, otherwise all modifiers will be returned
locationIds Only return modifiers which are made for one of the specified locations if this parameter is set
moduleInstanceIds Only return modifiers which are made for one of the specified module instances if this parameter is set
userDefinedDescriptions Only return modifiers which have a user defined description which is equal to one the descriptions in this list if this parameter is set
modifierTypeId Only return modifiers which are of the defined type if this parameter is set

Setter methods

putTimeSeriesForFilters

Code Block
void putTimeSeriesForFilters(String clientId, String filterId, String piTimeSeriesXmlContent, byte[] piTimeSeriesBinaryContent, boolean convertDatum);

...

Code Block

language	xml
linenumbers	true

<event date="2018-02-12" time="09:15:00" value="0.186" flag="2"/>
<event date="2018-02-12" time="09:16:00" value="0.186" flag="2"/>

putModifiers

Code Block
void putModifiers(String piModifiersXmlContent, boolean commitModifiers, boolean deleteAllModifiers);

...

piModifiersXml. A String which contains modifiers defined in xml-format,
commitModifiers. Indicates if the modifiers are committed after the upload.
deleteAllModifiers. Indicates if the modifiers should be deleted prior to inserting the new modifiers.

Run methods

runTask

Code Block
String runTask(String clientId, String workflowId, Date startTime, Date timeZero, Date endTime, String coldStateId, String scenarioId, String piParametersXml, String userId, String description);

...

clientId <id not used>.
workflowId Identifier of the task to run.
startTime Start of run period. Used for state selection period.
timeZero Forecast time zero. If missing System time is used (optional)
endTime End of run period. Used to define forecast length.
coldStateId Id of a coldstate. Can be used to force state selection (optional).
scenarioId Id of a predefined WhatIf scenario. Can be used to alter run parameters (optional).
piParametersXml Contents of a Pi ModelParameters XML file. PI ModelParameters can be exported by the General Adapter to provide information to external models being run by FEWS (optional).
userId User id (optional).
description Descriptive text to identify run (optional)
return taskId of run.

runTaskWithRunParameters

Code Block
String runTaskWithRunParameters(RunParameters runParameters);

...

workflowId Identifier of the task to run.
startTime Start of run period. Used for state selection period.
timeZero Forecast time zero. If missing System time is used (optional)
endTime End of run period. Used to define forecast length.
coldStateId Id of a coldstate. Can be used to force state selection (optional).
scenarioId Id of a predefined WhatIf scenario. Can be used to alter run parameters (optional).
piParametersXml Contents of a Pi ModelParameters XML file. PI ModelParameters can be exported by the General Adapter to provide information to external models being run by FEWS (optional).
useColdState Option to force the use of a cold state even when warm state is available.
description Descriptive text to identify run (optional)
return taskId of run.

getTaskRunStatus

Code Block
String getTaskRunStatus(String taskId, long maxWaitMillis)

...

taskId Id returned by runTask.
maxWaitMillis time in milliseconds to wait for response

return task run status which can be one of the following values:

Code Block

Valid values are
I = Invalid,
P = Pending,
T = Terminated,
R = running,
F = Failed,
C = Completed fully successful,
D = Completed partly successful,
A = Approved,
B = Approved partly successful
null = No status available (produces when method call times-out)

Installing a Tomcat Fews PI Service

N.B.: The DAC installation has become obsolete since FEWS 2017.02.

...

For the online installation manual check here.

Configuration

N.B.: The DAC configuration has become obsolete since FEWS 2017.02.

...

serviceName = Name of the service
namespaceUri = Namespace of the service
portName = Name of the service port
wsdl = URI of the service WSDL file

FEWS Client Config File (clientConfigFileId)

This is a simple text configuration file that is located in the FEWS configuration in the directory:

...

For more information about the possible properties, see FEWS Web Services Configuration FewsPiService.properties (- deprecated since 2022.02).

Example SOAP calls

See soap-example-calls.zip for examples SOAP client calls.

...

Warning
The Delft-FEWS PI SOAP Web Services has been deprecated and will be removed. See: Delft-FEWS End of Life Modules and Displays#FEWSEndofLifeModulesandDisplays-FEWSWebServicesAPIsthatwillberemoved

Introduction

The Tomcat Fews PI service is hosted in a Tomcat service container. This service allows SOAP clients to interact with a FewsPiService that is connected to a FEWS system through the FEWS DataAccessComponent. With this API the SOAP client can retrieve data from the FEWS system. Before a client application can access the FEWS system there is some configuration work that needs to be done.

For some examples on how to connect to the service, see: FEWS PI-XML SOAP Examples. For some sample SOAP request please see FEWS PI SOAP Web Service Request examples.

PI SOAP Web Service API

Description of the methods provided by the PI SOAP Service API.

Getter methods

getTimeZoneId

Code Block
String getTimeZoneId(String piVersion);

...

clientId: <id not used>
returns: String representation of time zone.

getFilters

Code Block
String getFilters(String filterId, String piVersion);

...

filterid: Subset filter id. (optional).
piVersion: File format version (optional).
returns: PiFilters xml file content.

getLocations

Code Block
String getLocations(String clientId, String filterId, String piVersion);

...

clientId <id not used>.
filterId Filter id (optional).
piVersion File format version (optional)
returns PiLocations XML file content.

getLocationsAsStream

Code Block
DataHandler getLocationsAsStream(String filterId, String piVersion);

...

filterId Filter id (optional).
piVersion File format version (optional)
returns javax.activation.DataHandler that allows client to stream response. The response is returned following the MTOM protocol.

getParameters

Code Block
String getParameters(String clientId, String filterId, String piVersion);

...

clientId <id not used>.
filterId Filter id (optional).
piVersion File format version (optional)
returns PiTimeSeriesParameters XML file content.

getParametersAsStream

Code Block
DataHandler getParametersAsStream(String filterId, String piVersion);

...

filterId Filter id (optional).
piVersion File format version (optional)
returns javax.activation.DataHandler that allows client to stream response.

getTimeSeriesHeadersForFilter

Code Block

String getTimeSeriesHeadersForFilter(String clientId, Date startTime, Date timeZero, Date endTime, String filterId, String[] locationIds, String[] parameterIds, boolean useDisplayUnits, String piVersion);

...

clientId <id not used>.
startTime start date/time of run.
timeZero Forecast time zero. If missing System time is used (optional)
endTime end date/time of run.
filterId Filter id (optional).
locationIds Subset of locations for which to retrieve timeseries (optional).
parameterIds Subset of parameters for which to retrieve timeseries (optional).
useDisplayUnits Export values using display units (optional).
piVersion File format version (optional)
return PiTimeseries xml file content.

getTimeSeriesHeadersForFilter2

Code Block

String getTimeSeriesHeadersForFilter2(String clientId, Date startTime, Date timeZero, Date endTime, String filterId, String[] locationIds, String[] parameterIds, boolean useDisplayUnits, String ensembleId, String piVersion);

...

clientId <id not used>.
startTime start date/time of run.
timeZero Forecast time zero. If missing System time is used (optional)
endTime end date/time of run.
filterId Filter id (optional).
locationIds Subset of locations for which to retrieve timeseries (optional).
parameterIds Subset of parameters for which to retrieve timeseries (optional).
useDisplayUnits Export values using display units (optional).
ensembleId Ensemble id (optional)
piVersion File format version (optional)
return PiTimeseries xml file content.

getTimeSeriesForFilter

Code Block

String getTimeSeriesForFilter(String clientId, Date startTime, Date timeZero, Date endTime, String filterId, String[] locationIds, String[] parameterIds, boolean convertDatum, boolean useDisplayUnits, String piVersion);

...

clientId <id not used>.
startTime start date/time of run.
timeZero Forecast time zero. If missing System time is used (optional)
endTime end date/time of run.
filterId Filter id (optional).
locationIds Subset of locations for which to retrieve timeseries (optional).
parameterIds Subset of parameters for which to retrieve timeseries (optional).
convertDatum Convert values from relative location height to absolute height values (optional).
useDisplayUnits Export values using display units (optional).
piVersion File format version (optional)
return PiTimeseries xml file content.

getTimeSeriesForFilter2

Code Block

String getTimeSeriesForFilter2(String clientId, Date startTime, Date timeZero, Date endTime, String filterId, String[] locationIds, String[] parameterIds, boolean convertDatum, boolean useDisplayUnits, String ensembleId, String piVersion);

...

clientId <id not used>.
startTime start date/time of run.
timeZero Forecast time zero. If missing System time is used (optional)
endTime end date/time of run.
filterId Filter id (optional).
locationIds Subset of locations for which to retrieve timeseries (optional).
parameterIds Subset of parameters for which to retrieve timeseries (optional).
convertDatum Convert values from relative location height to absolute height values (optional).
useDisplayUnits Export values using display units (optional).
ensembleId Ensemble id (optional)
piVersion File format version (optional)
return PiTimeseries xml file content.

getTimeSeries

Code Block

language	java

String getTimeSeries(QueryParams queryParameters);

...

convertDatum Convert values from relative location height to absolute height values.
endCreationTime End time of search period that looks for creation time of timeseries. Note: creation time of timeseries is actually the creation time of the task that produced/imported these timeseries.
endForecastTime End time of search period that looks for timeseries produced by forecasts that have their forecast time within this period.
endTime End time of search period that looks for timeseries values that lie within this period.
ensembleId Ensemble identifier of for timeseries
externalForecastTime Time value of for external forecast time.
filterId Filter id.
forecastSearchCount Number of forecast runs to return when using start- and end- forecast time. Default is 1.
importFromExternalDataSource Option to look data up in a linked external data source (eg. archive) or not.
locationIds Subset of locations for which to retrieve timeseries.
omitMissing Toggle omitting or returning of missing values in response
onlyHeaders Toggle to return only header information or also data
parameterIds Subset of parameters for which to retrieve timeseries.
piVersion File format version
showStatistics Toggle to return statistics information about timeseries. Use in combination with 'onlyHeaders=true'. Returns additional information about data availability of timeseries (available from 2015.01)
showThresholds Option to toggle the returning of threshold information in the headers
startCreationTime Start time of search period that looks for creation time of timeseries. Note: creation time of timeseries is actually the creation time of the task that produced/imported these timeseries.
startForecastTime Start time of search period that looks for timeseries produced by forecasts that have their forecast time within this period.
startTime Start time of search period that looks for timeseries values that lie within this period..
useDisplayUnits Export values using display units.
return PiTimeseries xml file content.

getTimeSeriesAsStream

Code Block

language	java

DataHandler getTimeSeriesAsStream(QueryParams queryParameters);

Same as getTimeSeries method except this method returns a DataHandler using the MTOM protocol.

getWorkflows

Code Block
String getWorkflows(String piVersion);

...

piVersion File format version (optional)
return PiWorkflows xml file content.

getSamplesAsStream

Code Block

language	java

DataHandler getSamplesAsStream(SampleQueryParams sampleQueryParams);

...

If no startCreationTime and endCreationTime have been set, the startTime and endTime are used to determine the search period.
If no startTime and endTime have been specified, the search period will be set to the current system time minus one day and one hour until the current system time plus one day and one hour.

getModifiers

Code Block
String getModifiers(Date startTime, Date endTime, String modifierTypeId);

...

If no startTime and endTime are given, the search period is any time.

getTimeSeriesModifiers

Code Block
String getTimeSeriesModifiers(Date startTime, Date endTime, String userId, boolean active, String[] locationIds, String[] moduleInstanceIds, String[] userDefinedDescriptions, String modifierTypeId);

...

startTime Start of the search period
endTime end of the search period
userId if this option is used only the modifiers of this user will be returned
active if this option is set to true only the enabled modifiers will be returned, otherwise all modifiers will be returned
locationIds Only return modifiers which are made for one of the specified locations if this parameter is set
moduleInstanceIds Only return modifiers which are made for one of the specified module instances if this parameter is set
userDefinedDescriptions Only return modifiers which have a user defined description which is equal to one the descriptions in this list if this parameter is set
modifierTypeId Only return modifiers which are of the defined type if this parameter is set

Setter methods

putTimeSeriesForFilters

Code Block
void putTimeSeriesForFilters(String clientId, String filterId, String piTimeSeriesXmlContent, byte[] piTimeSeriesBinaryContent, boolean convertDatum);

...

Code Block

language	xml
linenumbers	true

<event date="2018-02-12" time="09:15:00" value="0.186" flag="2"/>
<event date="2018-02-12" time="09:16:00" value="0.186" flag="2"/>

putModifiers

Code Block
void putModifiers(String piModifiersXmlContent, boolean commitModifiers, boolean deleteAllModifiers);

...

piModifiersXml. A String which contains modifiers defined in xml-format,
commitModifiers. Indicates if the modifiers are committed after the upload.
deleteAllModifiers. Indicates if the modifiers should be deleted prior to inserting the new modifiers.

Run methods

runTask

Code Block
String runTask(String clientId, String workflowId, Date startTime, Date timeZero, Date endTime, String coldStateId, String scenarioId, String piParametersXml, String userId, String description);

...

clientId <id not used>.
workflowId Identifier of the task to run.
startTime Start of run period. Used for state selection period.
timeZero Forecast time zero. If missing System time is used (optional)
endTime End of run period. Used to define forecast length.
coldStateId Id of a coldstate. Can be used to force state selection (optional).
scenarioId Id of a predefined WhatIf scenario. Can be used to alter run parameters (optional).
piParametersXml Contents of a Pi ModelParameters XML file. PI ModelParameters can be exported by the General Adapter to provide information to external models being run by FEWS (optional).
userId User id (optional).
description Descriptive text to identify run (optional)
return taskId of run.

runTaskWithRunParameters

Code Block
String runTaskWithRunParameters(RunParameters runParameters);

...

workflowId Identifier of the task to run.
startTime Start of run period. Used for state selection period.
timeZero Forecast time zero. If missing System time is used (optional)
endTime End of run period. Used to define forecast length.
coldStateId Id of a coldstate. Can be used to force state selection (optional).
scenarioId Id of a predefined WhatIf scenario. Can be used to alter run parameters (optional).
piParametersXml Contents of a Pi ModelParameters XML file. PI ModelParameters can be exported by the General Adapter to provide information to external models being run by FEWS (optional).
useColdState Option to force the use of a cold state even when warm state is available.
description Descriptive text to identify run (optional)
return taskId of run.

getTaskRunStatus

Code Block
String getTaskRunStatus(String taskId, long maxWaitMillis)

...

taskId Id returned by runTask.
maxWaitMillis time in milliseconds to wait for response

return task run status which can be one of the following values:

Code Block

Valid values are
I = Invalid,
P = Pending,
T = Terminated,
R = running,
F = Failed,
C = Completed fully successful,
D = Completed partly successful,
A = Approved,
B = Approved partly successful
null = No status available (produces when method call times-out)

Installing a Tomcat Fews PI Service

N.B.: The DAC installation has become obsolete since FEWS 2017.02.

The file DAC installation guide (final).doc describes how to install a Tomcat instance containing a DataAccessComponent instance. Once these steps are completed the FewsPiService.WAR can be deployed using a context xml file such as FewsPiService.xml.

Configuration

N.B.: The DAC configuration has become obsolete since FEWS 2017.02.

...

serviceName = Name of the service
namespaceUri = Namespace of the service
portName = Name of the service port
wsdl = URI of the service WSDL file

FEWS Client Config File (clientConfigFileId)

This is a simple text configuration file that is located in the FEWS configuration in the directory:

...

For more information about the possible properties, see FEWS Web Services Configuration FewsPiService.properties (- deprecated since 2022.02).

Example SOAP calls

See soap-example-calls.zip for examples SOAP client calls.

Page tree

Page History

Versions Compared

Old Version 45

New Version Current

Key

Introduction

PI SOAP Web Service API

Getter methods

getTimeZoneId

getFilters

getLocations

getLocationsAsStream

getParameters

getParametersAsStream

getTimeSeriesHeadersForFilter

getTimeSeriesHeadersForFilter2

getTimeSeriesForFilter

getTimeSeriesForFilter2

getTimeSeries

getTimeSeriesAsStream

getWorkflows

getSamplesAsStream

getModifiers

getTimeSeriesModifiers

Setter methods

putTimeSeriesForFilters

putModifiers

Run methods

runTask

runTaskWithRunParameters

getTaskRunStatus

Installing a Tomcat Fews PI Service

Configuration

FEWS Client Config File (clientConfigFileId)

Example SOAP calls

Introduction

PI SOAP Web Service API

Getter methods

getTimeZoneId

getFilters

getLocations

getLocationsAsStream

getParameters

getParametersAsStream

getTimeSeriesHeadersForFilter

getTimeSeriesHeadersForFilter2

getTimeSeriesForFilter

getTimeSeriesForFilter2

getTimeSeries

getTimeSeriesAsStream

getWorkflows

getSamplesAsStream

getModifiers

getTimeSeriesModifiers

Setter methods

putTimeSeriesForFilters

putModifiers

Run methods

runTask

runTaskWithRunParameters

getTaskRunStatus

Installing a Tomcat Fews PI Service

Configuration

FEWS Client Config File (clientConfigFileId)

Example SOAP calls