Manual for OpenEstate-ImmoTool

OpenEstate.org

2019-04-07

1 About this manual

1.1 Acknowledgement

We like to thank all participants in the OpenEstate project and alle Open Source developers. Without your support this project would not have been possible.

1.2 This manual is free of charge

This user manual was created as a part of the OpenEstate project. Its contents (texts and images) are freely available for personal use. A commercial distribution requires a written permission by the authors (see “License for the user manual”). Any third party modifications to this manual also have to published under the same license conditions.

Notice

The raw contents of this manual and the scripts used for exporting into different formats (HTML, PDF, ePub, etc.) are published at GitHub. You may use this platform to provide and discuss changes to this manual.

1.3 This manual is incomplete

This user manual documents OpenEstate-ImmoTool and OpenEstate-ImmoServer in its current state of development. Both applications are actively developed. Therefore this manual might not always be up to date. But we are trying our best to add and updates its contents as soon as possible.

1.4 Contributions are welcome

Users and developers are cordially invited to help us with the completion of this manual. Feel free to send us your comments or suggestions for improvements via GitHub or ticket system.

2 Introduction

2.1 About the OpenEstate project…

2.1.1 What is OpenEstate?

The OpenEstate project was initiated by Walter Wagner & Andreas Rudolph with the goal in mind to provide open software solutions for the real estate industry. You can find further information on its website OpenEstate.org.

2.1.2 What is OpenEstate-ImmoTool?

OpenEstate-ImmoTool (henceforth referred to as “ImmoTool”) is a free software for real estate management targeted at small and medium sized real estate companies.

The software is published under the terms of a Freeware license (see “License for OpenEstate-ImmoTool”). This means basically:

2.1.3 What is OpenEstate-ImmoServer?

OpenEstate-ImmoServer (henceforth referred to as “ImmoTool-Server”) provides a HSQL database. This application allows users to work from multiple workspaces on the same database.

The software is published under the terms of an Open Source license (see “License for OpenEstate-ImmoServer”). This means basically:

Notice

The source code of ImmoTool-Server is published at GitHub.

2.2 System requirements

ImmoTool and ImmoTool-Server may be used on all kinds of operating systems as long as they are fairly up to date and Java / OpenJDK is available for it in the required version.

2.2.1 Requirements of ImmoTool

Notice

There are no installation packages available for Linux systems on other architectures than x86 and x86-64. But you may still be able to run ImmoTool, if the Linux distribution provides an OpenJDK 11 package for the architecture being used (see “Using Java from the Linux package system”).

2.2.2 Requirements of ImmoTool-Server

Notice

There are no installation packages available for Linux systems on other architectures than x86 and x86-64. But you may still be able to run ImmoTool-Server, if the Linux distribution provides an OpenJDK 8 package (or newer) for the architecture being used (see “Using Java from the Linux package system”).

2.3 Download the applications

2.3.1 Obtain packages from the website

ImmoTool and ImmoTool-Server are available for download at the OpenEstate website in different packages. Older versions of the applications are also available here.

The following packages are provided for both applications:

2.3.2 Obtain packages from the Debian repository

As an alternative for a direct download from the website we provide a Debian repository, that may be used for all Debian based Linux distributions (e.g. Debian, Ubuntu or Linux Mint). Using the repository results in a better integration into the package management of the operating system and allows easier installation / updates.

Follow these steps in order to integrate the Debian repository into your operating system:

  1. Import the PGP key via:

  2. Register the repository via:

    Or alternatively add the following line to the end of the file /etc/apt/sources.list:

    deb https://debian.openestate.org/ openestate main
  3. Update the package index via:

  4. Afterwards you can install ImmoTool via:

    Or you can install ImmoTool-Server via:

Notice

In case you receive an error message on step 3, you may also need to install the package “apt-transport-https” with the following command:

sudo apt install apt-transport-https

2.4 How ImmoTool can be installed…

You may use ImmoTool in two different ways. Before installing the application you should decide for one of these usage scenarios.

Tip

If you want to make yourself familiar with the application, it is recommended to start with a single-user installation. Later you may switch to multi-user installation (see “Convert single-user into multi-user installation”).

2.4.1 Installing on a single workplace

Using the application on a single workplace (so called single-user installation) is the most straightforward installation method. In this case only the ImmoTool has to be installed. The ImmoTool-Server is not required for this type of installation.

On the first startup of the application a database is created automatically on the local hard drive, that gathers all processed data.

2.4.1.1 Advantages of single-user installations

2.4.1.2 Disadvantages of single-user installations

2.4.1.3 Steps for single-user installations

The following steps are required in order to start with a single-user installation:

  1. Download ImmoTool.
  2. Install ImmoTool.
  3. Start ImmoTool.
  4. Create a local project on first application startup.

2.4.2 Installing on a multiple workplaces

If multiple employees should be able to work on the same database from their workplace, a so called multi-user installation is required. In this case the shared database has to be provided by an external application (ImmoTool-Server).

The following image illustrates the setup schematically:

client-server model
client-server model

The ImmoTool-Server is placed in the center of the image. The employees workplaces are arranged in a circle around the ImmoTool-Server.

2.4.2.1 Advantages of multi-user installations

2.4.2.2 Disadvantages of multi-user installations

2.4.2.3 Steps for multi-user installations

A multi-user installation requires multiple steps, that need to be done on multiple computers / workplaces.

The ImmoTool-Server needs to be installed at first on one computer in the company network:

  1. Download ImmoTool & ImmoTool-Server.
  2. Install ImmoTool to the server computer.
  3. Install ImmoTool-Server to the server computer.
  4. Start ImmoTool-Server.
  5. Start AdminTool (provided with the ImmoTool installation) and create a database on the ImmoTool-Server.
  6. Start ImmoTool and create a remote project.

Notice

The ImmoTool installation on the server computer may be removed after the initial setup was finished successfully. But in case of problems it might be helpful in the future to have an ImmoTool / AdminTool on the same system as the ImmoTool-Server.

After the basic setup of ImmoTool-Server was completed you may consider setting up further features (e.g. encryption, automatic backups or installing a service).

In the next step you have to install ImmoTool on each workplace:

  1. Download ImmoTool.
  2. Install ImmoTool.
  3. Start ImmoTool.
  4. Create a remote project on first application startup.

2.5 Installing ImmoTool

2.5.1 Install the application

Download the ImmoTool installation package for your operating system (see “Download the applications”).

2.5.1.1 Installation on Windows

On Windows systems you should download the EXE installation file. On a 64bit Windows system you should use the corresponding 64bit installer.

Start the downloaded EXE installer with a double click. Afterwards an installation program shows up, that will guide you through the installation process.

Installing ImmoTool on Windows
Installing ImmoTool on Windows

2.5.1.2 Installation on macOS

On macOS systems you should download the DMG installation file. Start the downloaded file with a double click in order to show the following installation dialog:

Installing ImmoTool on macOS
Installing ImmoTool on macOS

Click with your mouse on the application symbol of “OpenEstate-ImmoTool” and drag it into the “Applications” folder. This will copy the application into your Applications folder. In future you can find the application in your Finder by opening the Applications folder.

Alternatively you can drop the application symbol somewhere else - e.g. on your desktop or any other location on your hard drive.

2.5.1.3 Installation on Debian, Ubuntu or similar

For Debian based Linux distributions (e.g. Debian, Ubuntu or Linux Mint) there are different Debian packages it is recommended to use the Debian repository (see “Obtain packages from the Debian repository”). After the repository was registered in the operating system you may install the Debian package with the following commands:

  1. Update the package index via:

  2. Install ImmoTool:

In case you do not like or want to use the repository, you may alternatively download the Debian package (resp. the DEB installation file). Install the package with a double click or via the following command:

sudo dpkg -i openestate-immotool_x.y.z_amd64.deb

(Replace x.y.z with the version number of the downloaded file.)

Notice

The Debian package installs the application into the /opt/OpenEstate-ImmoTool directory.

Notice

The Debian package automatically adds start menu entries of the application for each user in the operating system.

2.5.1.4 Installation on Linux

If you do not use a Debian based Linux distribution or do not want to use the repository, you may alternatively download the TAR.GZ installation file. Make sure to select the correct installation file for your processor architecture (most commonly used is x86-64).

After the file was extracted on your computer you should find a directory called OpenEstate-ImmoTool. Move this directory to your preferred location on your hard drive (e.g. into the home directory or to /opt/OpenEstate-ImmoTool).

Tip

You may execute the StartMenuAdd.sh script within the bin folder of the application. This will create the start menu entries of the application for the current user.

2.5.2 Starting ImmoTool

2.5.2.1 Start ImmoTool on Windows

The Windows installer will automatically create a desktop shortcut for the application. Alternatively you can find a folder called “OpenEstate-ImmoTool” in the start menu, that contains the shortcuts of the application.

Besides this you may start the application by executing the ImmoTool.exe (or ImmoTool.bat) file in the bin subfolder of the application directory.

2.5.2.2 Start ImmoTool on macOS

Open the application bundle called “OpenEstate-ImmoTool” with a double click. This will open a Finder window with the applications provided by ImmoTool.

Finder window with ImmoTool applications
Finder window with ImmoTool applications

To-Do

Provide an English screenshot.

A double click on the “ImmoTool” application will start the application.

Tip

You may integrate the “ImmoTool” application symbol into the Dock for future application starts (see documentation by Apple).

2.5.2.3 Start ImmoTool on Linux

If ImmoTool was installed with the Debian package, you will find an entry called “OpenEstate-ImmoTool” in your start menu.

If ImmoTool was installed with the TAR.GZ package, you may have to start the StartMenuAdd.sh script in the bin subfolder of the application directory in order to create the start menu entry for ImmoTool.

