Skip to end of metadata
Go to start of metadata

Corporate Edition only!

The installation procedure described here applies to iteraplan Corporate Edition only. Lite Edition users should follow the instructions in the bundled README.txt file.

The distribution package comes with the installation utility iteraplanInstaller.jar. You can use this to create application packages (.WAR file) for both iteraplan and iTURM. Both files are configured to the values you enter in the Installer, and can be used for operation in a servlet engine. If necessary, the Installer also creates the data required for running the application – such as an initial user account for administration – in the relevant databases. Launch the iteraplanInstaller with the following command in a command line window:

java -jar iteraplanInstaller.jar

Under Windows, you can also launch the tool by double-clicking the file name in Windows Explorer. After initialization, you will the see the welcome screen.

 iteraplan Installer welcome screen (via Windows Explorer)

The tool features both a graphical and text-based interface and you are automatically presented with the appropriate interface for your environment.

Text-based interface of the installation tool

In the graphical version of iteraplanInstaller you proceed to the next screen form by clicking the Next button. If you are working with the text-based version, please follow the instructions on the screen. You accept the default values – stated in square brackets – by pressing return.


First, you can choose a customization for the authentification mechanism of iteraplan. 

Auth customization screen

If LDAP + SSO option was selected, the (default) principal request header can be modified. If this header name was changed in your IIS, you must set in the next window the new name.  


Principal request header screen

When doing an installation with LDAP, the next step is the configuration of the LDAP connection.

LDAP configuration screen

If the checkbox next to "Encrypt password" is checked, that entered password is saved encrypted. If the checkbox is not set, the password is saved in plain text.

Optionally you can adapt the user search filter, if it does not reflect your directory schema. You can also adapt the role membership filter, if your directory uses an attribute other than 'member' to store role members.

Next, if any LDAP authentication is used, there is no need for installing iTurm. If you choose iTurm authentication, you can install both applications, iteraplan and iTurm. 

Selection of deployable web applications

Creating the iteraplan and/or iTURM WAR File(s)

The first step is to configure the name of the application. With the name of the application you can specify the URI path, from which the application can be addressed in the servlet container. With the default settings and default name "iteraplan", the application will be accessible under http://<servername>:<port>/iteraplan. You will also be prompted to name your iTURM installation, if you are installing iTURM as well.

 Form for entering the application name

 You then have to specify the database vendor and parameter, where the application data will be stored, as it is illustrated in the figure below. 

Before the Installer tool takes you to the next page, it checks whether it is able to establish a database connection or not. Please make sure the local firewall does not block this connection.

Specify database vendor

Form for entering the iteraplan database parameters. The choice between "ServiceName" and "SID" is only available, when Oracle was selected as database (see hint below).

If the checkbox next to "Encrypt password" is checked, that entered password is saved encrypted. If the checkbox is not set, the password is saved in plain text.

Only for Oracle Databases:

When connecting to a Oracle database, "User name for the DB" represents the "Schema" (as this is the same in Oracle DB). One can either use the Oracle Service Name or the Oracle SID for the database connection. Depending on what is entered in the field "ServiceName or SID", the correct radio button has to be selected below the field.

If you install iTurm, you must specify the database connection for iTurm in a seperate screen.

Next, you specify the folder in which the iteraplan technical log file should be stored. If you leave this field blank, the files are stored in the temp folder of the Tomcat installation. Please note, that these files may be lost if you change the Tomcat installation at a later date. Make sure the servlet engine has read & write access to these paths. If you are also installing iTURM, you will be prompted for its log file path as well.

Specifying the path for the technical log file

In the next step you can adjust the path where iteraplan will store its search index. The Hibernate Search index contains a full-text index of all data entered into iteraplan, in order to make searching efficient. Make sure that the servlet engine has read & write access to the directory you specify here.

 Form for specifiying the search index storage directory of iteraplan

In the following form you can enable Last Modification Logging. With this option enabled, all building blocks in the database are tagged with the login name of the last user who modified the record and the modification time. This information will be visible to all iteraplan users in the GUI.

 Form for enabling GUI display of the last change to business data records

Next, you have the option of initializing the database. This procedure populates the database with essential data.

