WaterCoach Display configuration

WaterCoach Display configuration

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.

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 element adjustSystemTimeAutomatically should be set to 'true' (default for a Stand Alone is false), 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"/>

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

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

      
      

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

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

8. Disable view permissions (optional). Useful in case the WaterCoach application can be accessed on home computers, or other locations where you don't know the user name people will use.
   1. Remove (or rename) the files UserGroups.xml and Permissions.xml
      This will result in warning messages for every viewPermission that has been configured, but will give any user full viewing permissions. See also 07 Permissions

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

The WaterCoach can be used in the so called participant mode. This is used with a single Delft-FEWS application, when multiple "operator clients" need to work together. This mode is an approximation of the live operational system, in which multiple operators can work in their own OC and in that way share the workload. In participant mode there is one "master" WaterCoach session, which controls the LocalDataStore as used by Delft-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:

• Master WaterCoach:
  
  • The vjdbcServicePortRange is configured in SystemConfigFiles/Explorer.xml to a specific port, e.g.: <vjdbcServicePortRange start="40402" end="40402"/>, (01 FEWS Explorer).
    
    • Note: this addition should be only made in the master WaterCoach configuration, and should not be included in the configuration of the participant WaterCoach sessions.
  • Needs access to the ScenarioScriptDatabase (SSD), to load the scenario as well as the script.

• Particpant WaterCoach(es):

  • Should link to the embeded vjdbc server run by the Master. This is configured in the clientConfig.xml of the Delft-FEWS application, see configuration example.

    • If the url can not be pre-configured (e.g. in a VM environment), you can generate this file from the Master application at the start of the exercise and export it to a location (see WaterCoachDisplay.xml), where it can be picked up for use in the Participant applications.

  • Should not have the vdjbc server configured in the Explorer.xml

  • Also need access to the ScenarioScriptDatabase (SSD), to make use of the script and to generate messages. If the SSD is not available, the WaterCoach Display will no start up properly.

Multiple system mode

It is possible to connect two or more Delft-FEWS applications for a combined training with WaterCoach with the multipleSystems option. This functionality allows to reproduce the behaviour of operational systems that share data with each other. This mode is enabled in the WaterCoach application (see below). The combining of multiple systems is is different from participant mode in that we now connect different Delft-FEWS applications in a single combined WaterCoach training. Within each Delft-FEWS application, you can also make use of the "participant mode", allowing multiple operators working on the same system at the same time.

The connection of multiple systems allows for:

• Time synchronisation: The "leader" system writes the systemTimeFile, the following system(s) read the systemTimeFile and change their system time accordingly. The applications will then by synchronized via the system time. See config example below.
• Data sharing: Create export and import workflows for data that is shared between the systems in normal operations. This will work even if the underlying Scenarios of the different systems have different dataStart, since the data is shared based on the synchronised (in-training) systemTime related to displayStart. The data is shared through files on a folder all applications have access to. Schedule these workflows to run automatically in the script (see Script configuration (scheduling workflows)).

For leader and followers the following should be configured in the WaterCoachDisplay.xml (see config example below):

• Enable the multipleSystems functionality in the Application configuaration file, see example config below.

• In this example the path and file name for the systemTimeFile is specified with the property WATERCOACH_SYSTEM_TIME_PATH, which in turn is defined in the rootConfigFile global.properties, eg as D:\WaterCoach\TimeKeeping\time.nc. This path and file name is the location where the NetCDF systemTimeFile will be written and read. Note, it is important that both the leader and follower of the WaterCoach session have access and read and write permissions for this path.
• When the application is configured correctly a new element will appear in the docked window of WaterCoach called “Multiple systems mode is active” with a check box to identify the application as a follower that will  "Synchronize time with training lead" (see User Guide). 

Note: If data created or modified during the training needs to be shared between the Delft-FEWS applications, check out the topic on scheduled workflows at Script configuration

Examples

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

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

<waterCoachDisplay>
 <multipleSystems enabled="true"> 
	     <systemTimeFile>$WATERCOACH_SYSTEM_TIME_PATH$</systemTimeFile>
	</multipleSystems>
	<config>
		...
	</config>
</waterCoachDisplay>

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

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

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

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

<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">
	<multipleSystems enabled="true"> 
	     <systemTimeFile>$WATERCOACH_SYSTEM_TIME_PATH$</systemTimeFile>
	</multipleSystems>
	<config>
		<scenarioScriptDatabasePath>$WATERCOACH_SCENARIO_DATABASE_PATH$</scenarioScriptDatabasePath>
		<hideYear>false</hideYear>
		<timeControl>
			<pause>true</pause>
			<next>true</next>
			<set>true</set>
			<fastForwardBackward>true</fastForwardBackward>
		</timeControl>
		<experienceLevel>
			<levels>Beginner;Intermediate;Expert</levels>
			<adjustLevel>false</adjustLevel>
		</experienceLevel>
		<fewsLogEventCodes>Manual.*</fewsLogEventCodes>
		<!-- option for developer, useful when you are working on the same scenario -->
		<copyLocalDataStore>true</copyLocalDataStore>
		<defaultUserName>defaultUserName</defaultUserName>
		<scriptLogPath>%REGION_HOME%/WaterCoachLog/</scriptLogPath>
		<displayConfirm>false</displayConfirm>
	</config>
</waterCoachDisplay>