Alternatively you may start the application by executing the ImmoTool.sh script in the bin subfolder of the application directory.

2.5.3 Language selection

If ImmoTool is started for the first time and the language of your operating system is not available in the application, you will have to select your preferred language.

Language selection on first application start
Language selection on first application start

This window provide a selection of languages, that the application was translated into.

Notice

ImmoTool may be translated into every language. If you like to help us out with a translation (z.B. new language or fixes in current translations), you can find further information on the OpenEstate website.

2.5.4 Create local project

If ImmoTool is started for the first time, the project wizards shows up. You will have to create a local project, that provides the database for the application.

Notice

Within ImmoTool a project is a synonym for a database, that contains all gathered data (real estates, customers, attachments, etc.). In most cases you will only need one project, that has to be created once on the first application start. On later startups this project is opened automatically.

Warning

In case you are planning to install a multi-user installation (see “Installing on a multiple workplaces”), please follow the advices in chapter “Installing ImmoTool-Server”. In this case it is not necessary to create a local project.

Create local project on first application start
Create local project on first application start

Enter the following options into the project wizard in order to create a local project:

After the license agreement was accepted you can create the project by clicking on the button “Create project”". The newly created project is automatically opened afterwards.

From now on you can work with the application. We wish you a lot of fun and success!

2.6 Installing ImmoTool-Server

The ImmoTool-Server is required, if multiple employees need to work on the same database from their workplace (see “Installing on a multiple workplaces”).

Notice

If you do not want to use ImmoTool in a network with multiple employees, you do not need to install ImmoTool-Server. Instead you can install ImmoTool as a single-user installation (see “Installing on a single workplace”).

2.6.1 Install the application

Download the ImmoTool-Server installation package for your operating system (see “Download the applications”).

2.6.1.1 Installation on Windows

On Windows systems you should download the EXE installation file. On a 64bit Windows system you should use the corresponding 64bit installer.

Start the downloaded EXE installer with a double click. Afterwards an installation program shows up, that will guide you through the installation process.

Installing ImmoTool-Server on Windows
Installing ImmoTool-Server on Windows

2.6.1.2 Installation on macOS

On macOS systems you should download the DMG installation file. Start the downloaded file with a double click in order to show the following installation dialog:

Installing ImmoTool-Server on macOS
Installing ImmoTool-Server on macOS

Click with your mouse on the application symbol of “OpenEstate-ImmoServer” and drag it into the “Applications” folder. This will copy the application into your Applications folder. In future you can find the application in your Finder by opening the Applications folder.

Alternatively you can drop the application symbol somewhere else - e.g. on your desktop or any other location on your hard drive.

2.6.1.3 Installation on Debian, Ubuntu or similar

For Debian based Linux distributions (e.g. Debian, Ubuntu or Linux Mint) there are different Debian packages it is recommended to use the Debian repository (see “Obtain packages from the Debian repository”). After the repository was registered in the operating system you may install the Debian package with the following commands:

  1. Update the package index via:

  2. Install ImmoTool-Server:

In case you do not like or want to use the repository, you may alternatively download the Debian package (resp. the DEB installation file). Install the package with a double click or via the following command:

sudo dpkg -i openestate-immoserver_x.y.z_amd64.deb

(Replace x.y.z with the version number of the downloaded file.)

Notice

The Debian package installs the application into the /opt/OpenEstate-ImmoServer directory.

Notice

The Debian package automatically installs a service in the operating system. The ImmoTool-Server will start automatically as soon as the computer is booted (see “Setup a service for ImmoTool-Server”).

Also the Debian package automatically installs a timer for daily backups. In order to make backups work properly, you have to set some configurations (see “Backup a running ImmoTool-Server”).

2.6.1.4 Installation on Linux

If you do not use a Debian based Linux distribution or do not want to use the repository, you may alternatively download the TAR.GZ installation file. Make sure to select the correct installation file for your processor architecture (most commonly used is x86-64).

After the file was extracted on your computer you should find a directory called OpenEstate-ImmoServer. Move this directory to your preferred location on your hard drive (e.g. into the home directory or to /opt/OpenEstate-ImmoServer).

2.6.2 Starting ImmoTool-Server

For the first installation it is recommended to start ImmoTool-Server manually.

If the application was properly configured an all workplaces can successfully connect to the ImmoTool-Server, you should consider installing a service for ImmoTool-Server. This allows the application to start automatically while the computer is booting (see “Setup a service for ImmoTool-Server”).

Notice

In order to make ImmoTool-Server available over the network you might have to open port 9001 in the firewall for incoming connections.

2.6.2.1 Start ImmoTool-Server on Windows

The Windows installer created a folder called “OpenEstate-ImmoServer” in the start menu, that contains the shortcuts of the application. Click on the shortcut “Start ImmoServer manually” in the start menu in order to start ImmoTool-Server in foreground.

Besides this you may start the application manually by executing the Start.exe (or Start.bat) file in the bin subfolder of the application directory.

2.6.2.2 Start ImmoTool-Server on macOS

Open the application bundle called “OpenEstate-ImmoServer” with a double click. This will open a Finder window with the applications provided by ImmoTool-Server.

Finder window with ImmoTool-Server applications
Finder window with ImmoTool-Server applications

To-Do

Provide an English screenshot.

A double click on the “Start” application will start ImmoTool-Server manually.

2.6.2.3 Start ImmoTool-Server on Linux

If ImmoTool-Server was installed with the Debian package, there is already a service available and ImmoTool-Server was already started. In this case you do not have to do any further steps.

On all Linux systems you can start ImmoTool-Server manually by executing the Start.sh script in the bin subfolder of the application directory.

2.6.3 Prepare ImmoTool-Server

Before employees can access ImmoTool-Server with ImmoTool you have to install a database. Start AdminTool in order to perform the necessary preparations. This application is installed together with the ImmoTool application.

Install ImmoTool on the server computer or any other machine in your network (see “Installing ImmoTool”) and start the AdminTool application (see “AdminTool starten”).

Connect to ImmoTool-Server with AdminTool
Connect to ImmoTool-Server with AdminTool

Select the option “Connect to remote database (stored on a server)” in the connection dialog. Afterwards you need to enter the connection settings for ImmoTool-Server:

Click on the button “Connect” in order to open a first connection from AdminTool to the ImmoTool-Server.

In the first step the application will detect, that no password was set for the database administrator (“SA”). It will ask you for a password. Please take a note of your selected password!

Enter an administration password in AdminTool
Enter an administration password in AdminTool

Afterwards the application will detect, that the database is not installed yet on the ImmoTool-Server. You may disable certain addons. After clicking the button “Submit” the application will initialize the database.

Install database on ImmoTool-Server
Install database on ImmoTool-Server

After these steps have been finished you may add further user accounts in the database (see “Manage user accounts”).

After you have finished the configuration you may close AdminTool. From now on employees may access the database via ImmoTool.

2.6.4 Connect to ImmoTool-Server

After the ImmoTool-Server was successfully prepared (see “Prepare ImmoTool-Server”) you may access the database via ImmoTool.

Install ImmoTool on each workplace (see “Installing ImmoTool”). After ImmoTool was started for the first time (see “Starting ImmoTool”) you have to create a remote project. Open the project wizard (if it does not start automatically click on “Main Menu → Project → new project”).

Create a remote project in project wizard
Create a remote project in project wizard

Enter the following settings into the project wizard in order to create a remote project:

Before the project is created, you have to verify the connection settings by clicking the “Login” button. If no errors were detected, you can create the project by clicking the “Create project” button. The remote project will be created and automatically opened afterwards.

On future application startups you can open the previously created remote project. The user has to enter his login name and password before database access is granted.

Login to a remote project
Login to a remote project

2.7 Installing Java

ImmoTool and ImmoTool-Server have been written in the Java programming language. In order to use the software a Java runtime environment (so called JRE) is required.

Notice

The provided installation packages of ImmoTool and ImmoTool-Server already contain the required Java runtime environment. In most cases it is not necessary to install Java separately.

There are only a few reasons not to use the Java version provided in the installation packages. It might be required, if a Linux system is used, for which no official installation package is available. For these rare cases the documentation below describes the steps to use a custom Java runtime environment.

Warning

Please consider, that OpenEstate can only give limited support for custom / external Java installations. We are trying to maintain compatibility to our best knowledge and belief. But we can not fully rule out possible errors or problems regarding custom Java installations.

By default each application contains a folder called jre, that contains the provided Java runtime environment. This folder may be replaced with a custom Java installation.

2.7.1 Using Java from a third-party supplier

Many third-party suppliers are providing Java or OpenJDK packages (e.g. AdoptOpenJDK, Azul Systems, BellSoft, JetBrains, Red Hat, SAP or Oracle). You may use their packages by following these steps:

2.7.2 Using Java from the Linux package system

Most Linux distributions also provide Java / OpenJDK through their package system. You may use their packages by following these steps:

If the jre folder is not present in the application directory, the application will automatically try to use the installed OpenJDK package on startup.

3 General usage notes

Sorry but the usage section of this manual is currently not available in English language. We are working on its completion. But it may take some time due to a lot of other work, that needs to be done. In case of questions about using the application feel free to contact the developers via ticket system.

Notice

If you like, you may help us out with the translation from German into English. Any kind of help is highly appreciated. Just get in contact with us or open a ticket.

4 Administrate ImmoTool

4.1 Starting ImmoTool

4.1.1 Start ImmoTool on Windows

The Windows installer will automatically create a desktop shortcut for the application. Alternatively you can find a folder called “OpenEstate-ImmoTool” in the start menu, that contains the shortcuts of the application.

Besides this you may start the application by executing the ImmoTool.exe (or ImmoTool.bat) file in the bin subfolder of the application directory.

4.1.2 Start ImmoTool on macOS

