What | Explorer.xml |
---|---|
Config group | SystemConfigFiles |
Required | yes |
Description | Defines the main display and configures system settings |
schema location | https://fewsdocs.deltares.nl/schemas/version1.0/explorer.xsd |
Introduction
The layout of the FEWS Explorer is configured in an XML file in the SystemConfigurations section. When available on the file system, the name of the XML file is for example:
Explorer 1.00 default.xml
Explorer Fixed file name for the explorer settings
1.00 Version number
default Flag to indicate the version is the default configuration (otherwise omitted).
Figure 5 shows the main elements of the Explorer configuration, these are divided into a number of sections, each of which will be discussed individually (these are indicated with a + sign).
Figure 5 Elements in the Explorer configuration
System Information
This section contains some general information of the DELFT-FEWS configuration.
Figure 6 Elements in the System Information section of the Explorer configuration
description
An optional description of the configuration element. This is for reference purposes only and will not be used elsewhere.
systemCaption
The caption that will appear in the title bar of the FEWS Explorer window.
systemHelpFile
Reference to the file name and location of the help file
systemHelpUrl
Base Url to a FEWS help web page.
This web page will be opened in the browser when pressing F1 or after clicking the help button.
When opening the help from a specific part in FEWS like the spatial display, an anchor will be added to the url.
For instance when the system help url is "http://www.fewsmanual.com/" and the help is opened from the spatial display the complete url to be openend in the browser will be: "http://www.fewsmanual.com/#spatialDisplay".
It is also possible to already include the anchor (#) in the base url, then "spatialDisplay" will be added without an extra #.
This would be the case when referring to this wiki since it always includes the page name in its anchor.
Example:
system help url: "https://publicwiki.deltares.nl/display/FEWSDOC/WIKI+Help+test#WIKIHelptest-" will refer to "https://publicwiki.deltares.nl/display/FEWSDOC/WIKI+Help+test#WIKIHelptest-spatialDisplay" when help openened from spatial display.
regionId
Overruling regionId. By default the regionId is taken from the REGION_HOME directory variable. This can be used by the archive dialogue in the case that the REGION_HOME variable differs between OC clients (e.g. Salzburg and SalzburgOC for the OC).
Date Time
This optional section allows to specify the handling of date and time in the GUI.
timeZoneOffset or timeZoneName
The configured time zones will be used to show date/time in the GUI (time series editor, status bar, t0 of the forecasts ,..). All configured time zones will be shown in the current system time change dialog.
dateTimeFormat
This element specifies how date/time should be displayed in FEWS, except the clock in the status bar. The dateTimeFormat should be configured according to the specifications listed here. When specifying a T0 in the global properties file, the configured dateTimeFormat should be obeyed.
cardinalTimeStep
Specifies the time step for entering the date/time in the Explorer GUI.
adjustSystemTimeAutomatically
Specifies if the explorer's system time is adjusted automatically or not. Default: false for a stand alone and true for an operational client. Note that for a stand alone, a T0 can be specified via the global properties, in which case adjustSystemTimeAutomatically will always be set to false despite its configuration.
Since 2017.02 a stand alone will store the system time (T0) in the user settings and load it from the user settings upon start-up, if and only if adjustSystemTimeAutomatically is set to false. Note that since adjustSystemTimeAutomatically is false by default for stand alone systems, this is the new default behaviour. If adjustSystemTimeAutomatically is configured as true, the system time will be adjusted to the current time instead. If a T0 is specified in the global properties, this T0 will be used instead.
systemTimeTrigger
Use this option to update the system time with the latest (external) forecast time of all the specified time series. If both external and simulated forecast series are configured, the latest forecast time of all the configured series will be used. This option wil work only if the automatic updating of system time is allowed, typically it is in OC or if the option adjustSystemTimeAutomatically is true. Time series can be specified via two elements (both can be used at the same time and both can appear an unbounded amount of times):
- <externalForecastTimeSeries>
- <simulatedForecastTimeSeries>
Panel sizes
This optional section allows the panel sizes to be pre-set by the configuration when a user first starts FEWS. After the first session, the sizes of the different data viewer panels will be stored in the user settings and these sizes will be used when FEWS is (re)started.
Example:
<panelSizes> <filterListSize>10</filterListSize> <locationListSize>25</locationListSize> <parameterListSize>20</parameterListSize> <qualifierListSize>20</qualifierListSize> <forecastListSize>5</forecastListSize> </panelSizes>
The configuration example above contains the defaults used by FEWS when no panelSizes element is configured. The numbers represent a weight of the particular panel. The % of the data viewer panel which will consist of that (sub)panel is equal to its weight divided by the total weight.
The deprecated elements <loggingPanelSize> and <listsPanelSize> (both are only relevant when using docking=false in the global properties), have been made optional since 2018.02.
Panel header labels
This optional section allows the configurator to specify headers above the left panels in the Explorer window. Not all headers need to be specified simultaneously.
Explorer Options
Deprecated section
Figure 7 Elements in the Explorer Options section of the Explorer configuration
The explorer options define whether a number of items are visible on the main display when started. Each of these may either have the value "true" or "false". The items listed in Figure 7 lists all the items. The names are self-explanatory.
Map
In this section the background maps can be defined. The configuration of this section is described here.
Location labels
Locations in the map by default are labeled with the ID, or the name or description of the location (configured in locations.xml or locationSets.xml). To specify the ID, name or description of the location, the following tags could be used: %ID%, %NAME%, and %DESCRIPTION%. In LocationSets.xml (for EsriShapeFile or CSVFile) it is also possible to replace or add text to the label, such as location attributes (using @ATTRIBUTE_ID@, Since 2013.02 or csv/dbf columns without defining an attribute with %COLUMN_NAME%), or timeseries related information (%LAST_VALUE%, %LAST_VALUE_TIME%,%FORECAST_START_TIME%, %MAXIMUM_VALUE%, %MAXIMUM_VALUE_TIME%, %MINIMUM_VALUE%, %MINIMUM_VALUE_TIME%). In case of timeseries related information, the label only shows the information for the selected parameter.
Example:
<label>%NAME% has last value: %LAST_VALUE%</label>
Other uses:
In the Filters.xml there is an additional option to show the last value (within the RelativeViewPeriod): lastValueVisible.
In Explorer.xml, in the map section, it is possible to configure that no labels are displayed. Likewise, the Options>>>Explorer Options "map" tab can turn labels on and off.
showThresholdWarningIcons
This setting determines the default value for whether the button for showing threshold icons is selected or not.
When FEWS closes, the current state of the button will be written to the user settings.
The next time FEWS starts, the state of the button will be taken from the user settings and will overrule what is configured in the config.
Zoom extents
The zoom extents is used to define the pre-configured zoom levels that can be selected from the main display.
Figure 8 Elements in the Explorer Options section of the Explorer configuration
zoomExtent
Main element of each zoomExtent defined. Note that multiple zoom extents may exist, with the elements below to be defined for each.
Attributes:
- title name of the zoom extent in the list of extents.
left, right, top, bottom
Coordinates of the corners of the zoom extent (specified in the geoDatum selected below)
mnemonic
Optional definition of a letter in the title to use as shortcut. Usage: Press Alt-E (to open menu "Extra"), then the configured letter.
Explorer Tasks
The explorer tasks define the tasks that can be carried out from the explorer. These tasks are for example the initiation of plug-ins such as the time series display, see also How to define an ExplorerTask - what are the possible taskClass options?.
NOTE: These settings should be amended only by expert users.
Figure 9 Elements in the Explorer Tasks section of the Explorer configuration
explorerTask
Main element of each explorer Task. Note that multiple tasks may exist, with the elements below to be defined for each.
Attributes;
- name name of the task
iconFile
Reference to an icon file to be used in the toolbar. If left empty the name will be used to identify the task in the toolbar.
Since 2019.02, the type of the button can be added to the toolbar (Icon or Text). Only the ButtonType (in <toolbarTask>) Icon will use the configured <iconFile>. If left blank, it will show the new, default grey-scale icon provided from the code.
The complete set of new, default, grey-scale icons can be downloaded here . See also the table below in the <predefinedDisplay> section.
Mnemonic
Optional definition of a letter in the title to use as shortcut.
predefinedDisplay
Enumeration of possible displays (alternativaly, you can define a taskClass, see below and How to define an ExplorerTask - what are the possible taskClass options?):
Display type | Type | default icon |
---|---|---|
archive | display | |
attribute filter | tool window | |
correlation display | display | |
data viewer | tool window | |
documents | tool window | |
forecast management | display | |
forecast mixer | display | |
forecast product info | display | |
interval statistics | display | |
manual forecast dialog | display | |
map | display | |
modifier display | display | |
plot overview | display | |
sample viewer | display | |
schematic status display | display | |
spatial display | display | |
system monitor | display | |
tabular config files display | display | |
threshold display | display | |
time series dialog | display | |
time series lister | display | |
topology diagram | tool window | |
topology tree | display | |
verifcation analysis tool | display | |
web browser | display | |
what-if dialog | display | |
workflow navigator | display |
displayConfigFileName
Since 2013.02. Config file of the display. The display to start is recognized by the schema name in the config file
taskExe
Command line for executable to run on initiating the task (the task may be either a call to an executable or to a Java class)
taskClass
Java class to run on initiating the task (the task may be either a call to an executable or to a Java class)
The possible taskClasses are listed in the next howto
Notice that you better use the predefinedDisplay or displayConfigFileName elements.
arguments
Optional argument string to be passed to the task.
In case of a embedded vJDBC service, you can parse the actual portnumber to an application with the argument %VJDBC_PORT% or %PORT%.
Since 2012.01, the TimeSeriesDisplay can be started with preselection of a statistical function (see example below)
workDir
Optional working directory to start the task in.
Description
Optional description of the task (for reference only)
toolbarTask
Boolean flag to indicate if the task is to appear as a part of the toolbar.
Since 2019.02 this element can either has new settings and dependencies. A buttonType can be configured. Options in this enumeration are 'icon' or 'text'
<buttonType> | Boolean | <iconFile> | appearance |
---|---|---|---|
icon | true | empty | Icon button with new 2019.02 default image |
true | reference to an image file | Icon button with configured image | |
false | empty or a reference to an image file | no button visible | |
text | true | empty or a reference to an image file | Text button with Taskname |
false | empty or a reference to an image file | no button visible |
menubarTask
Boolean flag to indicate if the task is to appear in the tools menu
allowMultipleInstances
Boolean flag to indicate if multiple instances of task can be initiated concurrently
accelerator
Optional shortcut key, note that the shortcut keys only work for tasks in the menu bar (when <menuBarTask> is set to true). Examples of shortcuts: "shift X", "control DELETE", "alt shift X" etc.
Permission
Optional name of the permission that is needed to use this task
doubleClickLocationEnabled
When double clicked at a location at the map or in the list, all the explorerTasks with this option set to true are started. The location is selected before the tasks are started, so you can for example start the time series dialog (TSD) and jump to the shortcut chart of the clicked location.
Note 1:
This functionality has been designed before the introduction of docking displays and assumes that each double click opens a new TSD. To be able to open a new TSD (with argument shortcuts), this task should have the option allowMultipleInstances=true. An already opened shortcuts TSD is not able to switch to an another shortcut chart.
Note 2:
a TSD with the argument shortcuts will open to the shortcut chart that is configured in DisplayGroups.xml. By default the first chart that contains the clicked location will open. To open a specific shortcut chart, an ‘explorerLocationId’ can be configured in this shortcut chart and the chart will open if the same location is double clicked at the map or in the list.
An example:
if LocB or LocC is double clicked , TSD will open to "Plot LocB" resp. "Plot LocC". If LocA is double clicked , TSD will open to "Plot LocC" , since this shortcut has <explorerLocationId>LocA</explorerLocationId>
<displayGroup name="Example"> <display name="Plot LocA"> <locationId>LocA</locationId> <plotId>Discharge</plotId> </display> <display name="Plot LocB"> <locationId>LocB</locationId> <plotId>Discharge</plotId> </display> <display name="Plot LocC"> <explorerLocationId>LocA</explorerLocationId> <locationId>LocC</locationId> <plotId>Discharge</plotId> </display> </displayGroup>
loadAtStartup
In this field can be configured which windows will be opened by default when the system starts up. This feature can only be used in docking mode.
Examples
In the below example for an explorerTask references are made to:
- %VJDBC_PORT%, the actual JDBC port number
- %PORT%, same as VJDBC_PORT
- %HOSTNAME%, the actual JDBC host, returned as IP adress
- %REGION_HOME%, internal variable of FEWS: returns the current FEWS application directory
- %FEWSDIR%, internal variable of FEWS: returns reference to the current FEWS application directory
$ART_VERSCHIL_EXE$, a variable from the global properties
<explorerTask name="Art_Verschil tool"> <iconFile>%FEWSDIR%/icons/matlab.ico</iconFile> <mnemonic>B</mnemonic> <arguments>/VJDBC_HOST=localhost /VJDBC_PORT=@VJDBC_PORT@</arguments> <workDir>%REGION_HOME%/Modules/Art_Verschil</workDir> <taskExe>$ART_VERSCHIL_EXE$</taskExe> <toolbarTask>true</toolbarTask> <menubarTask>true</menubarTask> <accelerator>ctrl B</accelerator> </explorerTask>
The next example calls the TimeSeriesDisplay with a preselected Statistical function:
<explorerTask name="Ensemble exceedence analysis"> <iconFile>exceedence.png</iconFile> <arguments>statisticalFunction ensemblePercentileExceedence</arguments> <taskClass>nl.wldelft.fews.gui.plugin.timeseries.TimeSeriesDialog</taskClass> <toolbarTask>true</toolbarTask> <menubarTask>true</menubarTask> </explorerTask>
Predefined Dashboards
Since 2019.02 FEWS supports creating and using dashboards. These dashboards can be created by the user or be predefined by a configurator. The predefined dashboards are configured through a "dashboards.ini" file (in the root config files) which contains the settings that would otherwise be stored in the user settings if the dashboard was user-defined. More information on the dashboards can be found in the User Guide > 33 Dashboard Display.
It is possible to set permissions for the predefined dashboards through the Explorer.xml.
<predefinedDashboards> <dashboard name="BE Compose"> <permission>Development</permission> </dashboard> </predefinedDashboards>
The configured "name" should match the name of a predefined dashboard present in the dashboards.ini file. The configured permission will then be applied to that dashboard, controlling for which users this dashboard will be present in the dashboards menu (thus allowing them to open it).
statusBar
The status Bar settings define the elements that can be shown in the FEWS Explorer status bar. This includes the configuration of the date/time and elements like showing the user, usergroup, etc..
Figure 10 Elements in the Status bar section of the Explorer configuration
dateTimeFormat
String defining the time format for time displayed in the status bar. For example HH:mm:ss will display time as 10:43:26.
Using <dateTimeFormat>dd-MM-yyyy kk:mm</dateTimeFormat> leads to hrs-indication of "24" of previous day instead of "00" (by using kk instead of HH).
userName / userGroup
scheduledTaskEndWarning
<statusBarConfig> <description>Standard date-time format</description> <dateTimeFormat>HH:mm:ss</dateTimeFormat> <timeGMT>true</timeGMT> <timeCurrent>false</timeCurrent> <timeLastRefresh>true</timeLastRefresh> <statusOfSystem>true</statusOfSystem> <mouseCoordinates>true</mouseCoordinates> <userName>true</userName> <scheduledTaskEndWarning> <color>aquamarine1</color> <time unit="minute" multiplier="75"/> </scheduledTaskEndWarning> </statusBarConfig>
systemTimePauseButton
Optional field. With this setting a "pause" button will be visible next to the current time in the status bar. Toggle this button to start or stop automatic adjusting of current time. If paused is set to "true", the pause button will be toggled at start-up.
Optional field. Maximal period of time for which the unacknowledged messages will be searched. Default 2 days. Also used as the initial length of the search period for LogBrowser
showLocationsOutsideVisibilityPeriod
Optional boolean value. Default is false.
When true Locations with a start and end time that does not include system time will be visible with a specific icon (instead of not being visible at all).
restSettings
This section includes additional settings for the FEWS Explorer.
Figure 11 Elements in the Rest Settings section of the Explorer configuration
defaultSelectFilterId
Defines the default filter to be selected on starting the fewsExplorer
geoDatum
Default definition of the geographic datum. This is an enumeration of geographic datums supported. As further geographic datums are supported, the list will be expanded;
For the enumeration of geoDatums suppoted, see Appendix B
globalDatum
It is possible to configure global datum label in a display group:
<globalDatum>AHD</globalDatum>
localDatum
Since 2020.02 it is possible to configure local datum label to specifically set the reference level of a certain axis in a display group:
<localDatum>someLocalDatum</localDatum>
dateTimeFormat
Format definition for time strings in displays (e.g. yyyy-MM-dd HH:mm:ss is resolved to 2004-07-03 10:43:26)
cardinalTimeStep
Default cardinal time step for the system. The system time will be rounded down to the actual time to the closest cardinal time step.
Attributes;
- unit (enumeration of: second, minute, hour, day, week)
- multiplier defines the number of units given above in a time step.
- divider same function as the multiplier, but defines fraction of units in time step.
timeZone
Defines the default time zone for the system. The default time zone is used for all times in user displays, unless locally overruled. This includes time series displays and the system time. The time zone used by the system should conform to a time zone that does not consider summer time. If this optional entry is not included then the timeZone is considered to be UTC+0:00 (or GMT). The time zone can be defined in two ways:
- timeZoneOffset: The offset of the time zone with reference to UTC (equivalent to GMT). Entries should define the number of hours (or fraction of hours) offset. (e.g. +01:00)
- timeZoneName: Enumeration of supported time zones. See appendix B for list of supported time zones.
In some areas that adhere to daylight saving time (DST), this is reflected in the time zone name. For example in New South Whales (Australia) the time zone is AET (Australian Eastern Time). However, since the adhere to DST, in Summer they use the time zone AEDT (Australian Eastern Daylight Time) and in winter it's AEST (Australian Eastern Standard Time). In Delft-FEWS this means that you configure / select the time zone AET (in Explorer.xml), but that the Current System Time will display as either AEST or AEDT depending on the time of year.
Queensland (Australia) doesn't adhere to DST and uses AEST all year round, so configure AEST in Explorer.xml for this state. Macquarie Island on the other hand uses AEDT all year round, so for that location you'll need to select AEDT in Explorer.xml.
logPanelConfig
This feature is not supported anymore. The logging levels can be configured in Log4jConfig.xml in the root directory .
Configuration of the log panel at the bottom of the main display. This can be configured to show all messages (DEBUG level and up), or filtered from a defined level. Two types of log message can be displayed; those generated by the DEBUG logger and those by the EVENT logger. In normal use the latter is defined to show messages from a level of INFO or above. The former is not normally used except for configuration in the stand alone when additional information may be useful. Different settings are available for stand alone clients and for operator clients
Figure 12 Elements in the Log Panel section of the Explorer configuration
clientFilter
Root element of a definition of filters (multiple entries may exist).
clientId
Definition of log filters for Operator client or for Stand alone system (both may be included).
logFilter
Root element for log filter definition
eventType
Filter applicable to System logger or to debug logger. Enumeration of "system"or "event".
Level
Level of log message below which messages are not displayed. Enumeration of DEBUG, INFO, WARN, ERROR, FATAL ERROR
rollingBarrelOptions
This allows you to set the rolling barrel options for the client. Available options for the type are:
- not_automatic: The Rolling Barrel will only run if you launch it using the F12 menu
- startup_only: The Rolling Barrel will only run when starting up the client
- shutdown_only: The Rolling Barrel will only run at showdown of the client
- interval: The Rolling Barrel will run at the specified interval
Example:
<rollingBarrelOptions> <type>interval</type> <interval unit="hour" multiplier="1"/> </rollingBarrelOptions>
Schema:
parameterListConfig
This allows you to set the default sorting option for the parameters in the Explorer. Available options are:
- default: Use the default sorting from the configuration file Parameters.xml.
- name: Sort by parameter name (ascending).
Example:
<parameterListConfig> <sortOption>name</sortOption> </parameterListConfig>
Schema:
notification
The system can notify the completion of a manually dispatched task run when the notification property is enabled (i.e. enabled=TRUE).
numberOfTimeSeriesBlobsForWarning
Number for the amount of time series blobs in database that indicates when the OC should give a popup warning on startup that FEWS is not designed for unlimited amount of data. Default is 1 million.
<numberOfTimeSeriesBlobsForWarning>1000000</numberOfTimeSeriesBlobsForWarning>
showIconForUnacknowledgedWarnings
Boolean option whether to show an opaque warning icon (
) in the status bar when unacknowledged warnings are present in database. Only if no unacknowledged errors are present.<showIconForUnacknowledgedWarnings>true</showIconForUnacknowledgedWarnings>
DebugMenuPermission
If the user has the debug menu permission, by pressing F12, the debug menu appears. An example of how to configure the debug menu permission and an screenshot of the debug menu follow:
<debugMenuPermission>admin</debugMenuPermission>
Filemenu options
From the FEWS Explorer File menu it is possible to configure a number of additional menu items (from which a few can also be found in the <F12> menu) . They are explained below.
Open most recent forecast
Opens the most recent forecast for selection (in dataviewer).
<fileMenu> <openMostRecentForecast visible="true"/> </fileMenu>
Open most recent current forecast
Opens the most recent current forecast for selection (in dataviewer).
<fileMenu> <openMostRecentCurrentForecast visible="true"/> </fileMenu>
Open last forecast
Opens the last forecast for selection (in dataviewer)
<fileMenu> <openLastForecast visible="true"/> </fileMenu>
Set system time to last available
Sets the system time to last available.
<fileMenu> <setSystemTimeToLast visible="true"/> </fileMenu>
Delete localdatastore
Deletes the local datastore.
<fileMenu> <deleteLocalDataStore visible="true"/> </fileMenu>
Exporttimeseries - interactiveExportFormats
From the FEWS Explorer File menu it is possible to export selected time series to a subset of the export file formats. To enable the Export Timeseries file menu option, it should be enabled in the Explorer.xml file. See Interactive Export
someSeriesCompletelyMissingIconVisible
When set to true, an orange cross will appear for locations/parameters/nodes where some, but not all timeseries contain missing data. Default is false (for backward compatibility)
DocumentViewer
The Documentviewer is used to show documents connected to workflows in the IFD. It is also possible to show documents connected to values in timeseries (eg picture of peilschaal). Here is more information on application and configuration.
All geographic locations used in DELFT-FEWS are resolved to WGS 1984. If another coordinate system is to be used, then the transformation between this and WGS 1984 will need to be added. There is a class definition for these transformations. Once added the enumeration used here can be extended
Care needs to be taken when working with time zones. Mixing time zones can lead to great confusion. It is wise to define the time zone as an offset with respect to UTC and use this throughout. In configuring import data, a local time zone can be used. It is advisable to always set time zones when required.
vjdbcServicePortRange
The FEWS Stand Alone can start an embedded VJDBC server automatically or through the debug mode.
Starting VJDBC server automatically:
When the Explorer.xml file of the Stand Alone system contains an additional element “vjdbcServicePortRange”, the Delft-FEWS internal vjdbc server will start automatically when the Stand alone is started. For the port number a range of the port numbers can be provided, for example <vjdbcServicePortRange start="2000" end="2005"/>
We advice to use the portrange starting from 2000.
Starting VJDBC server through the debug mode :
When there is no “vjdbcServicePortRange” configured, you can start VJDBC server with Explorer F12 menu option “M start embedded vjdbc server”. Then the embedded VJDBC Server will use port number 2000.
This VJDBC functionality can be used to analyse the database of the Stand Alone using external tools like DBVisualizer. Or it can be used to start a FEWS Stand Alone in participant mode or the Water Coach in participant mode (Application configuration#Participantmode)
showLocationsOutsideVisibilityPeriod