Versions Compared

Old Version 229

changes.mady.by.user Rudie Ekkelenkamp

Saved on

compared with

New Version 230

changes.mady.by.user Bart Adriaanse

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Retrieve Pi Locations file containing all locations that are available for the passed 'filterId' argument. If not filterId is passed then all locations configured in the pre-defined filter will be returned. The geoDatum used in the response is determined by the geoDatum configured in the locations.xml.

 


Request parameters

  • filterId (string): Filter id.
  • documentVersion (string): File format version.
  • documentFormat (string): PI_XML (default), PI_JSON or GEO_JSON (since 2021.02)
  • showAttributes (boolean) Since 2017.02: toggle to show location attributes.
  • includeLocationRelations (boolean) Since 2019.02: toggle to include locationRelations. Optional, default is false. For xml format avalable from version 1.26 or higher.
  • includeTimeDependency  (boolean) Since 2019.02: toggle to include timeDependency. Optional, default is false. For xml format avalable from version 1.26 or higher.

Response

  • Locations in PI-XML, GEO_JSON or PI-JSON file content.

...

Code Block
linenumberstrue
 {
  "version" : "1.26",
  "geoDatum" : "WGS 1984",
  "locations" : [ {
    "locationId" : "locA",
    "shortName" : "A",
    "lat" : "9.0",
    "lon" : "9.0",
    "x" : "9.0",
    "y" : "9.0",
    "z" : "9.0",
    "attributes" : [ {
      "name" : "TEST_ATTRIBUTE",
      "type" : "text",
      "id" : "TEST_ATTRIBUTE",
      "startDateTime" : "1890-01-01T00:00:00+0000",
      "endDateTime" : "1950-01-01T00:00:00+0000",
      "value" : "A1"
    }, {
      "name" : "TEST_ATTRIBUTE",
      "type" : "text",
      "id" : "TEST_ATTRIBUTE",
      "startDateTime" : "1950-01-01T00:00:00+0000",
      "value" : "A2"
    } ],
    "relations" : [ {
      "id" : "UPSTREAM",
      "relatedLocationId" : "locB"
    }, {
      "id" : "UPSTREAM",
      "relatedLocationId" : "locC"
    } ]
  }, {
    "locationId" : "locB",
    "shortName" : "B",
    "lat" : "7.0",
    "lon" : "7.0",
    "x" : "7.0",
    "y" : "7.0",
    "z" : "7.0",
    "attributes" : [ {
      "name" : "TEST_ATTRIBUTE",
      "type" : "text",
      "id" : "TEST_ATTRIBUTE",
      "startDateTime" : "1930-01-01T00:00:00+0000",
      "endDateTime" : "2000-01-01T00:00:00+0000",
      "value" : "B"
    } ],
    "relations" : [ {
      "id" : "UPSTREAM",
      "relatedLocationId" : "locC",
      "startDateTime" : "1930-01-01T00:00:00+0000",
      "endDateTime" : "1980-01-01T00:00:00+0000"
    }, {
      "id" : "UPSTREAM",
      "relatedLocationId" : "locF",
      "endDateTime" : "1980-01-01T00:00:00+0000"
    }, {
      "id" : "UPSTREAM",
      "relatedLocationId" : "locE",
      "startDateTime" : "1930-01-01T00:00:00+0000"
    } ]
  }, {
    "locationId" : "locC",
    "shortName" : "C",
    "lat" : "5.0",
    "lon" : "5.0",
    "x" : "5.0",
    "y" : "5.0",
    "z" : "5.0",
    "attributes" : [ ],
    "relations" : [ ]
  }, {
    "locationId" : "locD",
    "shortName" : "D",
    "lat" : "3.0",
    "lon" : "3.0",
    "x" : "3.0",
    "y" : "3.0",
    "z" : "3.0",
    "attributes" : [ {
      "name" : "TEST_ATTRIBUTE",
      "type" : "text",
      "id" : "TEST_ATTRIBUTE",
      "startDateTime" : "1930-01-01T00:00:00+0000",
      "endDateTime" : "1980-01-01T00:00:00+0000",
      "value" : "D"
    } ],
    "relations" : [ {
      "id" : "UPSTREAM",
      "relatedLocationId" : "locB"
    }, {
      "id" : "UPSTREAM",
      "relatedLocationId" : "locE"
    } ]
  }, {
    "locationId" : "locE",
    "shortName" : "E",
    "lat" : "2.0",
    "lon" : "2.0",
    "x" : "2.0",
    "y" : "2.0",
    "z" : "2.0",
    "attributes" : [ {
      "name" : "TEST_ATTRIBUTE",
      "type" : "text",
      "id" : "TEST_ATTRIBUTE",
      "startDateTime" : "1910-01-01T00:00:00+0000",
      "endDateTime" : "1930-01-01T00:00:00+0000",
      "value" : "E1"
    }, {
      "name" : "TEST_ATTRIBUTE",
      "type" : "text",
      "id" : "TEST_ATTRIBUTE",
      "startDateTime" : "1930-01-01T00:00:00+0000",
      "endDateTime" : "1950-01-01T00:00:00+0000",
      "value" : "E2"
    }, {
      "name" : "TEST_ATTRIBUTE",
      "type" : "text",
      "id" : "TEST_ATTRIBUTE",
      "startDateTime" : "1950-01-01T00:00:00+0000",
      "endDateTime" : "1980-01-01T00:00:00+0000",
      "value" : "E3"
    } ],
    "relations" : [ {
      "id" : "UPSTREAM",
      "relatedLocationId" : "locF"
    } ]
  }, {
    "locationId" : "locF",
    "shortName" : "F",
    "lat" : "1.0",
    "lon" : "1.0",
    "x" : "1.0",
    "y" : "1.0",
    "z" : "1.0",
    "attributes" : [ {
      "name" : "TEST_ATTRIBUTE",
      "type" : "text",
      "id" : "TEST_ATTRIBUTE",
      "value" : "F"
    } ],
    "relations" : [ ]
  } ]
}