Open the application bundle called “OpenEstate-ImmoTool” with a double click. This will open a Finder window with the applications provided by ImmoTool.

Finder window with ImmoTool applications
Finder window with ImmoTool applications

To-Do

Provide an English screenshot.

A double click on the “ImmoTool” application will start the application.

Tip

You may integrate the “ImmoTool” application symbol into the Dock for future application starts (see documentation by Apple).

Besides this you may start the application by executing the ImmoTool.sh file in the bin subfolder of the application directory.

4.1.3 Start ImmoTool on Linux

If ImmoTool was installed with the Debian package, you will find an entry called “OpenEstate-ImmoTool” in your start menu.

If ImmoTool was installed with the TAR.GZ package, you may have to start the StartMenuAdd.sh script in the bin subfolder of the application directory in order to create the start menu entry for ImmoTool.

Alternatively you may start the application by executing the ImmoTool.sh script in the bin subfolder of the application directory.

4.1.4 Start parameters of ImmoTool

You may customize the application startup via ImmoTool.exe / ImmoTool.bat / ImmoTool.sh with the following parameters:

To-Do

Add link to the project wizard in the usage section.

4.2 Directories of ImmoTool

ImmoTool operates on different directories on the hard drive.

4.2.1 Application directory of ImmoTool

The application directory contains the installed files necessary to run ImmoTool.

The application directory contains a bin subfolder with several scripts and applications for ImmoTool.

ImmoTool does not write any files / data into to the application directory. It only reads from this directory.

Tip

It is recommended to make sure, that regular users of the operating system only have read access to the application directory. Administrators might set appropriate permissions to this directory in order to avoid accidental modifications.

4.2.2 Data directory of ImmoTool

If a user starts ImmoTool for the first time, the program will automatically create a folder called OpenEstate-Files in his home directory. This folder contains data and settings for ImmoTool exclusively for this user.

This folder is used by ImmoTool to write certain data during its runtime (e.g. protocols or temporary files).

4.2.3 Project directory of ImmoTool

If a project is created within ImmoTool, the user can choose the location of the project directory for himself. By default the application stores the project directory into the projects subfolder of the data directory.

Notice

Each project created with ImmoTool is stored in its own / separate directory. This makes it easier to backup / move / replace a project by modifying the project folder.

Notice

It is theoretically possible, that multiple users share the same project directory (e.g. by using a shared folder). But local projects (resp. single-user-installations) can never be opened by multiple users at the same time.

Warning

You should not open a project directory from an unstable location (e.g. network drive or cloud drive). Network failures may corrupt the database. If you want to go this path nevertheless, keep in mind to backup the project as often as possible.

4.2.4 Plugin directory of ImmoTool

The plugin directory contains the extensions (addons) as ZIP files loaded by ImmoTool. There are two locations, where addons can be stored:

  1. In the application directory there is a plugins subfolder. The administrator of the operating system may place addons here, that are available for all users of the operating system.

  2. In the data directory of each user there is also a plugins subfolder. The user may place addons here, that are only available for himself.

While ImmoTool is starting both directories are synchronized. If both folders contain the same addon in different versions, the application will load the newer version.

Warning

On macOS the plugin directory inside the application directory (within the “OpenEstate-ImmoTool” application bundle) should not be modified. Otherwise the signature of the application bundle might get invalid and Gatekeeper might reject starting up the application. Therefore you should always place addons into the plugins subfolder of the data directory on macOS.

4.3 Updating ImmoTool

Once per day the application searches for available updates on startup. The following information is shown, in case that updates are available:

Information about available updates
Information about available updates

Click on “Download installation package.” in order to open the web browser and download the installation package for the currently used operating system.

Click on “Open download website.” in order to open the download page for the new application version.

Download the installation package for your operating system and start the installation process (see “Installing ImmoTool”). Thereby keep the following notices for your operating system in mind.

Warning

Always close the ImmoTool application before starting the update process.

Notice

If ImmoTool is installed on multiple workplaces (see “Installing on a multiple workplaces”), you should update the application on all workplaces. Different versions of ImmoTool might not work in a multi-user installation.

4.3.1 Update on Windows

The EXE installer automatically detects, where the application was installed beforehand and will update the files accordingly.

4.3.2 Update on macOS

Move the application symbol of “OpenEstate-ImmoTool” to the same location, where ImmoTool was installed beforehand. The operating system will show the following question:

Question about overwriting on macOS
Question about overwriting on macOS

To-Do

Provide an English screenshot.

Answer this question in the dialog window by clicking on “Replace”.

4.3.3 Update on Debian, Ubuntu or similar

If the Debian repository was configured in your operating system (see “Obtain packages from the Debian repository”), you do not have to download the updated version from the OpenEstate website. Instead you can execute the following commands:

sudo apt update
sudo apt install openestate-immotool

If you do not use the Debian repository but installed the program from the Debian package, you can download the DEB installation package. Install the downloaded package with a double click or via the following command:

sudo dpkg -i openestate-immotool_x.y.z_amd64.deb

(Replace x.y.z with the version number of the downloaded file.)

4.3.4 Update on Linux

  1. Find out the path, where ImmoTool was installed beforehand.
  2. Download the TAR.GZ installation package for your Linux system and extract the file on your computer.
  3. Rename the folder, you have determined in step 1 - e.g. OpenEstate-ImmoTool-OLD.
  4. Create a new / empty folder with the name, you have determined in step 1 - e.g. OpenEstate-ImmoTool.
  5. Copy the files, that were extracted in step 2 into the newly created / empty folder.

After you have been able to properly start the application in the updated version you might remove the temporary folder created in step 3.

4.3.5 Important advices for certain versions

This section contains advices about updates to certain application versions.

4.3.5.1 Update from version 1.0-beta to 1.x

ImmoTool 1.0.0 introduced some major changes, that should be considered during an update from version 1.0-beta.

4.3.5.1.1 New installation routine for Windows & macOS

A new installation routine was implemented for Windows and macOS systems (EXE and DMG installation packages). The new installation packages are not compatible with the old update procedure. Please make sure, that you do not overwrite the previous ImmoTool version while installing the update. Therefore we are recommending the following approach:

Future updates of ImmoTool 1.x do not require these steps and should work flawlessly.

4.3.5.1.2 Java can be removed

Since version 1.0.0 Java is bundled together with the ImmoTool application. Therefore you can remove Java from your operating system as long as you do not need it for other applications.

4.3.5.2 Update from version 0.9.x to 1.x

For a migration from ImmoTool 0.9.x to 1.x the same advices apply as for the migration from 1.0-beta to 1.x. But in this case the project is not migrated automatically. Therefore you also need to follow the instructions to migrate an old project into ImmoTool 1.x.

5 Administrate ImmoTool-Server

5.1 Starting ImmoTool-Server

The easiest way to start ImmoTool-Server is a manual startup in foreground.

If the application was properly configured an all workplaces can successfully connect to the ImmoTool-Server, you should consider installing a service for ImmoTool-Server. This allows the application to start automatically in background while the computer is booting (see “Setup a service for ImmoTool-Server”).

5.1.1 Start ImmoTool-Server on Windows

The Windows installer created a folder called “OpenEstate-ImmoTool” in the start menu, that contains the shortcuts of the application. Click on the shortcut “Start ImmoServer manually” in the start menu in order to start ImmoTool-Server in foreground.

Besides this you may start the application manually by executing the Start.exe (or Start.bat) file in the bin subfolder of the application directory.

If ImmoTool-Server was started for the first time, the operating system may ask to allow incoming connections for ImmoTool-Server. You should answer this question by clicking the “Allow access” button.

Grant access in the Windows firewall
Grant access in the Windows firewall

To-Do

Provide an English screenshot.

5.1.2 Start ImmoTool-Server on macOS

Open the application bundle called “OpenEstate-ImmoServer” with a double click. This will open a Finder window with the applications provided by ImmoTool-Server.

Finder window with ImmoTool-Server applications
Finder window with ImmoTool-Server applications

To-Do

Provide an English screenshot.

A double click on the “Start” application will start ImmoTool-Server manually.

If ImmoTool-Server was started for the first time, the operating system may ask to allow incoming connections for ImmoTool-Server. You should answer this question by clicking the “Allow” button.

Grant access in the macOS firewall
Grant access in the macOS firewall

To-Do

Provide an English screenshot.

5.1.3 Start ImmoTool-Server on Linux

If ImmoTool-Server was installed with the Debian package, there is already a service available and ImmoTool-Server was already started. In this case you do not have to do any further steps.

On all Linux systems you can start ImmoTool-Server manually by executing the Start.sh script in the bin subfolder of the application directory.

5.2 Directories of ImmoTool-Server

ImmoTool-Server operates on different directories on the hard drive.

5.2.1 Application directory of ImmoTool-Server

The application directory contains the installed files necessary to run ImmoTool-Server.

The application directory contains a bin subfolder with several scripts and applications for ImmoTool-Server.

ImmoTool-Server does not write any files / data into to the application directory. It only reads from this directory.

Tip

It is recommended to make sure, that regular users of the operating system only have read access to the application directory. Administrators might set appropriate permissions to this directory in order to avoid accidental modifications.

5.2.2 Data directory of ImmoTool-Server

All data, that is created and written by ImmoTool-Server, is stored in the data directory (e.g. databases, backups, log files).

5.2.3 Protocol directory of ImmoTool-Server

The protocol directory contains log files with messages created during the execution of ImmoTool-Server.

5.2.4 Configuration directory of ImmoTool-Server

ImmoTool-Server uses the configuration directory to load its configurations.

Notice

The chapter “Configure ImmoTool-Server” contains further information about how to configure ImmoTool-Server for your personal needs.

5.2.5 Configure directories of ImmoTool-Server

It is possible to change the location of the directories used by Immotool-Server.

Notice

