Skip to end of metadata
Go to start of metadata

1 Verify System Requirements

Before starting with the upgrade, please verify that you have the required software packages installed and upgraded to the required version. See here for details: Installation Prerequisites

2 Preparation

This guide provides instructions to upgrade iteraplan from release 6.1 to release 6.2. Please note that this guide is only applicable to these versions of iteraplan. For prior versions, please follow the appropriate iteraplan upgrade guides in order to upgrade to iteraplan 6.1 first.

The upgrade steps only need to be carried out once. However, they must be repeated for every installed instance of iteraplan (if applicable). The upgrade process is not intended to be reversible, i.e. after performing the upgrade there is no standard way to revert to the previously installed version of iteraplan. For that reason, we strongly recommend to create a complete backup of your entire iteraplan database and the application files.

To help you carry out the upgrade our checklist might prove useful.

2.1 Conventions and Assumptions

In the scope of this guide, it is assumed that iteraplan is deployed on an Apache Tomcat web server. The Tomcat installation directory is hereafter referred to as $TOMCAT_HOME, regardless of the underlying operating system. Furthermore, it is assumed that the iteraplan application is deployed under $TOMCAT_HOME/webapps/iteraplan. If you have deployed the application under a different name, replace iteraplan in the provided path as appropriate.

The Java Runtime Environment (JRE) or Java Developlent Kit (JDK) installation directory is denoted as $JAVA_HOME.

This guide uses Unix conventions for path names. For Windows, replace slashes (/) with back-slashes (\) and include drive letters where necessary.

3 Upgrade

3.1 Upgrade the database structure

Be sure that you have shut down iteraplan or the entire Tomcat instance. To shut down Tomcat on Windows, use the Computer Management Console to stop the Tomcat Service. Alternatively, run the batch script shutdown.bat in the $TOMCAT_HOME/bin directory. On Unix-like systems, use the normal daemon control mechanism, i.e. /etc/init.d/tomcat stop, or run the shell script in the $TOMCAT_HOME/bin directory.

All database upgrade scripts are encoded with UTF-8. Please ensure that you use this encoding.

Depending on whether you use MySQL, Oracle or SQLServer, use the SQL script for the respective database vendor. The script will perform all necessary modifications of your database.

In the directory upgrade/v6.1To6.2/ several files are provided:


Replace the placeholder [database] with the database you use. To execute the scripts, use a database management tool appropriate for your system.

3.2 Configure the new installation

Before iteraplan 6.2 is set up, the previous installation of iteraplan should be completely undeployed from the Tomcat instance. In particular, the following files and directories should be deleted from the Tomcat installation directory:


If your old iteraplan installation is deployed simultaneously with iteraplan 6.2, unexpected side effects may occur due to competing database and file access.

Launch iteraplan installer

Run the installer by launching the iteraplanInstaller.jar file and follow the instructions. Depending on your system configuration, double-clicking the jar file might not work. If this is the case, the file can be launched from the command line by executing

java jar iteraplanInstaller.jar

or by explicitly stating the JRE to use:

$JAVA_HOME/bin/java jar iteraplanInstaller.jar

Enter database connection parameters

During the installation process, the installer will request you to provide database connection parameters. The parameters to use are the same as the ones used for the installation of previous versions of iteraplan.

If you are not sure, you can look up the settings in the following two files of your old version’s backup:
$TOMCATBACKUP/webapps/iteraplan/WEB‑INF/classes/iteraplan‑ for the iteraplan database and $TOMCATBACKUP/conf/Catalina/localhost/iteraplan.xml for the iTURM database with authentication information.

Important: Make sure to disable database initialization. Otherwise, your current database contents will be deleted completely and you will need to resort to the data you have backed up.

Enter full-text search index storage directory

In a subsequent step, you will be requested to specify a directory where the files of the search index are to be stored. It is recommended to use a new empty subdirectory of the Tomcat installation directory, for example $TOMCAT_HOME/indexes.
In case several instances of iteraplan are deployed with different database configurations, it is important to use different search index directories.

Empty the search index directory

If you intend to use the search index directory of your previous installation of iteraplan, remove all files and subdirectories, as iteraplan will not be able to start up if the old indexes are still present. The location of the search index is denoted by the property in the config file $TOMCAT_HOME/webapps/iteraplan/WEB-INF/classes/

Empty Tomcat’s temporary work directory

Tomcat’s temporary work directory probably contains files of a previously installed version of iteraplan, even after installing the new version. This might cause problems. Therefore delete the following folder:


This forces Tomcat to recompile at start up.

Deployment on Tomcat and fine-tuning the configuration

After iteraplan 6.2 has been successfully configured by the installer, the generated WAR-file should be automatically copied into the Tomcat webapps directory ($TOMCAT_HOME/webapps). Then you can start Tomcat in order to deploy iteraplan 6.2.

During deployment, a directory $TOMCAT_HOME/webapps/iteraplan (corresponding to the name of the WAR-file), in which the iteraplan installation resides, will be generated. In case you made any customizations to your old installation’s configuration options, make sure to transfer the modifications analogously, for example to the the properties in $TOMCAT_HOME/webapps/iteraplan/WEB-INF/classes/ file or to any other *.properties file in $TOMCAT_HOME/webapps/iteraplan/WEB-INF/classes

Copy Graphics Reactor Contents

The iteraplan Graphics Reactor stores all input and output files in the file system. Copy the contects of $TOMCAT_BACKUP/webapps/iteraplan/WEB-INF/classes/reactor from the backup to the corresponding directory in the new installation. It’s okay if no files are to be copied.

Enable Compression within Tomcat

To speed up the initial load of the iteraplan client (amongst other operations) we recommend to enable compression in the Tomcat connector. This is not mandatory, but generally a good idea.

If you want to enable compression, add the following two settings to the connector entry in the Tomcat server.xml file:


Your connector entry might then look like this:

<Connector executor="iteraplanThreadPool"
      port="8080" protocol="HTTP/1.1"

Transfer LDAP authentication settings

If iteraplan was installed with LDAP authentication enabled, simply copy the file from your old installation’s backup to the $TOMCAT_HOME/webapps /iteraplan/WEB-INF/classes/ directory. The contents of the file do not need to be adjusted.

Final restart

As a final step, restart Tomcat to make sure that any modifications to the iteraplan configuration become active. 

3.3 Setup iteraplan 6.2

Initialize the Search Index

Once Tomcat is successfully started, log in to iteraplan with administrative rights.

In order to utilize the full-text search functionality, the search index needs to be re-build. This can be done via the System settings page: Go to Administration -> System and click the "Recreate index" button. The initial run may take several minutes.

3.4 Notes

After the upgrade, some users might report that iteraplan does no longer work as expected. Possible observations might include that buttons have wrong titles or that the client freezes when performing certain tasks.

In this case users should clear their local browser cache and re-login into iteraplan.

  • No labels