Function: | Configure topology of an IFD environment |
Where to Use? | Mandatory for an IFD installation |
Why to Use? | The topology.xml is necessary to be able to use panels like the topology panel and the forecast panel |
Description: | Topology panel is used to define the topology of an IFD environment. Also the behaviour of the forecast panel which is used to start |
Available since: | DelftFEWS201001 |
Contents
Introduction
The concept of the IFD (interactive forecast displays) was introduced in 2010. A central role in the configuration of the IFD is the topology.xml. This part of the wiki explains the configuration details of the topology.xml.
First the background of the topology.xml wil be explained in the overview section. In the following sections Configuration of nodes and Configuration of states, forecast lengths and time zero the most important configuration features of the topology.xml will be explained. In the last section all the configuration options will be explained in the order in which they can be found in the topology.xsd schema.
Overview
The topology.xml is a mandatory configuration file when you are setting up an IFD-environment. This configuration file is used to configure the topology of a FEWS-system.
The topology is defined by individual nodes and their connectivity. The topology can be viewed in the topology panel, which shows a block diagram of the topology. An example is shown below.
or in the forecast panel, which shows a tree view of the topology.
The behaviour of the forecast panel can also be configured in the topology-file. For example a workflow can be configured for a topology-node. By default the workflow will
run locally when the node is selected in the forecast panel. This can be switched off by setting the option enableAutoRun to false.
The topology.xml plays a central role in configuring an IFD-environment since it is used to configure the forecast panel which is the central panel in an IFD-environment.
The topology.xml was designed to configure the topology of a FEWS system. There are however also a lot of FEWS-system in which the topology.xml is used to configure the work process of a forecaster.
An example is given below.
Configuration of the nodes in the topology tree
The topology tree can be configured in the following way. The example belows show a simple topology tree with two leaf nodes A and B.
Both of them belong the group node C.
<?xml version="1.0" encoding="UTF-8"?> <topology xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/topology.xsd"> <nodes id="C" name="C"> <node id="A" name="A"/> <node id="B" name="B"/> </nodes> </topology>
It is possible to run a workflow in IFD mode or in server mode from the topology panel. In the example below some of the node(s) have a workflow configured.
<?xml version="1.0" encoding="UTF-8"?> <topology xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/topology.xsd"> <nodes id="C" name="C"> <workflowId>workflowC</workflowId> <node id="A" name="A"> <workflowId>workflowA</workflowId> </node> <node id="B" name="B"/> </nodes> </topology>
By default all the workflows started from a leaf node are started in IFD mode.
This means that the results of the run are only temporary available in FEWS and that the results are only available at the stand alone or operator client which started the run. As soon as the FEWS system is restarted all the IFD runs will be deleted.
A workflow which is started from a group node will by default be started as a server run. A server run will run at a FSS when it is started from an operator client. When it is started from a stand alone it will run locally but the results of the run will be available after a restart of the system.
It is possible to change these default settings by using the element localRun.
In the example below the runs from leaf node B will run in server mode and the runs started from the group node C will run in IFD mode.
<?xml version="1.0" encoding="UTF-8"?> <topology xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/topology.xsd"> <nodes id="C" name="C"> <workflowId>workflowC</workflowId> <localRun>true</localRun> <node id="A" name="A"> <workflowId>workflowA</workflowId> <localRun>false</localRun> </node> <node id="B" name="B"/> </nodes> </topology>
It is possible to connect nodes in the topology. In the example below the node STKA2 is connect to two previous nodes (SBFQ2 and ISKQ2).
<node id="STKA2" name="STKA2 Stikine R Wrangell"> <previousNodeId>SBFQ2</previousNodeId> <previousNodeId>ISKQ2</previousNodeId> <workflowId>STKA2_Forecast</workflowId> </node>
The way nodes are connected plays an important role when running workflows in IFD mode.
The example below shows the situation before the forecaster starts an IFD run for the node STKA2. The topology tree shows that
this node has not run yet and that it is connected to two nodes SBFQ2 and ISKQ2.
When the forecaster starts an IFD run for this node FEWS will detect that it is connected to other nodes which have to run to this run.
One of these nodes (SBFQ2) also has a previous node which has to run prior to running this node. Before running node STKA2 the IFD system will make sure that first all the necessary previous nodes are run in the correct order before node STKA2 will be run.
Configuration of states, time zero and the forecast length
Overview of all the configuration options
Nodes definition
The topology of a region is configured by defining the indvidual nodes off a region and grouping them. Below an example from the topology of the abrfc region
<topology xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="chps1/schemas/topology.xsd"> <nodes id="ABRFC"> <workflowId>ABRFC_Forecast</workflowId> <nodes id="NMWTX" name="NMWTX"> <workflowId>NMWTX_Forecast</workflowId> </node> <node id="EGLN5" name="EAGLE NEST DAM"> <workflowId>EGLN5_Forecast</workflowId> </node> <node id="CMMN5" name="CIMARRON 4SW"> <previousNodeId>EGLN5</previousNodeId> <workflowId>CMMN5_Forecast</workflowId>
In the example above we see that the region abrfc has two leaf nodes CMMN5 and EGLN5. They are grouped in the group NMWTX. The group NMWTX is part of the toplevel node ABRFC.
This simple example shows how a topology can be defined and how the nodes and groupnodes can be grouped together. It is also possible to configure the connnectivity between nodes. This can be done
by using the tag previousNodeId. In the example above we can see that EGLN5 is upstream of node CMMN5. The connectivity between nodes is visualised in the topology panel.
Configuration options which apply to all nodes
The topology.xml has two types of configuration options. The first group is applied to all nodes, the second group is applied to individual nodes. In this part the first group of options will be explained.
The following global options are available
- forecasterHelperDirectories
- enableOriginalButtons
- enableAutorun
- enableAutoSelectParameters
- enableRunUpstreamServerNodes
- enableRunAllPreviousNodes
- enableSelectNodesFromMap
- enableAutoSaveOnRun
- enableCrossGroupReferencing
- selectFirstPlotOnSelectionChange
These global options are configured at the top of the topology.xml before the definition of the nodes.
forecasterHelperDirectories
When present, this element specifies the directories where the forecaster helper should look for the files instead of the INFORMATION_PANEL_FOLDER property in oc_global.properties
enableOriginalButtons
Since 2014.01. By default the toolbar with 2 buttons is use: buttons 'Run' and 'Run approved forecast'. If a group node is selected, both buttons start the workflow of that node. When this element is set to true, the original toolbar with 4 or 5 buttons will be used. The original buttons are: 1) 'Switch to edit/forecast mode' (optional), 2) 'Go to next segment', 3) Re-run segment', 4) 'Re-run forecast group', and 5) 'Run approved forecast'.
enableAutoRun
This option is set to true by default. If a topology node is selected in the forecast panel and a workflow is configured for this node and the option is enabled than the associated workflow will automatically run. By setting this option to false this behaviour can be switched off. Note: This option only works if enableOriginalButtons is set to true.
enableAutoSelectParameters
This option is set to false by default. In a node is selected and a filter is configured for that node than the filter will be selected automatically. If this option is also enabled than the parameters of that filter will also be selected automatically. Because the parameters are also selected after selecting the node the plot display will automatically show the time series of the filters in the plot display.
enableRunUpstreamServerNodes
When this option is set to true upstream server nodes with a workflow are run at the server prior tot running the selected server node.
enableRunAllPreviousNodes
If this option is enabled and a node is run, all previous nodes in the topology tree are run before running the selected node, even if the nodes are not connected by the defined topology. Default this option is not enabled, then only the upstream nodes will be run.
enableSelectNodesFromMap
This option is set to false by default. If this option is enabled it will be possible to select nodes by clicking on the location in the map, if that node has a locationId and a filterId configured in the Topology file.
enableAutoSaveOnRun
Default is false. When this option is set to true all edits will be automatically saved to the database without having to press apply or confirm when a node is run.
enableCrossGroupReferencing
By default the topology only considers nodes which are part of the same group as being linked to the current node.
When FEWS tries to determine what the status of a node is, it will also take into account the nodes which are linked to that node.
If that node is however part of another group then FEWS will ignore that node despite the fact that it is linked to that node.
selectFirstPlotOnSelectionChange
When selecting an other topology node the (thumbnail) plot is selected that shows the same parameter or location as currently displayed. To revert to the behaviour of 2016.01 must set this option to true.
Configuration options which apply to individual nodes
The second group of configuration options are applied to indvidual nodes or a group of nodes. These options are defined in the nodes to which these options should be applied.
Groupnodes (<nodes>)
The following options are available for groupNodes:
- showModifiers
- properties
- workflowId
- StateSelection
- localRun
- showRunApprovedForecastButton
- node
- nodes
- groupId
- url
All options are optional.
showModifiers
Since 2014.01. This element will enable that modifiers are shown and editable at groupNodes
properties
These properties can be referenced in workflow files and moduleconfig files with $keys$, similar to global properties. These properties overrule the global properties and module properties.
Please note that Topology properties are only possible for local runs and not for server runs!
WorkflowId
The workflowid is optional for a node. If a workflow is configured this workflow is automatically started after selection of the node if the option enableAutorun is set to true. The workflow can also be started from the forecast panel or the modifier panel.
SecondaryWorkflowId
It is possible to run a second (supporting) workflow from the IFD. If a secondary workflow is configured an additional button will be shown in the button panel.
The running of a the secondary workflow will not have any influence on the icons in the topology panel.
RunSecondaryWorkflowAtServer
By default the secondary workflow will in the same mode as the primary workflow. If the primary workflow is a configured to run as a local (IFD) run then the secondary workflow will also as run as an IFD run.
The default behaviour can be changed with this option.
ModuleInstanceId
When no moduleInstanceId is specified, all moduleInstances in the workflow are executed. When you specify a modulInstance, only that specific modulInstance will run. Note: this will only work for local runs.
StateSelection
The forecast panel also allows the forecaster to select a state. The default state selection can be configured with this option.
Possible options are:
- coldState
- coldStateFromCurrentRun
- warmState
- warmStateSelectionPeriod
- noInitialState
- relativePeriod
LocalRun
This option can be used to configure if the workflow of this node should be run locally or at the server. By default workflow of leaf nodes are run locally and workflows of group nodes are run at the server. Local runs are considered to be temporary runs. The results of these runs are deleted when FEWS is stopped.
Viewpermission
With this option an (optional) viewpermission can be configured. If a user is not allowed to view this node it will not be visible in the forecast panel.
url
With this option an URL can be configured for a node. This URL can be opened with the HTML5 Display component.
Leaf nodes (<node>)
The following options are available for leaf nodes:
- showRunApprovedForecastButton
- localRun
- coldStateFromCurrentRun
- warmStateSelectionPeriod
- nodes
- coldState
- node
- moduleInstanceId
- groupId
- relativePeriod
- warmState
- noInitialState
- nextNodeId
- previousNodeId
- locationId
- filterId
- mapExtendId
- workflowId
- initialState
- localRun
- viewPermission
- url
NextNodeId
This option is used to configure the next node of a topology node in the case that two topology nodes have configured a node to be the previous node. The nextNodeId indicates which node is considered to be the next node when going downstream by using the next segment button in the topology panel
PreviousNodeId
The connectivity between nodes is configured by using the previousNodeId-option.
LocationId
This option can be used to connect a location to a topology node. After selection of a node the configured locations are automatically selected in the filters.
FilterId
If a filter is configured to a topology node it will automatically be selected after selection of the topology node.
MapExtendId
If a mapExtendId is configured the map will automatically zoom to the configured map extend after selection of the node.
The remaining options:workflowId, initialState, localRun and viewPermission are described in the section groupNodes.
Schema