The user of the operating system, who starts ImmoTool-Server, needs write permission on the protocol and data directory. For the configuration directory only read access is required.

5.2.5.1 Configure directories on Linux & macOS

On Linux and macOS systems you can create a file at /etc/default/OpenEstate-ImmoServer with the following contents:

# path to configuration directory
SERVER_ETC_DIR="/etc/OpenEstate-ImmoServer"

# path to protocol directory
SERVER_LOG_DIR="/var/log/OpenEstate-ImmoServer"

# path to data directory
SERVER_VAR_DIR="/var/lib/OpenEstate-ImmoServer"

Enter the desired path of the directories behind the variables and restart ImmoTool-Server afterwards.

5.2.5.2 Configure directories on Windows

On Windows it depends, how the individual applications provided by ImmoTool-Server are started.

5.3 Configure ImmoTool-Server

The configuration directory of ImmoTool-Server contains several files to customize the default behaviour of the application.

Notice

In most use cases the provided default configuration is sufficient. You should only change the configuration, if it is really necessary.

5.3.1 Configure databases

The configuration directory of ImmoTool-Server contains a file called server.properties. With this file the databases provided by ImmoTool-Server can be configured.

By default ImmoTool-Server provides exactly one database with the name “immotool”. When necessary you may provide more databases with ImmoTool-Server by editing the server.properties file. You can find further information about this configuration file in the HSQLDB documentation.

For example to register a second database called “immotool2” in ImmoTool-Server, you can follow these steps:

  1. Stop ImmoTool-Server, if it is currently running.

  2. Open the server.properties file with a text editor and add the following lines to the end of the file:

    This registers a second database called “immotool2”. Its data is stored in the data directory in the data/immotool2 subfolder.

  3. Save the modified server.properties file and restart ImmoTool-Server.

  4. Start AdminTool and create a connection to the newly created database (see “Prepare ImmoTool-Server”). Enter the database name “immotool2” in the connection dialog window in order to connect to the newly created database.

  5. After the database was prepared with AdminTool it can be accessed with ImmoTool (see “Connect to ImmoTool-Server”). Enter the database name “immotool2” in the project wizard (or login) window in order to connect to the newly created database.

In general ImmoTool-Server can provide an arbitrary number of databases in the server.properties file with freely choosable name. For each database you need to increment the counter - e.g.:

# database #0
server.database.0=file:${openestate.server.varDir}/data/immotool/db
server.dbname.0=immotool

# database #1
server.database.1=file:${openestate.server.varDir}/data/mydb/db
server.dbname.1=mydb

# database #2
server.database.2=file:${openestate.server.varDir}/data/anotherdb/db
server.dbname.2=anotherdb

Notice

The character string ${openestate.server.varDir} is automatically replaced with the configured path of the data directory.

5.3.2 Configure protocols

The configuration directory of ImmoTool-Server contains a file called logback.xml. With this file the logging behaviour of ImmoTool-Server can be configured.

By default the application stores its protocols into the protocol directory. In most cases it is not necessary to make any changes to this file. But you can find further information about customization in the documentation of Logback.

Notice

The character string ${openestate.server.logDir} in the logback.xml file is automatically replaced with the configured path of the protocol directory.

Notice

The character string ${openestate.server.app} in the logback.xml file is automatically replaced with the name of the executing application. This allows every application to use a separate log file.

5.3.3 Configure manager applications

ImmoTool-Server provides some helper applications to cover some administrative tasks (so called “manager applications”). These application are connecting themselves to the databases provided by the ImmoTool-Server in order to do their work (e.g. “Backup a running ImmoTool-Server”).

The manager applications need to open a connection to the provided database and login with administrative permissions. Therefore it is necessary to tell these application with which credentials to login. The required login credentials have to be placed in the manager.conf file within the configuration directory.

For each database, that is provided by ImmoTool-Server, you need to add the following lines into the manager.conf file:

urlid immotool
url jdbc:hsqldb:hsql://localhost:9001/immotool
username SA
password test1234

For the three example databases described in the “Configure databases” chapter, you would have to put the following lines into the manager.conf file:

urlid immotool
url jdbc:hsqldb:hsql://localhost:9001/immotool
username SA
password test1234

urlid mydb
url jdbc:hsqldb:hsql://localhost:9001/mydb
username SA
password test2345

urlid anotherdb
url jdbc:hsqldb:hsql://localhost:9001/anotherdb
username SA
password test3456

(Replace the password accordingly.)

You can find furter information about this configuration file in the HSQLDB documentation.

Warning

The manager.conf contains sensitive information. Only the users of the operating system, who are allowed to use the manager applications, should be able to read this file.

5.3.4 Configure SSL encryption

If ImmoTool-Server was installed outside of the local network or if connections from the internet are allowed, it is recommended to use encrypted communication between ImmoTool and ImmoTool-Server.

In other cases it also might make sense to use encryption because it improves security and integrity during data transfers. But keep in mind, that encryption will slow down the connection speed a bit and will increase the amount of computation time.

Notice

ImmoTool-Server does not allow to use encrypted and unencrypted at the same time. You need to decide which way you want to go and have to configure all ImmoTool installations in your network accordingly (see “Use SSL encryption in ImmoTool”).

5.3.4.1 Create SSL certificate

In order to provide SSL encryption you need to create a SSL certificate in the first step. The certificate ensures the trustworthiness of ImmoTool-Server towards the client applications.

ImmoTool-Server provides an application for easily creating a SSL certificate.

After the application was started a terminal window will show up with the following output:

Configure the SSL certificate
Configure the SSL certificate
  1. Enter the IP address (or hostname), that is used for connection to the ImmoTool-Server. The SSL certificate is created exactly for this address. All applications, that are connecting to ImmoTool-Server, will have to use the provided address.

  2. In the next step you have to enter a keystore password, that is used to protect the certificate from external modification. Note down the chosen password because it is needed afterwards.

After these settings were entered the application will create a ssl subfolder in the configuration directory. All created files are stored into this folder. The following summary is shown after the program finished its job:

Summary about the SSL certificate
Summary about the SSL certificate

Warning

The ssl subfolder in the configuration directory contains sensitive information. Only the users of the operating system, who are allowed to start ImmoTool-Server, should be able to read this file.

Notice

As an alternative to the application you can create the SSL certificate manually with the following commands:

keytool -genkey \
  -alias OpenEstate-ImmoServer \
  -keyalg RSA -validity 999 \
  -keystore keystore.jks \
  -storetype JKS

keytool -export \
  -alias OpenEstate-ImmoServer \
  -keystore keystore.jks \
  -rfc -file private.crt

The keytool application is located in the bin subfolder of the Java runtime environment.

The files created by the keytool applications have to be placed into the ssl subfolder of the configuration directory.

5.3.4.2 Enable SSL encryption

In the next step SSL encryption has to be enabled in the ImmoTool-Server. Edit the server.properties file in the configuration directory with a text editor. The following lines need to be changed:

# TLS/SSL (secure) sockets
server.tls=true
system.javax.net.ssl.keyStore=${openestate.server.etcDir}/ssl/keystore.jks
system.javax.net.ssl.keyStorePassword=test1234

Restart ImmoTool-Server in order to make the changes take effect.

Notice

The character string ${openestate.server.etcDir} is automatically replaced with the configured path of the configuration directory.

5.3.4.3 Use SSL encryption in ImmoTool

If a new remote project is created in ImmoTool, you need to select the protocol “hsqls” in the project wizard dialog.

To-Do

Add link to the project wizard in the usage section.

Enable SSL encryption in the project wizard
Enable SSL encryption in the project wizard

If an existing remote project is opened, you might also enable SSL encryption. Click on the “Modify server connection settings.” checkbox and select the protocol “hsqls”. This setting is stored permanently for the project and does not have to be set again.

Enable SSL encryption during login
Enable SSL encryption during login

5.3.4.4 Use SSL encryption in AdminTool

If a connection is established with AdminTool, you need to select the protocol “hsqls” in the connection dialog.

Enable SSL encryption in AdminTool
Enable SSL encryption in AdminTool

5.3.4.5 Use SSL encryption in manager applications

The manager application are configured with the manager.conf file in the configuration directory.

Modify this file with a text editor and update the value behind url for all configured databases.

The three example databases from the “Configure manager applications” chapter would have to be changed like this:

urlid immotool
url jdbc:hsqldb:hsqls://192.168.178.123:9001/immotool
username SA
password test1234

urlid mydb
url jdbc:hsqldb:hsqls://192.168.178.123:9001/mydb
username SA
password test2345

urlid anotherdb
url jdbc:hsqldb:hsqls://192.168.178.123:9001/anotherdb
username SA
password test3456

5.4 Setup a service for ImmoTool-Server

For the everyday operations it is useful to integrate ImmoTool-Server as a service into the operating system. This allows ImmoTool-Server to start automatically in background while the system is booting. The administrator can control the service from the outside (start / stop / restart).

5.4.1 Setup service on Windows

In order to install and control the service for ImmoTool-Server on Windows systems the Open Source software commons-daemon provided by the Apache Software Foundation is used. The applications in the bin\service subfolder of the application directory are provided by the “commons-daemon” project.

5.4.1.1 Install service on Windows

The service for ImmoTool-Server can be registered in the operating system in the following ways:

Because services can only be registered by an administrator the operating system might ask for administrative permissions.

After the service was successfully installed a dialog window will show up, which allows further configuration.

Manage the service on Windows
Manage the service on Windows

For example you might change the path of the application directories in the “Java” tab (see “Directories of ImmoTool-Server”):

Change directories in service management application
Change directories in service management application

After settings were changed click on the “Submit” button. You can close the dialog window afterwards or start the service in the “General” tab by clicking the “Start” button.

