Upgrading to Rational Team Concert for System z 2.0.0.2

There are several scenarios you can follow to upgrade from previous versions to Rational Team Concert™ for System z® 2.0.0.2.
In general, you can upgrade Rational Team Concert for System z clients and servers either from a .zip file or using IBM Installation Manager on platforms other than z/OS.
Tip: For Rational Team Concert for System z known problems or additional installation information, go to the Rational Team Concert for System z Release Notes page on Jazz.net.
The process for upgrading to Rational Team Concert for System z 2.0.0.2 is similar to upgrading to Rational Team Concert 2.0.0.2 except for the following considerations:
You can upgrade to Rational Team Concert for System z 2.0.0.2 in several ways, including the following scenarios:
Installing additional languages while upgrading: If you use the IBM® Installation Manager to install Rational Team Concert for System z 2.0.0.2 on a computer where Rational Team Concert for System z is not currently installed, the Installation Manager prompts you to select the languages you want to install. However, if you update from an earlier version to Rational Team Concert for System z 2.0.0.2, the Installation Manager assumes that you want to use the current languages and does not prompt you to select languages. To select additional languages, after you update to 2.0.0.2, select Modify from the main screen in the Installation Manager, then select the offering. The window that opens next displays the list of supported languages. Select the ones you need.
If you start the Jazz™ Team Server for System z 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:9443/jazz/admin.action=com.ibm.team.repository.admin.serverReset.
  2. Click Request Server Reset.
  3. Shut down the server.

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

Upgrading a Rational Team Concert for System z client for Eclipse IDE

Any Eclipse integrated development environment (IDE) client must be v2.0.0.1 or higher to be able to connect to a v2.x server. Although a Rational Team Concert for System z 2.0.0.1 client will connect to a 2.0.0.2 server, we recommended that you install the Rational Team Concert for System z 2.0.0.2 client to connect to your Rational Team Concert for System z 2.0.0.2 server. You can install this client using a .zip file, or you can update your prior IBM Installation Manager installations.
Note: Rational Team Concert 2.0 clients can connect to Rational Team Concert for System z 2.0 servers; however, Rational Team Concert clients cannot perform Rational Team Concert for System z-specific functions.

Upgrading a server from a trial release to a permanent release

From the 2.0 trial release, you can make your server permanent by purchasing and installing the Server Activation Kit for your edition from the Rational License Key Center. Details are available here: http://www.ibm.com/software/rational/support/licensing. The activation kit consists of a .jar file that contains the permanent server key. It is installed using the License Key Management page of your server's administrative Web interface.

Scenario 1: Upgrading a server from Rational Team Concert or Rational Team Concert for System z 1.0.1

You can upgrade directly to the 2.0 release of Rational Team Concert for System z from previous releases of Rational Team Concert or Rational Team Concert for System z. A database migration is required.

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 (for example, on Linux® for System z), then there is no intersection with the previous installation. You can install the 2.0 release from a .zip in a new location, or you can use the IBM Installation Manager to install an instance of 2.0.

If you used IBM Installation Manager to install the previous release, you can either install 2.0 as a separate instance or update the previous instance to 2.0. If you install a separate instance of the server for the 2.0 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 for System z, remove the previous jazz.war file and deploy the 2.0 jazz.war file.

To complete the upgrade, see Copying the required configuration files from a previous server installation and Installing 2.0 activation keys.

Scenario 2: Upgrading from Rational Team Concert for System z 1.0.1 on z/OS

Structural changes have been made to the repository database in version 2.0 that will prevent you from reusing the database from Rational Team Concert for System z 1.0.1 on z/OS. The process for upgrading to 2.0 from Rational Team Concert for System z v1.0.1 consists of the following steps:
  1. Export the v1.0.1 database contents using repotools.
  2. Install and configure the Jazz Team Server for System z v2.0 on the desired target platform. A new database will be created during this step. See Installing Rational Team Concert for System z on z/OS for details on installing the Jazz Team Server for System z 2.0 on your target platform.
  3. Import the .tar file that was created in step one into the v2.0 repository database using repotools.
