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:

• Everybody may download and use this software without any costs.
• Everybody may help in further development of the software.
• Everybody may extend the software with his own modules (so called addons) and may publish them under a freely chosen license.
• Every registered user may get support and help by the developers about technical issues with the software.
• There are no license fees.

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:

• Everybody may download and use this software without any costs.
• Everybody may help in further development of the software.
• Everybody may access and modify the provided source code (even for commercial purposes).
• Every registered user may get support and help by the developers about technical issues with the software.
• There are no license fees.

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

• Operating system:
  • Windows (from version 7 onwards; 32bit / 64bit)
  • macOS (from version 10.9 onwards)
  • Linux (x86 aka IA-32 / x86-64 aka amd64)
• Processor: 2 GHZ (the more the merrier)
• RAM: 512 MB are used by the application at maximum
• Hard drive space: approx. 150 MB after installation; more space is required depending on the amount of data
• Java: version 11 (already provided in the installation package)
• Internet access: not necessary, but helpful

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

• Operating system:
  • Windows (from version 7 onwards; 32bit / 64bit)
  • macOS (from version 10.9 onwards)
  • Linux (x86 aka IA-32 / x86-64 aka amd64)
• Prozessor: 1 GHZ (the more the merrier)
• RAM: 512 MB are used by the application at maximum
• Hard drive space: approx. 150 MB after installation; more space is required depending on the amount of data
• Java: version 8 at least; version 11 is recommended (already provided in the installation package)
• Internet access: not necessary

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:

• For Windows there are EXE installers available (32bit / 64bit).
• For macOS there is a DMG installation image available.
• For Debian based Linux distributions (e.g. Debian, Ubuntu or Linux Mint) there are different Debian packages available (DEB installation file).
• For other Linux systems there are different TAR.GZ files available.

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:

   wget -qO - \ 
     "https://debian.openestate.org/conf/debian.gpg.key" | \ 
     sudo apt-key add -

2. Register the repository via:

   sudo apt-add-repository \
     "deb https://debian.openestate.org/ openestate main"

   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:

   sudo apt update

4. Afterwards you can install ImmoTool via:

   sudo apt install openestate-immotool

   Or you can install ImmoTool-Server via:

   sudo apt install openestate-immoserver

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

• This is the most straightforward installation method. Only ImmoTool has to be installed.
• The database is created automatically on the first startup and the application is usable without any further setup.

2.4.1.2 Disadvantages of single-user installations

• Multiple users can not work on the same database at the same time.
• It is not possible to set permissions for different users. The user always has full access to the database and the application features.

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:

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

• Any number of employees may work at same time on the same database.
• Each employee has its own credentials for database access.
• Each employee may have its own permissions within the database (e.g. accessing certain data or using certain features).
• ImmoTool-Server may be installed in a data center. In this case employees may access the database from different locations. Alternatively the ImmoTool-Server might be made available through a Virtual Private Network.

2.4.2.2 Disadvantages of multi-user installations

• The installation procedure is more complicated because the ImmoTool-Server needs to be installed separately. Basic knowledge of networks and server administrations are helpful.
• Software updates are a bit more complicated because all workplaces should use the same ImmoTool version.

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.

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:

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:

   sudo apt update

2. Install ImmoTool:

   sudo apt install openestate-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.

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.

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.

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

• Project title:
  Enter any desired name for the project.

• Projekt type:
  Select the option “Create new local project.”.

• You may open the tab “Company” and add some more information about your company.

• You may open the tab “Addons” and enable / disable certain extensions in the 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.

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:

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:

   sudo apt update

2. Install ImmoTool-Server:

   sudo apt install openestate-immoserver

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.

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”).

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:

• DB type:
  Select the option “HSQL.remote”.

• Protocol:
  In normal case you should select the option “hsql”. If the ImmoTool-Server was configured for SSL encryption, you have to select the option “hsqls” (see “Configure SSL encryption”).

• Hostname:
  Enter the IP address or hostname of the computer, on which ImmoTool-Server was installed. In case AdminTool was started from the same computer you can keep the hostname “localhost” untouched.

• Port nr:
  By default the port number is “9001”. Only if ImmoTool-Server was configured for another port number, this value has to be changed.

• DB name:
  By default the name of the database is “immotool”. Only if another database with another name was configured in ImmoTool-Server, this value has to be changed.