If ImmoTool-Server was started for the first time, the operating system may ask to allow incoming connections for ImmoTool-Server. You should answer this question by clicking the “Allow access” button.

Grant access in the Windows firewall
Grant access in the Windows firewall

5.4.1.2 Uninstall service on Windows

The service for ImmoTool-Server can be removed from the operating system in the following ways:

A command line window will show up, which removes the service from the operating system. You will see a success or error message in this window after the application was finished.

Notice

If ImmoTool-Server is regularly uninstalled, a previously registered service is automatically removed.

5.4.1.3 Manage service on Windows

ImmoTool-Server provides an application for management / configuration of the service. You may start the application in one of the following ways:

This application provided by the Apache Software Foundation allows modification of the service. Also the service can be started / stopped from this application.

Alternatively you might use the service management provided by the Windows operating system.

  1. Press the “Windows key” together with the letter “R” to open a window for command execution. Alternatively you can open the command prompt.

  2. Enter the command services.msc and press the “ENTER” key.

The service management window provided by the Windows operating system will show up:

Windows service management
Windows service management

You might start / stop the service in this window or edit certain settings with a double click.

To-Do

Provide an English screenshot.

5.4.1.4 Start service on Windows

After the service was installed (see “Install service on Windows”) you might start the service manually in of these ways:

To-Do

Figure out the correct naming in the Windows service dialog.

Notice

By default the service will start automatically while the Windows system is booting. Therefore in most cases it is not possible to start the service manually.

5.4.1.5 Stop service on Windows

After the service was installed (see “Install service on Windows”) you might stop the service manually in of these ways:

To-Do

Figure out the correct naming in the Windows service dialog.

5.4.2 Setup service on macOS

On macOS the service is controlled with the launchd application, which is part of the operating system. The service is registered by creating a file org.openestate.tool.server.service.plist in the /Library/LaunchDaemons directory.

Notice

You might modify the created service file by yourself in order to make individual adjustments (see tutorial for launchd). But in most cases this should not be necessary.

5.4.2.1 Install service on macOS

Open the application bundle “OpenEstate-ImmoServer” and start the “ServiceInstall” application. A terminal window will show up, which will guide you through the installation of the service.

Installing the service on macOS
Installing the service on macOS

The application requires administrative permissions. While the application is running you might get asked for an administrator password.

You can select the following options during the installation of the service:

The service file org.openestate.tool.server.service.plist is created in the directory /Library/LaunchDaemons after all questions have been answered.

Summary after the service was installed on macOS
Summary after the service was installed on macOS

Beim ersten Start des ImmoTool-Servers werden Sie vom Betriebssystem eventuell gefragt, ob eingehende Verbindungen akzeptiert werden sollen. Diese Frage sollte mit “Erlauben” beantwortet werden.

Grant access in the macOS firewall
Grant access in the macOS firewall

5.4.2.2 Uninstall service on macOS

Open the application bundle “OpenEstate-ImmoServer” and start the “ServiceUninstall” application. A terminal window will show up, which will remove the service from the operating system.

The application requires administrative permissions. While the application is running you might get asked for an administrator password.

5.4.2.3 Start service on macOS

After the service was installed (see “Install service on macOS”) you might start the service manually in of these ways:

Notice

By default the service will start automatically while the macOS system is booting. Therefore in most cases it is not possible to start the service manually.

5.4.2.4 Stop service on macOS

After the service was installed (see “Install service on macOS”) you might stop the service manually in of these ways:

5.4.3 Setup service on Linux

On Linux the service is controlled with the systemd application, which is part of the operating system. The service is registered by creating a file called openestate-immoserver.service in the /etc/systemd/system directory.

Warning

Most Linux distributions are using “systemd”. To be on the safe side you should check, if you operating system also uses this software, before the service is installed.

Notice

You might modify the created service file by yourself in order to make individual adjustments (see manual of launchd). But in most cases this should not be necessary.

5.4.3.1 Install service on Linux

If ImmoTool-Server was installed with the Debian package, the service is already installed. In this case no further steps are necessary to install the service.

If ImmoTool-Server was installed with the TAR.GZ package, open the bin subfolder of the application directory and start the ServiceInstall.sh script.

Installing the service on Linux
Installing the service on Linux

The application requires administrative permissions. While the application is running you might get asked for an administrator password.

You can select the following options during the installation of the service:

If all questions have been answered, the service file openestate-immoserver.service is created in the /etc/systemd/system directory.

Summary after the service was installed on Linux
Summary after the service was installed on Linux

5.4.3.2 Uninstall service on Linux

Open the bin subfolder in the application directory and start the ServiceUninstall.sh script.

The application requires administrative permissions. While the application is running you might get asked for an administrator password.

5.4.3.3 Start service on Linux

After the service was installed (see “Install service on Linux”) you might start the service manually in of these ways:

Notice

Standardmäßig wird der Dienst unter Linux automatisch gestartet sobald der Rechner hochgefahren wird. Daher ist es in der Regel nicht nötig den Dienst von Hand zu starten.

5.4.3.4 Stop service on Linux

After the service was installed (see “Install service on Linux”) you might stop the service manually in of these ways:

5.5 Updating ImmoTool-Server

ImmoTool-Server is updated much more rarely compared to ImmoTool. In contradiction to ImmoTool the ImmoTool-Server does not check for updates automatically. Therefore you should visit the OpenEstate website regularly or subscribe to the RSS feed in order to get notifications about updates.

Download the installation package for your operating system and start the installation process (see “Installing ImmoTool-Server”). Thereby keep the following notices for your operating system in mind.

Warning

Always close the ImmoTool-Server application before starting the update process.

Tip

In order to avoid a data loss in case of an error, it is recommended to backup the data directory before starting the update procedure.

5.5.1 Update on Windows

The EXE installer automatically detects, where the application was installed beforehand and will update the files accordingly.

Warning

If you made custom modifications to the configuration directory, you should backup all files in this directory before installing the update. Afterwards you can copy the modified files back.

5.5.2 Update on macOS

Move the application symbol of “OpenEstate-ImmoServer” to the same location, where ImmoTool-Server was installed beforehand. The operating system will show the following question:

Question about overwriting on macOS
Question about overwriting on macOS

To-Do

Provide an English screenshot.

Answer this question in the dialog window by clicking on “Replace”.

5.5.3 Update on Debian, Ubuntu or similar

If the Debian repository was configured in your operating system (see “Obtain packages from the Debian repository”), you do not have to download the updated version from the OpenEstate website. Instead you can execute the following commands:

sudo apt update
sudo apt install openestate-immoserver

If you do not use the Debian repository but installed the program from the Debian package, you can download the DEB installation package. Install the downloaded package with a double click or via the following command:

sudo dpkg -i openestate-immoserver_x.y.z_amd64.deb

(Replace x.y.z with the version number of the downloaded file.)

Warning

If you made custom modifications to the configuration directory, you should backup all files in this directory before installing the update. Afterwards you can copy the modified files back.

5.5.4 Update on Linux

  1. Find out the path, where ImmoTool-Server was installed beforehand.
  2. Download the TAR.GZ installation package for your Linux system and extract the file on your computer.
  3. Rename the folder, you have determined in step 1 - e.g. OpenEstate-ImmoServer-OLD.
  4. Create a new / empty folder with the name, you have determined in step 1 - e.g. OpenEstate-ImmoServer.
  5. Copy the files, that were extracted in step 2 into the newly created / empty folder.

After you have been able to properly start the application in the updated version you might remove the temporary folder created in step 3.

Warning

If you made custom modifications to the configuration directory, you should backup all files in this directory before installing the update. Afterwards you can copy the modified files back.

5.5.5 Important advices for certain versions

This section contains advices about updates to certain application versions.

5.5.5.1 Update from version 1.0-beta to 1.x

ImmoTool-Server 1.0.0 introduced some major changes, that should be considered during an update from version 1.0-beta.

5.5.5.1.1 New directories

In contrast to the 1.0-beta version ImmoTool-Server does not save the databases in the application directory anymore. Before the old application directory is removed, you absolutely should backup the contents of the var/data subfolder from the old application directory.

After the new version of ImmoTool-Server was installed, start the application for the first time and shutdown the application afterwards immediately. This will create the new data directory. Open this directory and copy the previously saved contents of the var/data subfolder into the newly created data subfolder of the data directory.

You should find an already existing data subfolder. Remove or rename this folder before copying files into it.

Future updates of ImmoTool-Server 1.x do not require these steps and should work flawlessly.

5.5.5.1.2 New mechanism for services

Installation of services have been completely reworked with ImmoTool-Server 1.0.0. If you are using a service for the previous version, you should remove the service from the operating system before starting the update. In order to remove the service execute the ServiceUninstall.bat or ServiceUninstall.sh script in the bin directory of the old ImmoTool-Server installation.

After the new version of ImmoTool-Server was installed you can reinstall its service (see “Setup a service for ImmoTool-Server”).

Future updates of ImmoTool-Server 1.x do not require these steps and should work flawlessly.

5.5.5.1.3 New installation routine for Windows & macOS

A new installation routine was implemented for Windows and macOS systems (EXE and DMG installation packages). The new installation packages are not compatible with the old update procedure. Please make sure, that you do not overwrite the previous ImmoTool-Server version while installing the update. Therefore we are recommending the following approach:

Future updates of ImmoTool-Server 1.x do not require these steps and should work flawlessly.

5.5.5.1.4 Java can be removed

Since version 1.0.0 Java is bundled together with the ImmoTool-Server application. Therefore you can remove Java from your operating system as long as you do not need it for other applications.

5.6 Reset the password of a database user

This chapter describes different approaches how to reset the password of a database user.

5.6.1 Reset the password via AdminTool

If the password of a database user got lost, the administrator can login to AdminTool and assign a new password for the user in the user management (see “Manage user accounts”).

