This topic describes the manual process for upgrading Rational Team Concert™ version
2 to version 3.0.1.
Before you begin
Before you upgrade the server, ensure that you have a completely
up-to-date and valid backup of your Rational Team Concert v2 repository
database.
Ensure that the clocks on all servers are synchronized
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. 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 use Derby for the Rational
Team Concert v2 server, ensure that the repository database is
copied from RTC2.X_install_dir/server/repositoryDB to
the 3.0.1CCM_install_dir/server/conf/jazz/derby directory.
If
you plan to upgrade multiple products, see Upgrade order to
help you decide what to upgrade first.
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.
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
- Shut down the version 2 server.
- If you have not already, install the Jazz™ Team Server and the Change and Configuration
Management (CCM) application to a new location. If you have already
installed Jazz Team Server,
install the Change and Configuration Management application.
- During installation, select Use Rational Team
Concert 2.x context root to preserve the /jazz context
root.
- At the end of installation, select None for Which
program do you want to start.
- Create a separate database for Jazz Team Server with the
same parameters but different database name as your v2 database. For
more information about creating databases, see Setting up the database.
Note: A
separate Jazz Team Server database from the CCM database is required.
Create a new Jazz Team Server database if you have not already done
so.
Important: Open separate command-line windows
to run the version 2 and version 3 repotools commands. Use separate
command-line windows to ensure that there are no conflicts between
the environment variables that the version 2 and version 3 commands
use.
- Navigate to <3.0.1CCM_install_dir>/server and
run the following command to merge the Jazz and
Tomcat configuration file (including friends).
repotools-jazz -migration_ccm_updateConfigurationFiles oldApplicationHome=<2.x_install_dir>/server/conf
By
default, the -migration_ccm_updateConfigurationFiles command
updates both Jazz and Tomcat
configuration files. If Tomcat is not installed and you want to update
only the Jazz configuration
files, you must specify the updateTomcatFiles=false parameter.
The
following tasks are completed with the
-migration_ccm_updateConfigurationFiles command:
- Jazz configuration files:
- teamserver.properties (merges 1 Rational Team Concert file
into 2 files for the team server and the application)
- friendsconfig.rdf (copied 1 Rational Team Concert file
to 1 application file)
- Tomcat files:
- tomcat-users.xml (copies)
Remember: For Tomcat user
database only. The tomcat-users.xml file is copied (not merged with
the existing file). If you are upgrading multiple CLM applications
with a common JTS, you must manually merge the users and group information
in the tomcat-users.xml file. The user and group information will
be different if users are part of different groups in different applications.
For example, userA has JazzAdmins role in CCM and JazzUsers role in
QM. In addition, if some users are present in one application and
not in the other or vice versa, they must manually be added to the
tomcat-users.xml file.
- server.xml (merges)
- web.xml files contained inside application war files (merges 1 Rational Team Concert file
into 2 files for the team server and the application)
Important: It is possible that you have modified
other files in Rational Team Concert version 2, for example, the log4j.properties
file. You must manually merge these files.
For details
about the repotools command, see -migration_ccm_updateConfigurationFiles.
Remember: In the following examples, the location for the teamserver.properties file
is based on the default installation. If you have changed the file
layout for your deployment, ensure you are using the correct locations.
Also the following steps assume that the deployment is on one server.
By default, the newJTSHome parameter value is
derived from the newApplicationHome. If you are
using separate servers for CCM and Jazz Team Server, specify newJTSHome parameter
to point to the Jazz Team Server location. This way, the LDAP, email,
and database location properties will be merged from the Rational
Team Concert version 2 teamserver.properties file.
Also the tomcat configuration files will be copied to the Jazz Team
Server location.
- Verify that your updated properties files contain the following
information:
- The properties are copied from version 2 teamserver.properties file.
- Valid database vendor entries (ensure that the database specified
in the /conf/jts/teamserver.properties exists).
For more information, see Verifying the configuration files during upgrade.
- Verify that friendsconfig.rdf is copied
form <RTC2.X_install_dir>/server/conf/jazz to <3.0.1CCM_install_dir>/server/conf/jazz.
- Verify that tomcat-users.xml was copied
over.
- Open version 3 server.xml file and verify
that contains the information from version 2 (port numbers, LDAP settings
and other modifications).
- Open version 3 web.xml file and verify
that contains the information from version 2 (LDAP settings and other
modifications).
- Verify that a valid, distinct public URL com.ibm.team.repository.server.webapp.url exists
in the teamserver.properties files. (The URL
for the CCM application must be the same as the one used for Rational Team Concert version
2.)
- Open a command window and go to the <3.0.1CCM_install_dir>/server directory.
- Run the following command to add tables to the database:
repotools-jazz -addTables
- Run the following command to export user information from
the Rational Team Concert database:
repotools-jazz -migration_exportJTSData toFile=jtsData.tar
Note: If
you are following this process more than once, use a different file
name for the second tar file. For example, use jtsData2.tar.
- In the machine that the Jazz Team Server is installed,
run the following command to import user information into the Jazz
Team Server database:
Note: If you are not using the default
Derby database, ensure that the Jazz Team Server database referred
to in the conf/jts/teamserver.properties file
is a new database and exists.
repotools-jts -migration_importJTSData fromFile=jtsData.tar createMappingFile=rtc-mapping.txt createTables
Note: If
you are following this process more than once, use a different file
name for the second tar file. For example, use jtsData2.tar.
Attention: When you import the Jazz Team Server data from the
second installation of the CCM application, do not use the createTables parameter.
If CLM applications are already installed on Jazz Team Server and
you use the createTables parameter, you will
lose the user data in the Server.
- Run the following command to import Jazz Team Server user
information into the Rational Team Concert database:
repotools-jazz -migration_importUserMapping fromMappingFile=rtc-mapping.txt
- Run the following command to rebuild text indexes:
repotools-jazz -rebuildTextIndices
- Run the following command to rebuild Lucene and RDF indexes:
repotools-jazz -reindex
- If your version 2 product had a non default index location
and you want to continue to use a customized location for indexes,
you must modify the version 3.0.1 teamserver.properties file
to add the index location.
- Change the value of com.ibm.team.fulltext.indexLocation=conf/jts/indices/workitemindex to
the full path location of the full text index. For example com.ibm.team.fulltext.indexLocation=c:/indices/workitemindex.
- Change the value of com.ibm.team.jfs.index.root.directory=indices to
the full path location of JFS index root directory. For example com.ibm.team.jfs.index.root.directory=c:/indices.
- Verify the following:
- Ensure that the Jazz Team Server database location is different
from the application database location.
- Ensure that index or other file related properties are not
shared between application and Jazz Team Server.
- Ensure that the friendconfig.rdf file
is renamed to friendconfig.rdf.saved.
- If you are using Apache Tomcat, see Setting up Apache Tomcat.
- If you are using WebSphere Application Server, uninstall
your previously installed web applications and redeploy jts.war, ccm.war,
and clmhelp.war provided with 3.0.1 installation.
For further details, see Setting up WebSphere Application Server for the version 3 upgrade.
- 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 the Change and Configuration Management
application or any other CLM applications. (see Running the setup wizard) Use the
administrative web interface if you are adding the Change and Configuration
Management application to an established Jazz Team Server. (see Registering applications with the Jazz Team Server.