Exporting the Rational Team Concert for System z 1.0.1 repository database
Use member BLZEXPOR in hlq101.SBLZSAMP to export the contents of the repository database. The sample JCL in this member uses the repotools export command to create a .tar file containing your repository content.

Configure BLZEXPOR by following the instructions in the sample JCL. Submit the modified JCL and check the job log. The job has run successfully only if it ends with return code 300.

The export file will be placed in the HFS location specified by @jazzExport@. The name of the file will be @dbexport@.tar, as defined in BLZEXPOR.

Importing the exported database to Jazz Team Server for System z v2.0 on z/OS
Importing to a Derby database on z/OS
Use member BLZIMPO2 in hlq200.SBLZSAMP to import the v1.0.1 .tar file to your Jazz Team Server for System z v2.0 Derby database. Configure BLZIMPOR as described in the JCL comments, specifying the .tar file exported from the v1.0.1 database.

Submit the modified JCL and check the job log to verify that repotools completed successfully.

Importing to a DB2® database on z/OS
Use member BLZIMPOR in hlq200.SBLZSAMP to import the v1.0.1 .tar file to your Jazz Team Server for System z v2.0 DB2 database. Configure BLZIMPOR as described in the JCL comments, specifying the .tar file exported from the v1.0.1 database.

Submit the modified JCL and check the job log to verify that repotools completed successfully.

To complete the upgrade, see Copying the required configuration files from a previous server installation.

Scenario 3: Upgrading a Rational Team Concert for System z server from 2.0.0.1 to 2.0.0.2

You can upgrade directly to the Rational Team Concert for System z 2.0.0.2 release from previous releases. Additional actions for repository updates might be required, see the Rational Team Concert for System z Release Notes® page on Jazz.net for details.

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 (for example, on Linux for System z), then there is no intersection with the previous installation. You can install the new release from a .zip in a new location, or you can use the IBM Installation Manager to install an instance of 2.0.

If you used IBM Installation Manager to install the previous release, you can either install 2.0 as a separate instance or update the previous instance to 2.0. If you install a separate instance of the server for the 2.0 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 for System z, remove the previous jazz.war file and deploy the 2.0 jazz.war file.

To complete the upgrade, see Copying the required configuration files from a previous server installation and Installing 2.0 activation keys.

Scenario 4: Upgrading from Rational Team Concert for System z 2.0.0.1 to Rational Team Concert for System z 2.0.0.2 on z/OS

The SMP/E installation package contains RTCz 2.0.0.1. You need PTFs to upgrade the z/OS components to 2.0.0.2. The PTFs are available from ShopzSeries, IBM Support Portal, Jazz.net, or your regular service channel.

Search for the following APARs and order the corresponding PTFs: PM04798, PM04800, PM04802, PM05340, PM05341, PM05342, and PM05701.

You must apply these PTFs to the base Rational Team Concert for System z 2.0.0.1 installation using SMP/E. Additional information on the steps to apply the PTFs are included with the PTFs.

Additional configuration steps are required to update your existing configuration after you apply the PTFs.

Additional steps for upgrading an existing Tomcat configuration on z/OS from Rational Team Concert for System z 2.0.0.1 to 2.0.0.2

To redeploy thejazz.war to Tomcat on z/OS, make sure that the new jazz.war exists in the catalina_base/webapps directory and that any temporary jazz.war expansion directories have been removed. On z/OS, the new sample JOB BLZCP221 copies the jazz.war to your work directory in the catalina_base/webapps subdirectory.

You must also delete the directory where the jazz.war was previously expanded. This directory will be named "jazz" and will be found in the same webapps directory (@workPath@/catalina_base/webapps). Finally, you should also delete the Tomcat working directory. On z/OS, delete the contents of the catalina_base/work directory in your @workPath@ directory.

Restart Tomcat and the new jazz.war will be deployed with the new plug-ins provisioned.

Run repotools -addTables after deployment

When upgrading a Rational Team Concert for System z server from 2.0.0.1 to Rational Team Concert for System z 2.0.0.2, you must run the repotools -addTables command.

