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.
With the 2018.02 (and later) release(s), the structure of the Delft-FEWS binaries has changed compared to previous versions. The highlights are:
Note that the patch.jar patch mechanism is not applicable to the createShortCuts application.
The terminology further explained:
Use the createShortcuts application from the bin/linux directory of the boot build for setting up a Stand alone client / Operator Client and or Config Manager. It needs to be made executable first. When running the createShortcuts.exe application successfully, it will make:
Use the createShortcuts.exe application from the bin\windows directory of the boot build for setting up a Stand alone client / Operator Client and or Config Manager. When running the createShortcuts.exe application successfully, it will make:
If you have uploaded a basebuild via the admin interface, with a number below the patch number, this will be downloaded to a localBaseBuildRepository (\%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 basebuild 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). 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). Note that with Citrix it is best to use the Direct Database Access client.
The Operator Client uses 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 operating system specific files are found in their respective folders in the Delft-FEWS binaries folder.
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 (createShortcuts.exe file) can be found in the build package in the directory of the relevant operating system (Windows or Linux). With this application, shortcuts can be created for Stand Alone (SA), Operator Client (OC) or Configuration Manager (CM) applications of Delft-FEWS. For Linux it is necessary to run setExecutePermissions.sh to set proper execute permissions for the Delft-FEWS programs. 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:
The database connection options require a URL to the database server on which the Delft-FEWS central database is located. When the 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. In certain circumstances another pop-up will appear with the relevant (valid) *clientConfig.xml files 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). This requires a build > 87619. The shortcut can be transferred to other desktops or other users without asking the (other) users for database credentials. One can also encrypt the complete database connection string through the F12 option → S-clipboard → encrypt password. In that case, use the encrypted connection string but add the @ sign before it. Note that at anytime, both encrypted and unencrypted passwords can be entered, where it is recommended to share encrypted passwords only.
Examples of possible database URLs:
jdbc:sqlserver://dummy_hostname:1433;database=dummy_databasename;user=dummy_username;password=dummy_password
jdbc:postgresql://dummy_hostname/dummy_databasename?user=dummy_username&password=dummy_password"
jdbc:oracle:thin:dummy_username/dummy_password@dummy_hostname:1521:dummy_databasename
jdbc:vjdbc:servlet:https://dummy_hostname/FewsDatabaseHttpsProxy;user=dummy_username;password=dummy_accesskey;
When possible always enable single sign on in the database server so database credentials are not needed at all.
Notice that with this option, all folders and files are placed in the %appdata% (local) folder, which is cleaned after closing the client |
It is now possible to have multiple FEWS schemas/systems in a single (managed) database instance. By this you only need a single database and you can use a single OC/CM shortcut to access multiple FEWS systems.
When the database contains multiple FEWS schemas and the schema is not specified in the URL the OC/CM user gets automatically a pop-up to select the desired FEWS schema.
The schema creation script should be executed for every schema. Every FEWS schema/system can use a different FEWS version.
For non-OC/CM database connections and if you want to use a non-default schema you have to add the desired schema to the database URL.
jdbc:sqlserver://dummy_hostname:1433;database=dummy_databasename;user=dummy_username;password=dummy_password;currentSchema=test
jdbc:postgresql://dummy_hostname/dummy_databasename?user=dummy_username&password=dummy_password%currentSchema=test
jdbc:oracle:thin:dummy_username/dummy_password@dummy_hostname:1521:dummy_databasename/currentSchema=test
For the third option the path to an existing clientConfig.xml file can be entered directly, 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 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.
Notice that with this option, all folders and files are placed in the same folder as the selected clientConfig.xml |
The Debug option allows for more advanced options, as can be seen from the pop-up window that will appear:
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).
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> |
For Citrix kind of installations, one can edit or create shortcuts in a different way. This is explained here.
If you want to share a Delft-FEWS application and you want to distrubute a 'ready-to-launch' (SA) package regardless the location on a computer, please follow the steps below. In this way, after unzipping the package, the user only have to double-click the *lnk file in the Region_Home and the application launches (so CreateShortcuts.exe can be avoided by the end user).
.bat
C:\fews\bin\windows\Delft-FEWS.exe -Dregion.home=d:\fews\FEWS_GW
C:\fews\bin\windows\Delft-FEWS.exe -Dregion.home=d:\fews\FEWS_GW runIfdTask=d:\temp\taskProperties.xml
C:\fews\bin\windows\Delft-FEWS.exe -Dregion.home=d:\fews\FEWS_GW runIfdTaskAutoSaveToServer=d:\temp\taskProperties.xml
.so
/fews/bin/linux/jre/bin/java -Dregion.home=/fews/FEWS_GW -Xmx100m -Djava.library.path=/fews/bin/linux -XX:ErrorFile=./jvm-error.txt -XX:-UsePerfData -cp "/fews/bin/*" Delft.FEWS runIfdTask=/temp/taskProperties.xml