You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 173 Next »

WaterCoach application  / WaterCoach Display configuration (embedded WaterCoach, 2016.01 and up)

What

application_config.xml (stand alone WaterCoach)

waterCoachDisplay.xml (embedded WaterCoach part of Delft-FEWS config, 2016.01 and up)

Description

Configuration of the WaterCoach application or WaterCoach Display

Some changes to the Delft-FEWS configuration are required.

schema location

application_config.xsd or waterCoachDisplay.xsd

WaterCoach Application configuration (stand alone WaterCoach)

In the application configuration, global settings for the WaterCoach (fka FEWS Game) which are valid for all scenarios/scripts can be specified.

Schema definition

The structure of the XML-schema for the application configuration is as shown on the right.

 

Explanation

The keys in the XML-schema are explained in the figure on the right. Some of the keys are explained in more detail here.
Note: when 'relative path' is mentioned, this is the relative path with respect to the location of the WaterCoach executable (i.e. not the FEWS executable).

  • The value of the key locale must be a 2-letter abbreviation of the language in which the game screens will be displayed (currently available: EN for English or NL for Dutch). For specific applications, extensions to this locale are supported (currently available: EN_AU_BOM for the BoM in Australia).
  • Historical scenarios/scripts may be familiar to players of the game. Therefore it is possible to hide the year of the scenario/script in the WaterCoach by setting the flag hideYear to true. Note that for the WaterCoach a copy of the operational system should be used since some changes in the FEWS configuration are required; see below. A better option for misleading players is to overrule the date/time of the historical scenario by explicitly setting the in-game time in the script configuration.
  • The key fewsExecutable must contain the (absolute or relative) path to the FEWS executable, which is usually located in the bin-directory of a FEWS release. On the Linux platform, the FEWS executable is the shell script fews.sh. See below for required changes in the FEWS configuration.
  • The key fewsRegionDir is the (absolute or relative) path to the so-called region directory of FEWS. The region directory contains the FEWS configuration (the Config-subdirectory) and the global properties for the FEWS configuration. The WaterCoach is generic and can be used with any FEWS configuration. Note that on a Windows system, the FEWS region directory is also specified in the so-called jpif-file (for FEWS release 2014.01 or earlier) or ini-file (from FEWS release 2014.02 on) that is located in the bin-directory of the FEWS system. This specification must be consistent with the one in FewsRegionDir.
  • The system time in FEWS is controlled by the WaterCoach. The frequency for updating the FEWS system time is specified by the key fewsSystemTimeUpdateInMinutes . See below for required changes in the FEWS configuration. (obsolete as of FEWS release 2013.02)
  • Scenarios/scripts that can be played with the WaterCoach must be part of a scenario/script database. The key scenarioScriptDatabasePath contains the (absolute or relative) path to the scenario/script database.
  • Events in a script can be associated with a file that is executed during the game. For example, a pdf-file can be associated with an event to simulate an incoming e-mail or an mp3-file to simulate telephone calls. Using the key fileAssociation , programs can be specified with which files with indicated extensions must be processed. Default file associations are used if nothing is specified here.
  • In the section timeControl , the presence of buttons for time control during the game can be configured, namely a pause/play button, a next button for jumping to the next scheduled event in the script, fast Forward/Backward buttons for speeding up/down time, and a set button for adjusting the time manually.
  • Section  experienceLevel  contains configuration of experience levels in the game. With the key  levels , the actual experience levels are defined, separated by semi-colons, e.g. "Beginner;Intermediate;Expert". In the script configuration, events can be defined for each of these experience levels. The flag  adjustLevel  indicates that the experience level can be adjusted during the game.
  • Communication between FEWS and the WaterCoach is handled by the so-called FEWS PI service. This service requires a port number that must be specified in the section fewsPiPortNumber . See below for required changes in the FEWS configuration.
  • The key fewsLogEventCodes accepts a list (separated by semi-colons) of event codes from FEWS that have to be logged in the WaterCoach log, e.g. "Info;ManualForecast.started".

  • The option to visualize the script can be activated by setting  showVisualizeScriptButton  to true.

    Note on showVisualizeScriptButton

    The showVisualizeScriptButton is not supported in the embedded version of WaterCoach (2016.01 and up)

  • The WaterCoach can be played combined with the so-called "procedure game", developed for the Dutch Water Service (Waterdienst). In such a combined setting, the hostname and the port number for connecting to the combined game must be specified in serverHostName and serverPort , respectively. Furthermore, forecasts must be published to a file in so-called PI-format. This can be accomplished by setting the key writePiOutput to true (defaults to false).

  • The keyword participant should be used to indicated the game is part of a combined setting. See also below.

    Note on participant

    participant is deprecated in the embbeded version of WaterCoach (2016.01 and up), since this is configured in the clientConfig file. See also below.

  • The option copyLocalDataStore has been added to aid the script configurator. If you are working on the script for one scenario, you can turn of the copying of the localDataStore at the start-up of the WaterCoach by temporarily setting this keyword to false. Note: this option has no effect in an application that is configured as participant.

  • The keywords log4jConfigPath, logPath and scriptLogPath  can can be set to overrule the default locations of the various log input and output files.

    Note on logging

    log4jConfigPath and logPath are deprecated in the embbeded version of WaterCoach (2016.01 and up), since logging is in Log4jConfig.xml as it is for all plugins. The location of the log file can still be defined using scriptLogPath.

  • Keyword  displayConfirm  controls the presence of "Are you sure?" confirmation buttons.

