Upgrading to Rational Team Concert 2.0.0.2

Generally, you can upgrade Rational Team Concert™ clients and servers by either performing a zip or IBM® Installation Manager install.
Note: If you use the IBM Installation Manager to install Rational Team Concert 2.0.0.2 on a computer where Rational Team Concert is not currently installed, the Installation Manager prompts you to select the languages to install. However if you update from an earlier version to 2.0.0.2, the IBM Installation Manager assumes that you want to use the current languages and does not prompt you to select languages. To select the additional languages, after you update to 2.0.0.2, select Modify from the main screen in the IBM Installation Manager, then select the offering. The next screen shows the list of supported languages. Select the ones you need.
If you start the Jazz™ Team Server after you update to 2.0.0.2 and before you select Modify to add or remove languages, you must reset the server as follows:
  1. In a Web browser, navigate to
    https://<server-host>:<jazz-port>/jazz/admin?internal#action=com.ibm.team.repository.admin.serverReset
  2. Click Request Server Reset.
  3. Shut down the server.

Then you can select Modify in the IBM Installation Manager to add or remove languages.

Compatibility of Rational Team Concert clients and servers

The following table shows the compatibility of Rational Team Concert client versions with Jazz Team Server versions.
Table 1. Client and server compatibility
Rational Team Concert Client version Compatible Jazz Team Server version
1.0.x for Eclipse 0.6.x
2.0.x for Eclipse 1.0.x
2.0.0.0 for Microsoft Visual Studio 1.0.0.0
2.0.x for Microsoft Visual Studio 1.0.x

Upgrading a Rational Team Concert Client for Eclipse IDE

If you have 1.0, 1.0.1, or 1.0.1.1 versions of the Client for Eclipse IDE, it is required that you obtain the 2.0.x client to connect to your new version 2.0.x server. You can install this using a zip file, or you can update your prior IBM Installation Manager installs.

Installing a Rational Team Concert Client for Microsoft Visual Studio IDE

If you have 1.0.1.1 version of the Client for Microsoft® Visual Studio IDE, it is required that you obtain the 2.0.x client to connect to your new version 2.0.x server.
Remember: A .zip file is not provided for the Client for Microsoft Visual Studio. To install or upgrade to version 2.0.x, you must use IBM Installation Manager.

Upgrading a Server from a Trial or Early Access release to a Permanent release

If you are running an Early Access release of Rational Team Concert, first upgrade to the 2.0.0.2 Trial release.

From the 2.0.0.2 Trial release, you can make your server Permanent by purchasing and installing the Server Activation Kit for your edition, which is available here: http://www.ibm.com/software/awdtools/rtc/. The activation kit consists of a JAR file containing the Permanent server key. It is installed using the License Key Management page of your server's administrative Web interface.

Upgrading a Server from 1.0, 1.0.1, 1.0.1.1, or 2.0

You can upgrade directly to the 2.0.0.2 release of Rational Team Concert from the previous releases. A database migration is required for 1.x to 2.x updates. For information on performing a database migration, see Migrating Jazz repository after upgrading Jazz Team Server.

Note: Before you begin upgrading a WebSphere® Application Server, reset the server by navigating to https://{servername}:9443/jazz/admin#action=com.ibm.team.repository.admin.serverReset and clicking Request Server Reset.

If you installed the previous release from a zip file, then there is no intersection with the previous install. You can install the 2.0.0.2 release from a zip in a new location, or you can use the IBM Installation Manager to install an instance of 2.0.0.2.

If you used IBM Installation Manager to install the previous release, you can either install 2.0.0.2 as a separate instance or update the previous instance to 2.0.0.2. If you install a separate instance of the server for the 2.0.0.2 release, select Create a new package group on the Install Packages page of the installation wizard.

Note: To upgrade a WebSphere Application Server deployment of the Jazz Team Server, remove the previous jazz.war file and deploy the 2.0.0.2 jazz.war file.

To complete the upgrade, see Copying the required configuration files from a previous server installation and Installing 2.0.0.2 Activation Keys.

Upgrading a Server from one Rational Team Concert edition to another

You can upgrade between Rational Team Concert editions. Typical upgrades include moving from Express-C to Express®, or Express to Standard. You can also downgrade in the opposite direction by following the same process.

Because all Rational Team Concert 2.0.0.2 editions support Derby databases, you do not need to migrate from Derby to DB2® or Oracle if you are moving from Express-C to Express or Standard. We recommend that you migrate your server edition first, make sure things work smoothly with the existing database, and then perform a database migration if required. Note that Derby database only supports 10 users. For information on performing a database migration, see Migrating Jazz repository after upgrading Jazz Team Server .

