Local client preferences

The censhare clients need a couple of folders and files at different locations of the local filesystem to work properly, chiefly for the purpose of storing preferences or temporary files. While most of these files and folders will be created automatically by the client, some of this storage locations should be known to the system administrator as they allow for simplified installation processes and troubleshooting.

About the local preferences folder

A censhare preferences folder is created automatically upon the first application launch to store a couple of client-related preferences. In Windows environments this folder is created directly in the home directory of the user, under Mac OSX it is created in ~/Library/Preferences/. The censhare preferences folder contains the hosts.xml file with information about file storage locations and network parameters of the application server, as well as a main-release specific subfolder (currently called v4), which serves as a starting point for host- and user-specific preferences files.

Within the version-specific subfolder, there is a file called client.properties which contains a localized list of system messages. This file is generated upon each login and should not be edited.

The version-specific subfolder also contains another directory called hosts. This folder serves for application-server-specific preferences files. The client automatically creates one subfolder for each host that is accessed, where the name of the subfolder defaults to the hostname as defined in the hosts.xml file, but can be overwritten with a custom name as well to combine local data that belongs to the same censhare database, but might be accessed from multiple application servers. The host-specific subfolder contains a folder called filecache which provides a temporary storage for thumbnails, custom icons and the like. The filecache directory is completely maintained and purged by the system, but a maximum size for this directory can be specified in the general settings dialog of the client application.
Besides the filecache folder, the hosts folder also contains a set of XML-files with customization options for every client that has been started on the computer so far. Typically every application would create three files: <APPNAME>-app-def.xml, <APPNAME>-dialogs.xlm and <APPNAME>-preferences.xml file. The app-def and dialogs files are overwritten by the server upon each login and must not be touched. The preferences file, though, is copied from the server upon the first application launch after installation and then enriched with local preferences during the use of the client. This file contains parameters from the settings dialogs of the censhare client, hidden preferences that were defined on the server and information like sizes and positions of recently opened windows and the like. The preferences file is treated in a very special way, as hidden server parameters and local preferences are continually merged. This file can be used to distribute common preferences among all client computers.

A compact summary of the preferences folder hierarchy would look like this:

- censhare
-- hosts.xml
-- version
--- client.properties
--- hosts
---- <HOSTNAME>
------ <APPLICATION>-app-def-<USER>.xml
------ <APPLICATION>-dialogs-<USER>.xml
------ <APPLICATION>-preferences-<USER>.xml
------ filecache
------- <internal folder structure for cached components>

The default location and subfolder structure of the censhare preferences folder might slightly deviate in older versions of censhare.

Assign the local folder via the censhare Server

Add the local folder within the server-side (role-based) client preferences as follows:

1. In the censhare Admin Client, go to Configuration / Modules / Clients / Client / Client Preferences.
2. Set <asset create-local-folder="true"
3. Set local-folder="file:///${user.home}/censhare-local-folder/"
4. Update the Server configuration. 

If you encounter the message "unresolved properties [user.home]", you can ignore it.

Differences between Windows and macOS

As there is only one global variable user.home, we do not recommend to have different settings for Windows and macOS. The only possible way would be platform-based censhare roles, but this is not recommended.

Select a local folder

If you do not set the server-side option create-local-folder="true", users are asked to select the local folder.

This is to ensure that the server-side settings are only used if the local user has not yet selected a local folder. It helps to avoid that already checked out files ends up as orphans.