You are not logged in. Click here to log in.

codeBeamer ALM
Last Modified

Search In Project

Search inClear

Tags:  not added yet

Upgrading from older versions

This document describes how to upgrade to codeBeamer 8.x from older codeBeamer 5.x, codeBeamer 6.x or codeBeamer 7.x releases running with MySQL or Oracle.

This method cannot be used for any older codeBeamer versions. For applications developed by the API, see Migrating codeBeamer API Applications.

Only MySql-5.5, 5.6 and 5.7 are supported. Please upgrade your MySql instance before upgrading your codeBeamer instance.

The old codeBeamer installation will be referred as OLD-CB, the new one as NEW-CB throughout this document.

  1. It is imperative that you make a backup of your codeBeamer database before you upgrade.
  2. During the installation codeBeamer and the database must be stopped. Please ensure all java/javaw and database processes are stopped, otherwise you might end up losing data.

Please note: The upgrade procedure transfers your installation instance data from the old version to the new version. Migration from the new version back to the old version is NOT supported.

When you upgrade mysql to a newer version, do not forget to do the followings:

  • run the following command: "mysql_upgrade -u root -p --force"
  • restart mysqld

You can find more information on this webpage: http://dev.mysql.com/doc/refman/5.7/en/mysql-upgrade.html

Step 1. Install NEW-CB

Install NEW-CB into a new directory (the installation must not be executed into an existing directory) and do not start the CB server at the end of the installation.

If you install on Windows, make sure that you download and install the appropriate 32bit/64bit codeBeamer 7.x release for your platform!

Step 2. Copy repository data

Copy the following directories and files from OLD-CB/repository to NEW-CB/repository: (git, hg, src, svn, and acl.svn might not exist, depending on your RDBMS and SCM):

  • docs
  • git
  • hg
  • src
  • svn
  • acl.svn

Windows:

cd OLD-CB\repository
xcopy docs NEW-CB\repository\docs\ /EH
xcopy git NEW-CB\repository\git\ /EH
xcopy hg NEW-CB\repository\hg\ /EH
xcopy src NEW-CB\repository\src\ /EH
xcopy svn NEW-CB\repository\svn\ /EH
copy acl.svn NEW-CB\repository\

Unix:

$ cd OLD-CB/repository
$ find acl.svn docs git hg src svn | cpio -updv NEW-CB/repository


If you have customized your OLD-CB/repository structure, e.g. mounted external volumes as docs and/or git, hg or svn, then the above procedure might not be appropriate, and, for the given example, you would better unmount the external volumes from OLD-CB/repository and mount to NEW-CB/repository.

If you are upgrading from CB-6.0.0 or newer,

  • you can simply copy OLD-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml to NEW-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml,
  • if you are using Oracle database and you would like to upgrade to CB-7.1 or to a newer version, please continue with step 4 (add the create view privilege), then skip steps 5 to 7 and continue with step 8.
  • in any other cases you can skip the steps 4 to 7 and continue with step 8.

Step 3. Get and install a new license

When upgrading from a release older than CB-7.0, you'll need a new license! Older licenses are not valid any more.

Please read the "Getting Licenses" section in codeBeamer Licensing.

You need to have that license at hand before you continue with the next steps.

Please also consider that you can only request licenses from Intland Software from Monday through Friday, 8:00 - 17:00 GMT+2, and that processing a license request may take hours up to several days!

So do not shut down your live production system or schedule to upgrade overnight or during the weekend until you already have a license for the new system.

To install the new license:

  1. Copy the new license in XML format from the email you received to the clipboard.
  2. Edit NEW-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml and replace the (empty) <license> block with the license data from the clipboard.

Step 4. Database Configuration

There is no automatic migration of the OLD-CB database configuration to the NEW-CB installation.
Unless you change the <database> configuration in NEW-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml and install a new CB-7.x license, codeBeamer 7.x will use its built-in (initially empty) Apache Derby database.

If you configure codeBeamer 7.x to re-use an existing database and have installed a new license, codeBeamer will convert the existing database schema automatically into the new schema upon first startup, and consequently this database cannot be used by OLD-CB any more.
So if you plan to evaluate CB-7.x on your existing data, with the option of going back to the old system, you should operate NEW-CB on a copy of your original data, or at least make a full backup of your database before migration.

MySQL

A MySQL database is not bundled with CB-7.x and it is neither necessary nor recommended that the MySQL database files reside under NEW-CB/repository/mysql.

If you had a MySQL instance installed under OLD-CB/repository/mysql, or were running on MySQL 4.x or older, then you have to setup a new MySQL (5.5.x) instance as an independent service and to migrate the codeBeamer database schema from the old instance to the new instance:

  1. Create a dump of the OLD_CB codeBeamer database schema:
    mysqldump --routines -h localhost -P 3306 -u cbroot -pcbpassword codebeamer > cb.dump
    Please adjust database host, port, username and passwort according to your OLD_CB configuration.
  2. Shutdown OLD_CB instance forever.
  3. Setup a new MySQL instance as an independent service (you can also use an already existing shared MySQL 5.0 or higher instance) and prepare the new codeBeamer schema according to Preparing MySQL Database for Installation.
  4. Import the dump into the new database schema:
    mysql -h localhost -P 3306 -u root -p codebeamer < cb.dump
    Please adjust database host and port according to your NEW_CB configuration. You will also be prompted for the MySQL root password.