Create a new JCL member in hlq200.SBLZSAMP called BLZADDT. If you are using DB2, copy sample member BLZEXPOR into BLZADDT. If you are using Derby, copy BLZEXPO2.

Change:
//MAINARGS DD *                                              
-clean                                                       
-configuration @workPath@/eclipse/configuration              
-application com.ibm.team.repotools.rcp.repotools_application
-export                                                      
teamServer.properties=@confPath@/jazz/teamserver.properties  
logFile=@workPath@/logs/exportDb.log                         
toFile=@jazzExport@/@dbexport@.tar 
to:
//MAINARGS DD *                                              
-clean                                                       
-configuration @workPath@/eclipse/configuration              
-application com.ibm.team.repotools.rcp.repotools_application
-addTables                                                     
teamServer.properties=@confPath@/jazz/teamserver.properties  
logFile=@workPath@/logs/addTables.log
Customize the new JOB according to the JCL comments.
Note: You can ignore the JCL comments for @jazzExport@ and @dbexport@ updates.
Submit this job when the server is not running. The job should complete with return code 0.
Tip: You can also copy and modify sample JCL to run other repository tools functions on z/OS.

Additional upgrade information

The following sections contain additional information relevant to all upgrade scenarios.

Upgrading a server from one Rational Team Concert for System z edition to another

The Rational Team Concert for System z editions (Starter, Standard, and Enterprise) are all shipped in trial mode. To upgrade from one edition to another, you must load a combined set of trial activation keys for your target edition. These combined trial keys can be downloaded from https://jazz.net/downloads/rational-team-concert-z/.

The combined trial activation keys are included in a .zip file for your target edition. This combined .zip file is installed using the License Key Management page on your server's administrative Web interface.

Rational Team Concert for System z is shipped as Starter Edition trial mode only for installation on z/OS in version 2.0.0.1 and Standard Edition in version 2.0.0.2. If you need to upgrade to another Rational Team Concert for System z edition on z/OS, you must first upgrade to the edition you need, and then load permanent Server Activation kits and Client Access Licenses for your edition.

WebSphere Application Server configuration updates

The following steps are required to properly configure WebSphere Application Server in Rational Team Concert for System z 2.0.
  1. Ensure that the latest fix packs for WebSphere Application Server and the associated Java™ SDK are installed. If you deploy in WebSphere Application Server 7.0, it is critical that you install at least WebSphere Application Server 7.0.0.3. With WebSphere Application Server 6.1, it is critical that you install at least WebSphere Application Server 6.1.0.25.
  2. Remove the previous custom JVM properties:
    1. com.ibm.team.repository.provision.profile
    2. com.ibm.team.server.configURL
    3. log4j.configuration
  3. If it is not already available, add the new custom JVM property JAZZ_HOME and set the value to:
    file:///<JazzInstallDir>/server/conf   
    on systems other than z/OS.
    On z/OS, set the value to:
    file:///@confPath@
    where @confPath@ is configuration path set in BLZCPDIR.
  4. Ensure that you select the WebSphere Application Server setting Use available authentication data when an unprotected URI is accessed. If you are using the WebSphere Application Server Integrated Solutions Console, you can do this by following these steps:
    1. Navigate to Security > Secure administration, applications, and infrastructure > Web Security - General Settings.
    2. Select Use available authentication data when an unprotected URI is accessed.
  5. Ensure that you have deployed the Rational Team Concert for System z jazz.war file. The jazz.war should be updated to the latest Rational Team Concert for System z version.

Copying the required configuration files from a previous server installation

Copy the following files and directories from the source server to the target server. First, rename the original files in the upgraded server installation to create backups. If you used the IBM Installation Manager to update to Rational Team Concert for System z 2.0, a backup directory containing your 1.0.1 configuration files was created with a name like backup-config-<timestamp> in the server subdirectory of the installation location.

If you are upgrading to the Standard or Enterprise Edition and you have purchased the Developer Client Activation Kit for the Starter Edition, purchase and install the Developer Client Activation Kit for the 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 you install the correct activation kit.

