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

Compare with Current View Page History

« Previous Version 21 Next »

How to setup the launch of Delft-FEWS

This page describes the various elements involved in launching a Delft-FEWS application, what has changed in the 2018.02 compared to previous versions and provides a step-by-step guide on how to set up a Delft-FEWS client yourself.

New structure of the Delft-FEWS binaries

With the 2018.02 release, the structure of the Delft-FEWS binaries has changed compared to previous versions. This is due to the fact that:

  • java runtime environment (jre) is now included within the basebuild / boot build
  • the creation of (start up) shortcuts has changed (createShortcuts application)
  • a new concept is introduced with a boot build and a local base build repository (localBaseBuildRepository). This concept is explained on the wiki page of the new Forecasting Shell Servers.

The bin folder which contains your createShortcuts.exe we call the boot build, and lives wherever you want. If you launch the shortcut, it takes an executable from your boot build to initiate the launch process. During the launch process the clientConfig, etc. is downloaded from the central database.  Option 2 (Database connection URL to Operator Client, see section createShortcuts application below) in the createShortcuts application if run successfully it will make:

  • A shortcut in \%LOCALAPPDATA%\fews\NAME_OF_SHORTCUT (equivalent to your FEWS Operator Client executable for previous versions, the region home)
  • A shortcut on the desktop / start menu
  • %USERPROFILE%\.fews\secrets\FILE_WITH_ENCRYPTED_CREDENTIALS
Note that createShortcuts.exe has no way of using a patch. 

If you have uploaded a basebuild via the admin interface, with a number below the patch number, this will be downloaded to \%LOCALAPPDATA%\fews\localBaseBuildRepository on Windows or ~/.cache/fews/localBaseBuildRepository on Linux. Only the differences between the boot build and basebuilds are downloaded. The patch (in the region home) determines which basebuild will be used and the base build plus the patch determine the further behaviour of your Operator Client. 

Since the 2018.02 the region home folder only contains data that can be removed. All data in this folder will be rebuild (with all relevant files) from the central database when the user logs into the system again. The region home contains the user settings, global properties, the active patch, module datasets (e.g. for running models locally on client) and the localDatastore (if you do not use Direct Database Access). Note that with Citrix it is best to use the Direct Database Access client. Index files for the Operator Clients are now no longer maintained locally but by the Forecasting Shell servers (see table with information about status of Forecasting Shell Servers). 

The Operator Client user the Delft-FEWS.exe and Delft-FEWSc.exe from the boot build.  The Delft-FEWS1.exe, Delft-FEWS2.exe, Delft-FEWS3.exe and Delft-FEWS4.exe are optional and will only be used to ensure the Delft-FEWS button are not grouped on the Taskbar when a user runs multiple operator clients locally on 1 desktop.

All relevant files for each operating system are found in their respective folders in the Delft-FEWS binaries folder. 

The createShortcuts application

As mentioned above, the creation of the Delft-FEWS (start up) shortcuts has changed and this is now handled with the createShortcuts application. This application can be found in the directory of the relevant operating system (Windows or Linux) in the basebuild, in the form of the createShortcuts.exe file (see directory structure above). With this, shortcuts can be created for Stand Alone (SA), Operator Client (OC) or Configuration Manager (CM) applications of Delft-FEWS. A step-by-step guide on how to do this is listed below. The application opens a menu that looks like this:

As can be seen from this, the options for creating shortcuts are:

  • Database connection URL to Config Manager
  • Database connection URL to Operator Client
  • Path to Stand Alone or Operator Client *clientConfig.xml

The database connection options require a URL to the database server on which the application is located. When database server has no single sign on enabled and the username and password are not embedded in the URL, the user will receive a pop-up once, allowing him/her to enter these credentials, which are then saved (secure on Windows) for that specific shortcut. A pop-up will appear with the relevant (with client type Operator Client) and valid *clientConfig.xml in the database, so that the user can select the right one. When the database connection option is selected, shortcuts can only be created at the Desktop and/or Start Menu.

Embedding the database credentials in the URL should not be used when the database server is accessible from the internet. When the URL contains credentials the complete URL is encrypted in the shortcut file (.sh/.desktop/.lnk) (requires build > 87619). The shortcut can be transferred to other desktops and or users without asking the (other) users for database credentials.

jdbc:sqlserver://myhost:1433;database=mydatabase;user=john;password=secret;

jdbc:postgresql://myhost/mydatabase?user=john&password=secret";

jdbc:oracle:thin:john/secret@myhost:1521:mydatabase

When possible always enable single sign on in the database server so database credentials are not needed at all.


The path to an existing clientConfig.xml file can be directly entered, obtained by clicking on the Browse button or, alternatively, a completely new clientConfig.xml can be created by clicking the New button. This last option will by default create a clientConfig.xml file for a Stand Alone application (which could be edited to make it suitable for an Operator Client application). More information on what should be included in the clientConfig.xml file can be found at: Root Configuration Files for Operator Client and Forecasting Shell Servers. When this option is selected, shortcuts can be created at three possible locations (Desktop, Start Menu and/or Region Home directory, which is the same as the location of the clientConfig.xml file).

When information is entered correctly and the Create Shortcuts button is pressed, the shortcuts are created and the user is informed of this with a pop-up window:

When an invalid URL or path is entered, a similar pop-up window is shown, informing the user of the specific error without attempting to create the shortcuts. 

The Debug option allows for more advanced options, as can be seen from the pop-up window that will appear:

Step-by-step: how to create a SA (2018.02 and upward)

For this step-by-step guide, we assume that a Windows operating system is used. To create an OC or CM application, most of the steps are similar, with the exception of steps 4 (a SA application is not required), step 6 (a clientConfig.xml file is required for an OC and requires additional elements, see documentation) and step 8 (select the relevant option for an OC or CM).

  1. Create a new folder (somewhere on your system) where the application will be located. We'll use /FEWS/201802/ in this example.
  2. Create a /bin/ folder in this (201802) folder.
  3. Copy/extract the basebuild in this /bin/ folder.
  4. Copy a (Stand Alone) application folder into this (201802) folder. This is the Region Home folder for this application. We'll use /FEWS/201802/Example_SA/ in this example.
  5. Copy the patch into the Region Home folder (Example_SA). The directory structure should now look similar to this (some elements are optional):

  6. Open the clientConfig.xml file here, if it exists, and check if it contains at minimum the configuration below. More configuration options are available (see its XML schema and/or documentation page: Root Configuration Files for Operator Client and Forecasting Shell Servers). If the file does not exist, it can either be created manually with this minimum configuration or, alternatively, it can be created automatically during step 8.

    <?xml version="1.0" encoding="UTF-8"?>
<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">
    <clientType>Stand alone</clientType>
</clientConfiguration>
  7. Navigate to /FEWS/201802/bin/windows/ and double-click createShortcuts.exe.
  8. Click the option to use a clientConfig.xml file, navigate to the relevant folder (/FEWS/201802/Example_SA) using the Browse button and click on the clientConfig.xml file there. Alternatively, if it does not exist yet it can now be created automatically using the New button (make sure to place it in the same /FEWS/201802/Example_SA folder). Depending on your choices, the menu will look similar to this:
  9. Select the location(s) to place the shortcut(s) and click on 'Create shortcuts'.
  10. The next time you would like to start the application you can use any of the just created shortcuts.
  • No labels

Disclaimer