Upgrade to Codebeamer Release 22.10-LTS or Newer Using Two-Phase Upgrading Procedure - Since 22.10-SP7

This guide also applies to the upgrade procedure to Codebeamer releases 2.0.x.x. In case of using any version of the Codebeamer GINA release already, this guide is not relevant for you. Read and follow the instructions provided in this detailed description for the upgrading procedure.

Background

During the tracker configuration upgrade in Codebeamer release 22.10 (GINA) or newer, an unlimited number of scenarios can happen to a tracker throughout its lifecycle. Since the upgrade process attempts to resolve every issue, certain differences can be identified between the tracker configurations and their previous version.

Upgrade Prerequisites

Database Backup

Codebeamer release 22.10-LTS (GINA) or newer contains several database changes and modifications.

It is highly recommended to create a database backup and schedule this operation for the weekend.

Customers who have several Test Case trackers or a significant amount of trackers, some of the operations can take several hours.

Upgrade to the Latest Codebeamer 22.04 Service Pack

Upgrading to Codebeamer release 22.10-SP7 (GINA) is only available when the existing Codebeamer installation is already upgraded to the latest Codebeamer release 22.04 (FELICITY) before.

Test Case Tracker Test Step Field Reorganization

Before starting upgrading to Codebeamer release 22.10-LTS (GINA), it is strongly recommended to check the consistency of the existing Test Case trackers. See wiki page Check Test Step Reuse at Codebeamer Upgrade.

Database Setup

Using the new structure of the tracker configuration consumes significant disc space. Make sure the database can be extended to around 100% of the already used space.

Example:

ALTER SYSTEM SET UNDO_RETENTION = 3600;
create undo tablespace UNDOTBS2 datafile 'UNDOTBS02.DBF' size 5000M;
ALTER SYSTEM SET UNDO_TABLESPACE = UNDOTBS2 SCOPE=BOTH;

Environment Setup and Starting Upgrade Procedure

To set up your environment, follow the below steps:

1. Create a test environment of your production.
2. Stop Codebeamer on the test environment.
3. Upgrade to the latest service pack of Codebeamer release 22.04.
4. Add the following environment variable to the operation system: CB_trackerConfigUpgrade_preUpgradeEnabled=true
5. Restart the Codebeamer instance.
   1. The first phase of the tracker configuration upgrade procedure starts immediately.
   2. After Codebeamer started, it runs in Maintenance mode. Users are no longer allowed to log into Codebeamer.
6. Check whether the first part of the tracker configuration upgrade has been executed.
   1. Check the upgrade statements table: select * from upgrade_statements where statement_id='TrackerConfigComparator-SaveTrackerConfigs' or statement_id='TrackerConfigUpgrade_V2-SaveTrackerConfigs'
   2. Check whether the tracker_configurations_temp and tracker_comparator_temp tables exist. The tracker_configurations_temp table contains the tracker configurations for all tracker revisions which are upgraded by Codebeamer release 22.10 (GINA).
7. Upgrade to the latest service pack of Codebeamer release 22.10.
   1. The second phase of the tracker configuration upgrade procedure starts immediately.
8. Once the upgrade finished successfully, check whether the second part of the tracker configuration upgrade has been executed.
   1. Check the upgrade statements table: select * from upgrade_statements where statement_id='TrackerConfigComparator-CompareTrackerConfig'
   2. Check whether the tracker_configurations_temp, tracker_comparator_temp and upgraded_tracker_id tables exist. The upgraded_tracker_id table contains the IDs of those trackers that were upgraded while the tracker_comparator_temp table contains the possible differences after the upgrade.

Read the Tracker Differences

After the upgrade, the tracker_comparator_temp contains the differences between the previous and the current tracker revisions in the tracker_diff column.

It is recommended to set up another test environment with the production version, check the differences and, if necessary, change the tracker configuration on the Tracker Configuration page. It is also advised to change the template tracker in order to solve this issue in all the children trackers too.

Known limitation : After Upgrading to Codebeamer 22.10 (GINA) Using 22.04-SP7 Export

Field Value Combinations (Also Known As: Depends On)

After the finalizing the upgrade, there can be some extra field value setting configured as default value. This only happens when a child tracker removes an inherited parent tracker field dependency configuration. This is a known limitation for Codebeamer 2.0.0.1 and 22.10-SP8 upgrades, however, the upcoming versions will resolve such changes automatically.

Reading the Tracker Differences if there is no difference reported like "fieldValueCombinations", this step can be skipped.

As a workaround for 2.0.0.1 and 22.10-SP8 versions, execute the following SQL query:

update task_field_value_tuple set tuple_val=null where tuple_val='NULLCOMBINATION';

Affected versions:

• 22.10-SP8
• 2.0.0.1

Using 22.10-SP9 or 2.0.0.2 (or later versions), this step is not necessary.

Clean up the database

Delete the tracker_configurations_temp, tracker_comparator_temp and upgraded_tracker_id tables if the upgrade is successfully executed and validated:

drop table tracker_configurations_temp

drop table tracker_comparator_temp

drop table upgraded_tracker_id