GET parameters

Retrieve Pi PI Parameters file containing all parameters that are available for the passed 'filterId' argument. Parameters are also returned if no time series are available for a parameter. If no filterId is passed then all parameters configured in the pre-defined filter will be returned. 


Request parameters

  • showAttributes (boolean): Since 2021.02. toggle to show parameter attributes. Default is false. 
  • documentVersion (string): File format version.
  • documentFormat (string): PI_XML (default) or PI_JSON

Response

  • Parameters PI-XML or PI-JSON file content.

...

GET taskruns

Get the taskRuns that comply to the filters.

Request parameters

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

  • 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

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/taskruns?workflowId=ImportObserved"

Example response

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

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

Example response PI_XML

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

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

GET taskrunstatus (2017.02)
Track the status of a workflow using the taskRunId.
Request parameters
  • taskId (string, required): task Id of a workflow.
  • maxWaitMillis (integer) time in milliseconds to wait for response
Response
Status of the workflow task. Possible response codes are:
  • I = Invalid,
  • P = Pending,
  • T = Terminated,
  • R = running,
  • F = Failed,
  • C = Completed fully successful,
  • D = Completed partly successful,
  • A = Approved,
  • B = Approved partly successful
  • null= No status available (produces when method call times-out)
Example request
 Code Block
curl "localhost:8080/FewsWebServices/rest/fewspiservice/v1/taskrunstatus?taskId=1_0"

Example response
 Code Block
C
 

POST runtask (2017.02)
Runs a workflow task for a given workflowId. Returns a handle to the task in the form of a taskid. This taskId can be used to track the status of the workflow using the taskrunstatus method. Since 2018.02 it is possible to use a workflow descriptor attribute: waitWhenAlreadyRunning. This will allow running a task that hasn't been scheduled to wait when another task of that workflow is already running. 
Request parameters
  • workflowId (string, required): Identifier of the task to run
  • startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start of run period. Used for state selection period.
  • timeZero (dateTime: yyyy-MM-ddTHH:mm:ssZ): Forecast time zero. If missing System time is used (optional)
  • endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End of run period. Used to define forecast length.
  • coldStateId (string): Id of a coldstate. Can be used to force state selection (optional).
  • scenarioId (string): Id of a predefined WhatIf scenario. Can be used to alter run parameters (optional).
  • userId (string) User id of the user that runs the task.
  • description (string): Descriptive text to identify run.
Body parameters
  • piModelParametersXmlContent (pi XML url encoded): Contents of a Pi ModelParameters XML file. PI ModelParameters can be exported by the General Adapter to provide information to external models being run by FEWS. The xml file content has to be encoded in the 'application/x-www-form-urlencoded Content-Type.