Oracle

Please refer to Preparing Oracle Database for Installation and section Database Connectivity in Post-installation Configuration, how to configure an Oracle database for CB-7.x.

For CB-7.1 and newer, the codeBeamer database schema user must have the CREATE VIEW privilege.
Because this privilege was not required in older releases, it is typically missing and your database administrator has to grant it manually.

GRANT CREATE VIEW to <codeBeamer schema user>

Derby

No upgrade is supported for Apache Derby databases!
Please contact Intland Professional Services if you need to upgrade a codeBeamer instance with a Derby database, or want to migrate the Derby database to MySQL or Oracle.

Step 5. LDAP Configuration (Optional)

There is no automatic migration of the OLD-CB LDAP configuration to the NEW_CB installation.

Also the LDAP configuration in CB-5.5 has changed completely, so you cannot simply copy the <LDAP> section from OLD-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml, but instead you should transfer each setting individually to the appropriate sub-section, according to the following mapping table:

Old attribute New section New attribute Hint
connectionURL server url Only if no alternateURL was specified, otherwise use urls
alternateURL server urls connectionURL [, alternateURL]
connectionName server userDn If specified, set anonymousReadOnly="false"
connectionPassword server password
connectTimeout server connectTimeout
readTimeout server readTimeout
referrals server referral
LDAPAuthenticationEnabled realm enabled
userPattern realm userPattern
userBase realm userBase
userSearch realm userSearch
userSubtree realm userSubtree
storePassword realm storePassword
fallback realm fallback
caching cache enabled
cacheSuccessTTL cache successTTL
cacheFailureTTL cache failureTTL
userName mapping name
userPassword mapping password
title mapping title
firstName mapping firstName
lastName mapping lastName
company mapping company
address mapping address
postalCode mapping zip
city mapping city
state mapping state
country mapping country
timeZone mapping timeZonePattern
telephoneNumber mapping phone
mobile mapping mobile
mail mapping email
mailSuffix mapping mailSuffix


Attributes not listed in this table are no longer supported, e.g. "cn", "firstAndLastNameEditable".

Please refer to the section LDAP Access in the Post-installation Configuration document for information on how to re-configure your LDAP access in CB-7.0 again.

Step 6. Email Setup

You can copy your email sending settings from OLD-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml and replace the empty <mail ... ></mail> in NEW-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml.

Step 7. Login/Registration Setup

You can copy your login/registration settings from OLD-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml and replace the empty <login ... </login> in NEW-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml.

Step 8. Port Configuration

If you had configured an Apache server in front of OLD-CB (Tomcat) (via mod_jk), you need to enable the NEW-CB Tomcat AJP 1.3 Connector (typically on port 8009) again.

Please edit ~/NEW-CB/tomcat/conf/server.xml and remove the comments (<!---->) around the section

<Connector port="8009"
               enableLookups="false" redirectPort="8443" protocol="AJP/1.3" URIEncoding="UTF-8" ></Connector>

If you had used a different port for this connection, please adjust the port number as well.

Step 9. Runtime Parameters

If you had customized OLD-CB runtime variables, e.g. special JVM, HEAPSIZE, etc., then you should copy these settings from the OLD_CB start script to the NEW-CB start script.

Operating System Path Script
Unix/Linux/Mac OS X ~/NEW-CB/bin cb
Windows (No Service) ~/NEW-CB/bin cb.bat
Windows (Service) ~/NEW-CB/tomcat/bin cbservice.bat


For changes in ~/NEW-CB/tomcat/bin/cbservice.bat to take effect, you must run the following command manually afterwards

cbservice codebeamer codebeamer

Step 10. Start

Starting with codeBeamer 7.5.0, we introduced a post installation wizard that helps you configure your instance. (Alternatively, you can omit this wizard by selecting the upgrade option during the installation process). When the wizard is finished and every previous configuration is set, the application restarts the server and the upgrade procedure is finished.

Alternatively, you can switch off the wizard manually by modifying the NEW-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml by setting the setup attribute to false in the installation tag:

<installation setup="false" ></installation>

Start the NEW-CB server. The first time the codeBeamer server is started, the database schema will be upgraded to version NEW-CB.

Depending on which version you're upgrading from, and the amount of data in your database, the first startup of the NEW-CB server might take up to 10-120 min, because the database scheme will be updated in the background (the database process might use a lot of CPU).

Do not shutdown or kill the NEW-CB server as long as the database upgrade is in progress, otherwise the database might be corrupted.

Step 11. Logo Configuration

Your old custom logo and welcome text will not be migrated to CB-7.0 automatically.

To restore your custom logo and welcome text manually, you need to Login as system administrator and re-upload your logo file.

You can find the logo file used by OLD-CB at OLD-CB/tomcat/webapps/cb/images/IL_Logo_120x40.gif.

Step 12. Clearing Browser Caches

Because browsers cache javascript files, the cached javascript files must be re-loaded. We strongly recommend clearing the browsers' cache and then re-starting the browser.

Step 13. Starting Re-indexing

After upgrading, the index database is empty thus searching will not provide any matching. Starting with codeBeamer 6.1, re-indexing is automatic after a completed upgrade.
(In older versions, re-indexing was started by the System Administrator (Index link under System Admin tab)).