Upgrading manually to Rational Quality Manager and Jazz Team Server 3.0.1

This topic describes the manual process for upgrading Rational® Quality Manager version 2 to version 3.

Before you begin

Before you begin the upgrade, ensure that the clocks on all machines are synchronized using the Network Time Protocol (NTP). Time is the critical element that allows an event on one network node to be mapped to a corresponding event on another. To avoid problems, these challenges can be overcome by the enterprise deployment of the NTP service. For more information about NTP, visit http://www.ntp.org/ In addition, all servers must use the same authentication method for their users.

If you plan to upgrade multiple products, see Upgrade order to help you decide what to upgrade first.

In a WebSphere® Application Server environment, it is recommended that you change the installation path to one that contains no spaces, such as C:\IBM\JazzTeamServer. If any file name or file path parameter contains a space, you must surround the parameter with double quotes.

If you are upgrading from version 2.0.1 iFix02 or higher, upgrade to version 2.0.1.1 or higher before exporting your data. Then, run the following repotools command on the version 2 server to prevent potential errors with the export-import process.

Windows: repotools -repairRequests

Unix/Linux: ./repotools.sh -clean -repairRequests

Users of versions prior to 2.0.1 iFix02 can ignore this step.

Procedure

  1. Review the topics in the section on Planning the deployment and upgrade as needed.
  2. Verify your existing version 2 teamserver.properties file for the public URL property com.ibm.team.repository.server.webapp.url and for the information to connect to your database server, typically com.ibm.team.repository.db.vendor, com.ibm.team.repository.db.jdbc.location, and com.ibm.team.repository.db.jdbc.password.

    You must use the same public URL in version 3.0.1. If a public URL was not set, use the version 2 administrative web interface (Advanced Properties) to set the qualified hostname URL (https://hostname.example.com:port) before upgrading.

    The public URL line in the teamserver.properties should look similar to this:
    com.ibm.team.repository.server.webapp.url=https\://<hostname.example.com>\:9443/jazz
  3. Download the Rational Quality Manager software from the appropriate project page on jazz.net. For instructions, see Downloading the product installation media.
  4. Stop the version 2 server.
    Note: If you are working in a distributed environment, and you have already installed Jazz™ Team Server 3.0.1, to minimize downtime for the Jazz Team Server and other applications, you can optionally leave the server running until you have finished importing the version 2 data into the version 3 Quality Management (QM) database. At that point, you must stop the Jazz Team Server. You can restart it after you have finished importing the user and licensing data into the Jazz Team Server (14).
  5. Back up your version 2 database and the teamserver.properties file to a temporary location. By default, the teamserver.properties file is located at InstallDir\server\conf\jazz\teamserver.properties in version 2. For backup instructions, see the following topics:
  6. Export the data from your existing version 2 repository using the repotools -export command and save the file outside the Rational Quality Manager directory structure, as shown in the following example from version 2.0.1:
    repotools -export toFile=c:\export.tar teamserver.properties=c:\Program%20Files\IBM\RQM201\server\conf\jazz\teamserver.properties

    where toFile specifies the name of the TAR file that the repository is exported to and teamserver.properties specifies the path to the teamserver.properties file.

    Note: Detailed instructions for using repotools can be found at Getting Started with Repository Migration and at Repotools command line reference. Be sure to use the version of repotools that is included with your existing version 2 product.
  7. If you have not already installed the Jazz Team Server, install the server, the Quality Management application, and the Required Base License Keys to a new location on disk. If you have already installed the server, install the Quality Management application. For instructions, see Installing with IBM Installation Manager.
    Important: Requirements, defects, and other work items are no longer created within the Quality Management application, as they were in version 2. Test teams that want to take advantage of these capabilities must also install Requirements Management and Change and Configuration Management. In a distributed environment, these applications can be installed separately.

    During installation, select Use Rational Quality Manager 2.x context root. This will install the QM application to a context root of /jazz, rather than /qm. This option is required to preserve links to QM artifacts. Failure to select this option will result in a failed upgrade. For details, see Understanding the deployment and upgrade process.

  8. At the end of installation, select None for Which program do you want to start.
  9. If you are using a database other than the default Derby database, create the version 3 databases.

    Databases are required for the Jazz Team Server, Quality Management, Change and Configuration Management, and the Data Warehouse. You do not need to create a database for Requirements Management because Requirements Management uses the Jazz Team Server database for data storage. See the topics in Setting up the database for details about each database.

    Note: If you are using an Oracle or SQL Server database, be sure to copy the database driver to the correct location. For details, see Setting up an Oracle database and Setting up a SQL Server database.
  10. Open a new command window in version 3.0.1(RQM301InstallDir/server) and type repotools-jazz -migration_qm_updateConfigurationFiles oldApplicationHome=RQM2InstallDir/server/conf to merge the version 2 Jazz configuration files with those for version 3.

    If you installed the version 3.0.1 Jazz Team Server separately from the QM application, such as in a distributed deployment, do the following:

    • Mount the drive or file system where the Jazz Team Server is installed.
    • Specify the location of the 3.0.1 Jazz Team Server on the -migration_qm_updateConfigurationFiles command line by including the -newJTSHome argument.

    This command completes the following tasks:

    • Updates the version 3 teamserver.properties files for the applications and JTS based on the information from the version 2 Jazz teamserver.properties file
    • Copies the content of the Tomcat users xml file
    • Copies the friendsconfig.rdf file, which contains list of servers set up for cross-repository integration
    • Merges the content of the version 2 server.xml and web.xml (LDAP settings) files with version 3
  11. Verify your configuration files. For details, see Verifying the configuration files during the upgrade and -migration_qm_updateConfigurationFiles.
  12. If you are deploying on WebSphere Application Server, stop and uninstall the version 2 jazz.war and help.war applications.
  13. Import the Rational Quality Manager data from the exported version 2 repository to the new version 3 Quality Management (QM) repository using the repotools-jazz -import command, as shown in the following example:
    repotools-jazz -import fromFile=c:\export.tar

    where fromFile specifies the name of the TAR file that the repository will be imported from.

    Note: Importing large repositories for Quality Management 3.0.1 can lead to OutOfMemoryException errors. Customers with significant numbers of projects and artifacts should increase the -Xmx parameter in the repotools-jazz.bat or repotools-jazz.sh script from the default of 1500M to a higher value. 4096M is recommended if the machine has enough memory and is running a 64-bit OS.
  14. Create the new Jazz Team Server (JTS) database and transfer the user and licensing data from the Quality Management database.
    1. Export the user data from the Quality Management application using the following repotools-jazz command:
      repotools-jazz -migration_exportJTSData toFile=jtsData.tar 
    2. Import the user and licensing data into the Jazz Team Server database using the following repotools-jts command.
      Important: If this is a new installation of the Jazz Team Server and any of the Collaborative Lifecycle Management products, the repotools-jts command can include the createTables parameter, which creates a new JTS database. If there is already an existing JTS database, do not include the createTables parameter in the command line, as this will overwrite the existing database.
      repotools-jts -migration_importJTSData fromFile=jtsData.tar createMappingFile=mapping-qm.txt createTables 
    3. Import the user mapping data into the QM database using the following repotools-jazz command. The mapping is used by the QM application to communicate with the JTS database.
      repotools-jazz -migration_importUserMapping fromMappingFile=mapping-qm.txt   
  15. If you created a security certificate for use with the previous release, copy the certificate from the previous release or create a new one. See Configuring security certificates for details.
  16. If you are running the Tomcat application server as a Windows service, you must remove and reinstall the service. See Running in Apache Tomcat as a Windows service (32-bit, Rational Quality Manager) for the command syntax.
  17. If you are deploying on WebSphere Application Server, deploy the 3.0 WAR files and map security roles to user or group. For details, see Setting up WebSphere Application Server for the version 3 upgrade and Deploying CLM applications on WebSphere Application Server.
  18. Start your application server, either the version 3 Jazz Team Server or the WebSphere Application Server.
  19. Configure the server and any CLM applications that you installed.

    Run the server setup wizard if you are upgrading the Jazz Team Server together with Quality Management or any of the CLM applications (see Running the setup wizard. Use the administrative web interface if you are adding Quality Management to an established Jazz Team Server (see Registering applications with the Jazz Team Server).

  20. Go to jazz/admin and verify that there are no errors.
  21. Migrate your requirements from version 2 to the Requirements Management (RM) application. For details, see Migrating work-item-based requirements.
    Note: This step is required if you maintained your version 2 requirements internally within Rational Quality Manager. This step is not needed if you used an external requirements provider.
  22. Open your browser, clear the browser cache, and reconnect to your project.
  23. Upgrade your licenses. See Understanding licensing for a brief overview. Then, follow the steps in Installing and managing license keys.
    Note: The Quality Manager and Lab Manager licenses in version 2 are now called Quality Professional licenses in version 3. There are no longer separate Lab Manager licenses. Connector licenses in version 2 are still called Connector licenses, whereas Viewer licenses in version 2 are now called Contributor licenses.
  24. If your help application (clmhelp.war) is on a different server than the current application, configure the location of the help. For details, see Configuring the location of the help in a distributed environment.
  25. Upgrade your dashboards.

    Log into your application as an administrative user and navigate to any page with a dashboard. Then, click Migrate to upgrade all dashboards.

  26. Update your reports.
    1. Start by migrating the version 2 data warehouse. For details, see Migrating report data from version 2.
    2. Then, start the Rational Team Concert client and update to the latest report templates. For details, see Updating the predefined report templates.
    3. If you used Rational Common Reporting in version 2, you must migrate the reports to Rational Reporting for Development Intelligence. For details, see Migrating to Rational Reporting for Development Intelligence.
  27. Verify that the upgrade is complete. For details, see Verifying the upgrade.

What to do next

After the upgrade is complete, proceed to Configuring the Jazz Team Server and the first application after the upgrade.
Note: If you are migrating from Rational Common Reporting, back up your existing Rational Common Reporting data warehouse database before you configure the server. For backup instructions, see the documentation for the relational database management system that hosts your data warehouse.

Feedback