WorldServer - Configuring .properties files starting from version 11

Starting from WorldServer 11.x there are now 6 directories containing properties files such as tm.properties, general.properties, exchange.properties and more:

•    ..tomcat/webapps/ws/ …
•    ..tomcat/webapps/ws-legacy/ …
•    ..tomcat/webapps/ws-api/ …
•    c:/ws_config/ws/
•    c:/ws_config/ws-legacy/
•    c:/ws_config/ws-api/

Where should I place my properties file and what should I keep in mind when changing some properties configurations?

This is a diagram describing precedence and granularity of the configuration/properties files:



The WS_CONFIG folder is now the default folder where you should place your configuration files with your updated changes.

The directory of the WS_CONFIG folder might vary from the default " c:/ws_config" in your environment. If you are not sure where your WS_CONFIG folder and the subfolders are located, check the WS_CONFIG environment variable by opening a command prompt (cmd) and run

echo %WS_CONFIG%

or from the UI: Start->Right-click on Computer->Properties->Advanced system settings->Environment Variables-> System variables->WS_CONFIG​

Once you know its location, as mentioned above you will find that in the WS_CONFIG folder there are a ws-legacy, ws-api and a ws subfolders.

Do not ever modify the config files from the "tomcat/webapps​" folder anymore (this directory was relevant before Worldserver version 11). Configuration files under the tomcat directory will be overriden by an upgrade. In WorldServer 11.x, the config system works on the more specific, higher priority principle. Configure your properties file (for instance tm.properties) in

WS_CONFIG/tm.properties

so all 3 subfolders ws, ws-legacy and ws-api will inherit the same configuration. Summarizing:

WorldServer 11 has several places it will look for config files

1- The first place that WorldServer will try to find configuration information is in the registry. If you do not rename the entries there then any related config locations will be ignored in the config files
2- It will then check to see if there is a system environment variable called WS_CONFIG
3- If it finds one it will first look in the WS_CONFIG\ws-legacy, the WS_CONFIG\ws, and the WS_CONFIG\ws-api folders
4- It will then look directly in the WS_CONFIG folder
5- The last place it looks is in the tomcat\webapps\ws-legacy, the tomcat\webapps\ws and the tomcat\webapps\ws-api folders 

You can put all the properties files that you've been able to configure in all these 6 locations. HOWEVER: be aware that properties file under the tomcat/webapp folder will be overriden by upgrades so you might lose your changes there.  A well documented best practive is to place in the WS_CONFIG structure only the values that are changed for your environment.

For example, if you just want to change a specific properties in the tm.properties file and you want to apply it to all the WS components (ws_legacy, ws_api and ws) such as the tm_score_reverse_leverage_penalty property to be different than the default setting, you should have a tm.properties in WS_CONFIG that contains only a single line reflecting that change, for example:

tm_score_reverse_leverage_penalty=0.02

If more specific settings need to be set in the tm.properties file, more lines should be added to it under WS_CONFIG. WorldServer 11  knows to take this configuration from WS_CONFIG and the rest from the tomcat/webapp folder. In this fashion, you'll use the defaults from the provided configuration file and if they change, your system will be up to date.

If you need specific settings per component, you should add your properties files containing only those settings/keys that are specific for - as an example - ws-legacy but not for ws-api in the ws-legacy folder.

Basically the default settings should be stored in the webapps folder and any specific settings that are common to all components (legacy, api and partially ws) should be stored under WS_CONFIG. More granular setting for a specific component like for instance for  ws-legacy should be placed under that folder only.

This is also the recommended approach in case SDL changes the default general.properties or tm.properties or other properties files in future WorldServer versions adding or removing properties to the default. If your Worldserver uses a modified default properties file from your current version with all the changes in it, if a new default properties file is released as a Hotfix or as part of an upgraded version, you might need to merge your changes into the new default properties file(s) - which can be sensitive to errors.
Having your separate settings in a clean properties file under WS_CONFIG or if needed under one of the component subfolders under WS_CONFIG will eliminate the risks associated with this scenario.