Notice

As long as a password of at least one database user with administrative permissions is known this procedure can be used to reset the password of all users (even of other administrators).

5.6.2 Reset the password without administrator access

If the password of the database administrator is not known anymore, you can follow these steps in order to reset the password:

  1. Stop ImmoTool-Server, if it is currently running.

  2. Open the db.script file from the database directory in a text editor. By default the database directory is placed in the data/immotool subfolder of the data directory.

    Warning

    Create a backup of the db.script file before making any changes. Possible mistakes might lead to a defective database.

  3. Search in the db.script file for a line starting with:

    CREATE USER SA PASSWORD DIGEST

    Replace the line with the following line:

    CREATE USER SA PASSWORD DIGEST '16d7a4fca7442dda3ad93c9a726597e4'
  4. Save the modified db.script file and restart ImmoTool-Server.

  5. The password of the database administrator SA was changed to test1234. From now on you can use this password to login to the database via AdminTool / ImmoTool.

Warning

For security reasons you should connect to the database with AdminTool and enter a new secret password for the “SA” user (see “Manage user accounts”).

6 Further notes about administration

6.1 AdminTool

AdminTool is a helper application for administrators to manage ImmoTool databases. In most cases the application is used in conjunction with multi-user installations - e.g.

6.1.1 Starting AdminTool

AdminTool is installed together with the ImmoTool application (see “Installing ImmoTool”).

6.1.1.1 Start AdminTool on Windows

You can find a folder called “OpenEstate-ImmoTool” in the start menu, that contains a shortcut to start AdminTool.

Besides this you may start the application by executing the AdminTool.exe (or ImmoTool.bat) file in the bin subfolder of the application directory.

6.1.1.2 Start AdminTool on macOS

Open the application bundle called “OpenEstate-ImmoTool” with a double click. This will open a Finder window with the applications provided by ImmoTool.

Finder window with ImmoTool applications
Finder window with ImmoTool applications

To-Do

Provide an English screenshot.

A double click on the “AdminTool” application will start the application.

Tip

You may integrate the “AdminTool” application symbol into the Dock for future application starts (see documentation by Apple).

Besides this you may start the application by executing the AdminTool.sh file in the bin subfolder of the application directory.

6.1.1.3 Start AdminTool on Linux

If ImmoTool was installed with the Debian package, you will find an entry called “OpenEstate-AdminTool” in your start menu.

If ImmoTool was installed with the TAR.GZ package, you may have to start the StartMenuAdd.sh script in the bin subfolder of the application directory in order to create the start menu entry for AdminTool.

Alternatively you may start the application by executing the AdminTool.sh script in the bin subfolder of the application directory.

6.1.2 Connecting with a database

If AdminTool was started, you will see the following dialog window. You need to enter the connection settings for the database into this window.

Connecting with a database via AdminTool
Connecting with a database via AdminTool

There are two possible ways to connect with a database via AdminTool.

6.1.2.1 Connect via project folder

You may connect to a database of a previously created project (single-user or multi-user). In this case you need to select the project directory on the hard drive by clicking the button “Select”.

Connect to database via project folder
Connect to database via project folder

In this case AdminTool will use the connection settings provided by the selected project.

If the folder of a remote project (multi-user installation) was selected, you will also have to enter the login credentials of the database administrator into the “User” and “Password” field. In most cases the user name of the database administrator is “SA”.

6.1.2.2 Connect via explicit configuration

You may also connect to a database by explicitly entering the connection settings.

Connect to database via explicit configuration
Connect to database via explicit configuration

The following settings can be entered:

6.1.3 Toolbar

AdminTool shows a toolbar on top with the following button.

Toolbar of AdminTool
Toolbar of AdminTool

6.1.4 Edit company data

After a database connection was established you can find the “Agency” tab, which shows the currently used company data / logo. You may edit these settings within this tab.

Edit company data
Edit company data

6.1.5 Manage addons

After a database connection was established you can find the “Addons” tab, which shows information about currently used addons.

6.1.5.1 Manage installed addons

The tab “Installed addons” shows a tabular view of addons, that are currently installed in the project database.

Table of currently installed addons
Table of currently installed addons
6.1.5.1.1 Enable / Disable addons

An addon has to be enabled by the administration in order to make it available for database users within the project.

You may enable or disable an addon by clicking into the “active” table column. After clicking the “Save changes” button the settings are saved into the database.

6.1.5.1.2 Uninstall addons

Select the addon to uninstall from the table by selecting its table row. Afterwards click on the “Run uninstallation” button in order to remove the selected addon from the database completely.

Warning

Uninstalling an addon from the database means, that all of its previously stored data is being removed from the database.

6.1.5.2 Install further addons

An addon can be available in the ImmoTool plugin directory, but it might not installed into the database yet. Those addons are shown in the table within the “Further addons” tab.

Table of further addons
Table of further addons

You may install those addon by clicking into the “Install” table column. After clicking the “Run installation” button the addons are installed into the database.

6.1.5.3 Update addons

The tab “Updatable addons” shows a tabular view of addons and extensions, that are already installed into the database but need to be updated because a newer version is available on the hard drive.

Table of updatable addons
Table of updatable addons

In order to install an available update select the corresponding table rows and click on the “Run updates” button.

Notice

An addon or extension is only usable within ImmoTool, of the installed API version is equal to the required API version by the addon on the hard drive.

6.1.6 Manage user accounts

After a database connection was established you can find the “Users” tab, which provides user management. On multi-user installations you configure any number of users, that may work on the database at the same time.

Manage user accounts
Manage user accounts

On the left side of the tab there is a list of user accounts, that are currently registered in the database. Click on one of these accounts in order to manage their settings.

On the right side of the tab the information about the currently selected user account is shown.

The following action buttons are available on the top of the tab:

Notice

After any modification you need to click the “Submit” button. Otherwise these changes are not stored into the database.

6.1.6.1 General user data

If a user account was selected for modification, its general data is shown on the right side in the “User” tab.

General data of an user account
General data of an user account

Warning

If the database of a single-user installation is managed in AdminTool, you should not change the password of the “SA” user. In this particular case the password should always be empty.

6.1.6.2 Personal user data

If a user account was selected for modification, its personal data is shown on the right side in the “Person” tab.

Personal data of an user account
Personal data of an user account

Notice

The user might change his personal data via ImmoTool by himself, if he has the required permissions.

6.1.6.3 User memberships

If a user account was selected for modification, its group memberships are shown on the right side in the “Groups” tab.

Group memberships of an user account
Group memberships of an user account

The table shows the groups, that are currently available in the database. By clicking on the checkbox in the “assigned” column you might assign one or more groups to the user.

Notice

The user gains all permissions, that have been assigned to the groups of his memberships.

Notice

The user automatically becomes a member of the “IMMOTOOL” group, if his account was activated in the “User” tab.

6.1.6.4 User permissions

If a user account was selected for modification, its permissions are shown on the right side in the “Permissions” tab.

Permissions of an user account
Permissions of an user account

The table shows the permissions, which are defined by installed addons. By clicking on the checkbox in the “assigned” column you might assign one or more permissions to the user.

Tip

Instead of explicitly assigning permissions to a certain user, its often a better way to use user groups. In this case the permissions only have to be set once for the group. Each user, who becomes a member of the group, will automatically gain these permissions.

6.1.7 Manage user groups

After a database connection was established you can find the “Groups” tab, which provides group management.

Generally you can combine multiple users into multiple groups. By becoming a member of a group a user will automatically gain all permissions, that were assigned to the group.

Manage user groups
Manage user groups

On the left side of the tab there is a list of groups, that are currently registered in the database. Click on one of these groups in order to manage their settings.

On the right side of the tab the information about the currently selected user group is shown.

The following action buttons are available on the top of the tab:

Notice

After any modification you need to click the “Submit” button. Otherwise these changes are not stored into the database.

6.1.7.1 General group data

If a user group was selected for modification, its general data is shown on the right side in the “Group” tab.

General data of an user group
General data of an user group

6.1.7.2 Assign user accounts

If a user group was selected for modification, its group members are shown on the right side in the “Members” tab.

Members of an user group
Members of an user group

The table shows the user accounts, that are currently available in the database. By clicking on the checkbox in the “assigned” column you might assign one or more users to the group.

6.1.7.3 Group permissions

If a user group was selected for modification, its permissions are shown on the right side in the “Permissions” tab.

Permissions of an user group
Permissions of an user group

The table shows the permissions, which are defined by installed addons. By clicking on the checkbox in the “assigned” column you might assign one or more permissions to the group.

6.1.8 Browse database contents

After a database connection was established you can find the “SQL browser” tab, which provides read access to the raw database contents (tables, views and stored procedures).

Browse database contents
Browse database contents

This tab does not provide any special functionality. It might only be helpful for a database review.

6.1.9 Execute SQL commands

After a database connection was established you can find the “SQL console” tab, which allows the execution of SQL commands on the database.

Execute SQL commands via AdminTool
Execute SQL commands via AdminTool

Warning

Use this feature with caution. Any wrong SQL command might damage your database.

Notice

You can find a summary of supported SQL commands in the documentation of the HSQL database.

6.2 Backup & restore databases

For everyday usage it is highly recommended to find and implement a strategy for regular backups. This chapter describes different approaches about how to backup the databases of ImmoTool and ImmoTool-Server.

Please consider, that you have to follow different approaches for single-user installations and multi-user installations (see “How ImmoTool can be installed…”).

Warning

Do not simply rely on the backup features of your operating system. Practice has shown, that for example restore points on Windows led to corrupt databases.

Notice

In order to avoid a possible data loss, you should implement a backup strategy as soon as ImmoTool is used productively.

Tip

It is recommended to test the procedure of backup and restore beforehand. Take notes of the required steps. In case of a system failure you can rely on your notes and previously made experiences, which finally reduces a possible downtime.

