Upgrading to Rational Team Concert for System z 2.0.0.1

There are several scenarios you can follow to upgrade from previous versions to Rational Team Concert for System z® 2.0.0.1.

The process for upgrading to Rational Team Concert for System z is similar to upgrading to Rational Team Concert 2.0.0.1. The key steps involved in this process are:

1. Export the existing Rational Team Concert or Rational Team Concert for System z repository using the repository tools from your current version.
2. Install and configure Rational Team Concert for System z 2.0.0.1 including creating a new database.
3. Import the repository using the Rational Team Concert for System z repository tools.
4. Copy required installation files from a previous server installation.
5. Install Rational Team Concert for System z 2.0.0.1 Activation keys

You can upgrading to Rational Team Concert for System z 2.0.0.1 in several ways, including the following scenarios:

• Upgrading from a previous version of Rational Team Concert to Rational Team Concert for System z 2.0.0.1
• Upgrading from Rational Team Concert for System z 1.0.1 to Rational Team Concert for System z 2.0.0.1 on Linux® for System z
• Upgrading from Rational Team Concert for System z 1.0.1 to Rational Team Concert for System z 2.0.0.1 on z/OS®
• Upgrading from Rational Team Concert 2.0.0.1 to Rational Team Concert for System z 2.0.0.1

If you start the Jazz™ Team Server for System z after you update to 2.0.0.1 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

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 Rational Team Concert for System z 2.0.0.1 client to connect to your new Rational Team Concert for System z 2.0.0.1 server. You can install this using a .zip file, or you can update your prior IBM Installation Manager installations.

Upgrading a Server from a trial release to a permanent release

From the 2.0.0.1 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/rtcz/. 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, or 1.0.1.1

You can upgrade directly to the 2.0.0.1 release of Rational Team Concert from the previous releases. A database migration is required for 1.x to 2.x updates.

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.1 release from a zip in a new location, or you can use the IBM Installation Manager to install an instance of 2.0.0.1.

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

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.0.1 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.0.1 from Rational Team Concert for System z v1.0.1 consists of the following three steps:

1. Export the v1.0.1 database contents using repotools.
2. Install and configure the Jazz Team Server for System z v2.0.0.1 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.0.1 on your target platform.
3. Import the .tar file created in step one into the v2.0.0.1 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's 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 into Jazz Team Server for System z v2.0.0.1 on z/OS

Importing into a Derby Database on z/OS

Use member BLZIMPO2 in hlq200.SBLZSAMP to import the v1.0.1 .tar file into your Jazz Team Server for System z v2.0.0.1 Derby database. Configure BLZIMPO2 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 into a DB2® Database on z/OS

Use member BLZIMPOR in hlq200.SBLZSAMP to import the v1.0.1 .tar file into your Jazz Team Server for System z v2.0.0.1 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.

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

1. Ensure that the latest fix packs for WebSphere Application Server and the associated Java™ SDK are installed. If deploying in WebSphere Application Server 7.0, it is critical that at least WebSphere Application Server 7.0.0.3 is installed. With WebSphere Application Server 6.1, it is critical that at least WebSphere Application Server 6.1.0.25 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
   	

   on systems other than z/OS, or to:

         file:///@confPath@
       

   on z/OS where @confPath@ is configuration path set in BLZCPDIR.
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."
5. Ensure that the Rational Team Concert for System z jazz.war has been deployed.

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 Rational Team Concert 1.0.1 to Rational Team Concert for System z 2.0.0.1, a backup directory containing your 1.0.1 configuration files was created with a name such as backup-config-<timestamp> in the server subdirectory of the installation location.

1. If you are using Tomcat and have changed the configuration, copy over the tomcat/conf directory.
2. If you are using the Tomcat user database, copy over tomcat-users.xml.
3. If you are using Tomcat and you have customized the application deployment descriptor, copy the changes from your modified web.xml file for jazz.war, located in \JazzTeamServer\server\tomcat\webapps\jazz\WEB-INF and reapply them to your new 2.0.0.1-based web.xml.

If you are upgrading to Standard or Enterprise edition, and you have purchased the Developer Client Activation Kit for Starter, 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.1 activation keys

The Rational Team Concert for System z 2.0.0.1 release uses the Rational Team Concert for System z 2.0.0.1 activation keys. If a server is upgraded from 1.0.1 to 2.0.0.1 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.0.1 activation keys from Passport Advantage®. 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.0.1 Multiplatform (jazz_team_server_starter_zSeries-release.jar)
• IBM Rational Team Concert for System z Starter Edition - Developer Client License Activation Kit V2.0.0.1 Multiplatform (rtcz_starter_developer_unlocked.jar)
• IBM Rational Team Concert for System z - Contributor Client License Activation Kit V2.0.0.1 Multiplatform (rtc_all_contributor_unlocked.jar)
• IBM Rational Team Concert for System z Standard Edition - Server License Activation Kit V2.0.0.1 Multiplatform (jazz_team_server_standard_zSeries-release.jar)
• IBMRational Team Concert for System z Developer Client License Activation Kit V2.0.0.1 Multiplatform (rtc_standard_developer_unlocked.jar)
• IBM Rational Team Concert for System z Floating Developer Client License Activation Kit V2.0.0.1 Multiplatform (rtc_standard_floating_developer_unlocked.jar)
• IBM Rational Team Concert for System z - Floating Contributor Client License Activation Kit V2.0.0.1 Multiplatform (rtc_standard_floating-developer_unlocked.jar)
• IBMRational Team Concert for System z Enterprise Edition - Server License Activation Kit V2.0.0.1 Multiplatform (jazz_team_server_enterprise_release.jar )

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.0.1, projects can still have multiple timelines, but one of them can be marked as the "project timeline." When migrating your database to 2.0.0.1, 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.0.1.

Configuring the Source Control 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.0.1, 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 might encounter problems when trying to use these reports in version 2.0.0.1. 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 the processing of data sets: In the past, the 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 useful because it meant you 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 (RTC 1.0) with the BIRT 2.3.2 (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 for System z 2.0.0.1 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 for System z 2.0.0.1, there are several schema changes to the work items tables in the data warehouse. As a consequence, when migrating from 1.0.1 to 2.0.0.1, the importer will ignore any warehoused work items data. As a result, when you start the 2.0.0.1 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 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 for System z 2.0.0.1, 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 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 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.0.1. 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.