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

codebeamer Application Lifecycle Management (ALM)

Announcement: Changes in Codebeamer Technical Support Experience. More Details here.

Search In Project

Search inClear

Tags:  not added yet

Upgrading from older versions - advanced

  • This document describes how to upgrade from codebeamer 7.x or newer releases running with MySQL/Oracle.
  • For applications developed by the API, see REST API (v1).
For tested upgrade paths, see: Upgrading codebeamer
Before you start upgrading, carefully check the codebeamer release specific requirements especially supported Java and MySql/Oracle versions!To upgrade to newer version than 21.09 (Emma), first upgrading to Emma is required.

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. Ensure all java/javaw and database processes are stopped, otherwise you might end up losing data.

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:

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.

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
If you have customized documents directory with "storage-path" application key, copy docs with docs/1 subfolder to NEW-CB/repository in order to pass the initial startup check of the document folder.


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\


$ 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.

Step 3. Database Configuration

When you upgrade from CB 9.3 or newer, copy file from from OLD-CB/config to NEW-CB/config.

In case you upgrade from CB 9.2 or older copy general.xml instead from OLD-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml to NEW-CB/tomcat/webapps/cb/WEB-INF/classes/general.xml.

If you configure codebeamer 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.


  1. Create a dump of the OLD_CB codebeamer MySql schema:
    mysqldump --routines --single-transaction -h localhost -P 3306 --max_allowed_packet=128M -u root -p codebeamer > cb.dump
    Adjust database host, port, username and password 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 --max_allowed_packet=128M -u root -p codebeamer < cb.dump
  5. Adjust Oracle database access data in codebeamer according to your NEW_CB configuration.


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.

codebeamer database schema requires 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>
  1. Create a dump of the OLD_CB codebeamer Oracle schema with appropriate commands.
  2. Shutdown OLD_CB instance forever.
  3. Setup a new Oracle schema as described under Preparing Oracle Database for Installation.
  4. Import the dump into the Oracle schema.
  5. Adjust Oracle database access data in codebeamer according to your NEW_CB configuration.


No upgrade is supported for Apache Derby databases!
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 4. 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.

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, adjust the port number as well.

Step 5. 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 6. Start

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 are 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 7. Get and install a new license

  • Check whether your available license is compatible with target codebeamer release.

  • Read the Getting Licenses section in codeBeamer Licensing.

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

  • 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. Login with System Administrator and paste license to System Admin ► License.

Step 8. Logo Configuration

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 9. Clearing Browser Caches

Since 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 10. Starting Re-indexing

  1. After upgrading, the index database is empty thus searching will not return any match.
  2. Perform a re-indexing of artifacts by going to System Admin ► Indexing ► click on [YES, drop file cache and re-index!]
    Note: during the re-indexing process the search result may not contain all matches, so it is recommended to perform out of business hours.

Step 11. Apache SVN configuration (Optional)

acl.svn and .htaccess files have been moved under the <CB install directory>/repository/access/ directory, check the configuration guide for more details You must login to see this link. Register now, if you have no user account yet.

Step 12. Git http-backend verification ( Optional, for Windows- based installation )

Go to System Admin ► Application Configuration and verify and update the "http-backend" key in "git" section:

"git" : {
      "http-backend" : "C:\\NEW_CB_\\libexec\\git\\mingw64\\libexec\\git-core\\git-http-backend.exe",