Upgrading from Older Versions - Simple - Since Codebeamer 21.09 (EMMA)

Check the supported upgrade paths!

To control the whole upgrade process, use this upgrade guide: Upgrading from Older Versions - Advanced - Since 21.09 (EMMA)

Before Emma version, refer to Upgrading from Older Versions - Simple - Before 21.09 (EMMA)

If MySQL or Oracle database were used before upgrading to Codebeamer 21.09 (Emma), take into consideration that only MySQL 8.0 and Oracle 19 are supported from Codebeamer 21.09 (Emma). Upgrade your MySQL/Oracle instance before upgrading your Codebeamer instance.

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.

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

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 Codebeamer server at the end of the installation.

Step 2. Database Upgrade

Upgrade database engine if required. Only MySQL 8.0 and Oracle 19 are supported. See advanced description: Upgrading from Older Versions - Advanced - Since 21.09 (EMMA).

How to export/import MySQL database: Create and Load MySQL Dumps

How to export/import PostgreSql database: Create and Load PostgreSQL Dumps

How to export/import Oracle database: Import and Export codebeamer Database with Oracle

Setting Character Encoding on MySQL

Follow the steps described here: Migrate MySQL database to UTF8MB4 character encoding.

Step 3. Start Upgrade Script

Windows

NEW-CB\upgrade\upgrade.bat

Unix

NEW-CB\upgrade\upgrade.sh

Go through upgrade steps.

In case of errors occurring, fix the problem and start the whole process again. Reinstall new Codebeamer.

Step 4. Get a New License

Check the relevant Release Notes whether a new license is required.

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

Consider that you can only request licenses from PTC Licensing Team from Monday through Friday, 8:00 - 17:00 GMT+2, and that processing a license request may take hours up to several days!

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. Login Codebeamer with System Admin and open System Admin ► License page.
2. Click on [Edit License] button and insert the new License and Save.

For further information on licensing, see pages Managing Licenses and Licensing with FlexLM.

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.

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

Because browsers cache javascript files, the cached javascript files must be reloaded. It is strongly recommended clearing the browsers' cache and restarting the browser.

Step 8. Starting Re-indexing

After upgrading, the index database is empty thus searching will not provide any matching.

Perform a re-indexing of artifacts by going to System Admin ► Indexing, click on [YES, drop file cache and re-index!]

Step 9. Validate Logs

Check if ~/NEW-CB/tomcat/logs/errors.txt contains any error. In case of an error, create a bug ticket on https://codebeamer.com with the attached log files (cb.txt / errors.txt)

Step 10. Git Http-Backend Verification ( Optional, for Windows-Based Installation )

In System Admin > Application Configuration menu 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",[supported upgrade paths|https://intland.com/technical-support/#!/supported-version-software]

Troubleshooting

MisfireHandler: Error Handling Misfires

When seeing the following error in the log files:

ERROR impl.jdbcjobstore.JobStoreTX - MisfireHandler: Error handling misfires: Couldn't retrieve trigger: com.intland.codebeamer.search.IndexerJobContext; local class incompatible: stream classdesc serialVersionUID = -7585049943194384322, local class serialVersionUID = -8731699021495524083

The problem is that single run index triggers (manual triggers - MT) got stuck at shutdown, and do not get to be rescheduled, but rather fail when misfire handler tries to rerun the job.

Run the following SQL script to clean up these triggers:

-- check how many trigger is manually created #1
SELECT COUNT(*) FROM QRTZ_SIMPLE_TRIGGERS WHERE TRIGGER_NAME NOT LIKE 'com.intland%' AND TRIGGER_GROUP = 'DEFAULT';
SELECT COUNT(*) FROM QRTZ_TRIGGERS WHERE TRIGGER_NAME NOT LIKE 'com.intland%' AND TRIGGER_GROUP = 'DEFAULT';

-- check how many trigger is manually created #2
SELECT COUNT(*) FROM QRTZ_SIMPLE_TRIGGERS WHERE TRIGGER_NAME LIKE 'MT_%';
SELECT COUNT(*) FROM QRTZ_TRIGGERS WHERE TRIGGER_NAME LIKE 'MT_%';

If both SELECT statement pairs return the same numbers, execute the following DELETE statements:

-- remove unwanted single run triggers
DELETE FROM QRTZ_SIMPLE_TRIGGERS WHERE TRIGGER_NAME LIKE 'MT_%';
DELETE FROM QRTZ_TRIGGERS WHERE TRIGGER_NAME LIKE 'MT_%';