Response
  • taskId String with the identifier of the task that is run.
Example request
 Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/runtask/?workflowId=ImportObserved&startTime=2014-01-01T00:00:00Z+0000&timeZero=2014-01-01T00:00:00Z+0000&endTime=2014-01-01T00:30:00Z+0000" -X POST -H "Content-Type: application/x-www-form-urlencoded"  -d ""

Example response
 Code Block
1_0
 

GET timeseriesmodifiers (2017.02)
Get a list of all timeSeries modifiers
Request parameters
  • locationIds (string):
  • moduleInstanceIds (string):
  • startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): start time of modifiers search period
  • endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): end time of modifiers search period.
  • userId (string):
  • modifierTypeId (string):
  • active (boolean, default true):
  • userDefinedModifierDescriptionKeyValuePair (string):
If no startTime and endTime are given, the search period is any time.
Response
  • timeSeriesModifiers PI XML
Example request
 Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseriesmodifiers"

Example response
 Code Block
<?xml version="1.0" encoding="UTF-8"?>
<Modifiers 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_modifiers.xsd">
    <modifier>
        <name>T.obs.mean_DE BILT</name>
        <modifierId>0</modifierId>
        <systemActivityDescriptorId>34</systemActivityDescriptorId>
        <enabled>true</enabled>
        <modifierType>MISSING_VALUE_MODIFIER</modifierType>
        <userId>Andre Grijze</userId>
        <startTime date="1900-10-17" time="00:00:00"/>
        <endTime date="2017-11-23" time="00:00:00"/>
        <validTime date="3000-01-01" time="00:00:00"/>
        <creationTime date="2017-10-24" time="11:43:11"/>
        <constantValueTimeSeriesModifier>
            <timeSeriesSet>
                <moduleInstanceId>ImportObserved</moduleInstanceId>
                <parameterId>T.obs.mean</parameterId>
                <locationId>63306260000</locationId>
                <timeSeriesType>external historical</timeSeriesType>
                <timeStep unit="nonequidistant"/>
                <ensembleId>main</ensembleId>
            </timeSeriesSet>
            <startTime date="1900-10-17" time="00:00:00"/>
            <endTime date="2017-11-23" time="00:00:00"/>
            <value>NaN</value>
        </constantValueTimeSeriesModifier>
    </modifier>
</Modifiers>


 

GET modifiers
Get a list of all modifiers.
Request parameters
  • startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): start time of modifiers search period
  • endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): end time of modifiers search period.
  • modifierTypeId (string): filter on modifiers by modifierTypeId as specified in the ModifierTypes.xml configuration. If modifier type cannot be found, not filtering on type is done.
If no startTime and endTime are given, the search period is any time.
Response
  • Modifiers PI XML
Example request
 Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/modifiers?modifierTypeId=MISSING_VALUE_MODIFIER"

Example response
 Code Block
<?xml version="1.0" encoding="UTF-8"?>
<Modifiers 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_modifiers.xsd">
    <modifier>
        <name>T.obs.mean_DE BILT</name>
        <modifierId>0</modifierId>
        <systemActivityDescriptorId>34</systemActivityDescriptorId>
        <enabled>true</enabled>
        <modifierType>MISSING_VALUE_MODIFIER</modifierType>
        <userId>Rudie Ekkelenkamp</userId>
        <startTime date="1900-10-17" time="00:00:00"/>
        <endTime date="2017-11-23" time="00:00:00"/>
        <validTime date="3000-01-01" time="00:00:00"/>
        <creationTime date="2017-10-24" time="11:43:11"/>
        <constantValueTimeSeriesModifier>
            <timeSeriesSet>
                <moduleInstanceId>ImportObserved</moduleInstanceId>
                <parameterId>T.obs.mean</parameterId>
                <locationId>63306260000</locationId>
                <timeSeriesType>external historical</timeSeriesType>
                <timeStep unit="nonequidistant"/>
                <ensembleId>main</ensembleId>
            </timeSeriesSet>
            <startTime date="1900-10-17" time="00:00:00"/>
            <endTime date="2017-11-23" time="00:00:00"/>
            <value>NaN</value>
        </constantValueTimeSeriesModifier>
    </modifier>
</Modifiers>
 

