Upgrading Rational Quality Manager to 3.0.1 using the upgrade script

This topic describes how to upgrade Rational® Quality Manager version 2 to version 3 using the qm_upgrade script.

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.

Important: To use the upgrade script in a distributed environment where you install Quality Management separately from the Jazz™ Team Server, the upgrade script must be able to access the drive or file system where the Jazz Team Server is installed. On Windows, for example, the mapping must be of the form mapped drive letter:\server\conf. An absolute path (\\machine name\installdir\server\conf) will not work. The mounted drive must be configured with read-write-execute privileges for the admin account.

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 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 the upgrade script has 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 the script has finished importing the user and licensing data into the Jazz Team Server.
  5. Back up your 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.
    1. Change to the version 2 RQM2InstallDir\server directory.
    2. Run 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:

    Windows: repotools -export toFile=c:\tmp\export.tar

    Unix/Linux: ./repotools.sh -export toFile=/tmp/export.tar

    where toFile specifies the name of the TAR file that the repository is exported to.

    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, download and 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 deploying on WebSphere Application Server, stop and uninstall the version 2 jazz.war and help.war applications.
  10. 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.
  11. In your version 3 installation, open a new command window, navigate to JazzInstallDir\server, and run the upgrade\qm_upgrade.bat script on Windows or the upgrade/qm_upgrade.sh script on UNIX systems.
    Note: You can run the script by specifying all of the arguments on the command line. As an alternative, if you are going to rerun the upgrade script multiple times, you can also edit the script's parameters file and run an abbreviated command line. See 12 for instructions about the parameters file.
    Important: Although the script file is located under the upgrade directory, it must be run from the server directory. Also if your path contains spaces, ensure you enclose it in double quotation marks.

    If you installed the version 3.0.1 Jazz Team Server together with the QM application, and this is the first or only application you are upgrading, the command syntax is as follows:

    Windows:

    upgrade\qm_upgrade.bat -oldApplicationHome RQM201InstallDir\server\conf -importFromFile c:\tmp\export.tar -createJTSTables

    Unix/Linux:

    ./upgrade/qm_upgrade.sh -oldApplicationHome RQM201InstallDir/server/conf -importFromFile /tmp/export.tar -createJTSTables
    Note: The -createJTSTables parameter applies to installations where you are installing the Jazz Team Server 3.0.1 for the first time.

    If you installed the version 3.0.1 Jazz Team Server separately from the QM application, such as in a distributed deployment, you need to specify the location of the 3.0.1 Jazz Team Server and run the script from the QM 3.0.1 installation directory. In this case, include the -newJTSHome argument.

    Windows:

    upgrade\qm_upgrade.bat -oldApplicationHome RQM201InstallDir\server\conf -importFromFile c:\tmp\export.tar -newJTSHome JTS301InstallDir\server\conf

    Unix/Linux:

    ./upgrade/qm_upgrade.sh -oldApplicationHome RQM201InstallDir/server/conf -importFromFile /tmp/export.tar -newJTSHome JTS301InstallDir\server\conf
    Note:
    • If you have a distributed deployment and have not configured the Jazz Team Server version 3.0.1, then you can add the -createJTSTables parameter to the command line example above.
    • The -jtsURL parameter is the Public URI of the Jazz Team Server. By default, the Jazz Team Server public URI is derived from the application's public URI. This parameter must be specified in a distributed deployment where the Jazz Team Server is running on a different server instance than the QM application.
    • If Jazz Team Server 3.0.1 is still running, you must stop it before the script starts the process of migrating user and license information. The Jazz Team Server and any applications that depend on it will be offline.

    If you need more details about command line options, type the following command:

    Windows: upgrade\qm_upgrade.bat -help

    Unix/Linux: ./upgrade/qm_upgrade.sh -help

    This script completes the following tasks:

    1. Updates the version 3 configuration files as follows:
      • Runs the -migration_qm_updateConfigurationFiles command and updates the configuration and Tomcat files. Enter [E] to execute the command, [S] to skip the step, or hit [Enter] to cancel the script execution.
        Note: If you have not already installed the Jazz Team Server version 3.0.1, then at this time you need to enter the database location property for the new Jazz Team Server database that you created earlier in Step 10, or, if you are reusing your Quality Manager version 2 database, ensure that the database has been backed up in case you need to restart the Quality Manager version 2 server.
        Important: Do not modify the properties to connect to the data warehouse database, even if they are currently set to Derby. Only use the server setup wizard to modify these properties.
      • After the configuration files are merged successfully, enter [C] to continue. A Notepad window (or a vi editor on the AIX or Linux systems) opens in which you can verify the Jazz Team Server teamserver.properties file. Verify that the Public URI root denoted by the com.ibm.team.repository.server.webapp.url property is correct. Also verify that the database properties are correct. When done, save your changes, if any, and close the editor to continue the script execution.
      • Copies the version 2 Tomcat users xml file.
      • Merges the version 2 friendsconfig.rdf file, which contains the list of servers set up for cross-repository integration, with version 3
      • Merges the content of the version 2 server.xml and web.xml (LDAP settings) files with version 3
    2. Imports the exported version 2 data from the TAR file into the version 3 Quality Management (QM) database using the repotools-jazz -import command.
      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.
    3. Exports the user and licensing data from the Quality Management (QM) database.
    4. Imports the QM user and licensing data into the Jazz Team Server.
    5. Imports the user mapping data into the QM database. The mapping is used by the QM application to communicate with the Jazz Team Server database.
    Note: To view the detailed Rational Quality Manager list of changes made to the configuration files, see Rational Quality Manager changes
  12. Optional: As an alternative to the previous step, you can open the script's parameters file, modify the default values, and run an abbreviated form of the command line.

    The English and translated versions of the parameters files are located in the directory JazzInstallDir\server\upgrade\params\qm_params.bat on Windows or ./params/qm_params.sh on UNIX systems.

    1. To get the exact name of the parameters file for your language, from the JazzInstallDir\server\upgrade directory, run locale.bat -qm -showParamFileName on Windows and ./locale.sh -qm -showParamFileName on UNIX systems.
    2. Open qm_params or a translated version of it for editing and specify values for each parameter. One of the parameters that must be set is the path to the OLD_APPLICATION_HOME directory. If your path contains spaces, ensure you enclose it in double quotation marks. Refer to JazzInstallDir\server\upgrade\doc\qm_help.txt for information about each parameter.
  13. Verify your configuration files. For details, see Verifying the configuration files during the upgrade and -migration_qm_updateConfigurationFiles.
  14. 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.
  15. If you are running a 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) for the command syntax.
  16. 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.
  17. Start your application server, either the version 3 Jazz Team Server or the WebSphere Application Server.
    Note: If the QM application is installed separately, you will also need to start the CLM application as well.
  18. 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).

  19. 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.
  20. Open your browser, clear the browser cache, and reconnect to your project.
  21. 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.
  22. 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.
  23. 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

  24. 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.
  25. 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 and Registering additional applications with the Jazz Team Server.
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