Page History

Introduction

The embedded Fews PI service data exchange is a SOAP service hosted by a FEWS client instance (SA/OC/headless) ande uses XFire, a java SOAP framework. This framework allows a client application to obtain a proxy instance to the FewsPiService API hosted by a FEWS client. With this API the client can retrieve data from an OC or write data to an OCa FEWS client instance. Before a client application can access the FEWS system there is some configuration work that needs to be done.

 User's looking to use XFire on a new project, should use CXF instead. CXF is a continuation of the XFire project and is considered XFire 2.0. It has many new features, a ton of bug fixes, and is now JAX-WS compliant! XFire will continue to be maintained through bug fix releases, but most development will occur on CXF now. For more information see the XFire/Celtix merge FAQ and the CXF website.

To use the Fews PI service from other programming languages, see Using the Fews PI service from C, which also contains an example of using Tcl.

You can run the FEWS system in the background, if this is needed or desirable (see below).

Embedded Fews PI Service API

Description of the methods provided by the Embedded Fews PI Service API.

Getter methods

System info

String getLocationsgetClientConfigFile(String clientIdin0, String in1);

• clientId: <id not required>
• returns: Default Locations.xml file from the OC configuration. Note file is not is PI_Locations XSD format.

...

Retrieves a client configuration file.

• in0 -

...

String getClientConfigFile(String clientId, String fileExtension);

• clientId: File name of client configuration file located in the OC configuration directory 'PiClientConfigFiles'. This file is free format and content is only read only read by client application. Only requirement is that content is text based.
• in1 - fileExtension: Extension of client file.
• returns: Text file containing client configuration.

Date getSystemTime(String clientIdin0);

Get current OC system time.

• in0 - clientId: <id not required>
• returns: Date field containing OC system time.

Stringlong getTimeZoneIdgetLastUpdateTime(String clientId);

...

Get last time that OC is updated.

• returns: String Long representation of time zone(modified Julian date).

String[] getColdStateIdsgetDisplayUnit(String clientId, String idin0);

• clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• id: Reference to the ID of a ModuleState element in the service configuration file.
• returns: List of ColdStateGroup ids.

...

Retrieves display unit for a specific parameter

• in0 - parameterId
• returns: String holding the unit

Identifiers

String getTimeZoneId(String in0);

Get OC timeZone id.

• in0 - clientId: <id not required>
• returns: String representation of time zone.

String[] getSelectedFilterIds();

Retrieves filter identifiers selected in the FEWS Explorer

• returns: String array holding the identifiers of the selected filters

String[] getSelectedLocationIds();

Retrieves location identifiers selected in the FEWS Explorer

• returns: String array holding the identifiers of the selected locations

String[] getSelectedParameters();

Retrieves parameter identifiers selected in the FEWS Explorer

• returns: String array holding the identifiers of the selected parameters

String getActiveSegmentId();

Retrieves active (selected) segment/node id in the FEWS Explorer Topology panel

• returns: String identifier to active segement node

String[] getColdStateIds(String in0, String in1);

Get list of available ColdState ids.

• in0 -

...

Date[] getAvailableStateTimes(String clientId, String id);

• clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• id: Reference to the ID of a ModuleState element in the service configuration file.
• returns: Available warmstate times for requested ModuleState.

int[] getEnsembleMemberIndices(String clientId, String ensembleId);

• clientId: <id not required>
• ensembleId: Id of requested ensemble.
• returns: Available member indices of requested ensemble.

String getLogMessages(String clientId, String taskId)

• clientId: <id not required but can not be null>
• taskId: Task ID for which to retrieve log messages. Only messages for the last run are returned.
• returns: String containing the log messages in the format defined by the PI Diag XSD

byte[] getModuleDataSet(String clientId, String id, String ensembleId, int ensembleMemberIndex)

• clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - id: Reference to the ID of a ModuleDataSet ModuleState element in the service configuration file.
• ensembleId: <currently not supported>
• ensembleMemberIndex: <currently not supported>
• returns: Binary content of the ModuleDataSet file for requested ModuleState.List of ColdStateGroup ids.

Date

byte[] getModuleParameterSetgetAvailableStateTimes(String clientIdin0, String id, String ensembleId, int ensembleMemberIndex)
in1);

Get available warm state times.

• in0 - clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - id: Reference to the ID of a ModuleParameterSet ModuleState element in the service configuration file.ensembleId: <currently not supported>
• ensembleMemberIndex: <currently not supported>
• returns: String content of the ModuleParameterSet file returns: Available warm state times for requested ModuleState.

byteint[] getModuleStateBinarygetEnsembleMemberIndices(String clientIdin0, String id, Date stateTime, String ensembleId, int ensembleMemberIndexin1);

• clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• id: Reference to the ID of a ModuleState element in the service configuration file.
• stateTime: Time for which to retrieve warm state file. Time values can be obtained from method #getAvailableStateTimes
• ensembleId: <currently not supported>
• ensembleMemberIndex: <currently not supported>

String getTimeSeriesHeaders(String clientId, String id, String taskId, Date startTime,
		Date timeZero, Date endTime, String[] parameterIds, String[] locationIds, String ensembleId, int ensembleMemberIndex);

Get available ensemble member ids.

• in0 - clientId: <id not required>
• in1 - ensembleId: Id of requested ensemble.
• returns: Available member indices of requested ensemble.

Content

String getFilters(String in0);

Get the configured filter ids from the FEWS system.

• in0 - piVersion: (Optional) Pi Version for the return file. Defaults to the latest PI version.
• returns: String content of a Pi_Filters XML file containing Fews Filters.

String getLocations(String in0, String in1, String in2);

Get location information available for the passed 'filterId' argument.

• in0 - clientId: (Optional) clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD. If not
  
• id: Reference to the ID of a TimeSeries element in the service configuration file.
• taskId: <id not required however can not be null>
• startTime: Start date/time of run - Long.MAXVALUE if the configured default is to be used
• timeZero: Forecast time zero.
• endTime: End date/time of run - Long.MAXVALUE if the configured default is to be used
• parameterIds: Subset of parmater IDs for which to retrieve timeseries.
• locationIds: Subset of location IDs for which to retrieve timeseries.
• ensembleId: Id of the ensemble, can be null.
• ensembleMemberIndex Ensemble member index for this time series. (Only if configured)
• returns: String content of a PiTimeseries XML file only containing header information.

String getTimeSeries(String clientId, String id, String taskId, Date startTime,
		Date timeZero, Date endTime, String[] parameterIds, String[] locationIds, String ensembleId, int ensembleMemberIndex);

• provided then no id mapping will be done.
• in1 - filterId: Filter Id. Can be retrieved using the String getFilters(String piVersion) method.
• in2 - piVersion: (Optional) Pi Version for the return file. Defaults to the latest PI version.
• returns: String content of a Pi_Locations XML file containing the locations available for passed filter id.

String getParameters(String in0, String in1, String in2);

Get timeseries parameter information available for the passed 'filterId' argument.

• in0 - clientId: (Optional) clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• id: Reference to the ID of a TimeSeries element in the service configuration file.
• taskId: <id not required however can not be null>
• startTime: Start date/time of run - Long.MAXVALUE if the configured default is to be used
• timeZero: Forecast time zero.
• endTime: End date/time of run - Long.MAXVALUE if the configured default is to be used
• parameterIds: Subset of parmater IDs for which to retrieve timeseries.
• locationIds: Subset of location IDs for which to retrieve timeseries.
• ensembleId: Id of the ensemble, can be null.
• ensembleMemberIndex Ensemble member index for this time series. (Only if configured)
• returns: String content of a PiTimeseries XML file.

byte[] getTimeSeriesBytes(String clientId, String id, String taskId, Date startTime,
		Date timeZero, Date endTime, String[] parameterIds, String[] locationIds,
                String ensembleId, int ensembleMemberIndex);

• If not provided then no id mapping will be done.
• in1 - filterId: Filter Id. Can be retrieved using the String getFilters(String piVersion) method.
• in2 - piVersion: (Optional) Pi Version for the return file. Defaults to the latest PI version.
• returns: String content of a Pi_TimeSeriesParameters XML file containing the parameters available for passed filter id.

String getRatingCurves(String[] in0);

Retrieves rating curves content in PI-rating curve format for selecetd rating curve identifiers

• in0 - ratingCurveIds: String array with lcoation identifiers of the ratings
• returns: Xml string in Pi_ratyingcurves format holding rating curves

String getLogMessages(String in0, String in1)

Get log messages produces by the last run of given task id.

• in0 - clientId: <id not required but can not be null>
• in1 - taskId: Task ID for which to retrieve log messages. Only messages for the last run are returned.
• returns: String containing the log messages in the format defined by the PI Diag XSD

byte[] getModuleDataSet(String in0, String in1, String in2, int in3)

Get a module data set.

• in0 - clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - id: Reference to the ID of a TimeSeries ModuleDataSet element in the service configuration file.
• taskIdin2 - ensembleId: <id not required however can not be null>
• startTime: Start date/time of run - Long.MAXVALUE if the configured default is to be used
• timeZero: Forecast time zero.
• endTime: End date/time of run - Long.MAXVALUE if the configured default is to be used
• parameterIds: Subset of parmater IDs for which to retrieve timeseries.
• locationIds: Subset of location IDs for which to retrieve timeseries.
• ensembleId: Id of the ensemble, can be null.
• ensembleMemberIndex Ensemble member index for this time series. (Only if configured)
• returns: Content of the binary file that can be exported together with the PITimeseries XML files.

Setter methods

void putLogMessage(String clientId, String piDiagnosticsXmlContent);

• clientId: <id only used as description>
• piDiagnosticsXmlContent: String containing the log messages in the format defined by the PI Diag XSD

void putModuleDataSet(String clientId, String taskId, String id, byte[] byteModuleDataSetContent,
               Date validityStartTime, Date validityEndTime, String ensembleId, int ensembleMemberIndex);

• <not implemented>

void putModuleParameterSet(String clientId, String id, String taskId, String piParameterSetXmlContent,
               Date validityStartTime, Date validityEndTime, String ensembleId, int ensembleMemberIndex);

