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
This guide provides instructions to upgrade iteraplan from release 6.2 to release 6.3. 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.2 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
This guide uses Unix conventions for path names. For Windows, replace slashes (/) with back-slashes (\) and include drive letters where necessary.
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 shutdown.sh 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.2To6.3/ 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.
In case any error occurs during execution of the SQL scripts, do NOT continue with the upgrade process. Contact the iteraplan support team with the error message.
With iteraplan 6.3 some predefined attributes are converted to user defined attributes. The new user defined attributes are organized in an attribute type group "[Core Attributes]". If an attribute type group with this name already exists in iteraplan 6.2 this attribute type group needs to be renamed. This attribute type group can be reorganized with iteraplan 6.3 after the upgrade.
3.2 Configure the new installation
Before iteraplan 6.3 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.3, 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
or by explicitly stating the JRE to use:
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‑db.properties 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
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 hibernate.search.index in the config file
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.3 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.3.
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/iteraplan.properties file or to any other *.properties file in
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
Your connector entry might then look like this:
Transfer LDAP authentication settings
If iteraplan was installed with LDAP authentication enabled, simply copy the
iteraplan-auth.properties 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.
As a final step, restart Tomcat to make sure that any modifications to the iteraplan configuration become active.
3.3 Setup iteraplan
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.
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.