Page History

...

The FEWS Schematic Status Display (SSD) Web Service allows requesting SSD displays (formerly called Scada displays) using a simple REST web interface. This web service is available only in FEWS 2019 2020.01 and later versions.

For more information on configuring SSD/Scada displays, please refer to the SSD configuration page,  The SSD web service uses the same configuration as the FEWS explorer UI and report generator, so for an existing configuration setting up the FEWS SSD web services can use the same region home folder as the FEWS explorer UI without requiring additional configuration.

...

Get the list of available available SSD 'displays' and 'panels' and additional configuration information that is required to successfully use the SSD web service, like the time step and relative period to use for time 'navigation'. GetCapabilties will return its content as XML. 

Request parameters

• FORMAT (optional) : the requested capabilities format. ( 'application/xml' or 'application/json')  The default format is XML.
• SSD : by specifying the name of a SDD display panel the capabilities can be rendered for only one specific SSD display panel.
• SHOWTIMESTEPS : when SHOWTIMESTEPS =TRUE  the time dimension information will include a list of individual time steps. (default is false)
• TIMEZERO : the reference time0 which is used to transform relative times used in the SSD configuration to absolute date/time values (default is current time)
  
  

Example request

http://localhost:8080/FewsWebServices/wmsssd?request=GetCapabilities&format=application/xml

...

Get the SSD display as SVG document for one of the configured SSD "DisplayPanel" items listed in the capabilities XML. The DisplayPanel (Scada panel) to be rendered is specified by name using the SSD parameter.

Request parameters

...

• SSD (required): the name of the SSD "DisplayPanel" to render. Only one SSD can be rendered at a time.
• TIME (optional): the time for which the SSD is to be rendered. Time has to be in the ISO_8601 dateformat:  yyyy-MM-ddTHH:mm:ssZ. The default time is the current time.
• LANGUAGE (optional): a 2 character language code to use while rendering the SVG file. The language control affects how numbers are formatted, i.e. for language=nl a decimal comma will be used as decimal separator. The default is 'US' for US English.

...

For a given X, Y coordinate (in pixels relative to the upper left corner of a rendered SVG graphic), the GetFeatureInfo request will determine the topmost element in the SVG file at that coordinate and return the element Id. This request supports applications where the SVG image is shown on a web page using the <img > HTML element and the user needs to be able to click on elements in the SVG graphic to query the underlying data.

Request parameters

• SSD SSD (required): the name of the SSD "DisplayPanel" to render. Only one SSD can be queried at a time.
• X (required): the horizontal X coordinate in pixels relative to the left of the SVG graphic.
• Y (required): the vertical Y coordinate in pixels relative to the top of the SVG graphic.
• WIDTH: (optional) If the SVG was displayed with a size different from the default SVG size, this width (in pixels) should be specified so the given X coordinate can be scaled accordingly.
• HEIGHT: (optional) If the SVG was displayed with a size different from the default SVG size, this height (in pixels) should be specified so the given Y coordinate can be scaled accordingly.
• TIME (optional): the time for which the SSD is to be rendered. Time has to be in the ISO_8601 dateformat:  yyyy-MM-ddTHH:mm:ssZ. The default time is the current time.
• FORMAT (optional) : the requested output format. ( 'application/xml' or 'application/json')  The default format is XML.

Response

The response to the GetFeatureInfo request is XML or JSON formatted text giving the id of the (topmost) selected SVG element found at the given coordinate. for example in XML format:

...

For a given SVG element ID, this request can provide information about specific actions that have been configured in the FEWS scada/ssd display configuration. Specifically the leftSingleClickAction and leftDoubleClickAction that have been configured can be retrieved using this request. This request is designed specifically to support web developers in the development of web applications where the user can click on elements in the SVG image to display more detailed information about a location in the SSD display.

Request parameters

• SSD (required): the name of the SSD "DisplayPanel" to query. Only one SSD can be queried at a time.
• OBJECTID: the id of the SVG object to retrieve the configured actions for.
• ACTION: the type of user interaction, can be either LEFTSINGLECLICK or LEFTDOUBLECLICK (case insensitive)
• TIMEZERO : the reference time0 which is used to transform relative times used in the SSD or timeseries display configuration to absolute date/time values (default is current time)
  
