This topic describes how to perform upgrading steps manually
for offline migration of the server from IBM® Rational® Requirements Composer
version 2 to version 3.0.1.
Before you begin
Before you begin the upgrade, ensure that the clocks on
all machines are synchronized by using the Network Time Protocol (NTP).
Time is the critical element that enables an event on one network
node to be mapped to a corresponding event on another. 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 an IBM WebSphere® Application Server environment,
change the installation path to one that contains no spaces, such
as C:\IBM\JazzTeamServer. However, if any file
name or file path parameter does contain a space, you must surround
the parameter with double quotation marks. For example, "C:\Program
Files\IBM".
Procedure
- Review the Understanding the deployment and upgrade process topic.
Also review the topics in the following section as required: Planning the deployment and upgrade.
Important: - The original RM version 2 context root (/rdm) and URIs for all
RM artifacts will be preserved. The context root of the Jazz™ Team Server will be changed from /jazz
to /jts.
- If a public URI was set in your version 2 installation, you must
use the same public URI in version 3.0.1.
- Verify that your hardware and software meets or exceeds
the minimum the requirements for your application. See system
requirements. Retrieve the following information from the existing
version 2 teamserver.properties file:
- The public URI property - com.ibm.team.repository.server.webapp.url
- 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 URI in version 3.0.1. If a public
URI was not set, use the version 2 administrative web interface (Advanced
Properties) to set the qualified host name URI (https://hostname.example.com:port)
before upgrading.
The public URI line in the teamserver.properties
file will look similar to this example:
com.ibm.team.repository.server.webapp.url=https\://<hostname.example.com>\:9443/jazz
- Download the IBM Rational Requirements Composer software
and other applications in the Rational solution for Collaborative Lifecycle
Management (CLM) to install on Jazz.net. For instructions, see Downloading the product installation media.
- Stop the IBM Rational Requirements Composer version
2 server.
- Back up your IBM Rational Requirements Composer version
2 database and the teamserver.properties file
to a temporary (tmp) location. The teamserver.properties file
contains the database location, which each application requieres to
connect to the database. By default, this file is located in the InstallDir\server\conf\jazz\teamserver.properties file
in version 2. For backup instructions, see these topics:
- Export the data from your existing IBM Rational Requirements Composer version
2 database.
- Change to the IBM Rational Requirements Composer version
2 RRC2InstallDir\server directory.
- Run the repotools -export Windows command or ./repotools.sh
- export AIX® or Linux systems command, and save
the file outside the IBM Rational Requirements Composer directory
structure, as shown in the following example from version 2.0.1:
Windows: repotools
-export toFile=c:\tmp\rrcdata.tar
AIX or Linux: repotools -export toFile=/tmp/rrcdata.tar
where
the toFile variable specifies the name of the .tar
file that the database is exported to.
- If you have already installed the Jazz Team Server version
3.0.1, stop all version 3.0.1 servers including Jazz Team Server and
other CLM applications and back up your Jazz Team Server version
3.0.1 database and environment. Skip to Step 10.
- If you have not installed the Jazz Team Server version
3.0.1, install the Jazz Team Server.
Do not run the setup wizard.
- If you have not already installed the Jazz Team Server version
3.0.1, and you are using a database other than the default Derby database,
you must create the Jazz Team Server databases.
Databases are required for the Jazz Team Server and
the data warehouse. You do not have to create a database for the Requirements
Management application because that application uses the Jazz Team Server database
for data storage. See the topics in Setting up the database for details about
each database.
- Install the Requirements Management application
to another machine. For instructions, see Installing with IBM Installation Manager.
During
installation, select Use Rational Requirements Composer
2.x context root. This will install the RM application
with the required option to preserve the /rdm version 2 context root
for RM, which is necessary for preserving links to RM artifacts. If
you do not select this option, the upgrade will fail. For details,
see Understanding the deployment and upgrade process.
- At the end of the installation, select None for Which
program do you want to start, click Finish,
and then click Exit.
- If you are deploying on WebSphere Application Server,
stop and uninstall the following version 2 .war files: converter.war, jazz.war, rrc-help.war,
and rdm.war. For more information, see Setting up WebSphere Application Server for the version 3 upgrade.
- Open a new command window from the location where you installed
the Jazz Team Server version
3.0.1, navigate to JTS301InstallDir\server,
and use the following command to merge the version 2 configuration
files with those for version 3.0.1: repotools-jts -migration_rm_updateConfigurationFiles
oldApplicationHome=RRCS20InstallDir/server/conf.
If you installed the Jazz Team Server version
3.0.1 separately from the RM application, such as in a distributed
deployment, you must specify the location of the RM application and
run the script from the Jazz Team Server version
3.0.1 installation directory. In this case, include the newApplicationHome argument.
repotools-jts -migration_rm_updateConfigurationFiles
oldApplicationHome=RRC2InstallDir/server/conf newApplicationHome=<JTS301_install_dir>/server/conf -jtsURL https://<fully qualified domain name>:<port>/jts
Note: The -jtsURL parameter
is the public URI of the Jazz Team Server.
By default, the Jazz Team Server public
URI is derived from the public URI of the application. This parameter
must be specified in a distributed deployment where the Jazz Team Server is
running on a different server instance than the RM application.
This
command completes the following tasks:
- Updates the version 3 JazzInstallDir/server/conf/app/teamserver.properties files
based on the information from the version 2 Jazz JazzInstallDir/server/conf/jazz/teamserver.properties file.
You will be given the opportunity to edit values, such as the Jazz Team Server database
location properties, which is information that the script cannot obtain
from version 2.
Note: If you have not already installed and configured
the
Jazz Team Server version
3.0.1, at this point you must enter the database location property
for the new
Jazz Team Server database
you created earlier in Step
9.
- Copies the version 2 Tomcat users .xml file.
- Merges the version 2 friendsconfig.rdf file,
which contains the list of servers that are set up for cross-repository
integration, with version 30.1.
- Merges the content of the version 2 server.xml and web.xml (LDAP
settings) files with version 3.0.1.
For additional details, see Merging configuration files and -migration_updateConfigurationFiles.
- Import the Rational Requirements Composer data from
the exported version 2 repository to the new version 3 Requirements
Management (RM) repository by using the repotools-jts -importapplicationdata command,
as shown in the following example:
repotools-jts migration_importapplicationdata fromFile=c:\export.tar
where
the fromFile variable specifies the name of the .tar file
that the repository will be imported from.
Note: - If this is a new installation of the Jazz Team Server and
any of the Collaborative Lifecycle Management products, you can include
the createTables parameter in the command link
if you are importing user data into the Jazz Team Server for
the first time. The createTables parameter creates
a Jazz Team Server database
and imports the contents of the .tar file. If there is already an
existing Jazz Team Server database,
do not include the createTables parameter
in the command line, as this will overwrite the existing database.
- If you used floating licenses in IBM Rational Requirements Composer version
2, there is a known issue where you might have to stop the upgrade
script, start the Jazz Team
Server, and install version 3.0.1 floating licenses before you import
your data from the IBM Rational Requirements Composer version
2 database. For more information about how to do this, see https://jazz.net/library/article/659.
- Importing large repositories for Requirements Management version
3.0.1 can lead to OutOfMemoryException errors. If you have significant
numbers of projects and artifacts, increase the -Xmx parameter
in the repotools-jts.bat or repotools-jts.sh script
from the default value of 1500M to a higher value. For best results,
use 4096M if the machine has enough memory.
- To view the detailed Rational Requirements Composer list of changes
that are made to the configuration files, see Rational Requirements Composer changes.
- Verify your repository data and configuration files. For
details, see Verifying the
configuration files during the upgrade.
- After offline migration is finished, back up the Jazz Team Server version
3.0.1 database and environment to a location different from where
you backed up the version 2 database. Back up before you continue
to online migration. Do not overwrite your version 2 database backup.
- If you created a security certificate for use with the
previous release, copy the certificate or create 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) for the
command syntax.
- If you are deploying on IBM WebSphere Application Server,
deploy the 3.0 WAR files and map security roles to a user or group.
For details, see Setting up WebSphere Application Server for the version 3 upgrade and Deploying CLM applications on WebSphere Application Server.
- After the backup is complete, continue with the steps in
online migration. See Online migration upgrade steps.