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.0/6.0.5 to release 6.1. 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.0 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 Ready to start?

Please ensure that the following points have been considered before starting the iteraplan upgrade to relaese 6.1:

  • Migration of saved queries from the Classic Client
  • Migration of the history data (see chapter 3.1)
  • Object-related permissions: No longer present in iteraplan
  • Time series (not date intervals attributes): No longer present in iteraplan
  • Excel templates for the Spreadsheet Reports & Visio templates for Information Flow Diagram
  • Seal functionality at Information System Elements: No longer present in iteraplan.
  • Audit log file: No longer present in iteraplan.

If these points have not been taken care of, some data might be lost irrecoverably.

2.2 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 Migrate history data


  • the history function has never been active in the past or
  • you already migrated the history data when upgrading to the release 5.4 / 5.5 / 6.0 or 
  • you do not want to keep the history data,

skip this chapter completely and proceed with chapter 3.2.

If you want to migrate your history data from previous version, please proceed with the following steps. Please be aware that these steps need to be done after the database structure has been upgraded to version 6.0/6.0.5, but before the upgrade of the database structure to 6.1 is done (chapter 3.2). The latter one will remove the old history data.


The history migration will take several hours. Our internal test show times from 5 up to 20 and more hours. We strongly recommend to run this long-running job over night and/or on a weekend. During this job iteraplan needs to be shut down to prevent data inconsistency.

This migration needs to be run only once.

iteraplan 5.4 and later comes with a reworked implementation of its historization functionality. If the history functionality has been enabled in older iteraplan versions and you want to migrate that history data to be used in iteraplan 6.1, the provided history migration tool has to be executed once.

To run the history migration tool, proceed as follows:

  1. Backup your iteraplan database, if not already done.

  2. Extract the provided file into a folder. The folder has to be located on the same computer or virtual machine like iteraplan is running on.

    After extraction of the zip-file, the folder should contain the following files:

    • historyMigrationTool.jar

    • migrateHistory.bat (for Windows systems)

    • (for Unix systems)

  3. Copy the following files from your old iteraplan installation to the folder with the migration tool:

    1. from the $TOMCAT_HOME/webapps/iteraplan/WEB-INF/classes folder:, and

    2. from $TOMCAT_HOME/lib: The jdbc driver jar file corresponding to your database:

        • for MS SQL Serversqljdbc[version].jar (for example sqljdbc4.jar)

        • for Oracleojdbc[version].jar (for example ojdbc6.jar)
        • for MySQL: mysql-connector-java-[version].jar (for example mysql-connector-java-5.1.31.jar)

                          If more than one of those files exists, only copy the file for the database you use with iteraplan.

  4. Make sure the environment variable JAVA_HOME is set correctly.

  5. Run the shell script appropriate for your operating system: on Linux systems or migrateHistory.bat on Windows systems.

During the migration the history migration tool uses two different log-files. In the file "migration.log" the progress of the tool is tracked. It contains one entry for each element that is migrated. The file "iteraplan.log" contains eventual exceptions.

If it is not possible to migrate a single change set, this is logged in both files. The migration of other changesets is not affected in this case. If there is an error during the migration, please contact the iteraplan customer support.

3.2 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.0To6.1/ several files are provided:




Replace the placeholder [database] with the database you use.

When upgrading from iteraplan 6.0, excute both scripts in the proper order. When upgrading from 6.0.5, only execute the second script. To execute the scripts, use a database management tool appropriate for your system.

3.3 Configure the new installation

Before iteraplan 6.1 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.1, 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.1 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.0.

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.4 Setup iteraplan 6.1

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.

Transfer Plugin API scripts

Starting with release 6.1, the plugin API scripts are no longer stored in the filesystem. The scripts are now stored in the iteraplan database together with all other data elements.

To transfer the scripts form the filesystem in the old installation to iteraplan 6.1, go to Administration -> Plugin API and upload the scripts from $TOMCAT_BACKUP/webapps/iteraplan/WEB-INF/classes/scripts one after the other. It’s okay if no files are to be uploaded. Uploading is only neccessary once with this upgrade.

3.5 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