Multiple application configurations

Instead of specifying an application configuration as described above, it is also specify a meta-application configuration that contains a list of application configurations. The structure of the XML-file is shown on the right. If such a meta-application configuration is specified, then the WaterCoach will look for scenario's in all collected scenarioScriptDatabasePaths in the list of application configuration files. The user can then choose one of the scenario's to play.

WaterCoach Display configuration (embedded WaterCoach, 2016.01 and up)

The WaterCoach Display configuration for the embedded WaterCoach replaces the application configuration of the Stand Alone WaterCoach configuration. In it, global settings for the WaterCoach can be specified, which are valid for all scenarios/scripts. This display is part of the is part of the Delft-FEWS configuration , and as such needs to be declared in the Delft-FEWS configuration.

 

Schema definition

The structure of the XML-schema for the WaterCoach Display configuration is as shown on the right.

 

Explanation

The keys in the XML-schema are explained in the figure on the right. Some of the keys are explained in more detail here.

  • Scenarios/scripts that can be played with the WaterCoach must be part of a scenario/script database. The key scenarioScriptDatabasePath contains the (absolute or relative) path to the scenario/script database.
  • Historical scenarios/scripts may be familiar to players of the game. Therefore it is possible to hide the year of the scenario/script in the WaterCoach by setting the flag hideYear to true. Note that for the WaterCoach a copy of the operational system should be used since some changes in the FEWS configuration are required; see below. A better option for misleading players is to overrule the date/time of the historical scenario by explicitly setting the in-game time in the script configuration.
  • Events in a script can be associated with a file that is executed during the game. For example, a pdf-file can be associated with an event to simulate an incoming e-mail or an mp3-file to simulate telephone calls. Using the key fileAssociation , programs can be specified with which files with indicated extensions must be processed. Default file associations are used if nothing is specified here.
  • In the section timeControl , the presence of buttons for time control during the game can be configured, namely a pause/play button, a next button for jumping to the next scheduled event in the script, fast Forward/Backward buttons for speeding up/down time, and a set button for adjusting the time manually.
  • Section  experienceLevel  contains configuration of experience levels in the game. With the key  levels , the actual experience levels are defined, separated by semi-colons, e.g. "Beginner;Intermediate;Expert". In the script configuration, events can be defined for each of these experience levels. The flag  adjustLevel  indicates that the experience level can be adjusted during the game.
  • The WaterCoach can be played combined with the so-called "procedure game", developed for the Dutch Water Service (Waterdienst). In such a combined setting, the hostname and the port number for connecting to the combined game must be specified in serverHostName and serverPort , respectively. Furthermore, forecasts must be published to a file in so-called PI-format. This can be accomplished by setting the key writePiOutput to true (defaults to false).
  • The key fewsLogEventCodes accepts a list (separated by semi-colons) of event codes from FEWS that have to be logged in the WaterCoach log, e.g. "Info;ManualForecast.started".
  • The option to visualize the script can be activated by setting  showVisualizeScriptButton  to true.
  • The keyword participant should be used to indicated the game is part of a combined setting. See also below.
  • The option copyLocalDataStore has been added to aid the script configurator. If you are working on the script for one scenario, you can turn of the copying of the localDataStore at the start-up of the WaterCoach by temporarily setting this keyword to false. Note: this option has no effect in an application that is configured as participant.
  • Some default values can be entered (useful when developing a game): defaultUserName, defaultScenario and defaultScript.
  • The keywords log4jConfigPath, logPath and scriptLogPath  can can be set to overrule the default locations of the various log input and output files.
  • Keyword  displayConfirm  controls the presence of "Are you sure?" confirmation buttons.

