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
- 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
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).
- 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:
- 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.
- 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.
- At the end of installation, select None for Which
program do you want to start.
- 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.
- 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
- Verify your configuration files. For details, see Verifying the configuration files
during the upgrade and -migration_qm_updateConfigurationFiles.
- If you are deploying on WebSphere Application Server,
stop and uninstall the version 2 jazz.war and help.war applications.
- 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.
- Create the new Jazz Team Server (JTS)
database and transfer the user and licensing data from the Quality
Management database.
- Export the user data from the Quality Management application
using the following repotools-jazz command:
repotools-jazz -migration_exportJTSData toFile=jtsData.tar
- 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
- 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
- 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 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.
- 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.
- 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).
- Go to jazz/admin and verify that there are no errors.
- 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.
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.