Page History

POST timeseries (2017.02)

Write timeseries data to the FEWS system using the timeseries sets defined by the filters. The timeSeries are stored in the piTimeSeriesXmlContent.

The timeseries you post to the rest service should match one of the time series sets in the default filter or one of its sub filters. To make sure you only write time series for a specific filter, you can pass a filterId with the POST request. Only timeseries that have timeseries sets that are configured in that filter (or one of its sub filters) will be accepted. If no filterId is used, all time series will be accepted that are configured in the default filter. Writing the time series works similar to importing time series using the pi.xml format using the "PI" import type. See also: Delft-Fews Published Interface timeseries Format (PI) Import

The 'convertDatum' argument is to allow timeseries that support a datum to have their values converted to a value relative to the location height. If values are already relative to location then enter FALSE or omit.

In case a time series already exists in the database, the time series will be overwritten by the ones that are posted. For forecast time series with different forecastDates a new time series will be added. The latter can be achieved by providing a forecastDate element in the POST request, e.g. <forecastDate date="2013-01-01" time="00:00:00"/>.

N.B.: by default POST operations are disabled in the Delft-FEWS WebServices and have to be explicitly enabled by setting the READONLY_MODE to false in the FewsPiService.properties. See also: FEWS Web Services Configuration FewsPiService.properties (deprecated since 2022.02).

Request parameters

• filterId (string, optional): Filter id for when the input timeseries maps to multiple internal timeseries. Within the scope of the filter the input timeseries should only map to one internal timeseries. When no filterId is specified, the default filter applies.

• convertDatum (boolean, optional): Convert values from relative location height to absolute height values

Body parameters

• piTimeSeriesXmlContent (xml string, required): PiTimeseries xml file  encoded in the 'application/x-www-form-urlencoded Content-Type. Example of a piTimeSeriesXmlContent (unencoded):

  Code Block

  <?xml version="1.0" encoding="UTF-8"?> <TimeSeries xmlns="http://www.wldelft.nl/fews/PI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_timeseries.xsd" version="1.12"> <timeZone>0.0</timeZone> <series> <header> <type>instantaneous</type> <locationId>63306260000</locationId> <parameterId>T.obs.mean</parameterId> <timeStep unit="nonequidistant"/> <startDate date="2013-01-01" time="00:40:00"/> <endDate date="2013-01-01" time="00:50:00"/> <missVal>-999.0</missVal> <stationName>DE BILT</stationName> <lat>51.76391247583424</lat> <lon>4.329717456157946</lon> <x>82000.0</x> <y>420000.0</y> <z>0.0</z> <units>m</units> </header> <event date="2013-01-01" time="00:40:00" value="13.0" flag="0"/> <event date="2013-01-01" time="00:50:00" value="13.0" flag="0"/> </series> </TimeSeries>

  Since 2018.02 the service also supports milliseconds. The parser automatically recognises which format is used.

• 
  

  Code Block
  language xml linenumbers true
  <?xml version="1.0" encoding="UTF-8"?> <TimeSeries xmlns="http://www.wldelft.nl/fews/PI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_timeseries.xsd" version="1.12"> <timeZone>0.0</timeZone> <series> <header> <type>instantaneous</type> <locationId>63306260000</locationId> <parameterId>T.obs.mean</parameterId> <timeStep unit="nonequidistant"/> <startDate date="2013-01-01" time="00:40:00.750"/> <endDate date="2013-01-01" time="00:50:00.250"/> <missVal>-999.0</missVal> <stationName>DE BILT</stationName> <lat>51.76391247583424</lat> <lon>4.329717456157946</lon> <x>82000.0</x> <y>420000.0</y> <z>0.0</z> <units>m</units> </header> <event date="2013-01-01" time="00:40:00.750" value="13.0" flag="0"/> <event date="2013-01-01" time="00:50:00.250" value="13.0" flag="0"/> </series> </TimeSeries>

  
  

• N.B. The SOAP Web Service has support for posting timeSeries as binary data using the piTimeSeriesBinaryContent. This is NOT support in this REST service of the PI Service.

• When sending in a set of timeseries that correspond to (e.g.) a completed forecast over multiple locations, it is not necessary to POST each location separately, the entire set be sent in one TimeSeries XML document with multiple series.
• There is no option in the REST Web Service to do any aggregation or transformation.

Response

• Diag PI xml response with all diagnostic output.

Example request

The following example shows how timeSeries can created using the POST method. Take note that the TimeSeries have to be posted in PI XML Format in the body of the POST request using the piTimeSeriesXmlContent key. The value is the content of the PI XML Timeseries in application/x-www-form-urlencoded format.

curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseries/" -X POST -H "Content-Type: application/x-www-form-urlencoded" -d piTimeSeriesXmlContent=%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%0D%0A%3CTimeSeries%20xmlns%3D%22http%3A%2F%2Fwww.wldelft.nl%2Ffews%2FPI%22%20xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22%0D%0A%09%09%09xsi%3AschemaLocation%3D%22http%3A%2F%2Fwww.wldelft.nl%2Ffews%2FPI%20http%3A%2F%2Ffews.wldelft.nl%2Fschemas%2Fversion1.0%2Fpi-schemas%2Fpi_timeseries.xsd%22%20version%3D%221.12%22%3E%0D%0A%09%3CtimeZone%3E0.0%3C%2FtimeZone%3E%0D%0A%09%3Cseries%3E%0D%0A%09%09%3Cheader%3E%0D%0A%09%09%09%3Ctype%3Einstantaneous%3C%2Ftype%3E%0D%0A%09%09%09%3ClocationId%3E63306260000%3C%2FlocationId%3E%0D%0A%09%09%09%3CparameterId%3ET.obs.mean%3C%2FparameterId%3E%0D%0A%09%09%09%3CtimeStep%20unit%3D%22nonequidistant%22%2F%3E%0D%0A%09%09%09%3CstartDate%20date%3D%222013-01-01%22%20time%3D%2200%3A40%3A00%22%2F%3E%0D%0A%09%09%09%3CendDate%20date%3D%222013-01-01%22%20time%3D%2200%3A50%3A00%22%2F%3E%0D%0A%09%09%09%3CmissVal%3E-999.0%3C%2FmissVal%3E%0D%0A%09%09%09%3CstationName%3EDE%20BILT%3C%2FstationName%3E%0D%0A%09%09%09%3Clat%3E51.76391247583424%3C%2Flat%3E%0D%0A%09%09%09%3Clon%3E4.329717456157946%3C%2Flon%3E%0D%0A%09%09%09%3Cx%3E82000.0%3C%2Fx%3E%0D%0A%09%09%09%3Cy%3E420000.0%3C%2Fy%3E%0D%0A%09%09%09%3Cz%3E0.0%3C%2Fz%3E%0D%0A%09%09%09%3Cunits%3Em%3C%2Funits%3E%0D%0A%09%09%3C%2Fheader%3E%0D%0A%09%09%3Cevent%20date%3D%222013-01-01%22%20time%3D%2200%3A40%3A00%22%20value%3D%2213.0%22%20flag%3D%220%22%2F%3E%0D%0A%09%09%3Cevent%20date%3D%222013-01-01%22%20time%3D%2200%3A50%3A00%22%20value%3D%2213.0%22%20flag%3D%220%22%2F%3E%0D%0A%09%3C%2Fseries%3E%0D%0A%3C%2FTimeSeries%3E

Example response

<?xml version="1.0" encoding="UTF-8"?>
<Diag xmlns="http://www.wldelft.nl/fews/PI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.
wldelft.nl/schemas/version1.0/pi-schemas/pi_diag.xsd" version="1.2">
    <line level="2" description="Multiple time series sets found for parameter=T.obs.mean location=63306260000"/>
    <line level="3" description="Import.Info: External time series successfully mapped to FEWS time series 63306260000 T.obs.mean   (m) nonequidistant Tue Jan 0
1 01:40:00 CET 2013 z=0.0"/>
    <line level="3" description="Import.info: 1 time series imported, 0 time series rejected"/>
    <line level="3" description="Import.info: The following locations-parameter combination imported  63306260000:T.obs.mean"/
</Diag>

Example response with non-matching time series.

It is possible that the posted time series do not match any of the time series sets that have been configured in the default filter or in a passed filterId. In that case, the response will report that some time series couldn't be mapped. In the following eexample 8 time series were posted, but only one time series was actually writte, 7 time series were rejected:

<?xml version="1.0" encoding="UTF-8"?>
<Diag xmlns="http://www.wldelft.nl/fews/PI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_diag.xsd" version="1.2">
    <line level="3" description="Import.Info: External time series successfully mapped to FEWS time series amerongen_beneden H.voorspeld   (m) 10 minutes Tue Jan 01 01:00:00 CET 2013 z=0.0"/>
    <line level="3" description="Import.Info: 1 time series imported, 7 time series rejected"/>
    <line level="3" description="Import.Info: The following locations-parameter combination imported  amerongen_beneden:H.voorspeld"/>
</Diag>

Example forecast time series.

By specifying a forecastDate it is possible to write external forecasts using the PI service.

<?xml version="1.0" encoding="UTF-8"?>
<TimeSeries xmlns="http://www.wldelft.nl/fews/PI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_timeseries.xsd" version="1.12">
    <timeZone>0.0</timeZone>
    <series>
        <header>
            <type>instantaneous</type>
            <locationId>amerongen_beneden</locationId>
            <parameterId>H.voorspeld</parameterId>
            <timeStep unit="minute" multiplier="10"/>
            <startDate date="2013-01-01" time="00:00:00"/>
            <endDate date="2013-01-01" time="00:30:00"/>
            <forecastDate date="2013-01-01" time="00:00:00"/>
            <missVal>-999.0</missVal>
            <units>m</units>
        </header>
        <event date="2013-01-01" time="00:00:00" value="10.0" flag="0" />
        <event date="2013-01-01" time="00:10:00" value="12.0" flag="0"/>
        <event date="2013-01-01" time="00:20:00" value="11.8" flag="0"/>
        <event date="2013-01-01" time="00:30:00" value="9.0" flag="0"/>
    </series>
