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
- Review the topics in the section on Planning the deployment and upgrade as needed.
- 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
- Download the Rational Quality Manager software
from the appropriate project page on jazz.net. For instructions, see Downloading the product installation media.
- 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.
- 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:
- Export the data from your existing version 2 repository.
- Change to the version 2 RQM2InstallDir\server directory.
- 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.
- 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.
- At the end of installation, select None for Which
program do you want to start.
- If you are deploying on WebSphere Application Server,
stop and uninstall the version 2 jazz.war and help.war applications.
- 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.
- 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:
- Updates the version 3 configuration files as follows:
- 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.
- Exports the user and licensing data from the Quality
Management (QM) database.
- Imports the QM user and licensing data into the Jazz Team Server.
- 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.
- 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.
- 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.
- 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.
- Verify your configuration files. For details, see Verifying the configuration files
during the upgrade and -migration_qm_updateConfigurationFiles.
- 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.
- 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.
- 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.
- 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.
- 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).
- 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.
- Open your browser, clear the browser cache, and reconnect
to your project.
- 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.
- 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.
- 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
- Update your reports.
- Start by migrating the version 2 data warehouse. For
details, see Migrating report data from version 2.
- Then, start the Rational Team Concert client
and update to the latest report templates. For details, see Updating the predefined report templates.
- 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.
- 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.