• <not implemented>

void putState(String clientId, String taskId, String piStateXmlContent, String byteStateFileName,
                byte[] byteStateContent, String ensembleId, int ensembleMemberIndex);

• <not implemented>

void putTimeSeries(String clientId, String taskId, String id, String piTimeSeriesXmlContent,
                String ensembleId, int ensembleMemberIndex);

• currently not supported>
• in3 - ensembleMemberIndex: <currently not supported>
• returns: Binary content of the ModuleDataSet file for requested ModuleState.

byte[] getModuleParameterSet(String in0, String in1, String in2, int in3)

Get a module parameter set.

• in0 - clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - id: Reference to the ID of a ModuleParameterSet element in the service configuration file.
• in2 - ensembleId: <currently not supported>
• in3 - ensembleMemberIndex: <currently not supported>
• returns: String content of the ModuleParameterSet file for requested ModuleState.

byte[] getModuleStateBinary(String in0, String in1, Date in2, String in3, int in4);

Get a cold state file.

• in0 - clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - id: Reference to the ID of a ModuleState element in the service configuration file.
• in2 - stateTime: Time for which to retrieve warm state file. Time values can be obtained from method #getAvailableStateTimes
• in3 - ensembleId: <currently not supported>
• in4 - ensembleMemberIndex: <currently not supported>

Timeseries

String getTimeSeriesHeaders(String in0, String in1, String in2, Date in3,
		Date in4, Date in5, String[] in6, String[] in7, String in8, int in9,
		boolean in10);

Get the header information for requested timeseries.

• in0 - clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFilesclientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• taskId: <id not required>
• id: Reference to in1 - id: Reference to the ID of a TimeSeries element in the service configuration file.
• piTimeSeriesXmlContent: Time Series content in the form of a Pi timeseries xml file.
• in2 - taskId: <id not required however can not be null>
• in3 - startTime: Start date/time of run - Long.MAXVALUE if the configured default is to be used
• in4 - timeZero: Forecast time zero.
• in5 - endTime: End date/time of run - Long.MAXVALUE if the configured default is to be used
• in6 - parameterIds: Subset of parameter IDs for which to retrieve timeseries.
• in7 - locationIds: Subset of location IDs for which to retrieve timeseries.
• in8 - ensembleId: Id of the ensemble, can be null.
• in9 - ensembleMemberIndex : Ensemble member index for this time series. NULL if this is not an ensemble.(Only if configured)
• in10 - thresholdsVisible: (Optional) Option to add threshold values in the header if set to TRUE. Default is FALSE
• returns: String content of a PiTimeseries XML file only containing header information.