• FORMAT (optional) : the requested output format. ( 'application/xml' or 'application/json')  The default format is XML.
• OPTIONS (optional) : one or more specific options that affect the output, separated by commas. Currently supported are CONFIG (providing additional configuration information) and IMPORTFROMEXTERNALDATASOURCE (add support for external data from a configured FEWS Open Archive)  
  (for example: OPTIONS=CONFIG,IMPORTFROMEXTERNALDATASOURCE to provide both)
  note: it is also possible to specify these optons separately using the syntax CONFIG=TRUE or IMPORTFROMEXTERNALDATASOURCE=TRUE
  
  

Response

The response to the GetAction request is XML or JSON formatted text giving information about the action that has been configured in FEWS. An action always consists of an action (or service) type (i.e. open another SSD panel, url of PDF document). For example a configured "switchToScadaPanel" action response in XML format:

...

{
  "results" : [ {
    "type" : "SSD",
    "requests" : [ {
      "request" : "Stevinsluizen"
    } ]
  } ]
}

Please note that in the FEWS scada/sdd display configuration, only one action can be configured for either a leftSingleClickAction or leftDoubleClickAction, yet the result of a GetAction request is presented as a list that can contains more than one result. This is because for some specific actions (i.e. openDisplay/timeSeriesDisplay) it is expected that more than one implementation may become available in the future.

An example action response for a openDisplay/timeSeriesDisplay action with multiple PI requests:

{
  "results" : [ {
    "type" : "PI",
    "requests" : [ {
      "request" : "rest/fewspiservice/v1/timeseries?timeSeriesType=EXTERNAL_HISTORICAL&locationIds=IJS_ReestWieden_In&parameterIds=Q.balans.in&moduleInstanceIds=Import_dump&startTime=2019-10-25T12%3A50%3A00Z&endTime=2019-11-02T12%3A50%3A00Z"
    }, {
      "request" : "rest/fewspiservice/v1/timeseries?timeSeriesType=EXTERNAL_HISTORICAL&locationIds=IJS_ReestWieden_In&parameterIds=Q.balans.in&moduleInstanceIds=Import_dump&qualifierIds=Gemiddelde&qualifierIds=24uur&timeStepId=Hydro_dag&startTime=2019-10-25T12%3A50%3A00Z&endTime=2019-11-02T12%3A50%3A00Z"
    }, {
      "request" : "rest/fewspiservice/v1/timeseries?timeSeriesType=EXTERNAL_FORECASTING&locationIds=IJS_ReestWieden_In&parameterIds=Q.balans.in&moduleInstanceIds=Import_dump&qualifierIds=Gemiddelde&qualifierIds=Nu&startTime=2019-11-01T11%3A50%3A00Z&endTime=2019-11-01T12%3A50%3A00Z"
    } ]
  } ]
}

GetVersion (2022.01)

GET version inforamtion of the current installed Web Services.

Request parameters

• documentFormat (string): PI_XML (default) or PI_JSON

Response

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

Example request

curl "http://localhost:8080/FewsWebServices/ssd?request=GetVersion"

Example PI-XML response

<?xml version="1.0" encoding="UTF-8"?>
<Version 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_version.xsd">
    <implementation>2017.02</implementation>
    <buildType>stable</buildType>
    <buildNumber>12345</buildNumber>
    <buildTime>2017-10-31T23:00:00Z</buildTime>
</Version>

GetOAS (2022.01)

GET open api specification of the SSDService.

Response

• • JSON response with the open api specification.

Example request

curl "http://localhost:8080/FewsWebServices/ssd?request=GetOAS"

Example PI-XML response

{
  "openapi" : "3.0.3",
  "info" : {
    "title" : "Delft-FEWS Web Services - WMS Service",
    "description" : "Delft-FEWS Web Services - SSD Service",
    "version" : ""
  },
  "servers" : [ {
    "url" : "/FewsWebServices",
    "description" : "API server"
  } ]
}

Implementation status

As the SSD web service is currently under development, not all possible actions supported by FEWS have been implemented yet, Simple actions like switchToScadaPanel, openPdfFile and openUrl have been implemented first while less trivial actions (timeSeriesDisplay , spatialDisplay) are yet to be implemented, providing a working implementation to follow up on such actions in a web application requires more web based development.  For example, the idea is that a spatialDisplay action could provide a link to a FEWS WMS server context, and timeSeriesDisplay could be linked to a FEWS-PI webservice request that at least retrieves that time series data required to implement s 'similar' time series chart in the context of a web application.

...

Installation

For general FewsWebServices requirements, see: Installation. There are no additional requirements for the FEWS SSD web service.

...