</TimeSeries>

Example code

To post timeSeries to the Delft-FEWS WebServices, the following is example JAVA code:

String piTimeSeries = "PI XML Content";
URL url = new URL("http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseries");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setDoInput(true);
connection.setRequestMethod("POST");
connection.setDoOutput(true);
connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
connection.setRequestProperty("charset", "utf-8");
String postData = "piTimeSeriesXmlContent=" + URLEncoder.encode(piTimeSeries, StandardCharsets.UTF_8);
connection.setRequestProperty("Content-Length", Integer.toString(postData.length()));
connection.setUseCaches(false);
try (DataOutputStream wr = new DataOutputStream(connection.getOutputStream())) {
    wr.write(postData.getBytes());

}
 

GET taskruns

Get the taskRuns that comply to the filters. By default only forecasts are returned.

Request parameters

• onlyForecasts (boolean): option to toggle if only forecasts should be returned. Default true.

• onlyCurrent (boolean): option to toggle if only current forecasts should be returned. Default false.

• startDispatchTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for taskruns that have their dispatch time within this period.

• endDispatchTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for taskruns that have their dispatch time within this period.

• startForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for taskruns that have their forecast time within this period.

• endForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for taskruns that have their forecast time within this period.

• workflowId (string): Filter by an existing workflow id.

• scenarioId (string): Filter by an existing whatsif scenario id.

• mcId (string): Filter by mcId. Since 2021.01.
• taskRunStatusIds (string): Filter taskruns using the taskrunstatus code value. For valid status codes see the section 'Get taskrunstatus' below.

• documentVersion (string, 1.9 or up): File format version (optional). For example: 1.23

Response

• TaskRuns PI XML file content.

Example request

curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/taskruns?workflowId=ImportObserved&onlyForecasts=false"

Example response

<?xml version="1.0" encoding="UTF-8"?>
<TaskRuns xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews/PI" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_taskruns.xsd" version="1.23">
    <timeZone>0.0</timeZone>
    <taskRun taskRunId="0_0">
        <forecast>false</forecast>
        <status>completed fully successful</status>
        <workflowId>ImportObserved</workflowId>
        <dispatchTime date="2017-08-13" time="09:55:18"/>
        <completionTime date="2017-08-13" time="10:21:35"/>
        <time0 date="2017-08-13" time="09:45:00"/>
        <outputStartTime date="1743-11-01" time="00:00:00"/>
        <outputEndTime date="2017-08-01" time="00:00:00"/>
        <user>rudie</user>
    </taskRun>
</TaskRuns>

GET moduleruntimes (2021.02)

Get all expected runtimes for workflows per module instance id. The list can optionally be filtered by workflowId. Only workflows of scheduled tasks that contain module instance descriptors that have been configured with updateModuleRunTimesOnCompletion enabled, will be available in this end point.

The expected start time of a module is calculated based on the scheduled next due time and the expected pending duration time. The expected end time of a module is calculated based on the scheduled next due time, the expected pending duration time and the expected running time. For triggered tasks, the expected start time en end time won't be available until the task is actually started.

Request parameters

• workflowId (string): optional, allow filtering for a specific worklowId.

• documentFormat (string): PI_XML (default)

Response

• ModuleRunTime PI XML or PI JSON content.

Example request

curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/moduleruntimes?workflowId=Meuse_DWD_COSMO_LEPS"

Example response PI_XML

<?xml version="1.0" encoding="UTF-8"?>
<ModuleRunTimes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews/PI" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_moduleruntimes.xsd">
    <moduleRunTime>
        <mcId>nldefedmc00</mcId>
        <workflowId>Meuse_DWD_COSMO_LEPS</workflowId>
        <moduleInstanceId>Dummy</moduleInstanceId>
        <expectedStartTime date="2021-10-13" time="13:15:01"/>
        <expectedCompletionTime date="2021-10-13" time="13:16:54"/>
        <expectedPendingDuration>1465</expectedPendingDuration>
        <expectedRunningDuration>112634</expectedRunningDuration>
    </moduleRunTime>
</ModuleRunTimes>

Example response PI_JSON

{
  "moduleRunTimes" : [ {
    "workflowId" : "Meuse_DWD_COSMO_LEPS",
    "moduleInstanceId" : "Dummy",
    "mcId" : "nldefedmc00",
    "expectedStartTime" : 1414882800000,
    "expectedCompletionTime" : 1414886400000,
    "expectedPendingDuration" : 1465,
    "expectedRunningDuration" : 112634
  } ]
}

curl "localhost:8080/FewsWebServices/rest/fewspiservice/v1/taskrunstatus?taskId=1_0"

C

Since 2022.02 the taskrun status response supports PI_JSON as well. For example:

{
  "version" : "1.29",
  "code" : "C",
  "description" : "Completed fully successful"
}