Tip

In order to ensure the best possible failure safety you should save the database backups to an external location. For example use an external hard drive or send the backup files to an external server (e.g. your webspace or cloud provider).

6.2.1 Backup single-user installations

On single-user installations the database is managed by the Immotool itself (see “Installing on a single workplace”). Therefore in most cases the backup should be executed from the same system, on which ImmoTool is installed.

6.2.1.1 Copy project folder

The easiest way of backing up a single-user installation is copying the project directory. Find out where your project directory is located and copy this folder accordingly.

Notice

By default ImmoTool creates a separate directory for each project in the OpenEstate-Files/projects subfolder of the user’s home directory.

Warning

You should only copy the project directory, if ImmoTool is not running or the project is currently not opened.

6.2.1.2 Manual backup via ImmoTool

After the local project was opened in ImmoTool you can click in the main menu at “Extras → Database → Backup” in order to create a database backup manually. A dialog window is shown, where you can select the save location of the backup file.

6.2.1.3 Automatic backup via ImmoTool

As an alternative to a manual backup you can configure automatic backups for local projects (single-user installations). In this case the application will automatically create backups in certain situations.

After the local project was opened in ImmoTool you can click in the main menu at “Extras → Settings” in order to open the settings dialog window. After selecting the form “Database” you will see the following view:

Configure automatic backups
Configure automatic backups

You can choose a target folder, where automatic backups are saved at. Besides this you may choose, in which case an automatic should be created (e.g. while the project is opened).

The number selected as “Limit” determines, how many backups are kept in the selected target directory. For example if more than five backups are stored in the target directory, the oldest backups are automatically removed. The defined limit will not be exceeded.

Tip

You might select an external hard drive or a network drive as backup location. This makes sure, that the backups are not lost in case of a hardware failure on your local system.

6.2.1.4 Restoring a backup

If the project directory was copied (see “Copy project folder”), you can simple copy the folder back to its original location. Afterwards the project can be opened again with ImmoTool. Further steps for restoring the backup are not necessary in this case.

Backups created within ImmoTool have been stored as TAR.GZ archives (see “Manual backup via ImmoTool” and “Automatic backup via ImmoTool”). In order to restore these archives you can follow these steps:

  1. Close ImmoTool, if it is currently running.
  2. Extract the TAR.GZ archive, that contains the database backup.
  3. Open the project directory in your file browser (Explorer / Finder).
  4. Rename the data subfolder - e.g. to data-old.
  5. Create a new / empty data subfolder.
  6. Copy the files extracted from step 2 into the newly created data folder.
  7. Start ImmoTool and open the project.

If the restored project was successfully opened, you might remove the folder data-old created in step 4.

Tip

If you do not know where the project is located or do not have a project available anymore, you might create a new / empty local project first and afterwards follow the steps above.

6.2.2 Backup multi-user installations

On multi-user installations the database is managed by Immotool-Server (see “Installing on a multiple workplaces”). Therefore in most cases the backup should be executed from the same system, on which ImmoTool-Server is installed.

6.2.2.1 Backup an inactive ImmoTool-Server

If ImmoTool-Server is not running (or was temporarily stopped), you can copy its data directory. By default this directory contains the files of all managed databases.

Warning

It is not recommended to copy the data directory while ImmoTool-Server is running. This may lead to a faulty backup, that can not be restored easily.

6.2.2.2 Backup a running ImmoTool-Server

You can create backups of ImmoTool-Server while the application is running. For this use case the helper application “ManagerBackup” is provided.

The ManagerBackup application needs to connect with the databases to backup. Therefore the application needs to login with an administrative account for all databases to backup.

Open the manager.conf file in the configuration directory with a text editor. For each database to backup you need to provide these lines:

urlid immotool
url jdbc:hsqldb:hsql://localhost:9001/immotool
username SA
password

After the password value you need to enter the password of the database administrator (SA) separated by space - e.g. password test1234 (see “Configure manager applications”).

By default the ManagerBackup application creates a backup for all databases specified in the manager.conf file. By default the application stores the backup into the backups subfolder of the data directory.

Notice

Before automating the backup process you should test, if the ManagerBackup is properly configured and works as expected.

6.2.2.2.1 Automatic backup on Windows

The Windows operating system provides a dialog window for task scheduling, which can be used for automatic execution of the ManagerBackup application at freely chosen times.

Open the Windows Task Scheduler application:

  1. Press the “Windows key” together with the letter “R” to open a window for command execution. Alternatively you can open the command prompt.

  2. Enter the command taskschd.msc and press the “ENTER” key.

Click on the right side in the “Actions” section on the “Create task” link.

Create task for automatic backup
Create task for automatic backup

A new dialog window shows up, which allows the creation of the backup task.

General settings for the task
General settings for the task

Open the tab “General” and enter a suitable name and description for the task. Besides this you should click on the “Change User or Group” button and select the “Local Service” user.

Zeit der Ausführung wählen
Zeit der Ausführung wählen

Open the tab “Triggers” in order to configure the execution time of automated backups.

Auszuführendes Programm wählen
Auszuführendes Programm wählen

Open the tab “Actions” and select the ManagerBackup.exe application from the bin subfolder of the application directory.

You may change further settings in this dialog window. After you have completed the configuration, click on the “OK” button in order to register the task in the operating system.

To-Do

Provide English screenshots.

6.2.2.2.2 Automatic backup on macOS

While installing a service for ImmoTool-Server on macOS you can enable daily automatic backups (see “Setup service on macOS”).

If automated backups were enabled while installing the service, the script creates a file org.openestate.tool.server.backup.plist in the /Library/LaunchDaemons directory. This file tells the operating system to automatically execute ManagerBackup once in a day.

Notice

You are not forced to use the provided mechanism for automated backups. You might also create your own cronjob (or agent for launchd), that executes the ManagerBackup application.

6.2.2.2.3 Automatic backup on Linux

If ImmoTool-Server was installed with the Debian package, a timer for daily automated backups is already installed.

Alternatively a timer can be registered, while a service for ImmoTool-Server on Linux is installed (see “Setup service on Linux”).

The files openestate-immoserver-backup.timer and openestate-immoserver-backup.service in the /etc/systemd folder are used to trigger automatic execution of the ManagerBackup application.

Notice

You are not forced to use the provided mechanism for automated backups. You might also create your own cronjob (or timer for systemd), that executes the ManagerBackup application.

6.2.2.2.4 Parameters for ManagerBackup

The ManagerBackup can be controlled by the following command line parameters:

6.2.2.3 Restoring a server backup

A database backup is a copy of the database files. You can restore these files quite easily by following these steps:

  1. Stop ImmoTool-Server, if it is currently running.

  2. If the backup is created as ZIP or TAR.GZ archive, extract these files accordingly.

  3. Rename the database directory and create a new / empty database directory with the same name.

  4. Copy the database files db.data, db.lobs, db.properties & db.script into the database directory (see “Data directory of ImmoTool-Server”).

  5. Start ImmoTool-Server in order to make the restored databases available.

If the restored project was successfully opened, you might remove the renamed database directory created in step 3.

6.3 Convert single-user into multi-user installation

A single-user installation can be migrated to a multi-user installation. Therefore the database has to be copied to the ImmoTool-Server and slightly modified.

  1. Install ImmoTool-Server, if it is not installed yet (see “Installing ImmoTool-Server”).

  2. Stop ImmoTool-Server, if it is currently running.

  3. Open the data directory of the ImmoTool-Server and create a folder data/immotool, if it does not already exist. If the directory does already exist, remove all contained files and subfolders.

  4. Open the directory of the local project. There you should find a data folder. This directory contains the database files: immotool.data, immotool.lobs, immotool.properties and immotool.script.

  5. Copy the database files located in step 4 into the directory created in step 3. Rename these files to db.data, db.lobs, db.properties and db.script.

  6. Start ImmoTool-Server and connect to the copied database with AdminTool. Use the username “SA” and an empty password. On the first connection with AdminTool you will be asked to enter a password for the “SA” user.

From now on the database is available for ImmoTool and AdminTool as a remote project. To finally access the database with ImmoTool you need to create a remote project (see “Connect to ImmoTool-Server”).

If the migration was successfully completed and ImmoTool properly connects to ImmoTool-Server, you might remove the old directory of the local project.

6.4 Convert multi-user into single-user installation

A multi-user installation can be migrated to a single-user installation. Therefore the database has to be copied into a local project and slightly modified.

  1. Start ImmoTool and create a new / empty local project (see “Create local project”). Into this project the database will be transferred in the next steps.

  2. Close ImmoTool after the new / empty local project was created and opened for the first time.

  3. Stop ImmoTool-Server, if it is currently running.

  4. Open the directory of the local project created in step 1. The data subfolder should contain these files: immotool.data, immotool.lobs, immotool.properties and immotool.script. Remove all files and subfolders from the data subfolder.

  5. Open the database directory of the ImmoTool-Server. By default you find this directory in the data/immotool subfolder of the data directory. You should find these files in this folder: db.data, db.lobs, db.properties and db.script. Copy these files into the data subfolder of the previously created project (see step 4). Rename the copied files to immotool.data, immotool.lobs, immotool.properties and immotool.script.

  6. Edit the immotool.script file from the data folder of the local project in a text editor.

    Warning

    Copy a backup of the immotool.script file before making any changes. A mistake while editing may lead to a faulty database.

  7. Seach in the immotool.script file for a line starting with:

    CREATE USER SA PASSWORD DIGEST

    Replace this line with:

    CREATE USER SA PASSWORD DIGEST 'd41d8cd98f00b204e9800998ecf8427e'
  8. Save the modified immotool.script file.

From now on you can open the local project with ImmoTool. All data from ImmoTool-Server is available in the local project.