If you have installed a Rational Team Concert 2.0.0.2 edition and want to upgrade to another, download and install the new edition, alongside the existing edition, and then copy the required configuration files to run the new edition. The section below describes the configuration files that you require.

If you installed your previous edition from a zip file, then there is no intersection with the previous install. You can install the new edition from a zip in a new location, or you can use the IBM Installation Manager install for the new edition. We recommend that the IBM Installation Manager be used for production servers to enable future updates to be applied.

If you used IBM Installation Manager to perform your previous server install, and want to use IBM Installation Manager to install your new edition, during the new Installation Manager install, do not overlay the previous edition. On the Install Packages page of the installation wizard, select Create a new package group.

This will install the new edition in a different location and create program shortcuts using the new package group name.

If you do not perform this task, the installation will fail with a file collision. This occurs if you see an error dialog titled Installation Failed, and the details show the following text:
Installation failed.
  Error during "install" phase:
    Failed to extract zip standard 1.0.1.I20081018-1820.  File
    D:\JazzTeamServer\server\license-update-site\site.xml already exists.

If this occurs, it is not fatal; you can restart the installation and correctly create a new package group.

WebSphere Application Server configuration updates

The following steps are required to properly configure WebSphere Application Server in Rational Team Concert 2.0.0.2.
  1. Ensure that the latest fix packs for WAS and WASDK are installed. If deploying in WAS 7.0, it is critical that at least WebSphere Application Server 7.0.0.3 is installed.
  2. Remove the old custom JVM properties:
    1. com.ibm.team.repository.provision.profile
    2. com.ibm.team.server.configURL
    3. log4j.configuration
  3. Add the new custom JVM property JAZZ_HOME and set the value to:
    file:///<JazzInstallDir>/server/conf
  4. Ensure that the WAS security setting "Use available authentication data when an unprotected URI is accessed" is checked. If you are using the WAS Integrated Solutions Console, you can do this by:
    1. Navigating to Security -> Secure administration, applications, and infrastructure -> Web Security - General Settings.
    2. Selecting the checkbox for "Use available authentication data when an unprotected URI is accessed".

Copying the required configuration files from a previous server installation

Copy the following files from the source server to the target server. First, rename the original files in the upgraded server install to create backups. If you used the IBM Installation Manager to update from 1.0, 1.0.1, or 1.0.1.1, or 2.0 to 2.0.0.2, a backup directory containing your 1.0.x or 2.0 configuration files was created with a name, such as backup-config-timestamp in the server subdirectory of the installation location.

If you are upgrading to Standard or Enterprise edition, and you have purchased the Developer Client Activation Kit for Express, purchase and install the Developer Client Activation Kit for Standard or Enterprise Editions, so that you can use those client licenses. Your Developer license assignments will still be in effect, but the Developer licenses will be deactivated until the correct activation kit is installed.

Installing 2.0.0.2 Activation Keys

The 2.0.0.2 release uses the 2.0.0.2 Activation keys. If a server is upgraded from 1.0.x.x to 2.0.x, it reverts to a trial license after the upgrade, and you need to obtain the 2.0 or 2.0.0.2 activation keys from IBM Rational License Key Center.

For more information on the IBM Rational License Key Center, see the IBM Rational licensing support site and the related jazz.net Tech Tip.

Below are the names of the applicable keys for each kit:

  • IBM Rational Team Concert Express Edition Server Activation Kit V2.0, 2.0.0.2
  • IBM Rational Team Concert Standard Edition Server Activation Kit V2.0, 2.0.0.2
  • IBM Rational Team Concert Enterprise Edition Server Activation Kit V2.0, 2.0.0.2
  • IBM Rational Team Concert Contributor Client Access Activation Kit V2.0, 2.0.0.2
  • IBMRational Team Concert Developer Client Access Activation Kit V2.0, 2.0.0.2
  • IBM Rational Team Concert Express Edition Developer Client Access Activation Kit V2.0, 2.0.0.2
  • IBM Rational Team Concert Floating Contributor Client Access Activation Kit V2.0, 2.0.0.2
  • IBM Rational Team Concert Floating Developer Client Access Activation Kit V2.0, 2.0.0.2

Setting a project timeline

In Rational Team Concert 1.x, projects could have multiple timelines (previously called "development lines") and all of these timelines were considered equal.

In Rational Team Concert 2.0, projects can still have multiple timelines, but one of them can be marked as the "project timeline". When migrating your database to 2.0, the project's primary timeline is not known, so your projects will not have a project timeline set. You can manually update your projects to set the project timeline, after you upgrade to 2.0

Configuring the Source Control Management snapshot

The Source Control Management (SCM) snapshot for the Data Warehouse collects data on streams, including information about the size of streams and the activity (change set and file/folder changes) within it. In version 1.0, this snapshot automatically collected information about all streams. As this can be a costly operation, in version 2.0, the configurability options are added to the SCM snapshot to let the users decide for which streams the data should be collected. The immediate impact of this change is that, unless you configure it, no data will be collected.