Delft-FEWS configuration

It is advisable to use a Stand Alone application for the WaterCoach, to prevent any possible obstructions to operational activities. Also, some minor changes are needed in the FEWS configuration in order to use it with the WaterCoach. These changes can be made to the live system as well, without much consequences. 
Note: for a more detailed description of the FEWS configuration files, please refer to the wiki pages of the Delft FEWS Configuration Guide .

  1. FEWS configuration file Explorer.xml  in the directory  SystemConfigFiles
    1. the  dateTime  section  
      1. In order to hide the year within FEWS, the dateTimeFormat must be configured accordingly.  
      2. The cardinalTimeStep  should be consistent with fewsSystemTimeUpdateInMinutes . Indeed, it makes no sense to set it in the WaterCoach to 1 minute, while it is set to 1 hour in the FEWS configuration (although this will not cause any problems in the game). (obsolete as of FEWS release 2013.02)
      3. The element adjustSystemTimeAutomatically should be set to 'true' (this is the default), otherwise it will not be possible for the WaterCoach to alter the systemTime during the game. (Also make sure that you don't have a T0 configured in the global.properties file).

    2. To have a pop-up appear with new messages, vjdbcServicePortRange needs to be configured in Explorer.xml. This same service is also required for the participant mode, and should only be configured for a Stand Alone or a Master application. Note: by specifying this range the vjdbc service is started. This part of the configuration can be kept the same in the live system, but be aware that this means that this service will be started in the live system as well.

      <vjdbcServicePortRange start="40402" end="40402"/>

    3. Note: this change is no longer required with the embedded WaterCoach: The port number  fewsPiPortNumber for the FEWS PI service has to be in the range of port numbers that must be specified in Explorer.xml . Note: by specifying this range the PI service is started. This part of the configuration can be kept the same in the live system, but be aware that this means that the PI service will be started in the live system as well.

      <piServicePortRange start="50505" end="50505"/>
    4. To distinguish the FEWS configuration for the WaterCoach, one could change the name and panel labels. The name of the Explorer window is configured with systemCaption and the name of the panels with panelHeaderLabels . For example, the term TRAINING or SERIOUS GAME could be added to the captions of these panels.  (obsolete as of FEWS release 2013.02 since the FEWS user interface contains a yellow border when operated in WaterCoach mode)
  2. Depending on the set-up of the scenario and script database, an additional change could be required, see Scenario and Script database.
  3. Note: with some configurations at the start-up of fews via the WaterCoach, the error message 'Fault occurred' may occur. This message can be ignored. 
  4. Since all data for a scenario is pre-loaded in the FEWS local data store, it is desirable to hide certain data after the current system time, e.g. measurement data. This can be accomplished by specifying hideExternalHistoricalAfterSystemTime=true in the file global.properties , which is located in the FEWS configuration directory. As the name of this key implies, only time series of the type "external historical" are hidden; time series of the types "external forecast", "simulated historical", and "simulated forecast" are completely visible. As of FEWS release 2012.02, this step is no longer required.

Additional steps for embedded WaterCoach (2016.01 and up)

  1. Changes to the global.properties
    1. add key WATERCOACH_SCENARIO_DATABASE_PATH=%REGION_HOME%/WaterCoach
      Note, this is optional, you could also define this location directly in waterCoachDisplay.xml

    2. configure localDatastoreFormat=firebird, since the default 2016.01 database is Dirby

      Note: the shared database approach for the participant mode is only supported for Firebird at the moment

  2. Create <My_WaterCoachDisplay>.xml in <root_folder>\Config\DisplayConfigFiles\, see configuration example
    If you have an existing application_config.xml, make the following changes:
    1. move file to <root_folder>\Config\DisplayConfigFiles\ and rename if you like
    2. replace root element config with root element waterCoachDisplay
    3. add element config
    4. remove elements
      1. locale,
      2. fewsExecutable,
      3. fewsRegionDir,
      4. fewsPiPortNumber
    5. move element hideYear under the element scenarioScriptDatabasePath
    6. use key from global.properties to configure scenarioScriptDatabasePath
    7. add element /waterCoachDisplay to the end of the file
  3. FEWS configuration file Explorer.xml  in the directory  SystemConfigFiles

    1. Add WaterCoach plugin to Explorer.xml, see the configuration example (Only for the embedded WaterCoach, Delft-FEWS 2016.01 and up).

      loadAtStartup with embedded WaterCoach (Delft-FEWS 2016.01 and up)

      Note: with the embedded WaterCoach (Delft-FEWS 2016.01 and up), it is recommended to use the option loadAtStartup in Explorer.xml set to true, when the script_config.xml makes use of the option dataStart . This is because to be able to change the time in the GUI Delft-FEWS needs to restart. After the restart, only those tasks in Explorer.xml with loadAtStartup=true are started. If this option is set to false for the WaterCoachDisplay, the user will have to manually restart the display, just after she started the WaterCoach mode the first time, which can be confusing.


  4. Optional: Modifiy Delft-Fews layout to start with WaterCoach plugin in the front

    1. Make sure you have configured the WaterCoach plugin in Explorer.xml to loadAtStartup is true (see previous step)

    2. Start Delft-FEWS

    3. Bring WaterCoach plugin window to the front and

    4. select menu -> File -> Save Layout

  5. Managing of the logging from WaterCoach

    1. User category name nl.wldelft.fews.gui.plugin.watercoach in Log4jConfig.xml to enter specific rules for logging from WaterCoach.
      See configuration example , in which all debug messages in WaterCoach are suppressed.

Delay visibility of forecasts

When Fews is used in combination with the WaterCoach, automatically forecast made in "the future" are invisible, both in the displays as in the forecast manager. Forecasts that where current in the past at the system time are made current again.

In practice, forecasts often come available with a certain delay. To take this into account, a delay can be specified.

  • Simulated forecasts are linked to a workflow, which can be delayed in the WorkflowDescriptors xml file.

    	<workflowDescriptor id="exampleWorkFlow" visible="true" forecast="true">
		<waterCoachDelay unit="hour" multiplier="4"/>
	</workflowDescriptor>

  • External forecasts can have a delay configured for each seperate moduleInstance in the ModuleInstanceDescriptors xml file.

        <moduleInstanceDescriptor id="ImportECMWF">
        <waterCoachExternalForecastDelay unit="hour" multiplier="6"/>
    </moduleInstanceDescriptor>

Show specific external historical timeseries in the future (e.g. astronomical tide forecast or climatological data)

Astronomical tide is often imported once a year into the system as an external historical, even though it's in fact a forecast. Default the WaterCoach mode won't show future values of external historical timeseries. To be able to show the tide "forecast", an exception has been made for external historical timeseries with synchlevel=4. This same synchlevel also for proper synchronisation of this data to the OC in a live system (see B Enumerations#A.5SynchronisationLevels). Note that the synchLevel=4 should explicitly be specified also in the display configuration files (e.g. Filter.xml, etc) in order for the future values of the timeseries to be visible in WaterCoach.

Participant mode

Note on shared database approach

The shared database approach for the participant mode is only supported for Firebird at the moment

The WaterCoach can be used in the so called participant mode. In that case there is one "master" WaterCoach session, which controls the LocalDataStore as used by FEWS. The other students start up the WaterCoach and make a connection to this same LocalDataStore. For this the shared LocalDataStore should be available to all students (e.g. network, citrix, internet). Also, some actions are necessary.

  • The master WaterCoach session needs to make her LocalDataStore shareable using the F12-P function within the Fews application. In the future this action will be done automatically, if the WaterCoach application is so configured. As of FEWS release 2013.02, this step is no longer required, as long as the vjdbcServicePortRange is configured in SystemConfigFiles/Explorer.xml to a specific port, e.g.: <vjdbcServicePortRange start="40402" end="40402"/>. Note: this addition should be only made in the master WaterCoach configuration, and not be included in the configuration of the participant WaterCoach sessions. (01 FEWS Explorer)
  • Start the embeded vdjbc server using the F12-L option. This action provides an IP adress and port number in the log-window of the Fews application. These should correspond to the IP adress and port defined in the client_config.xml file of the particpant WaterCoach sessions. Replace by next step (url).

  • The particpant WaterCoach session(s) should link to this embeded vjdbc server by configuring this in the clientConfig.xml of the FEWS application, see configuration example. Note: the participant WaterCoach sessions should not have the vdjbc server configured in the Explorer.xml

  • The master WaterCoach session can not be used for the training, because LocalDataStore of its Fews application is not updated by changes made by the participant WaterCoach sessions.

  • The participant sessions also need access to the ScenarioScriptDatabase (SSD). They won't make use of the scenario, but they will make use of the script, to generate messages. If the SSD is not available, the WaterCoach Display will no start up properly.

    With the embedded WaterCoach (2016.01 and up) the master WaterCoach session can be used for training and the LocalDataStore of its Fews applications are updated by changes made by the participant WaterCoach sessions.

     

 

Examples

Example of clientConfig configuration (Participant)
<clientConfiguration 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/clientConfig.xsd">
    <databaseServer>
    <url>jdbc:vjdbc:rmi://<host>:<port>/VJdbc,FewsDatabase</url> 
<!-- replace <host> with the correct host (e.g. localhost if both applications are run on the same pc, the Ip address of the pc, or a network location) -->
<!-- replace <port> according to the port configuration in Explorer.xml in the Master FEWS configurations (e.g. 40404 according to the example on this wiki) -->
    </databaseServer>
    <localCacheSizeMB>500</localCacheSizeMB>
</clientConfiguration>

Example of application configuration (Stand Alone WaterCoach)
   <config 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/application_config.xsd">
      <name>Example of application configuration</name>
      <locale>EN</locale>
      <hideYear>false</hideYear>
      <fewsExecutable>..\FEWS_WaterCoach\bin\Fews_WC.exe</fewsExecutable>
      <fewsRegionDir>..\FEWS_WaterCoach\Fews_WC</fewsRegionDir>
      <scenarioScriptDatabasePath>ScenarioScriptDatabase\Fews_WC</scenarioScriptDatabasePath>
      <fileAssociation extension="pdf">C:\Program Files\Adobe\Reader 9.0\Reader\AcroRd32.exe</fileAssociation>
      <fileAssociation extension="jpg">C:\WINDOWS\system32\mspaint.exe</fileAssociation>
      <timeControl>
         <pause>true</pause>
         <next>false</next>
         <set>false</set>
         <fastForwardBackward>true</fastForwardBackward>
      </timeControl>
      <experienceLevel>
         <levels>Beginner;Expert</levels>
         <adjustLevel>false</adjustLevel>
      </experienceLevel>
      <fewsPiPortNumber>50505</fewsPiPortNumber>
      <showVisualizeScriptButton>true</showVisualizeScriptButton>
      <! participant keyword is deprecated since 2016.01. This has to be configured in the clientConfig file. !>
	  <participant>false</participant> 
      <!-- option for developer, useful when you are working on the same scenario -->
      <copyLocalDataStore>false</copyLocalDataStore>
   </config>

Example of meta-application configuration
   <configList 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/watercoachschemas/version1.0/application_config.xsd">
      <configPath>C:\path\to\application\configuration\application_configuration.xml</configPath>
      <configPath>C:\some\other\path\to\application\configuration\application_configuration.xml</configPath>
   </configList>

Example of display configuration (Embedded WaterCoach, 2016.01 and up)
   <waterCoachDisplay 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/waterCoachDisplay.xsd">
<config>
      <scenarioScriptDatabasePath>ScenarioScriptDatabase\Fews_WC</scenarioScriptDatabasePath>
      <hideYear>false</hideYear>
      <fileAssociation extension="pdf">C:\Program Files\Adobe\Reader 9.0\Reader\AcroRd32.exe</fileAssociation>
      <fileAssociation extension="jpg">C:\WINDOWS\system32\mspaint.exe</fileAssociation>
      <timeControl>
         <pause>true</pause>
         <next>false</next>
         <set>false</set>
         <fastForwardBackward>true</fastForwardBackward>
      </timeControl>
      <experienceLevel>
         <levels>Beginner;Expert</levels>
         <adjustLevel>false</adjustLevel>
      </experienceLevel>
	  <fewsLogEventCodes>*</fewsLogEventCodes>
	  <!-- option for developer, useful when you are working on the same scenario -->
      <copyLocalDataStore>false</copyLocalDataStore>
      <defaultUserName>defaultUserName</defaultUserName>
      <defaultScenario>defaultScenario</defaultScenario>
      <defaultScript>defaultScript</defaultScript>
      <scriptLogPath>%REGION_HOME%/WaterCoach_log</scriptLogPath>
      <displayConfirm>false</displayConfirm>
</config>
</waterCoachDisplay>

Example of WaterCoach plugin configuration in Explorer.xml (Embedded WaterCoach, 2016.01 and up)
  <explorerTask name="WaterCoach">
    <displayConfigFileName>My_WC_Display_Config_File</displayConfigFileName>
    <toolbarTask>false</toolbarTask>
    <menubarTask>false</menubarTask>
    <allowMultipleInstances>false</allowMultipleInstances>
    <toolWindow>true</toolWindow>
    <loadAtStartup>true</loadAtStartup> <!-- select true if configuration will only be used in WaterCoach mode __>
										 <!-- and/or dataStart is used in script_config.xml -->
</explorerTask>

Example of logging configuration for category nl.wldelft.fews.gui.plugin.watercoach (Embedded WaterCoach, 2016.01 and up)
 <category name="nl.wldelft.fews.gui.plugin.watercoach" additivity="false">
                <priority value="INFO"/> <!--If another level is used, the WC script messages won't become visible in Delft-FEWS-->
				<appender-ref ref="dataStoreLogEntriesTable"/>
                <appender-ref ref="defaultLogFile"/>
                <appender-ref ref="explorerLogPanel"/> 
 </category>
  • No labels

Disclaimer