In case you don’t need ImmoTool-Server anymore, you might uninstall ImmoTool-Server after the migration was successfully finished.

6.5 Migrate an old project from ImmoTool 0.9.x

ImmoTool 0.9.x is already very old. It is not developed any further and can not be supported by OpenEstate anymore. Therefore it is heavily recommended to migrate the application to the latest 1.x version. This chapter describes the required steps for migration.

Notice

You should not overwrite old ImmoTool 0.9.x installation. ImmoTool 1.x has to be installed separately. In case of problems during the migration you can continue using the old version until the problem was solved.

6.5.1 Export project from ImmoTool 0.9.x

In the first step you need to open ImmoTool 0.9.x and create a backup of the project database.

  1. Make sure, that the latest available old version is used (at least 0.9.15 or 1.0-beta10f). Therefore click in the main menu at “Extras → Updates”.

    Update the old ImmoTool version
    Update the old ImmoTool version

    Alternatively you might download version 0.9.33 (the latest 0.9.x Version) from the OpenEstate website.

  2. Open the project to migrate in the old ImmoTool installation and create a database backup by clicking in the main menu at “Extras → DB type → Sicherung für Version 1.x”. (The translation in the application is incorrect here.)

    Create a backup for ImmoTool 1.x
    Create a backup for ImmoTool 1.x

    This will create a ZIP archive with the contents of the project database. You will need this ZIP archive in the following steps.

The next steps depend on how you want to use ImmoTool 1.x in the future (as single-user installation or multi-user installation).

6.5.2 Migrate into a single-user installation

If ImmoTool 1.x should be used as single-user installation, install the latest version of ImmoTool 1.x next to your old ImmoTool installation (see “Installing ImmoTool”).

Warning

Do not overwrite the old ImmoTool installation! Both versions should be installed next to each other.

If ImmoTool 1.x is started for the first time, the project wizard shows up. Create a new project and select the previously created ZIP file.

To-Do

Add link to the project wizard in the usage section.

Datensicherung via Projektassistent importieren
Datensicherung via Projektassistent importieren

Select as “Project type” the option “Migrate local project from ImmoTool 0.9.x”. Below you can find a form, where the previously created ZIP file can be selected by clicking the “Select” button. The application will validate the ZIP file and automatically load the company information.

You might check and fix the company information and addon. Afterwards click on the “Create project” button. While the project is created the data from the ZIP file is automatically imported into the database.

Notice

After the migration was successfully finished you might remove the old installation of ImmoTool 0.9.x.

6.5.3 Migrate into a multi-user installation

If ImmoTool 1.x should be used as multi-user installation, install the latest version of ImmoTool 1.x next to your old ImmoTool installation (see “Installing ImmoTool”) and ImmoTool-Server (see “Installing ImmoTool-Server”).

Warning

Do not overwrite the old ImmoTool installation! Both versions should be installed next to each other.

After ImmoTool-Server was installed you can import the database backup with AdminTool into ImmoTool-Server. The previously created ZIP file can be imported via AdminTool in one of these ways:

After the contents of the ZIP file were imported the database is ready for use. Start ImmoTool 1.x and create a remote project in order to connect to the database (see “Connect to ImmoTool-Server”).

Notice

After the migration was successfully finished you might remove the old installation of ImmoTool 0.9.x.

7 Appendix

7.1 Support & Assistance

Each user, that has been registered on the OpenEstate website, may receive free technical support for ImmoTool, ImmoTool-Server and other OpenEstate projects. This includes assistance with

For supports requests to developers the ticket system should be used preferably. All communication through the ticket system is confidential and not visible to other users.

7.2 License agreements

7.2.1 License for OpenEstate-ImmoTool

The following usage agreement is concluded between the OpenEstate developers (subsequently called „licensor“) and the licensee.

1. Object of agreement

  1. Object of this license are programs and libraries (subsequently called „software“), that were created and published by the licensor as a part of the OpenEstate project. Further information about the OpenEstate projects are available at: https://openestate.org

2. Rights of the licensee

  1. The software is downloadable and usable for free and may be used without limitations.

  2. Updates of the software are provided by the licensor for free.

  3. The software may be copied and distributed in a private circle of friends and acquaintances.

  4. A distribution of the software for commercial purpose requires a written permission by the licensor.

  5. The licensor does not have any rights on the data, that was created with the software. The licensee is free to do whatever he likes with his data.

  6. The licensor may develop and publish his own extensions for the software (commonly called „Add-Ons“) as long as this license agreement is not undermined thereby.

  7. The licensee may register for free at the OpenEstate website in order to get free technical support for the software by the licensor.

3. Duties of the licensee

  1. Any kind of manipulation, decompilation or disassembly of the software is prohibited.

  2. In any kind of case of replication of the software the copyright notes and license texts must be preserved.

  3. It is not allowed to rent or sell the software in any way without a permission of the licensor.

  4. If customly made extensions (commonly called „Add-Ons“) are distributed by the licensee, the existing copyright notes and license texts must be preserved. The license for customly made extensions is free to choose as long as it does not undermine this license agreement and licenses of provided libraries.

4. Revocation of the usage agreement

  1. If the licensee violates against the duties documented in this agreement, the licensee is eligible to revoke the usage license for the software.

5. Disclaimer of liability

  1. Unless required by applicable law or agreed to in writing, the licensor provides the software on an „as is“ basis, without warranties or conditions of any kind, either express or implied, including, without limitation, any warranties or conditions of title, non-infringement or fitness for a particular purpose. The licensee is solely responsible for determining the appropriateness of using or redistributing the software and assume any risks associated with his exercise of permissions under this license agreement. In case of errors, any costs for required services (for example repairing or data restoring) have to be beared by the licensee.

  2. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the licensor be liable to the licensee for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this license agreement or out of the use or inability to use the software (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the licensor has been advised of the possibility of such damages.


as from 25.05.2018

7.2.2 License for OpenEstate-ImmoServer

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

  1. Definitions.

    “License” shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.

    “Licensor” shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

    “Legal Entity” shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, “control” means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

    “You” (or “Your”) shall mean an individual or Legal Entity exercising permissions granted by this License.

    “Source” form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.

    “Object” form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.

    “Work” shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).

    “Derivative Works” shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

    “Contribution” shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, “submitted” means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as “Not a Contribution.”

    “Contributor” shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.

  2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.

  3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.

  4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:

    1. You must give any other recipients of the Work or Derivative Works a copy of this License; and

    2. You must cause any modified files to carry prominent notices stating that You changed the files; and

    3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and

    4. If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.

    You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.

  5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.

  6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.

  7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.

  8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.

  9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

7.2.3 License for the user manual

Attribution-NonCommercial 4.0 International


Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.

Using Creative Commons Public Licenses

Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.

Considerations for licensors: Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC- licensed material, or material used under an exception or limitation to copyright. More considerations for licensors: wiki.creativecommons.org/Considerations_for_licensors

Considerations for the public: By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. More considerations for the public: wiki.creativecommons.org/Considerations_for_licensees


Creative Commons Attribution-NonCommercial 4.0 International Public License

By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-NonCommercial 4.0 International Public License (“Public License”). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.

Section 1 – Definitions.

  1. Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.

  2. Adapter’s License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.

  3. Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
  4. Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.

  5. Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.

  6. Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License.

  7. Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.

  8. Licensor means the individual(s) or entity(ies) granting rights under this Public License.

  9. NonCommercial means not primarily intended for or directed towards commercial advantage or monetary compensation. For purposes of this Public License, the exchange of the Licensed Material for other material subject to Copyright and Similar Rights by digital file-sharing or similar means is NonCommercial provided there is no payment of monetary compensation in connection with the exchange.

  10. Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.

  11. Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.

  12. You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.

Section 2 – Scope.

  1. License grant.

    1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:

      1. reproduce and Share the Licensed Material, in whole or in part, for NonCommercial purposes only; and

      2. produce, reproduce, and Share Adapted Material for NonCommercial purposes only.

    2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.

    3. Term. The term of this Public License is specified in Section 6(a).

    4. Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)
      1. never produces Adapted Material.
    5. Downstream recipients.

      1. Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.

      2. No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.

    6. No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).

  2. Other rights.

    1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.

    2. Patent and trademark rights are not licensed under this Public License.

    3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties, including when the Licensed Material is used other than for NonCommercial purposes.

Section 3 – License Conditions.

Your exercise of the Licensed Rights is expressly made subject to the following conditions.

  1. Attribution.

    1. If You Share the Licensed Material (including in modified form), You must:

      1. retain the following if it is supplied by the Licensor with the Licensed Material:
      • identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);

      • a copyright notice;

      • a notice that refers to this Public License;

      • a notice that refers to the disclaimer of warranties;

      • a URI or hyperlink to the Licensed Material to the extent reasonably practicable;

      1. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and

      2. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.

    2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.

    3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.

    4. If You Share Adapted Material You produce, the Adapter’s License You apply must not prevent recipients of the Adapted Material from complying with this Public License.

Section 4 – Sui Generis Database Rights.

Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:

  1. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database for NonCommercial purposes only;

  2. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and

  3. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.

For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.

Section 5 – Disclaimer of Warranties and Limitation of Liability.

  1. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.

  2. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.

  3. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.

Section 6 – Term and Termination.

  1. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.

  2. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:

    1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or

    2. upon express reinstatement by the Licensor.

    For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.

  3. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.

  4. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.

Section 7 – Other Terms and Conditions.

  1. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.

  2. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.

Section 8 – Interpretation.

  1. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.

  2. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.

  3. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.

  4. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.


Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” The text of the Creative Commons public licenses is dedicated to the public domain under the CC0 Public Domain Dedication. Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at creativecommons.org/policies, Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.

Creative Commons may be contacted at creativecommons.org.