To configure the SCM snapshot:
  1. You must have write permissions for the stream that you want to collect data for.
  2. Go to the Reports page in Web UI.
  3. In the left navigation panel, select Administer SCM Snapshot. A list of streams are displayed.
  4. Select the checkbox for one or more streams, and then select Save Changes.

Data will be collected for the selected streams in all subsequent snapshots.

Incompatible changes to BIRT reports

If you have used the BIRT report designer to create your own report templates, you may run into one or more problems when trying to use these reports in version 2.0. You should be aware of the following issues:
  • Changes to the order in which Java and JavaScript classes are resolved. If you have written JavaScript code in your BIRT report which uses the importPackage() statement to import the java.lang package, be aware that unqualified references to Object in the code, which used to refer to the Java class, may now refer to the JavaScript class (and as a result won't work properly). Other classes which are identically named between JavaScript and Java, such as java.util.Date, may have the same problem. The solution is to fully qualify your reference to the Java class and remove the importPackage() statement.
  • Changes to the processing of data sets. In the past, the simple act of binding an element (such as a Label) to a data sets, caused the data set to be processed in its entirety when the element was rendered. This was handy because it meant one could enforce an ordering to data set processing by using (hidden) labels bound to the data sets in the order they should be processed. Now, such a binding will process only the first row of the data set. To get the previous behavior, use a Dynamic Text element and invoke some JavaScript code which will force processing of the entire data set. Total.count() is a good choice.
  • BIRT report designer bugs can cause loss of data. These problems appear when you open a BIRT report design file created in BIRT 2.2.2 (i.e. RTC 1.0) with the BIRT 2.3.2 (i.e. RTC 2.0) report designer. The following issues have been observed:
    • When editing a data set for the first time with BIRT 2.3.2, on the "Parameters" page, the "Default Value" and "Report Parameter" fields may be lost. The workaround is to re-enter the values, or to copy and paste the values from a previous version of the editor. After saving the file with the new values entered, the problem will not recur.
    • When editing a report design file for the first time with BIRT 2.3.2, the default value for report parameters may be lost. This may also occur after the previous problem described. The workaround is to re-enter the values, or to copy and paste the values from a previous version of the editor. After saving the file with the new values entered, the problem will not recur.

    These issues can be very serious if not noticed, as the data gathered by the report could be incorrect. It is a good practice to check each data set and each report parameter when editing a report for the first time with the BIRT 2.3.2 report designer. These problems do not occur for new reports that are created with the BIRT 2.3.2 tools.

    The above changes are made to all Rational Team Concert 2.0 out-of-the-box reports - no action is required on your part. However, if you have manually created report templates in your project area using our out-of-the-box reports, and have not specified an appropriate identifier (consistent with our usage), your report template will not be refreshed when it is migrated. That is, the content will be out of date, and will not work. In that case, you should upload new content for the affected templates, using the appropriate out-of-the-box .rptdesign file.

Import of the Work Items data in the data warehouse

In Rational Team Concert 2.0, there are several schema changes to the work items tables in the data warehouse. As a consequence, when migrating from 1.0 to 2.0, the importer will ignore any warehoused work items data. As a result, when you start the 2.0 server for the first time, your work items reports may not function correctly. The workaround is either to wait for the work items snapshot to run for the first time, or to manually cause it to run after you start the server. On the first run after migration, the work items snapshot will reconstitute the entire historical work items information in the data warehouse. This also means that the first run of the snapshot after migration is likely to take much longer than an average nightly run.

Discovering new reports

In Rational Team Concert 2.0, several new reports are added. While these reports appear in the new process templates that ship with the product, they are not automatically added to the existing project areas on migration. We have added a new action that will help you to discover and deploy these new report templates in your existing project areas after migration. To deploy new report templates:
  1. In the rich client, open the Team Artifacts view.
  2. Expand your project area, expand Reports.
  3. Right-click Report Templates and select Deploy New Templates.

The dialog will help you to discover any report templates which are available but not already deployed to your project area. You may select one or more of them and they will be created. After creation, you may create new reports from those templates using the available menu actions.

Customizations

Changes that you make to work item types, attributes, workflows, roles, and event handlers are preserved when you upgrade from 1.x to 2.0. If you customized a predefined process template (such as Scrum), be aware that if you redeploy the predefined template (in the Process Templates view), you will overwrite your customizations. If you need to redeploy the predefined template, you should first change the name and ID of the predefined template that you customized, so it will not be overwritten.


Feedback

Did this help? You can provide feedback at Jazz.net (registration required): Comment in the forums or submit a bug