Install Java-based censhare clients

Typical installation procedures for the Java-based censhare Client and Admin Client. For Service Client installation, see Install and configure censhare Service Client.

Target groups

System administrators
Users (on self-managed workstations)

Prerequisites

Version parity

When Keycloak is used as an identity provider, you can only connect with the censhare Java-based clients 2023.x to the censhare Server of the same version. Older clients may not work with the newer server versions.

Exceptions:

Keycloak with censhare standard authentication
Clients and server within the same minor update, but different patch updates may work together. However, such combinations are not recommended.

censhare ID

You need a censhare ID to download censhare software.

Virtual file system (VFS)

You use the Java-based censhare Client with a virtual file system (VFS). censhare-Client installers always include the VFS. Your hosts.xml settings determine whether the VFS is activated. Since the standard censhare-Client installation uses VFS, unless otherwise specified in the settings, the VFS is activated. For more information, see Virtual File System (VFS).

The Admin-Client does not use a VFS.

Download censhare software

The censhare Product Portal is the central location for all censhare-related information. Downloads for censhare clients are available from the Download Portal of the censhare Product Portal.

Individual download files are available for each client version and operating system. All censhare clients are available for macOS and Windows 64-bit.

Steps

Go to the censhare Product Portal.
Click the menu and select Download Portal.
You are prompted to log in with your censhare ID. If you have not registered yet, you are asked to do so. Please register and proceed.
The Download Portal opens
To locate the required download, use the filter options to search. You can combine multiple filters:
- Client Software: Filters for a specific type of censhare client, installer, or Java version.
- Operation system: Filters for censhare clients that run on macOS or Windows 64.
- Software version: Filters for specific censhare-client releases.
- File Format: Filters for downloads of a specific file type.
From the list of search results, click
of the desired censhare software.
The Downloads dialog opens.
In the Downloads dialog, click Master (size of download) to begin the download.
Unpack and install

There are two basic types of installations: client software with an installer and client software without an installer. In general, we recommend that you use the installers. The censhare Admin-Client and Service Client do not include an installer for Windows. The installer automatically de-installs the older version of the VFS/CBFS and installs the current version. To use different client and VFS/CBFS versions in parallel, re-install CBFS versions as needed. censhare provides separate installer packages for each CBFS version.

Windows 11 installer | Known issue

Windows installer known issue

On Windows, the installer may fail and require some workaround. The reason is that the installer fails to validate the certificate associated with the VFS driver. You will see the following error message:

What to do

The first thing to try is to cancel the installation and start it again.
If the installation fails again, you need to install the certificate manually.

Manual VFS driver certificate installation

download the attached public certificate
double-click on it
click Install certificate

select Local machine

select the correct place for the certificate, which is Trusted Root Certification Authorities
- browse your certificate stores

- select Trusted Root Certification Authorities and proceed with saving the certificate

after the successful import of the certificate, try the installation again

The installer will be able to proceed successfully.

Prepare local folder

The local folder provides temporary storage for files that are currently checked out. All versions of the Java-based censhare Client require a local folder.

If a local folder is not present from a previous installation of a censhare client, you must create the folder in the operating system (Explorer/Finder) of the destination computer. The censhare client creates a sub-directory in this local folder automatically. To name the sub-directory, the censhare client uses the server name or database name that is defined in your hosts.xml file.

Some special characters are automatically replaced with an underscore in the sub-directory name.

Place the local folder in the home directory of the user. Since the user does not need to access or view the local folder, the folder can be located deep within the home-directory hierarchy. The local folder can be named as desired.

When no local folder is assigned, the user must select a local folder the first time that the censhare Client requires storage. A dialog in which the user must select a local folder opens automatically. This dialog is untitled and can cause confusion on the part of the end-user. The location that the user selects as the local folder is where the censhare Client creates a sub-directory. To ensure a good user experience, always create and define the local folder during the installation process.

You can assign the local folder manually or with the censhare Server.

To ensure the best possible performance, place the local folder on a network device that has the adequate speed for your intended use case.

The user must have sufficient permissions to access the location of the local folder on the system. If you use an administrative account for the installation procedure, verify that the user can write to the local folder.

Assign local folder (manually)

The first time the censhare Client launches, a dialog to enter general settings opens. Define the name and location of the local folder in this dialog. The censhare Client stores the location of the folder in the preferences file of the censhare Client.

To define the location of the local folder manually, launch the censhare Client application.
In the File menu, select Preferences| General.
A dialog to enter general settings opens.
In the Assets area of the dialog, define a folder location in the Local folder field.
Click Select to browse locations on the local computer or enter a path manually. For example, on macOS: Macintosh HD/Users/<USERNAME>/censhare-local-folder. For example, on Windows: C:\Users\<USERNAME>\censhare-local-folder .
To save your changes, click OK.

Assign local folder (with the censhare server)

To define the location of the local folder with the censhare server, open the censhare Admin-Client.
Navigate to Configuration | Modules | Clients | Client | and open the desired Client preferences.
A [New] Client Preferences dialog opens.
In the [New] Client Preferences dialog, select Edit XML-File.
The Client Preferences XML file opens.
In the Preferences XML file, locate the asset tag.
In the asset tag, add a create-local-folder="true" attribute and a local-folder="file:///${user.home}/censhare-local-folder/" attribute.

Standard-server settings override any manual settings that are present.

Define connection parameters

The first installation of a censhare client requires communication parameters to access the application server. Define the communication parameters in a hosts.xml file. Install the hosts file in the correct location before the initial launch of the censhare Client.

If you install a censhare client on multiple computers, distribute the hosts.xml to the required computers to ensure consistency. Do not set communication parameters individually on each computer. For more information, see The hosts.xml file and Client Preferences (partner login required).

When the censhare client cannot locate a valid hosts.xml file, a file browser will be opened, and you will need to select the hosts.xml manually.