POST modifiers (2017.02)
Create new modifiers.
Request parameters
  • commitModiifers (boolean): Indicates if the modifiers should be committed after the uploaded. This option defaults to true.
  • deleteAllModifiers (boolean): Indicates if all the existing modifiers should be deleted prior to inserting the new modifiers. This option defaults to false.
Body parameters
  • piModifiersXmlContent (pi Modifiers XML url encoded): Contents of a  modifiers file. The xml file content has to be encoded in the 'application/x-www-form-urlencoded Content-Type.
Response
  • Diag PI xml response with all diagnostic output.
Example request
 Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/modifiers" -X POST -H "Content-Type: application/x-www-form-urlencoded"  -d "piModifiersXmlContent="%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%0D%0A%3CModifiers%20xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22%20xmlns%3D%22http%3A%2F%2Fwww.wldelft.nl%2Ffews%2FPI%22%20xsi%3AschemaLocation%3D%22http%3A%2F%2Fwww.wldelft.nl%2Ffews%2FPI%20http%3A%2F%2Ffews.wldelft.nl%2Fschemas%2Fversion1.0%2Fpi-schemas%2Fpi_modifiers.xsd%22%3E%0D%0A%20%20%20%20%3Cmodifier%3E%0D%0A%20%20%20%20%20%20%20%20%3Cname%3ET.obs.mean_DE%20BILT%3C%2Fname%3E%0D%0A%20%20%20%20%20%20%20%20%3Cenabled%3Etrue%3C%2Fenabled%3E%0D%0A%20%20%20%20%20%20%20%20%3CmodifierType%3EMODIFY_TIMESERIES%3C%2FmodifierType%3E%0D%0A%20%20%20%20%20%20%20%20%3CuserId%3ERudie%20Ekkelenkamp%3C%2FuserId%3E%0D%0A%20%20%20%20%20%20%20%20%3CstartTime%20date%3D%221900-10-24%22%20time%3D%2200%3A00%3A00%22%2F%3E%0D%0A%20%20%20%20%20%20%20%20%3CendTime%20date%3D%222017-10-25%22%20time%3D%2200%3A00%3A00%22%2F%3E%0D%0A%20%20%20%20%20%20%20%20%3CvalidTime%20date%3D%222017-10-24%22%20time%3D%2200%3A00%3A00%22%2F%3E%0D%0A%20%20%20%20%20%20%20%20%3CcreationTime%20date%3D%222017-10-24%22%20time%3D%2211%3A15%3A43%22%2F%3E%0D%0A%20%20%20%20%20%20%20%20%3CtransformationTimeSeriesModifier%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3CtimeSeriesSet%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CmoduleInstanceId%3EImportObserved%3C%2FmoduleInstanceId%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CparameterId%3ET.obs.mean%3C%2FparameterId%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3ClocationId%3E63306260000%3C%2FlocationId%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CtimeSeriesType%3Eexternal%20historical%3C%2FtimeSeriesType%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CtimeStep%20unit%3D%22nonequidistant%22%2F%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CensembleId%3Emain%3C%2FensembleId%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3C%2FtimeSeriesSet%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cmultiplier%3E1.0%3C%2Fmultiplier%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cdivider%3E1.1%3C%2Fdivider%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cincrementer%3E0.0%3C%2Fincrementer%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cdelay%3E0%3C%2Fdelay%3E%0D%0A%20%20%20%20%20%20%20%20%3C%2FtransformationTimeSeriesModifier%3E%0D%0A%20%20%20%20%3C%2Fmodifier%3E%0D%0A%3C%2FModifiers%3E"

Example response
 Code Block
<?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="Successfully imported modifier:none MODIFY_TIMESERIES -1 T.obs.mean_DE BILT none"/>
</Diag>
 

GET workflows (2017.02)
Request parameters
  • documentVersion (string, 1.9 or up): File format version (optional). For example: 1.23
Response
  • xml workflows.
Example request
 Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/workflows"

Example response
 Code Block
<?xml version="1.0" encoding="UTF-8"?>
<workflows 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_workflows.xsd" version="1.23">
    <workflow id="ImportObserved">
        <name>Import Observed Data</name>
        <description>Import observed scalar data from external sources and process the imported data</description>
    </workflow>
</workflows>
 

GET samples (2017.02)
Request parameters
...
GET version (2022.01)
GET version inforamtion information of the current installed Web Services.
...