Introduction

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 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.

SSD Request methods

The available request methods with their supported parameters are described here.

GetCapabilties

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/ssd?request=GetCapabilities&format=application/xml

Example xml response

<SSD_Capabilities version="1.0.0">
<Service>
	<Name>SSD</Name>
	<Title>Delft-FEWS Schematic Status Display Service (SSD)</Title>
</Service>
<Capability>
	<Request>
		<GetCapabilities>
			<Format>application/xml</Format>
			<Format>application/json</Format>
		</GetCapabilities>
		<GetDisplay>
			<Format>image/svg+xml</Format>
		</GetDisplay>
	</Request>
	<DisplayGroup>
		<Name>ScadaOverzichtsscherm_WMCN</Name>
		<Title>Scada Overzichtsscherm NL</Title>
		<Time>
			<RelativePeriod unit="day" start="-15" end="2"/>
			<TimeStep unit="hour" value="1"/>
		</Time>
		<DisplayPanel>
			<Name>Overzichtsscherm_WMCN</Name>
			<Title>Overzichtsscherm Nederland</Title>
		</DisplayPanel>
		<DisplayPanel>
			<Name>Verwachtingenscherm_WMCN</Name>
			<Title>Verwachtingen Nederland</Title>
		</DisplayPanel>
	</DisplayGroup>
</Capability>
</SSD_Capabilities>

Please note that the used naming conventions are slightly different from those used on the SSD configuration page,  This is because the terms "Scada display" and "Scada panel" are quite closely related to their appearance in the FEWS explorer UI where a FEWS display contains a list of multiple panels a user can choose from. As the SSD Web service has no visual appearance the terms "display" and "panel" become more or less arbitrary. Keeping in mind that a "Scada display" is a group of "Scada panels" (where it is the "Scada panel" that actually displays the Scada/SDD schematic, the name "DisplayGroup" and DisplayPanel" is used instead.  ("DisplayGroup" is equivalent to "ScadaDisplay" and "DisplayPanel" is equivalent to "ScadaPanel").

GetDisplay

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.

Example SVG response:

GetFeatureInfo

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 (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:

<?xml version="1.0" encoding="UTF-8"?>
<SSD_FeatureInfo version="1.0.0">
    <id>Genem_Q</id>
</SSD_FeatureInfo>

The same information in JSON format:

{"id":"Genem_Q"}

GetAction

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:

<?xml version="1.0" encoding="UTF-8"?>
<SSD_Actions version="1.0.0">
    <Results>
        <Result>
            <Type>SSD</Type>
            <Request>Stevinsluizen</Request>
        </Result>
    </Results>
</SSD_Actions>

The same information in JSON 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.

The table below lists the actions as listed on the SSD/scada configuration page that have been implemented, with a short description of the Type and request fields in the output of the GetAction request:

Installation

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

The tomcat server the FEWS web services are running on should have sufficient memory. When many concurrent users are using the SSD and other services the CPU and memory requirements will increase with the number of SSD displays in a configuration and also depends on the size of the SVG templates used.

Since the SSD service is stateless, it can be scaled both vertically (more cpu and memory) and horizontally (more tomcat instances).