• User:
  The login name of the database administrator is “SA”. In most cases this value has not to be changed.

• Password:
  If a first connection to the ImmoTool-Server is established, this value can stay empty. After a password was set for the database administrator it has to be entered here.

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!

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.

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”).

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

• Project title:
  Enter any desired name for the project.

• Projekt type:
  Select the option “Create new connection to a remote project.”.

• DB type:
  Select the option “HSQL.remote”.

• Protocol:
  In normal case you should select the option “hsql”. If the ImmoTool-Server was configured for SSL encryption, you have to select the option “hsqls” (see “Configure SSL encryption”).

• Hostname:
  Enter the IP address or hostname of the computer, on which ImmoTool-Server was installed. In case ImmoTool was started from the same computer you can keep the hostname “localhost” untouched.

• Port nr:
  By default the port number is “9001”. Only if ImmoTool-Server was configured for another port number, this value has to be changed.

• DB name:
  By default the name of the database is “immotool”. Only if another database with another name was configured in ImmoTool-Server, this value has to be changed.

• User:
  Enter the name of the database user. If other users were created via AdminTool, you may enter its login name here. Otherwise you can use the default administrator account “SA”.

• Password:
  Enter the password of the user provided in the “User” field.

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.

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:

• Remove the jre folder from the application directory of ImmoTool / ImmoTool-Server.
• Extract the archive, that you have downloaded from the third-party supplier.
• Rename the extracted folder into jre and copy it into the application directory of ImmoTool / ImmoTool-Server.

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:

• Remove the jre folder from the application directory of ImmoTool / ImmoTool-Server.

• Install the OpenJDK package of your Linux distributions - e.g. via:

  sudo apt install openjdk-11-jdk

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.

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:

• -help
  Shows a summary of available command line arguments.

• -noProject
  Starts the application without automatically opening a project. Instead the project wizard is shown.

• -project <PROJECT>
  Automatically opens the project located in the <PROJECT> folder on startup.

• -projectLogin <USER>
  If the project specified by the -project parameter is a multi-user project, the program will automatically login as user <USER>.

• -projectPass <PASSWORD>
  If the project specified by the -project parameter is a multi-user project, the program will automatically login with the password <PASSWORD>.

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.

• On Windows systems the path C:\Programme\OpenEstate-ImmoTool is used by default. But during the installation process the user might select another location.

• On macOS systems it depends, where the application bundle was copied to during the installation. By default the application bundle should be located at /Applications/OpenEstate-ImmoTool.app. The application directory itself is located inside the application bundle in the Contents/Resources subfolder.

• If the Debian package (or Debian repository) was used on Debian, Ubuntu, Linux Mint or similar for installation, the application is located at /opt/OpenEstate-ImmoTool.

• If the TAR.GZ package was used on Linux for installation, it depends where the extracted folder was moved to.

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:

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:

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:

• Find out, in which folder ImmoTool 1.0-beta is currently installed on your hard drive.

  • If the application is located on Windows systems at C:\Programme\OpenEstate-ImmoTool, you should rename this folder - e.g. in C:\Programme\OpenEstate-ImmoTool-OLD.

  • On macOS systems there should not be a problem with the naming of the folder. But nevertheless you should figure out, where the application is located.

• On Windows you should remove of the application (from the Desktop or start menu). On macOS you might remove the application from the Dock.

• Start the installation procedure (see “Installing ImmoTool”).

• If the application was successfully installed and started, you can remove the installation folder of ImmoTool 1.0-beta.

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.

• On Windows you can open the system control panel and open the section for software removal. You should find an entry for “Oracle Java”, that can be removed.

• On macOS you can follow these steps in order to remove “Oracle Java”:

  1. Click on the “Finder” icon located in your dock.
  2. Click on “Go” in the Finder menu.
  3. Click on “Utilities”.
  4. Double-click on the “Terminal” icon.

  5. In the Terminal window copy and paste the commands below:

     sudo rm -fr /Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin
     sudo rm -fr /Library/PreferencePanes/JavaControlPanel.prefPane
     sudo rm -fr ~/Library/Application\ Support/Oracle/Java

  (quoted from the official instructions by Oracle)

• On Linux you might remove “OpenJDK” via the package system of your distribution. Or if “Oracle Java” was installed, you might remove its installation folder manually.

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.