String getTimeSeries(String in0

void putTimeSeriesBinary(String clientId, String taskIdin1, String idin2, StringDate piTimeSeriesXmlContentin3,
		Date in4, Date in5, String[]             bytein6, String[] byteTimeSeriesContentin7, String ensembleIdin8, int ensembleMemberIndexin9,
		boolean in10);

Get header and data for requested timeseries.

• in0 - clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• taskId: <id not required>
• idin1 - id: Reference to the ID of a TimeSeries element in the service configuration file.
• piTimeSeriesXmlContent: Time Series content in the form of a Pi timeseries xml file.
• byteTimeSeriesContent: TimeSeries data content in the form of a byte array.
• in2 - taskId: <id not required however can not be null>
• in3 - startTime: Start date/time of run - Long.MAXVALUE if the configured default is to be used
• in4 - timeZero: Forecast time zero.
• in5 - endTime: End date/time of run - Long.MAXVALUE if the configured default is to be used
• in6 - parameterIds: Subset of parmater IDs for which to retrieve timeseries.
• in7 - locationIds: Subset of location IDs for which to retrieve timeseries.
• in8 - ensembleId: Id of the ensemble, can be null.
• in9 - ensembleMemberIndex : Ensemble member index for this time series. NULL if this is not an ensemble.

Run methods

...

String createTask(String clientId);

• clientId: <not required>
• returns: Unique task id.

...

• (Only if configured)
• in10 - thresholdsVisible: (Optional) Option to add threshold values in the header if set to TRUE. Default is FALSE
• returns: String content of a PiTimeseries XML file.

byte[] getTimeSeriesBytes(String in0, String in1, String in2, Date in3,
		Date in4, Date in5, String[] in6, String[] in7, String in8, int in9);

Get binary data for requested timeseries.

• in0 - clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - id: Reference to the ID of a TimeSeries element in the service configuration file.
• in2 - taskId: <id not required however can not be null>
• in3 - startTime: Start date/time of run - Long.MAXVALUE if the configured default is to be used
• in4 - timeZero: Forecast time zero.
• in5 - endTime: End date/time of run - Long.MAXVALUE if the configured default is to be used
• in6 - parameterIds: Subset of parameter IDs for which to retrieve timeseries.
• in7 - locationIds: Subset of location IDs for which to retrieve timeseries.
• in8 - ensembleId: Id of the ensemble, can be null.
• in9 - ensembleMemberIndex Ensemble member index for this time series. (Only if configured)
• returns: Content of the binary file that can be exported together with the PITimeseries XML files.

String getTimeSeriesHeadersForFilter(String in0, Date in1, Date in2, Date in3, String in4, String[] in5, String[] in6, boolean in7, String in8);

Get the header information for requested timeseries using a filter id.

• in0 - clientId: (Optional) File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD. If not
  provided then no id mapping will be done.
• in1 - startTime: Start date/time of run - Long.MAXVALUE if the configured default is to be used
• in2 - timeZero: Forecast time zero.
• in3 - endTime: End date/time of run - Long.MAXVALUE if the configured default is to be used
• in4 - filterId: Filter Id. Can be retrieved using the String getFilters(String piVersion) method.
• in5 - locationIds: Subset of location IDs for which to retrieve timeseries.
• in6 - parameterIds: Subset of parameter IDs for which to retrieve timeseries.
• in7 - useDisplayUnits: (Optional) Option to export values using display units (TRUE) instead of database units (FALSE).
• in8 - piVersion: (Optional) Pi Version for the return file. Defaults to the latest PI version.
• returns: String content of a Pi_Timeseries XML file only containing header information.

String getTimeSeriesForFilter(String in0, Date in1, Date in2, Date in3, String in4, String[] in5, String[] in6, boolean in7, boolean in8, String in9);

Get the timeseries data for requested timeseries using a filter id.

• in0 - clientId: (Optional) File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD. If not
  provided then no id mapping will be done.
• in1 - startTime: Start date/time of run - Long.MAXVALUE if the configured default is to be used
• in2 - timeZero: Forecast time zero.
• in3 - endTime: End date/time of run - Long.MAXVALUE if the configured default is to be used
• in4 - filterId: Filter Id. Can be retrieved using the String getFilters(String piVersion) method.
• in5 - locationIds: Subset of location IDs for which to retrieve timeseries.
• in6 - parameterIds: Subset of parameter IDs for which to retrieve timeseries.
• in7 - convertDatum: Option to convert values from relative to location height to absolute values (TRUE). If FALSE values remain relative.
• in8 - useDisplayUnits: Option to export values using display units (TRUE) instead of database units (FALSE).
• in9 - piVersion: (Optional) Pi Version for the return file. Defaults to the latest PI version.
• returns: String content of a Pi_Timeseries XML file only containing header information.

String getTimeSeriesForSegment(String in0, String in1, Date in2, Date in3, Date in4, boolean in5);

Get the timeseries data for requested timeseries using a filter id.

• in0 - segmentId: identifier of the segment node
• in1 - clientId: (Optional) File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD. If not provided then no id mapping will be done.
• in2 - timeZero: Forecast time zero.
• in3 - startTime: Start date/time of run - Long.MAXVALUE if the configured default is to be used
• in4 - endTime: End date/time of run - Long.MAXVALUE if the configured default is to be used
• in5 - threhsoldsVisisble: Option to include (TRUE) or exclude (FALSE) thresholds in the time series headers. Default is FALSE
• returns: String content of a Pi_Timeseries XML file containing all timeseries including headers for this segemnt

Client datasets

String[] getAllNodesWithDataset();

Retrieves all identifiers of sgement nodes holding one or more client datasets

• returns: Array of string identifiers of nodes

String[] getAllDataSetsIdsForNode(String in0, String in1);

Retrieves all identifiers to client datasets available for this segement node

• in0 - clientId: (Optional) File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - nodeId: Segment node identifier
• returns: Array of string identifiers referring to client datasets

String getDescription(String in0, String in1)

Retrieves description of a specific client dataset from the local datastore

• in0 - clientId: (Optional) File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - id: Identifier of client dataset
• returns: String description of dataset content

byte[] getDataSet(String in0, String in1)

Retrieves client dataset from the local datastore

• in0 - clientId: (Optional) File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - id: Identifier of client dataset
• returns: Byte content of the requested client dataset

long getLastModificationTimeDataSets();

Retrieves latest time when a client dataset has been modified

• returns: Modifcation Time as Long (modified Julian date)

Setter methods

void setSystemTime(Date in0);

Sets system time (Time zero)

• in0 - systemTime: new SystemTime

void putLogMessage(String in0, String in1);

Insert log messages

• in0 - clientId: <id only used as description>
• in1 - piDiagnosticsXmlContent: String containing the log messages in the format defined by the PI Diag XSD

void putModuleDataSet(String in0, String in1, String in2, byte[] in3,
               Date in4, Date in5, String in6, int in7);

Insert a module data set.

• <not implemented>

void putModuleParameterSet(String in0, String in1, String in2, String in3,
               Date in4, Date in5, String in6, int in7);

Insert a module parameter set.

• <not implemented>

void putState(String in0, String in1, String in2, String in3,
                byte[] in4, String in5, int in6);

• <not implemented>

void putTimeSeries(String in0, String in1, String in2, String in3,
                String in4, int in5);

Insert a timeseries.

• in0 - clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - taskId: <id not required>
• in2 - id: Reference to the ID of a TimeSeries element in the service configuration file.
• in3 - piTimeSeriesXmlContent: Time Series content in the form of a Pi timeseries xml file.
• in4 - ensembleId: Id of the ensemble
• in5 - ensembleMemberIndex: Ensemble member index for this time series. NULL if this is not an ensemble.

void putTimeSeriesBinary(String in0, String in1, String in2, String in3,
                 byte[] in4, String in5, int in6);

Insert a timeseries using the binary format.

• in0 - clientId: File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - taskId: <id not required>
• in2 - id: Reference to the ID of a TimeSeries element in the service configuration file.
• in3 - piTimeSeriesXmlContent: Time Series content in the form of a Pi timeseries xml file.
• in4 - byteTimeSeriesContent: TimeSeries data content in the form of a byte array.
• in5 - ensembleId: Id of the ensemble
• in6 - ensembleMemberIndex: Ensemble member index for this time series. NULL if this is not an ensemble.

void putTimeSeriesForFilters(String in0, String in1, byte[] in2, boolean in3);

Insert a timeseries using the Filters configuration.

• in0 - clientId: (Optional) File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD. If not
  provided then no id mapping will be done.
• in1 - piTimeSeriesXmlContent: Time Series content in the form of a Pi timeseries xml file. Timeseries must be
  available in the FEWS Filters configuration file.
• in2 - byteTimeSeriesContent: (Optional) TimeSeries data content in the form of a byte array.
• in3 - convertDatum Option to convert the values to values that are relative to location height (TRUE). If FALSE then no conversion is performed.

Run methods

String createTask(String in0);

Create a new task.

• in0 - clientId: <not required>
• returns: Unique task id.

String runTask(String in0, String in1, String in2, Date in3, Date in4,
          Date in4, String in5, String in6, String in7, String in8);

Run a newly created task.

• in0 - clientId: <not required>
• in1 - taskId: Id obtained by calling method #createTask
• in2 - workflowId: Id of workflow to run by task.
• in3 - startTime: <not required>
• in4 - timeZero: <not required>
• in5 - endTime: <not required>
• in6 - coldStateId: <not implemented>
• in7 - userId: Id of user running task.
• in8 - scenarioId: Id of what-if scenario.
• in9 - description: Description
• returns: TaskRun id

void cancelTask(String in0, String in1);

Cancel a running task.

• <not implemented>

boolean waitForTask(String in0, String in1, int in2);

Wait for a running task to finish.

• in0 - clientId: <not required>
• in1 - taskId: Id of task run. Returned by callingmethod #runTask.
• in2 - waitMillis: Wait time in milli seconds.
• returns: TRUE if task run completes successfully, else FALSE

When running tasks via the embedded FewsPiService they will run in the same way as they would run via the Manual Forecast Dialog. In some cases it might be required that tasks run via the service are run as IFD run. In this case it is possible to configure an option in the global.properties files:

PiServiceRunIfdTasks=true

Conversion methods

float[] convertToDisplayUnitValue(String in0, float[] in1);

Converts parameter values from base unit to display unit

• in0 - parameterId: Parameter identifier, used to trace down the associated base unit as well as the display unit
• in1- value: array of values to be converted
• returns: Array of converted values (floats)

float []inverseConvertToDisplayUnitValue(String in0, float[] in1);

Converts parameter values from display unit to base unit

• in0 - parameterId: Parameter identifier, used to trace down the associated base unit as well as the display unit
• in1 - value: array of values to be converted
• returns: Array of converted values (floats)

float[] convertStageToDischarge(float[] in0, String in1, long in2);

Converts stage value to discharge using a rating curve at a specific location valid for a particular moment in time

• in0 - locationId: Identifier of the rating cruve location
• in1 - time: time for which the rating curve should be valid
• in2 - stages: array of stages to be converted to discharge
• returns: array of values respresenting discharges

float[] convertDischargeToStage(float[] in0, String in1, long in2);

Converts discharge value to stage using a rating curve at a specific location valid for a particular moment in time

• in0 - locationId: Identifier of the rating cruve location
• in1 - time: time for which the rating curve should be valid
• in2 - discharge: array of discharges to be converted to stage
• returns: array of values respresenting stage

Data management methods for client data sets

void saveDataSet(String in0, String in1, byte[] in2, String in3, String in4);

Saves client data set to local datastore

• in0 - clientId: (Optional) File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - id: Identifier of client data set
• in2 - description: (Optional) description of the client dataset content
• in3 - dataSet: Byte object holding the client dataset
• in4 - nodeId: Segment/nodeId which is associated to this client dataset

void updateDataSet(String in0, String in1, byte[] in2, String in3, String in4);

Updates existing client data set in local datastore

• in0 - clientId: (Optional) File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1 - id: Identifier of client data set
• in2 - description: (Optional) description of the client dataset content
• in3 - dataSet: Byte object holding the client dataset
• in4 - nodeId: Segment/nodeId which is associated to this client dataset

void deleteDataSet(String in0, String in1);

Removes existing client data set from local datastore

• in0 - clientId: (Optional) File name of service configuration file located in the OC configuration directory 'PiServiceConfigFiles'. This file is an instance of the FewsPiServiceConfig XSD.
• in1- id: Identifier of client data set

void uploadDataSets();

Initiates a database synchronization to upload the client data set to the Master Controller

Installing a PI Service Client

Setting up a PI Service Client requires the following actions:

• Install an OC or SA.
• Select an available port number on which the service will be listening.
• Configure a FewsPiServiceCofig file for the OC/SA region.

PI Service configuration

The Pi Service configuration files are located in the directory 'PiServiceConfigFiles' of the region configuration. These files link the IDs know by the client applications to FEWS data, such as TimeSeries, States, ModuleDataSets and ModuleParameterSets.

A Pi Service file has five sections:

1. General: Contains general configuration, such as import and export locations. Id mapping information for mapping client location/parameter ids to FEWS location/parameter ids.
2. TimeSeries: Contains the mapping of client timeseries ids to the FEWS timeseries sets. Also some extra export options.
3. ModuleDataSet: Contains the mapping of client moduleDataSet ids to the FEWS moduleInstance descriptor ids.
4. ModuleParameterSet: Contains the mapping of client moduleParameterSet ids to the FEWS moduleInstance descriptor ids.
5. ModuleState: Contains the mapping of client moduleState ids to the FEWS moduleInstance descriptor ids.

If a client application requires an application specific configuration file then this file must be configured in the directory ' PiClientConfigFiles' of the region configuration. This file is free format (text) and can be obtained from the API by calling #getClientConfigFile.

Initializing PI Service in Explorer config

The FEWS system does not automatically start up the PI service listener environment. This needs to be configured in the Explorer configuration file located in the directory 'SystemConfigFiles' of the region configuration. To do this the following line must be entered at the end of Explorer configuration file:

<piServicePortRange start="8100" end="8100"/>

Where 'start' and 'end' represent the port number range within which the PI Service must find an available port. To fix the PI Service to a single port enter the same number twice.

Installing a FEWS PI Service as a backend process

It is also possible to initialize the FEWS PI Service as a backend process. The backend process is the same as the FEWS PI Service Client application, but then without the user interface. To run the service as a backend process the client needs to be installed first, as described above. After this has been completed continue with the following installation procedures:

The backend FEWS PI Service can be started in Windows by installing a Windows service that can start and stop the FEWS PI Service. Unpack the following archive containing the service installation files: NT_FewsEnvironmentShell_Service_Install.zip. Open a DOS command prompt in the directory containing the unpacked archive. Run the install:

install_service.bat <work dir> <region name>

# Where 'work dir' is the directory containing the BIN, JRE and REGION dirs
# and 'region name' is the directory name of the region for which to install the service

Running the install_service.bat creates a file called bin.txt. This file contains the class path variable that needs to be inserted into the service parameter field JVM Option Number 1. This must be done using the tool 'regedit'. The reason for this complicated step is that the FEWS class path is too long causing the service install script to fail.

When in 'regedit' the installed service can be found in the location:
Computer->HKEY_LOCAL_MACHINE->SYSTEM->CurrentControlSet->services->FewsShell <pi service name>

Start and stop the new service using the Windows services application. The service will have the following name; FewsShell <region name>.

Or in Linux by using the fews_piservice.sh file. This file should be placed in the same directory as the links to the JRE, BIN and the REGION dirs.

# start the service
./fews_piservice.sh <REGION NAME> start

# stop the servie
./fews_piservice.sh <REGION NAME> stop

This backend FEWS PI Service does not use the Explorer configuration, as described above, to obtain the listener port number. This is to make sure that the client FEWS PI Services can run independently from the backend FEWS PI Services without port conflicts. Instead the backend FEWS PI Service obtains its listener port from the global.properties files, using the entry:

PiServicePort=2001

When not configured the value defaults to 2001.

Example code

Here follows some example code of how client applications can set up a connection the PI Service of a running FEWS OC.

Setting up a connection in JAVA

Before starting the client will require the following library: xfire-all-1.2.5.jar. This library can be found in the bin directory of the FEWS system.

ObjectServiceFactory serviceFactory = new ObjectServiceFactory();
Service service = serviceFactory.create(FewsPiService.class);
XFireProxyFactory proxyFactory = new XFireProxyFactory();
 //port Number must be equal to the number configured in the Explorer.xml
int portNumber = 8100;
//localhost can be replaced by the ip address of the machine on which the FEWS system is running.
FewsPiService serviceProxy = (FewsPiService) proxyFactory.create(service, "http://localhost:" + portNumber + "/FewsPiService")

Setting up a connection in C

Before starting the client will require the following librarys: libtcl.so and the libraries belonging to the TclSOAP package.
While there is a C++ libraries to handle SOAP, we could not find a pure C library. At first sight the C++ libraries seem to make it necessary to define classes and so on before you can start using them. With the Tcl approach the code remains quite simple. (We have not investigated exactly what TclSOAP requires, but it can be downloaded from ActiveState)

For the example fewspi.tcl file used refer to the attachment fewspi-C.tgz

#include <stdio.h>
#include <tcl.h>

/* Define some helper variables and functions */

Tcl_Interp *interp;

int main( int argc, char *argv[] ) {

    /* Get the library started */

    if ( Init( argv[0] ) != TCL_OK ) {
        fprintf( stderr, "Sorry, initialisation failed: %s\n",
            Tcl_GetStringResult( interp ) );
    }

    /* Here insert calls to Pi Service */
    fprintf( stdout, "Locations: %s\n", getLocations( "id not required" ) );
    fprintf( stdout, "New task: %s\n", createTask( "id not required" ) );
}

void TearDown () {Tcl_Finalize();}

int EvalFile (char *fileName) {
    return Tcl_EvalFile(interp, fileName);
}

int Init (char *argv0) {
    char *pchar;
    char  buffer[1000];

    /* Initialise the library itself */

    Tcl_FindExecutable(argv0);
    interp = Tcl_CreateInterp();
    if (Tcl_Init(interp) != TCL_OK) {
        return TCL_ERROR;
    }

    /* Initialise the FEWS PI services */

    strcpy( buffer, argv0 );
    pchar = strrchr( buffer, '/' );
    if ( pchar == NULL ) {
        pchar = strrchr( buffer, '\\' );
    }
    if ( pchar == NULL ) {
        pchar = buffer;
    }
    strcpy( buffer, "fewspi.tcl" );

    return EvalFile( buffer );
}

Setting up method calls JAVA

Here follow some code examples of how to query the PI Service proxy from the client application. The configuration used to make these examples can be found in the attached Example Configuration.

   /**
     * Test the retrieval of system time.
     * <p/>
     * With this test the system time of a running Fews Region (on port 8191) can be retrieved. If the
     * system time of the region is changed then the returned value here will match the change.
     */
    public void testSystemTime() {
        String clientId = "not required";
        Date date = serviceProxy.getSystemTime(clientId);


        System.out.println("Current System time : " + dateFormat.format(date));
    }

    /**
     * Return the warm state times from the data base for the configured moduleState id=RSNWELEV_DETO3I
     * in the service configuration file = TestConfig.

...

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

• clientId: <not required>
• taskId: Id obtained by calling method #createTask
• workflowId: Id of workflow to run by task.
• startTime: <not required>
• timeZero: <not required>
• endTime: <not required>
• coldStateId: <not implemented>
• userId: Id of user running task.
• description: Description
• returns: TaskRun id

void cancelTask(String clientId, String taskId);

• <not implemented>

boolean waitForTask(String clientId, String taskId, int waitMillis);

• clientId: <not required>
• taskId: Id of task run. Returned by callingmethod #runTask.
• waitMillis: Wait time in milli seconds.
• returns: TRUE if task run completes successfully, else FALSE

Installing a PI Service Client

Setting up a PI Service Client requires the following actions:

• Install an OC or SA.
• Select an available port number on which the service will be listening.
• Configure a FewsPiServiceCofig file for the OC/SA region.

PI Service configuration

The Pi Service configuration files are located in the directory 'PiServiceConfigFiles' of the region configuration. These files link the IDs know by the client applications to FEWS data, such as TimeSeries, States, ModuleDataSets and ModuleParameterSets.

A Pi Service file has five sections:

1. General: Contains general configuration, such as import and export locations. Id mapping information for mapping client location/parameter ids to FEWS location/parameter ids.
2. TimeSeries: Contains the mapping of client timeseries ids to the FEWS timeseries sets. Also some extra export options.
3. ModuleDataSet: Contains the mapping of client moduleDataSet ids to the FEWS moduleInstance descriptor ids.
4. ModuleParameterSet: Contains the mapping of client moduleParameterSet ids to the FEWS moduleInstance descriptor ids.
5. ModuleState: Contains the mapping of client moduleState ids to the FEWS moduleInstance descriptor ids.

If a client application requires an application specific configuration file then this file must be configured in the directory ' PiClientConfigFiles' of the region configuration. This file is free format (text) and can be obtained from the API by calling #getClientConfigFile.

Initializing PI Service in Explorer config

The FEWS system does not automatically start up the PI service listener environment. This needs to be configured in the Explorer configuration file located in the directory 'SystemConfigFiles' of the region configuration. To do this the following line must be entered at the end of Explorer configuration file:

<piServicePortRange start="8100" end="8100"/>

Where 'start' and 'end' represent the port number range within which the PI Service must find an available port. To fix the PI Service to a single port enter the same number twice.

Example code

Here follows some example code of how client applications can set up a connection the PI Service of a running FEWS OC.

Before starting the client will require the following library: xfire-all-1.2.5.jar. This library can be found in the bin directory of the FEWS system.

Setting up a connection

ObjectServiceFactory serviceFactory = new ObjectServiceFactory();
Service service = serviceFactory.create(FewsPiService.class);
XFireProxyFactory proxyFactory = new XFireProxyFactory();
 //port Number must be equal to the number configured in the Explorer.xml
int portNumber = 8100;
//localhost can be replaced by the ip address of the machine on which the FEWS system is running.
FewsPiService serviceProxy = (FewsPiService) proxyFactory.create(service, "http://localhost:" + portNumber + "/FewsPiService")

Setting up method calls

Here follow some code examples of how to query the PI Service proxy from the client application. The configuration used to make these examples can be found in the attached Example Configuration.

   /**
     * Test the retrieval of system time.
     * <p/>
     * With this test the system time of a running Fews Region (on port 8191) can be retrieved. If the
     * system time of the region is changed then the returned value here will match the change.
     */
    public void testSystemTime() {
        String clientId = "not required";
        Date date = serviceProxy.getSystemTime(clientId);


        System.out.println("Current System time : " + dateFormat.format(date));
    }

    /**
     * Return the warm state times from the data base for the configured moduleState id=RSNWELEV_DETO3I
     * in the service configuration file = TestConfig.
     */
    public void testGetWarmStateTimes() {
        //name of service config file
        String clientId = "TestConfig";
        //id of moduleState element
        String moduleId = "RSNWELEV_DETO3I";

        Date[] stateTimes = serviceProxy.getAvailableStateTimes(clientId, moduleId);

        System.out.println("State times for Module " + moduleId);
        for (Date stateTime : stateTimes) {
            System.out.println("time: " + dateFormat.format(stateTime));
        }
    }

    /**
     * Return the cold state ids from the data base for the configured moduleState id=RSNWELEV_DETO3I
     * in the service configuration file = TestConfig.
     */
    public void testGetColdStateIds() {
        //name of service config file
        String clientId = "TestConfig";
        //id of moduleState element
        String moduleId = "RSNWELEV_DETO3I";

        String[] stateIds = serviceProxy.getColdStateIds(clientId, moduleId);

        System.out.println("Cold state ids for model " + moduleId);
        for (String id : stateIds) {
            System.out.println("cold state: " + id);
        }
    }

    /**
     * Return the warm state file from the data base for the configured moduleState id=SNOW17_LSMO3U
     * in the service configuration file = TestConfig. Write file to location d:/temp/<moduleStateId>.zip
     */
    public void testGetModuleStateBinary() throws IOException {
        //name of service config file
        String clientId = "TestConfig";
        //id of moduleState element
        String moduleId = "SNOW17_LSMO3U";

        Date[] stateTimes = serviceProxy.getAvailableStateTimes(clientId, moduleId);
        byte[] binary = serviceProxy.getModuleStateBinary(clientId, moduleId, stateTimes[0], null, -1);

        ZipInputStream zipInputStream = new ZipInputStream(new ByteArrayInputStream(binary));
        try {
            ZipUtils.unzipFiles(zipInputStream, new File("d:/temp/" + moduleId + ".zip"));
        } finally {
            zipInputStream.close();
        }
    }

    /**
     * Returns the content of a client configuration file from the config directory PiClientConfigFiles.
     *
     * Only requirement is that a configuration file (any type) with the clientId as name and moduleId as extension
     * must exist in this config directory.
     */
    public void testGetClientConfigurationFile(){
        //Name of client file
        String clientId = "MyClientConfigFile";
        //extension of client file
        String moduleId = "txt";

        String clientText = serviceProxy.getClientConfigFile(clientId, moduleId);

        System.out.println("Client file content: " + clientText);

    }

    /**
     * Retrieve the content of the locations xml. Write this to d:/temp/locations.xml
     * @throws IOException
     */
    public void testGetLocations() throws IOException {

        String locations = serviceProxy.getLocations("id not required");

        System.out.println("Content of locations xml file: " + locations);
        FileUtils.writeText("d:/temp/locations.xml", IOUtils.UTF8_CHARSET, locations);

    }

    /**
     * Return the member indices for the ensemble id = "ESP" from the timeseries table.
     *
     * This only works when there are ensemble members in the TimeSeries table.
     */
    public void testGetEnsembleMemberIndices(){

        String ensembleId = "ESP";
        int[] indices = serviceProxy.getEnsembleMemberIndices("id not required", ensembleId);

        System.out.println("Ensemble id " + ensembleId + " contains " + indices.length + " members.");
        System.out.println("indices are: ");
        for (int indice : indices) {
            System.out.println(indice);
        }

    }

    /**
     * Get the logentries for an Import TaskId.
     *
     * Check the LogEntries table to find a matching taskId.
     * 
     * @throws IOException
     */
    public void testGetLogInformation() throws IOException {

        String taskId = "NWSNWMC00:0000026"; //=import
        String logInfo = serviceProxy.getLogMessages("id not required", taskId);

        System.out.println("Content of log: " + logInfo);
        FileUtils.writeText("d:/temp/log.xml", IOUtils.UTF8_CHARSET, logInfo);

    }

    /**
     * Return the timeseries defined in the service configuration file under timeSeries element with id 'Reservoir'.
     *
     * Filter using parameter ids QIN and RQIN and location ids DETO3, GPRO3 and FOSO3
     *
     * Check timeseries table to look for existing times for these timeseries.
     *
     * @throws IOException
     */
    public void testGetTimeSeries() throws IOException {

        Date systemTime = serviceProxy.getSystemTime("id not required");
        Calendar instance = GregorianCalendar.getInstance(TimeZone.getTimeZone("GMT"));
        instance.set(2009, 4, 1);
        Date start = instance.getTime();
        instance.set(2009, 4, 11);
        Date end = instance.getTime();
        String[] params = new String[]{"QIN", "RQIN"};
        String[] locs = new String[]{"DETO3","GPRO3","FOSO3"};
        String headers = serviceProxy.getTimeSeriesHeaders("TestConfig", "Reservoir", null, start, systemTime, end, params, locs, null, -1);

        System.out.println("Content of tineseries headers: " + headers);

        String timeseriesfile = serviceProxy.getTimeSeries("TestConfig", "Reservoir", null, start, systemTime, end, params, locs, null, -1);

        FileUtils.writeText("d:/temp/timeseries.xml", IOUtils.UTF8_CHARSET, timeseriesfile);

    }

    /**
     * Upload a pi_diag log file to the region.
     *
     * Make sure to create an input file in corresponding directory.
     *
     * @throws IOException
     */
    public void testInsertLogMessages() throws IOException {

        String logText = FileUtils.readText("d:/temp/inputlog.xml");
        serviceProxy.putLogMessage("used as description", logText);
    }

    /**
     * Upload a pi_timeseries file to the Region. The timeseries in this file must be linked to timeseries configured
     * in the PiServiceConfig file.
     *
     * Make sure to create an input file in the corresponding directory.
     *
     * @throws IOException
     */
    public void testInsertTimeSeriestestGetWarmStateTimes() throws IOException {
{
        //name of service config file
        String timeseriesTextclientId = FileUtils.readText("d:/temp/inputtimeseries.xml")"TestConfig";
        System.out.println("Input timeseries: " + timeseriesText);//id of moduleState element
        serviceProxy.putTimeSeries("TestConfig", null, "Reservoir", timeseriesText, null, -1);String moduleId = "RSNWELEV_DETO3I";

    }

    /**
     * Schedule a task run and wait for it to finish.
     * Date[] stateTimes = serviceProxy.getAvailableStateTimes(clientId, moduleId);

        System.out.println("State times for Module " + moduleId);
     */
   for (Date publicstateTime void: testRunningTask(stateTimes) {
         String taskId = serviceProxySystem.out.createTaskprintln("id not required"time: " + dateFormat.format(stateTime));
        }
 Date date = serviceProxy.getSystemTime(""); }

    /**
     *  System.out.println("Starting task with id " + taskId + " time=" + new Date(System.currentTimeMillis()));Return the cold state ids from the data base for the configured moduleState id=RSNWELEV_DETO3I
     * in the Stringservice configuration taskRunIdfile = serviceProxy.runTask("id not required", taskId, "Santiam_Forecast", date, date, date, null, null, "Test user", "PiWebservice taskrun");
TestConfig.
     */
    public void testGetColdStateIds() {
        boolean//name resultof = serviceProxy.waitForTask("id not required", taskRunId, 120000);service config file
        String clientId = "TestConfig";
        //id of moduleState element
        String moduleId = "RSNWELEV_DETO3I";

        String[] stateIds = serviceProxy.getColdStateIds(clientId, moduleId);

        System.out.println("Task with idCold state ids for model " + taskId + (result ? " finished successfully" : " failed"));
 moduleId);
        for (String id : stateIds) {
            System.out.println("time=cold state: " + new Date(System.currentTimeMillis()));id);
        }
    }

Appendix

FewsPiService API

Example of the FewsPiService class. This class defines the API.

/* ================================================================
 * Delft FEWS
 * ================================================================
 *
 * Project Info:  http://www.wldelft.nl/soft/fews/index.html
 * Project Lead:  Karel Heynert (karel.heynert@wldelft.nl)
 *
 * (C) Copyright 2003, by WL | Delft Hydraulics
 *                 
    /**
     * Return the warm state file from the data base for the configured moduleState id=SNOW17_LSMO3U
     * in the service configuration file = TestConfig. Write file to location d:/temp/<moduleStateId>.zip
     */
    public void testGetModuleStateBinary() throws IOException {
       P.O. Box 177
 *   //name of service config file
        String clientId = "TestConfig";
        //id of  2600 MH  DelftmoduleState element
 *       String moduleId = "SNOW17_LSMO3U";

        Date[] stateTimes = serviceProxy.getAvailableStateTimes(clientId, moduleId);
  The Netherlands
 *    byte[] binary = serviceProxy.getModuleStateBinary(clientId, moduleId, stateTimes[0], null, -1);

        ZipInputStream zipInputStream = new  http://www.wldelft.nl
 *
 * DELFT-FEWS is a sophisticated collection of modules designed
 * for building a FEWS customised to the specific requirements
 * of individual agencies. An open modelling approach allows users
 * to add their own modules in an efficient way.
 *
 * ----------------------------------------------------------------
 * WebService.java
 * ----------------------------------------------------------------
 * (C) Copyright 2003, by WL | Delft Hydraulics
 *
 * Original Author:  Erik de Rooij
 * Contributor(s):
 *
 * Changes:
 * --------
 * 10-Sep-2007 : Version 1 ();
 *
 *
 */
package nl.wldelft.fews.system.pi;

import java.util.Date;

/**
 * TODO <code>ISSUES</code>
 *<li>Optional Date arguments can not be set to NULL when not used.</li>
 *<li> When retrieving timeseries. What use is it to add ensemble Id? Because the timeseries set already contains the ensemble id. </li>
 *<li> Some interface call do not require the clientId. Should we remove this to simplify things?</li>
 */
public interface FewsPiService {


    String getLocations(String clientId);ZipInputStream(new ByteArrayInputStream(binary));
        try {
            ZipUtils.unzipFiles(zipInputStream, new File("d:/temp/" + moduleId + ".zip"));
        } finally {
            zipInputStream.close();
        }
    }

    /**
     * Returns the content of a client configuration file from the config directory PiClientConfigFiles.
     *
     * Only requirement is that a configuration file (any type) with the clientId as name and moduleId as extension
     * must exist in this config directory.
     */
    public void testGetClientConfigurationFile(){
        //Name of client file
        String clientId = "MyClientConfigFile";
        //extension of client file
        String moduleId = "txt";

        String clientText = serviceProxy.getClientConfigFile(clientId, moduleId);

        System.out.println("Client file content: " + clientText);

    }

    /**
     * Retrieve the configurationcontent fileof forthe thelocations xml.

 Write this to d:/temp/locations.xml
     * @param@throws clientIdIOException
 Id of web service client*/
 (obtained on command linepublic whenvoid invokedtestGetLocations()
 throws IOException {

  * @param fileExtension. Case insensitive. Extension ofString thelocations config file (e.g. xml, ini), One client can have multiple config files
 = serviceProxy.getLocations("id not required");

    * with different file extensions.
     * @return client config text file. FormatSystem.out.println("Content of filelocations mustxml befile: known" by client.+ locations);
     */
    String getClientConfigFile(String clientId, String fileExtension);
FileUtils.writeText("d:/temp/locations.xml", IOUtils.UTF8_CHARSET, locations);

    }

    /**
     * CreateReturn athe newmember Task.indices Usefor returnthe Taskensemble id when= exporting"ESP" datafrom tothe thetimeseries WebServicetable.

     *
 @param clientId Id of web* serviceThis client (obtained on command lineonly works when invoked)
there are ensemble members  * @return Task id for in the newTimeSeries tasktable.
     */
    Stringpublic void createTasktestGetEnsembleMemberIndices(String clientId);{

    /**
    String *ensembleId Return the current time zero of the system.
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @return Time zero= "ESP";
        int[] indices = serviceProxy.getEnsembleMemberIndices("id not required", ensembleId);

        System.out.println("Ensemble id " + ensembleId + " contains " + indices.length + " members.");
     */
    Date getSystemTime(String clientId);


System.out.println("indices are: ");
    /**
    for *(int TODO
indice : indices)   *{
     * ID of Configured timezone for the webservice System.out.println(indice);
     * @param clientId
     * @return
     */ }

    String getTimeZoneId(String clientId);}

    /**
     * RunGet athe Singlelogentries task.for TaskIdan must be obtained using the method {@link FewsPiService#createTask(String)}Import TaskId.
     *
     * @paramCheck clientIdthe LogEntries Idtable ofto webfind servicea client (obtained on command line when invoked)matching taskId.
     *
     * @param taskId Task Id@throws IOException
     */
 @param workflowId Workflow Id
public void testGetLogInformation() throws IOException *{

 @param startTime start date/time of run - NULLString iftaskId the configured default is to be used
= "NWSNWMC00:0000026"; //=import
        String *logInfo @param timeZero Forecast time zero.= serviceProxy.getLogMessages("id not required", taskId);

     * @param endTime end date/time System.out.println("Content of runlog: -" NULL if the configured default is to be used
     * @param coldStateId String identifying the cold state to use - NULL if a cold state start is not forced
     * @param userId Id of user running task.+ logInfo);
        FileUtils.writeText("d:/temp/log.xml", IOUtils.UTF8_CHARSET, logInfo);

    }

    /**
     * Return the timeseries defined in the service configuration file under timeSeries element with id 'Reservoir'.
     *
     * Filter @paramusing descriptionparameter Description
ids QIN and RQIN and *location @returnids ReturnsDETO3, theGPRO3 TaskRunand idFOSO3
     */
    String runTask(String clientId, String taskId, String workflowId, Date startTime, Date timeZero, Date endTime, String coldStateId, String scenarioId, String userId, String description);

	/**
	 * Request Ids of available cold states
	 ** Check timeseries table to look for existing times for these timeseries.
     *
     * @throws IOException
     */
    public *void @paramtestGetTimeSeries() clientIdthrows IdIOException of{

 web service client (obtained on command line whenDate invoked)
systemTime = serviceProxy.getSystemTime("id not required");
 * @param id Id of the State moduleCalendar instance for which to retrieve the cold state ids.
	 * @return List of available cold state groups
	 */
	String[] getColdStateIds(String clientId, String id);
= GregorianCalendar.getInstance(TimeZone.getTimeZone("GMT"));
        instance.set(2009, 4, 1);
        Date start = instance.getTime();
    /**
     * Request run status of task. This can be used to wait for a task to complete
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId Task Id
     * @param waitMillis number of milli-seconds to wait between status requestsinstance.set(2009, 4, 11);
        Date end = instance.getTime();
        String[] params = new String[]{"QIN", "RQIN"};
        String[] locs = new String[]{"DETO3","GPRO3","FOSO3"};
        String headers = serviceProxy.getTimeSeriesHeaders("TestConfig", "Reservoir", null, start, systemTime, end, params, locs, null, -1);

     * @return boolean if task is complete or has been cancelled
 System.out.println("Content of tineseries headers: " + headers);

      */
  String timeseriesfile boolean= waitForTask(String clientId, String taskId, int waitMillisserviceProxy.getTimeSeries("TestConfig", "Reservoir", null, start, systemTime, end, params, locs, null, -1);

    /**
     * cancel task. Cancel a running taskFileUtils.writeText("d:/temp/timeseries.xml", IOUtils.UTF8_CHARSET, timeseriesfile);

    }

     /**
     * @paramUpload clientIda Idpi_diag oflog webfile serviceto client (obtained on command line when invoked)the region.
     *
     * Make @paramsure taskIdto Taskcreate Id
an input file in corresponding */directory.
    void cancelTask(String clientId, String taskId);

    /***
     * @throws IOException
     */
 Retrieve  the indicespublic forvoid thetestInsertLogMessages() giventhrows ensembleIOException id.{

     *
   String  * @param clientId Id of web service client (obtained on command line when invoked)logText = FileUtils.readText("d:/temp/inputlog.xml");
        serviceProxy.putLogMessage("used as description", logText);
    }

 * @param ensembleId Id of the ensemble /**
     * @returnUpload Alla validpi_timeseries indicesfile forto thisthe ensembleRegion.
 The timeseries in this */
file must be linked int[] getEnsembleMemberIndices(String clientId, String ensembleId);

to timeseries configured
      /*** in the PiServiceConfig file.
     *
 Write timeseries associated to a* specificMake tasksure to webservice.create Thean webserviceinput will store this information file in the databasecorresponding directory.
     *
     * If@throws theIOException
 time series is an ensemble*/
 then each ensemble memberpublic needsvoid totestInsertTimeSeries() bethrows submittedIOException individually.{

      *  String usingtimeseriesText the <i>ensembleMemberIndex</i> argument. For deterministic time series the <i>ensembleMemberIndex</i> is NULL= FileUtils.readText("d:/temp/inputtimeseries.xml");
        System.out.println("Input timeseries: " + timeseriesText);
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * to obtain valid ensemble member index values.serviceProxy.putTimeSeries("TestConfig", null, "Reservoir", timeseriesText, null, -1);
    }

    /**
     *
 Schedule a task run *and Thewait TaskIdfor mayit beto NULLfinish.
 or the requested task id.*
     */
 In case it ispublic NULL the time series is written as data visible to all other processes in FEWSvoid testRunningTask(){
        String taskId = serviceProxy.createTask("id not required");
     * In case itDate isdate TaskId the time series will be used only by the task run with TaskId (e.g. scenario time series)= serviceProxy.getSystemTime("");
        System.out.println("Starting task with id " + taskId + " time=" + new Date(System.currentTimeMillis()));
     *
   String  * @param clientId Id of web service client (obtained on command line when invoked)taskRunId = serviceProxy.runTask("id not required", taskId, "Santiam_Forecast", date, date, date, null, null, "Test user", "PiWebservice taskrun");

     *  @param taskIdboolean result Task= serviceProxy.waitForTask("id. Obtainednot using method {@link FewsPiService#createTask(String)}required", taskRunId, 120000);
     * @param id Id of the Pi timeseries xml content.
     * @param piTimeSeriesXmlContent  Time Series content in the form of a Pi timeseries xml file.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    void putTimeSeries(String clientId, String taskId, String id, String piTimeSeriesXmlContent, String ensembleId, int ensembleMemberIndex System.out.println("Task with id " + taskId + (result ? " finished successfully" : " failed"));
        System.out.println("time=" + new Date(System.currentTimeMillis()));
    }

Setting up method calls C

Here follow some code examples of how to query the PI Service proxy from the client application. The configuration used to make these examples can be found in the attached Example Configuration.

/* Fews PI services: wrapper functions */

char *getLocations( char *clientId ) {
    char buffer[1000];

    strcpy( buffer, "getLocations " );
    strcat( buffer, clientId );

    /**
if ( Tcl_Eval( interp, buffer *) Write timeseries. The webservice will store this information in the database.
     *!= TCL_OK )
{
        return NULL;
    } *else <p>{
     * For performance reasons it is possible to split the timeseries header information from the timeseries data. The header informationreturn Tcl_GetStringResult( interp ) ;
    }
}

char *createTask( char *clientId ) {
    Tcl_Obj *obj[2];

 is stored in obj[0] = Tcl_NewStringObj( "createTask", -1 );
    obj[1] = Tcl_NewStringObj( clientId, -1 );

    Tcl_IncrRefCount( obj[0] ) ;
    Tcl_IncrRefCount( obj[1] ) ;

    if ( Tcl_EvalObjv( interp, 2, obj, 0 ) != TCL_OK ) {
        return NULL;
    } else {

        Tcl_DecrRefCount( obj[0] ) ;
        Tcl_DecrRefCount( obj[1] ) ;
        return Tcl_GetStringResult( interp ) ;
    }
}

Appendix

FewsPiService WSDL

Example of the FewsPiService WSDL definition. This definition file is used by other applications to connect to the webservice.
fewsPiServiceWSDL.xml

FewsPiService API

Example of the FewsPiService class. This class defines the API.

/* ================================================================
 * Delft FEWS
 * ================================================================
 *
 * Project Info:  http://www.wldelft.nl/soft/fews/index.html
 * Project Lead:  Karel Heynert (karel.heynert@wldelft.nl)
 *
 * (C) Copyright 2003, by WL | Delft Hydraulics
 *                        P.O. Box 177
 *                        2600 MH  Delft
 *                        The Netherlands
 *                        http://www.wldelft.nl
 *
 * DELFT-FEWS is a sophisticated collection of modules designed
 * for building a FEWS customised to the specific requirements
 * of individual agencies. An open modelling approach allows users
 * to add their own modules in an efficient way.
 *
 * ----------------------------------------------------------------
 * WebService.java
 * ----------------------------------------------------------------
 * (C) Copyright 2003, by WL | Delft Hydraulics
 *
 * Original Author:  Erik de Rooij
 * Contributor(s):
 *
 * Changes:
 * --------
 * 10-Sep-2007 : Version 1 ();
 *
 *
 */
package nl.wldelft.fews.system.pi;

import java.util.Date;

/**
 * TODO <code>ISSUES</code>
 *<li>Optional Date arguments can not be set to NULL when not used.</li>
 *<li> When retrieving timeseries. What use is it to add ensemble Id? Because the timeseries set already contains the ensemble id. </li>
 *<li> Some interface call do not require the clientId. Should we remove this to simplify things?</li>
 */
public interface FewsPiService {


    String getLocations(String clientId);the <i>piTimeSeriesXmlContent</i> and the timeseries data is stored in the <i>byteTimeSeriesContent</i>.
     * <p>
     * If the time series is an ensemble then each ensemble member needs to be submitted individually.
     * using the <i>ensembleMemberIndex</i> argument. For deterministic time series the <i>ensembleMemberIndex</i> is NULL
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * to obtain valid ensemble member index values.
     *
     * The TaskId may be NULL or the requested task id.
     * In case it is NULL the time series is written as data visible to all other processes in FEWS
     * In case it is TaskId the time series will be used only by the task run with TaskId (e.g. scenario time series)
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param id Id of the Pi timeseries xml content.
     * @param piTimeSeriesXmlContent  TimeSeries content in the form of a Pi timeseries xml file.
     * @param byteTimeSeriesContent  TimeSeries data content in the form of a byte array.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    void putTimeSeriesBinary(String clientId, String taskId, String id, String piTimeSeriesXmlContent, byte[] byteTimeSeriesContent, String ensembleId, int ensembleMemberIndex);

    /**
     * Write information about the parameter set file given the webservice.
     *
     * The TaskId may be NULL or the requested task id.
     * In case it is NULL the parameters version will be upaded
     * In case it is TaskId the parameters will be used only by the task run with TaskId (e.g. scenario run)
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param id Id of parameter set
     * @param piParameterSetXmlContent  Parameters content in the form of a Pi parameters xml file.
     * @param validityStartTime Start time of parameter validity (NULL if not applicable)
     * @param validityEndTime End time of parameter validity (NULL if not applicable)
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    void putModuleParameterSet(String clientId, String id, String taskId, String piParameterSetXmlContent, Date validityStartTime, Date validityEndTime, String ensembleId, int ensembleMemberIndex);

    /**
     * Write informationRetrieve about the datasetconfiguration file for the .

 given taskId back to the* webservice.@param TheclientId webserviceId willof storeweb thisservice informationclient and(obtained willon addcommand itline towhen theinvoked)
     * task@param propertiesfileExtension. when Case insensitive. Extension of the taskconfig is run.
     *file (e.g. xml, ini), One client can have multiple config files
     * @paramwith clientIddifferent Idfile ofextensions.
 web service client (obtained on* command@return lineclient whenconfig invoked)
text file. Format of file *must @parambe taskIdknown by Task idclient.
 Obtained using method {@link FewsPiService#createTask(String)} */
    String * @param id Id of Module DataSet file.getClientConfigFile(String clientId, String fileExtension);


    /**
     * @paramCreate byteModuleDataSetContenta Zippednew moduleTask. datasetUse file
return Task id when exporting data to the WebService.

     * @param validityStartTimeclientId StartId timeof ofweb datasetservice validityclient (NULL if not applicableobtained on command line when invoked)
     * @param@return validityEndTimeTask Endid timefor ofthe dataset validity (NULL if not applicable)new task.
     */
 @param ensembleId Id ofString the ensemblecreateTask(String clientId);

    /**
 * @param ensembleMemberIndex Ensemble member* indexReturn forthe thiscurrent time series.zero NULLof if this is not an ensemblethe system.
     */
     void* putModuleDataSet(String@param clientId, StringId taskId,of Stringweb id, byte[] byteModuleDataSetContent, Date validityStartTime, Date validityEndTime, String ensembleId, int ensembleMemberIndex);service client (obtained on command line when invoked)
     * @return Time zero
     */
    Date getSystemTime(String clientId);


    /**
     * TODO
    Write state*
 information to webservice. The webservice* willID storeof thisConfigured informationtimezone infor the database.webservice
     * @param clientId
     * <p>@return
     */
 The state information consistsString of two seperate parts. The <i>piStateXmlContent</i> containing informationgetTimeZoneId(String clientId);

    /**
     * aboutRun thea stateSingle filestask. AndTaskId the <i>byteStateContent</i> containingmust be obtained using the actualmethod state data for the module{@link FewsPiService#createTask(String)}.
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}Id
     * @param piStateXmlContentworkflowId  Pi state xml file.Workflow Id
     * @param byteStateFileNamestartTime start namedate/time of run - NULL if the stateconfigured filedefault datais contentto bytebe array.used
     * @param byteStateContenttimeZero Forecast time Statezero.
 file data content in the* form@param ofendTime aend byte array.
     * @param ensembleId Id of the ensembledate/time of run - NULL if the configured default is to be used
     * @param ensembleMemberIndexcoldStateId EnsembleString identifying memberthe indexcold forstate thisto timeuse series.- NULL if this a cold state start is not an ensemble.forced
     */
 @param scenarioId  void putState(String clientId,identifying Stringthe taskId, String piStateXmlContent, String byteStateFileName, byte[] byteStateContent, String ensembleId, int ensembleMemberIndex);


    /**
     * Put a log message
     *"what if" scenario - NULL if not used
     * @param userId Id of user running task.
     * @param clientIddescription IdDescription
 of web service client (obtained* on@return commandReturns linethe whenTaskRun invoked)id
     */
 @param piDiagnosticsXmlContent Pi Diagnostics xml file.
     */
    void putLogMessage(String clientIdString runTask(String clientId, String taskId, String workflowId, Date startTime, Date timeZero, Date endTime, String coldStateId, String scenarioId, String userId, String piDiagnosticsXmlContentdescription);

    	/**
	     * ReadRequest moduleIds datasetof informationavailable fromcold webservice.states
	     *
     * <p>
@param clientId Id of web *Defaultservice dataclient set(obtained ison returned.
command line when   *invoked)
     * @param clientIdid Id of webservice configuration that isthe State module instance for which to beretrieve queried
the cold state  ids.
	 * @param@return id IdList of theavailable modulecold datastate set .
     * @return Module data set file as byte array.groups
	 */
	String[] getColdStateIds(String clientId, String id);

    /**
     * @paramRequest ensembleIdrun Idstatus of thetask. ensemble
This can be used  * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.to wait for a task to complete
     *
     */
 @param clientId Id of byte[] getModuleDataSet(String clientId, String id, String ensembleId, int ensembleMemberIndex);

web service client (obtained on command line when invoked)
     /**
 @param taskId Task Id
 *   Read module* parameter@param setwaitMillis informationnumber from webservice.
     *of milli-seconds to wait between status requests
     * <p>
@return boolean if task is *Defaultcomplete dataor parameterSethas isbeen returned.cancelled
     */
     * @paramboolean waitForTask(String clientId, IdString oftaskId, webservice configuration that is to be queriedint waitMillis);

    /**
     * cancel @paramtask. idCancel namea ofrunning thetask
 binary module parameter set file.*
     * @param ensembleIdclientId Id of the ensemble web service client (obtained on command line when invoked)
     * @param ensembleMemberIndextaskId EnsembleTask memberId
 index for this time series. NULL if this is not an ensemble.
     * @return Module parameter set PiParameters xml.
     * */
    Stringvoid getModuleParameterSetcancelTask(String clientId, String id, String ensembleId, int ensembleMemberIndextaskId);


    /**
     * ReadRetrieve allthe availableindices statefor timesthe forgiven requestedensemble state fileid.
     *
     * @param clientId Id of web service webserviceclient configuration(obtained thaton iscommand toline bewhen queriedinvoked)
     * @param idensembleId Id of the module state .ensemble
     * @return All availablevalid state timesindices for this module state fileensemble.
     */
    Dateint[] getAvailableStateTimesgetEnsembleMemberIndices(String clientId, String idensembleId);


    /**
     * ReadWrite moduletimeseries stateassociated information fromto a specific task to webservice.
     * The webservice will store this information in the database.
     * <p>
     *Module If statethe datatime fileseries is returned for given time. Use method {@link FewsPiService#getAvailableStateTimes(String, String)}an ensemble then each ensemble member needs to be submitted individually.
     * tousing retrieve the available state times.
     *
     * @param clientId Id of webservice configuration that is to be queried<i>ensembleMemberIndex</i> argument. For deterministic time series the <i>ensembleMemberIndex</i> is NULL
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * @paramto idobtain Idvalid ofensemble themember stateindex values.
     *
 @param stateTime Time for which to retrieve a state file    * The TaskId may be NULL or the requested task id.
     * @returnIn Modulecase stateit datais fileNULL asthe bytetime array.
series is written as data *visible @paramto ensembleIdall Idother ofprocesses thein ensembleFEWS
     * @paramIn ensembleMemberIndexcase Ensembleit memberis indexTaskId for thisthe time series. NULL if this is not an ensemble. will be used only by the task run with TaskId (e.g. scenario time series)
     */
    byte[] getModuleStateBinary(String * @param clientId, StringId id,of Dateweb stateTime,service String ensembleId, int ensembleMemberIndex);


client (obtained on command line when invoked)
     /**
 @param taskId  Task * Read the timeseries from the webservice. Returns a pi timeseries xml file containing the timeseries informationid. Obtained using method {@link FewsPiService#createTask(String)}
     * @param id Id of the Pi timeseries xml content.
     *
     * <p> @param piTimeSeriesXmlContent  Time Series content in the form of a Pi timeseries xml file.
     * If @param ensembleId Id of the ensemble
  id has been configured* for@param thisensembleMemberIndex timeseriesEnsemble thenmember addindex thefor <i>ensembleMemberIndex</i>this astime argumentseries. Use NULL if this is not an ensemble.
     */
 Use   {@linkvoid FewsPiService#getEnsembleMemberIndicesputTimeSeries(String clientId, String)}
 taskId, String id, String *piTimeSeriesXmlContent, toString obtainensembleId, valid index values.int ensembleMemberIndex);

     /**
     * Write timeseries. The webservice TaskIdwill maystore bethis NULLinformation orin the requested task iddatabase.
	 * In case it is*
 TaskId the time series is* retrieved<p>
 for the taskId only for* simulatedFor time series
	 * In caseperformance reasons it is NULLpossible timeto series forsplit the currenttimeseries forecastheader willinformation befrom retreived
the timeseries data. The header *information
     * @paramis clientIdstored Id of webservice configuration that is to be queriedin the <i>piTimeSeriesXmlContent</i> and the timeseries data is stored in the <i>byteTimeSeriesContent</i>.
     * @param<p>
    id Id* ofIf the time series string.
is an ensemble then each *ensemble @parammember taskIdneeds to Taskbe submitted idindividually.
  Obtained using method {@link FewsPiService#createTask(String)}
     * @param startTime start date/time of run - NULL if the configured default is to be used* using the <i>ensembleMemberIndex</i> argument. For deterministic time series the <i>ensembleMemberIndex</i> is NULL
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * @param timeZero Forecast time zeroto obtain valid ensemble member index values.
     *
 @param endTime   end* date/timeThe ofTaskId runmay -be NULL ifor the configuredrequested default is to be usedtask id.
     * @paramIn parameterIdscase Subsetit ofis parmatersNULL forthe whichtime toseries retrieveis timeseries.
written as data visible to *all @paramother locationIdsprocesses Subset of locations for which to retrieve timeseries.in FEWS
     * In @paramcase ensembleIdit Idis ofTaskId the time ensemble
series will be used only *by @paramthe ensembleMemberIndextask Ensemblerun memberwith index for thisTaskId (e.g. scenario time series. (Only if configured)
     *
 @return  PiTimeseries xml file content.
     */
    String getTimeSeries(String clientId, String id, String taskId, Date startTime, Date timeZero, Date endTime, String[] parameterIds, String[] locationIds, String ensembleId, int ensembleMemberIndex);


    /*** @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param id Id of the Pi timeseries xml content.
     * @param piTimeSeriesXmlContent Read theTimeSeries timeseriescontent fromin the webservice.form Returnsof a piPi timeseries xml file.
     * containing@param byteTimeSeriesContent the timeseriesTimeSeries headersdata information.content Retrievein the timeseries data usingform of a byte array.
     * @param ensembleId Id of the methodensemble
     * {@link FewsPiService#getTimeSeriesBytes(String, String, String, java.util.Date, java.util.Date, java.util.Date, String[], String[], String, int)}
     @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    void putTimeSeriesBinary(String clientId, String taskId, String id, String piTimeSeriesXmlContent, byte[] byteTimeSeriesContent, String ensembleId, int ensembleMemberIndex);

    /**
     * <p>
Write information about the parameter set *file Ifgiven the ensemble id has been configured for this timeseries then add the <i>ensembleMemberIndex</i> as argument. Otherwise
     * this argument is skipped by the webservice.
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * to obtain valid index values.
     *
     * The TaskId may be NULL or the requested task id.
	     * In case it is TaskIdNULL the timeparameters seriesversion iswill retrievedbe forupaded
 the taskId only for simulated time series
	 * In case it is NULL time series forTaskId the current forecastparameters will be retreived
used only by the task *
run with TaskId (e.g. scenario *run)
 @param clientId Id of webservice*
 configuration that is to be* queried
@param clientId Id of web *service @paramclient id(obtained Idon ofcommand theline time series string.when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param startTimeid startId date/time of runparameter -set
 NULL if the configured default* is@param topiParameterSetXmlContent be used
Parameters content in the form *of @parama timeZeroPi Forecastparameters timexml zerofile.
     * @param endTimevalidityStartTime endStart date/time of runparameter -validity (NULL if the configured default is to be usednot applicable)
     * @param parameterIdsvalidityEndTime Subset of parmaters for which to retrieve timeseries.
     * @param locationIds Subset of locations for which to retrieve timeseries.End time of parameter validity (NULL if not applicable)
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. (OnlyNULL if configured)
this is not   * @return  PiTimeseries xml file contentan ensemble.
     */
    Stringvoid getTimeSeriesHeadersputModuleParameterSet(String clientId, String id, String taskId, DateString startTimepiParameterSetXmlContent, Date timeZerovalidityStartTime, Date endTimevalidityEndTime, String[] parameterIds, String[] locationIds, String ensembleId, int ensembleMemberIndex);

    /**
     * Write information Readabout the timeseriesdataset datafile fromfor the webservice.given Returns the data belongingtaskId back to the
 webservice. The webservice will *store timeseriesthis thatinformation areand retrieved whenwill add it to the
 method  {@link FewsPiService#getTimeSeriesBytes(String, String, String, java.util.Date, java.util.Date, java.util.Date, String[], String[], String, int)} * task properties when the task is run.
     *
  is called using the* same@param arguments.
clientId Id of web service *
client (obtained on command line *when <p>invoked)
     * @param IftaskId the ensembleTask id. hasObtained beenusing configuredmethod for this timeseries then add the <i>ensembleMemberIndex</i> as argument. Otherwise
     * this argument is skipped by the webservice.{@link FewsPiService#createTask(String)}
     * @param id Id of Module DataSet file.
     * @param byteModuleDataSetContent Zipped module dataset file
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}@param validityStartTime Start time of dataset validity (NULL if not applicable)
     * @param tovalidityEndTime obtainEnd validtime indexof values.
dataset validity (NULL if not *applicable)
     * The@param TaskIdensembleId mayId beof NULLthe orensemble
 the requested task id.
	 * @param InensembleMemberIndex caseEnsemble itmember isindex TaskIdfor thethis time series. isNULL if retrievedthis foris thenot taskIdan onlyensemble.
 for simulated time series
	 */
 In case it is NULL time series for the current forecast will be retreived void putModuleDataSet(String clientId, String taskId, String id, byte[] byteModuleDataSetContent, Date validityStartTime, Date validityEndTime, String ensembleId, int ensembleMemberIndex);

     /**
     * @param clientId Id of webservice configuration that is to be queriedWrite state information to webservice. The webservice will store this information in the database.
     *
  @param id Id of* the<p>
 time series string.
  * The state *information @paramconsists taskIdof two Taskseperate idparts. ObtainedThe using<i>piStateXmlContent</i> method {@link FewsPiService#createTask(String)}containing information
     * @paramabout startTimethe start date/time of run - NULL ifstate files. And the <i>byteStateContent</i> containing the configuredactual defaultstate isdata tofor bethe usedmodule.
     * @param timeZero Forecast time zero.
     * @param endTimeclientId endId date/time of runweb -service NULLclient if(obtained theon configuredcommand defaultline is to be usedwhen invoked)
     * @param parameterIdstaskId Subset ofTask parmatersid. forObtained whichusing tomethod retrieve timeseries.{@link FewsPiService#createTask(String)}
     * @param locationIdspiStateXmlContent Subset ofPi locationsstate for which to retrieve timeseriesxml file.
     * @param byteStateFileName ensembleId Idname of the ensemblestate file data content byte array.
     * @param ensembleMemberIndexbyteStateContent Ensemble member index for this time series. (Only if configured) State file data content in the form of a byte array.
     * @param ensembleId Id of the ensemble
     * @return  PiTimeseries xml file content@param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    byte[]void getTimeSeriesBytesputState(String clientId, String idtaskId, String taskIdpiStateXmlContent, Date startTime, Date timeZero, Date endTime, String[] parameterIdsbyteStateFileName, Stringbyte[] locationIdsbyteStateContent, String ensembleId, int ensembleMemberIndex);


    /**
     * getPut a log message
 associated to a specified taskId*
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @return PiDiagnostics XML file content.
     */
    String getLogMessages(String clientId, String taskId);


}

FewsPiServiceConfig XSD

...

 when invoked)
     * @param piDiagnosticsXmlContent Pi Diagnostics xml file.
     */
    void putLogMessage(String clientId, String piDiagnosticsXmlContent);

    /**
     * Read module dataset information from webservice.
     *
     * <p>
     *Default data set is returned.
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the module data set .
     * @return Module data set file as byte array.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    byte[] getModuleDataSet(String clientId, String id, String ensembleId, int ensembleMemberIndex);

    /**
     * Read module parameter set information from webservice.
     *
     * <p>
     *Default data parameterSet is returned.
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id name of the binary module parameter set file.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     * @return Module parameter set PiParameters xml.
     */
    String getModuleParameterSet(String clientId, String id, String ensembleId, int ensembleMemberIndex);


    /**
     * Read all available state times for requested state file.
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the module state .
     * @return All available state times for this module state file.
     */
    Date[] getAvailableStateTimes(String clientId, String id);


    /**
     * Read module state information from webservice.
     *
     * <p>
     *Module state data file is returned for given time. Use method {@link FewsPiService#getAvailableStateTimes(String, String)}
     * to retrieve the available state times.
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the state .
     * @param stateTime Time for which to retrieve a state file.
     * @return Module state data file as byte array.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    byte[] getModuleStateBinary(String clientId, String id, Date stateTime, String ensembleId, int ensembleMemberIndex);


    /**
     * Read the timeseries from the webservice. Returns a pi timeseries xml file containing the timeseries information.
     *
     * <p>
     * If the ensemble id has been configured for this timeseries then add the <i>ensembleMemberIndex</i> as argument. Use NULL if not an ensemble
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * to obtain valid index values.
     *
     * The TaskId may be NULL or the requested task id.
	 * In case it is TaskId the time series is retrieved for the taskId only for simulated time series
	 * In case it is NULL time series for the current forecast will be retreived
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the time series string.
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param startTime start date/time of run - NULL if the configured default is to be used
     * @param timeZero Forecast time zero.
     * @param endTime end date/time of run - NULL if the configured default is to be used
     * @param parameterIds Subset of parmaters for which to retrieve timeseries.
     * @param locationIds Subset of locations for which to retrieve timeseries.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. (Only if configured)
     * @return  PiTimeseries xml file content.
     */
    String getTimeSeries(String clientId, String id, String taskId, Date startTime, Date timeZero, Date endTime, String[] parameterIds, String[] locationIds, String ensembleId, int ensembleMemberIndex);


    /**
     * Read the timeseries from the webservice. Returns a pi timeseries xml file
     * containing the timeseries headers information. Retrieve the timeseries data using the method
     * {@link FewsPiService#getTimeSeriesBytes(String, String, String, java.util.Date, java.util.Date, java.util.Date, String[], String[], String, int)}
     *
     * <p>
     * If the ensemble id has been configured for this timeseries then add the <i>ensembleMemberIndex</i> as argument. Otherwise
     * this argument is skipped by the webservice.
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * to obtain valid index values.
     *
     * The TaskId may be NULL or the requested task id.
	 * In case it is TaskId the time series is retrieved for the taskId only for simulated time series
	 * In case it is NULL time series for the current forecast will be retreived
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the time series string.
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param startTime start date/time of run - NULL if the configured default is to be used
     * @param timeZero Forecast time zero.
     * @param endTime end date/time of run - NULL if the configured default is to be used
     * @param parameterIds Subset of parmaters for which to retrieve timeseries.
     * @param locationIds Subset of locations for which to retrieve timeseries.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. (Only if configured)
     * @return  PiTimeseries xml file content.
     */
    String getTimeSeriesHeaders(String clientId, String id, String taskId, Date startTime, Date timeZero, Date endTime, String[] parameterIds, String[] locationIds, String ensembleId, int ensembleMemberIndex);

    /**
     * Read the timeseries data from the webservice. Returns the data belonging to the
     * timeseries that are retrieved when the method  {@link FewsPiService#getTimeSeriesBytes(String, String, String, java.util.Date, java.util.Date, java.util.Date, String[], String[], String, int)}
     * is called using the same arguments.
     *
     * <p>
     * If the ensemble id has been configured for this timeseries then add the <i>ensembleMemberIndex</i> as argument. Otherwise
     * this argument is skipped by the webservice.
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * to obtain valid index values.
     *
     * The TaskId may be NULL or the requested task id.
	 * In case it is TaskId the time series is retrieved for the taskId only for simulated time series
	 * In case it is NULL time series for the current forecast will be retreived
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the time series string.
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param startTime start date/time of run - NULL if the configured default is to be used
     * @param timeZero Forecast time zero.
     * @param endTime end date/time of run - NULL if the configured default is to be used
     * @param parameterIds Subset of parmaters for which to retrieve timeseries.
     * @param locationIds Subset of locations for which to retrieve timeseries.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. (Only if configured)
     * @return  PiTimeseries xml file content.
     */
    byte[] getTimeSeriesBytes(String clientId, String id, String taskId, Date startTime, Date timeZero, Date endTime, String[] parameterIds, String[] locationIds, String ensembleId, int ensembleMemberIndex);

    /**
     * get a log message associated to a specified taskId
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @return PiDiagnostics XML file content.
     */
    String getLogMessages(String clientId, String taskId);


}

FewsPiServiceConfig XSD

Example of the FewsPiServiceConfig schema file.
Image Added

Running Delft-FEWS in the background

When you use the PI service it is not necessary to have the main window displayed or anyone
operating the program at all. Under Windows, there is always a monitor, but on Linux machines
this may not be the case, especially with server machines.

To start Delft-FEWS in the background on Linux with no window present, use the following
recipe:

• Start the X virtual framebuffer server, Xvfb
• Set the DISPLAY environment variable to point to that display
• Start FEWS in the background

This way no window will be visible and no monitor will be needed. A small shell script
will take care of the details:

#
# Start the Xvfb server using screen "1" (to avoid issues with a possibly running X server)
Xvfb :1
#
# Set the DISPLAY environment variable so that FEWS will use the Xvfb server
#
export DISPLAY=:1.0
#
# Start FEWS (standalone or operator client) in the background
#
bin/fews.sh REGION