If you would like to install a newer version of iteraplan using an existing database, please skip this step by leaving the default option No, I will do that at a later time. However, bear in mind that the existing database schemas may have to be adjusted using a special migration script. The individual migration scripts of the according installer can be found within the installer package in the folder "upgrade".

If you are installing iteraplan for the first time and only have a fresh iteraplan database schema as described in (see Creating the Database Schemas), your next step is to initialize it. To do this, activate the option Yes, initialize the database. Please bear in mind that this re-initialized the database and any data already in the database will be irrevocably lost. All tables in the database are deleted, created afresh, and re-initialized with data.

The database initialization process also creates the administrative role iteraplan_Supervisor and a couple of sample user roles. User with the administrative role iteraplan_Supervisor have comprehensive access privileges in iteraplan. You will have to use iTURM or LDAP in order to manage individual users and password and their role memberships.

If you are also installing iTURM, you will also be asked whether you wish to initialize its database.

 Form for choosing whether to initialise the database

If you chose to initialize the database, you are then asked to enter the location of the appropriate JDBC driver (see also Database drivers).

Form for entering the JDBC connector driver location

Form for entering the JDBC connector driver location

The next step is to specify a destination folder into which the iteraplan Installer will copy the generated iteraplan .WAR file. If the CATALINA_HOME environment variable is configured, the Installer suggests the webapps subfolder of the Tomcat installation. Hence, Tomcat will deploy iteraplan automatically.

 Form for selecting where to store the WAR file

On the next dialog page, you have to select the required access protocol for iteraplan users. You can choose between HTTP and HTTPS security, as it is shown in the screenshot below. If you choose HTTPS, all connection attempts to iteraplan will be redirected to a secured HTTPS/SSL connection. This requires that your Tomcat servlet engine accepts HTTPS connections and has an appropriate SSL certificate installed. Please refer to Configuration Options and Notes and to the Tomcat documentation for configuration instructions

By choosing HTTP, iteraplan will accept both unsecured and secured connections. If your Tomcat has a HTTPS connector configured, iteraplan will work with HTTP and HTTPS simultaneously.

Security level selection

If you selected one of the LDAP configurations, the next screen offers the option to specify a group of your LDAP system to which supervisor privileges for iteraplan will be granted.


Supervisor group

Note: If you are doing a new installation (including database setup), you must specify a group that has full access to iteraplan. If you don't do that, you will not be able to access any feature of the application. Members of this supervisor group can configure all privileges for other users or groups within iteraplan. Also the privileges of the choosen supervisor group can be restricted in the application.

Please ensure that the specified LDAP-group is written exactly the same (with upper and lower case)!

On the next page a email address for the iteraplan administrator (who has superuser privileges) can be configured. This setting can be changed in "" file (""). This email address is used to give iteraplan users the option to send problem report links to their iteraplan administrator.

Administrator Email Address

On the last page, use the Execute button to create the .WAR file and – depending on your settings in the form – initialise the database. Show Details -> Output shows the log output of this process; Show Details -> Errors shows any errors that occurred.

When initializing a database, the Installer first attempts to delete existing tables from the database. If a new schema is being created for the database (meaning no tables as yet exist for iteraplan), the Installer issues an error message stating that it is unable to locate the tables to delete. You can safely ignore this message here.

Once generated, the .WAR file is located in the folder you previously specified. When Tomcat is launched, the file is automatically unpacked and the application can then be accessed in the browser. With the default setting, the application can be accessed at http://*servername*:8080/iteraplan/. If you use iTURM for user management, the initial administrator user has the login name system and the password password. For security reasons we strongly recommend to change the default password after installation.

If your iteraplan license key has not been registered yet, please enter license key provided by e-mail on the page http://[HOST]/[iteraplanContext]/client/license_upload.html. For details see here.

Configure Chrome or Chromium

Chrome or Chromium has to be installed on the iteraplan server to enable the Shared Visualization feature. Set the system property chrome_binary in the Tomcat startup configuration, e.g.

CATALINA_OPTS="$CATALINA_OPTS -Dchrome_binary=/path/to/your/google-chrome"
  • No labels