Note: Additional configuration update instructions for Jazz Team Server for System z running on z/OS are available in the PTF packages.

Installing 2.0 activation keys

The Rational Team Concert for System z 2.0 release uses the Rational Team Concert for System z 2.0 activation keys. If a server is upgraded from 1.0.1 to 2.0, or from Rational Team Concert to Rational Team Concert for System z, it reverts to a trial license after the upgrade, and you must obtain the Rational Team Concert for System z 2.0 activation keys from the Rational License Key Center. Below are the names of the applicable keys for each kit:

  • IBM Rational Team Concert for System z Starter Edition - Server License Activation Kit V2.0 Multiplatform (jazz_team_server_starter_zSeries-release.jar)
  • IBM Rational Team Concert for System z Starter Edition - Developer Client License Activation Kit V2.0 Multiplatform (rtcz_starter_developer_unlocked.jar)
  • IBM Rational Team Concert for System z - Contributor Client License Activation Kit V2.0 Multiplatform (rtcz_all_contributor_unlocked.jar)
  • IBM Rational Team Concert for System z Standard Edition - Server License Activation Kit V2.0 Multiplatform (jazz_team_server_standard_zSeries-release.jar)
  • IBM Rational Team Concert for System z Developer Client License Activation Kit V2.0 Multiplatform (rtcz_standard_developer_unlocked.jar)
  • IBM Rational Team Concert for System z Floating Developer Client License Activation Kit V2.0 Multiplatform (rtcz_std_floating-developer_unlocked.jar)
  • IBM Rational Team Concert for System z - Floating Contributor Client License Activation Kit V2.0 Multiplatform (rtcz_std_floating-contrib_unlocked.jar)
  • IBM Rational Team Concert for System z Enterprise Edition - Server License Activation Kit V2.0 Multiplatform (jazz_team_server_enterprise_zSeries-release.jar)

Verifying that you have successfully upgraded

There are two key requirements of a successful Jazz Team Server upgrade to Rational Team Concert for System z 2.0.0.2:
  1. The Jazz Team Server jazz.war Web application from Rational Team Concert for System z 2.0.0.2 must be installed.
  2. The Jazz Team Server must be provisioned with the new plug-ins for Rational Team Concert for System z 2.0.0.2
To be sure that both requirements were successful, complete the following steps:
Step 1:
First, to verify that the jazz.war has been successfully updated, access the Jazz Team Server Administrative Web UI as an administrator (typically at a URL like: https://yourhost:9443/jazz/admin).

The initial Status Summary Installed Products section should show the Jazz Foundation Jazz Team Server as 1.0.0.2 and Rational Team Concert as 2.0.0.2.

If the Installed Products section does not show these levels, you can redeploy the jazz.war. The new jazz.war can be found in the tomcat/webapps subdirectory of the installation directory.
WebSphere
To redeploy the jazz.war to WebSphere Application Server, use the WebSphere Application Server administration console to uninstall or update the existing jazz.war and replace with the new jazz.war.
Tomcat
To redeploy the jazz.war to Tomcat, make sure that the new jazz.war exists in the tomcat/webapps directory and that any temporary jazz.war expansion directories have been removed. The new jazz.war is copied to the tomcat/webapps directory by Installation Manager on platforms other than z/OS. On z/OS, the new sample JOB BLZCP221 copies the jazz.war to your work directory in the catalina_base/webapps subdirectory.
Note: On z/OS, both of these steps are required for Tomcat. Also, you must delete the directory where the jazz.war was previously expanded. This directory will be named "jazz" and will be found in the same webapps directory (tomcat/webapps or catalina_base/webapps). If you had customized the jazz web.xml, you should make a copy before you delete the expansion directory, so that you can integrate your changes with the new web.xml. Finally, you should also delete the Tomcat working directory. On platforms other than z/OS, delete the contents of the server/tomcat/work directory. On z/OS, delete the contents of the catalina_base/work directory in your @workPath@ directory.
Restart Tomcat. You can recheck the status after the restart.
Step 2:
To verify that the Jazz Team Server has been provisioned with the new plug-ins, you can view the Server Provision Status, which shows when the server was provisioned and with which plug-ins. You can accessServer Provision Status using a URL similar to:
https://yourhost:9443/jazz/admin#action=com.ibm.team.repository.admin.provisionStatus
You should see that the server provisioning date and time is after the application of the upgrade to Rational Team Concert for System z 2.0.0.2. If the server has not been reprovisioned since you updated, you can request a server reset via a URL similar to:
https://yourhost:9443/jazz/admin#action=com.ibm.team.repository.admin.serverReset

Click the Request Server Reset button. Restart Tomcat or WebSphere Application Server and verify that the Server Provisioning Status has been properly updated.

Setting a project timeline

In Rational Team Concert 1.0.1 or Rational Team Concert for System z 1.0.1, projects could have multiple timelines (previously called "development lines"), and all of these timelines were considered equal.

In Rational Team Concert for System z 2.0, projects can still have multiple timelines, but only one of them can be marked as the "project timeline." When you migrate your database to 2.0, the primary project 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.1, this snapshot automatically collected information about all streams. As this can be a costly operation, in version 2.0, the configuration options are added to the SCM snapshot to let you decide for which streams the data should be collected. The immediate impact of this change is that, unless you configure it, no data is collected.

To configure the SCM snapshot, perform the following steps:
  1. You must have Write permissions for the stream for which you want to collect data.
  2. Go to the Reports page in the Rational Team Concert for System z Web interface.
  3. In the left navigation panel, select Administer SCM Snapshot. A list of streams is displayed.
  4. Select One or more streams, then select Save Changes.

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

Incompatible changes to BIRT reports

If you used the BIRT report designer to create your own report templates, you might encounter problems when you try 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 that uses the importPackage() statement to import the java.lang package, be aware that unqualified references to Object in the code, which previously referred to the Java class, might now refer to the JavaScript class and, as a result, will not work properly. Other classes that are identically named between JavaScript and Java, such as java.util.Date, might have the same problem. The solution is to fully qualify your reference to the Java class and remove the importPackage() statement.
  • Changes to data set processing: In the past, the act of binding an element (such as a label) to a data set caused the data set to be processed in its entirety when the element was rendered. This was useful because it meant you could enforce an order 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 apply the previous behavior, use a Dynamic Text element and invoke any 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 occur when you open a BIRT report design file created in BIRT 2.2.2 (Rational Team Concert 1.0) with the BIRT 2.3.2 (Rational Team Concert 2.0) report designer. The following issues have been observed:
    • When you edit a data set for the first time with BIRT 2.3.2, on the Parameters page, the Default Value and Report Parameter fields might be lost. The workaround is to reenter the values, or to copy and paste the values from a previous version of the editor. After you save the file with the new values, the problem will not recur.
    • When you edit a report design file for the first time with BIRT 2.3.2, the default value for report parameters might be lost. This might also occur when you edit a data set for the first time with BIRT 2.3.2. The workaround is to reenter the values, or to copy and paste the values from a previous version of the editor. After you save the file with the new values, the problem will not recur.
    Note: These issues can be very serious if you do not monitor them, as the data gathered by the report could be incorrect. Check each data set and each report parameter when you edit 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 for System z 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 Rational Team Concert for System z 2.0 out-of-the-box reports, and you have not specified an appropriate identifier (consistent with Rational Team Concert for System z 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 for System z 2.0, there are several schema changes to the work items tables in the data warehouse. As a result, when you migrate from 1.0.1 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 might not function correctly. The workaround is either to wait for the work items snapshot to run for the first time, or to manually force 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 for System z 2.0, several new reports are added. While these reports appear in the new process templates that ship with the Rational Team Concert for System z, they are not automatically added to the existing project areas when you migrate your data to Rational Team Concert for System z 2.0. To discover and deploy these new report templates in your existing project areas after migration, perform the following steps:
  1. In the Eclipse 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 that opens will help you to discover any report templates that are available but not already deployed to your project area. You can select one or more of them and they will be created. After creation, you can 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.0.1 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 that it will not be overwritten.


Feedback