Upgrading to version 6.0

Complete the planning checklist

Use this planning checklist to ensure that you are ready to upgrade.

	Planning task	More information
	Use the software product compatibility reports: On this page, you can search and generate reports for a specific product. The information includes prerequisites, product translation into a specific language, end of service, server virtualization environments, and more.	Software product compatibility reports
	Gather required information: Before starting the upgrade process, you must gather and record specific data that is required during the upgrade process, such as URLs, user IDs and passwords, database locations, name of databases installed, and so on.
	Verify that your hardware and software meet the minimum system requirements: New requirements exist for version 6.0, and a few older versions are deprecated. To learn about the new requirements and to see whether your system meets the minimum requirements, click the System requirements link.	System requirements
	Get the product installation media: For a local repository download, you need approximately 5 GB of hard drive space to download and extract your product installation media.	You can download the server installation files from jazz.net
	Review an upgrade topology example.	Distributed enterprise topology Standard single-server departmental topology
	Synchronize the clocks on all servers: In a distributed environment, ensure that the clocks on all servers are synchronized by using the Network Time Protocol (NTP).	For more information about NTP, visit ntp.org
	Understand the upgrade process: Learn about the upgrade process and how the upgrade might affect your deployment.	Understanding the deployment and upgrade process
	Plan for your applications to be unavailable: Your applications will be unavailable for a brief period while you back up everything and update your applications to version 6.0. All of the applications that are connected to Jazz Team Server will be offline while Jazz Team Server is offline. Be sure to provide time to completely back up your existing applications.
	Meet your database prerequisites: You can access the previous release database and copy the derby/repositoryDB directory. You have the correct user name and password. On UNIX systems, use the password for the DB2 instance owner, which is typically the db2inst1 user. Before you start the upgrade process, verify the integrity of the database by running the -verify repotools command. You backed up your database before you started the upgrade process. You have the correct user name and password. Before you start the upgrade process, verify the integrity of the database by running the -verify repotools command. You backed up your database before you started the upgrade process. For more information about backing up databases, see your database vendor documentation. You are using JRE version 6.0 or 7.0, and you are using the ojdbc6.jar driver. You created an environment variable named ORACLE_JDBC_DRIVER_FILE and pointed to the JDBC driver. You have the correct user name and password. Before you start the upgrade process, verify the integrity of the database by running the -verify repotools command. You backed up your database before you started the upgrade process. For information about backing up databases, see your database vendor documentation. You ensured that the Java Database Connectivity (JDBC) driver is installed, and you are using sqljdbc4.jar. You created an environment variable named SQLSERVER_JDBC_DRIVER_FILE and pointed to the JDBC driver. The SQL service is started. Important: Before you start the Quality Management - Requirements Management application upgrade, run statistics to update the database tables. Otherwise, the migration might take several hours. The following tables must contain up-to-date database statistics: REPOSITORY.ITEM_STATES REPOSITORY.ITEM_CURRENTS REPOSITORY.ITEM_TYPES LINKS.AUDITABLE_LINK REPOSITORY_ITEM_STATES REPOSITORY_ITEM_CURRENTS REPOSITORY_ITEM_TYPES LINKS_AUDITABLE_LINK For information about the DB2 database RUNSTATS command, see the DB2 website. For information about the Oracle database DBMS_STATS command, see the Oracle website. For information about the SQL Server database Update Statistics command, see the SQL Server website.	Backing up and Restoring a DB2 database Setting up an Oracle database Setting up an SQL Server database   For information about the verify command, see Repository tools command to verify the integrity of a database
	Learn about licensing: Click the link to learn about licenses in this release.	Managing licensing
	Check browser compatibility: Enable JavaScript in your web browsers so that wizards can be displayed. For web browsers that are used for migrations, make sure that pop-up blockers are disabled.
	Check your Java Virtual Machine options: Make sure that the Java Virtual Machine has the appropriate heap size setting. To set these properties in WebSphere Integrated Solutions Console, click Servers > Server Types > WebSphere application servers > server1. Under Server Infrastructure, click Java and Process Management > Process definition. Under Additional Properties, click Java Virtual Machine. In the Generic JVM arguments field, check that the following lines exist: -Xmx4g -Xms4g -Xmn512m -Xgcpolicy:gencon -Xnocompressedrefs -XX:MaxDirectMemorySize=1G -Xmx4g -Xms4g -Xmn512m -XX:MaxPermSize=768M -XX:ReservedCodeCacheSize=512M -XX:CodeCacheMinimumFreeSpace=2M -XX:MaxDirectMemorySize=1G -Xmx4g -Xms4g -Xmn512m -Xgcpolicy:gencon -Xcompressedrefs -Xgc:preferredHeapBase=0x100000000 -XX:MaxDirectMemorySize=1G Tip: If you need more heap size, then you can use the following setting, replacing {N} with the amount of memory to be used and {N/8} with 1/8 of the total memory. For example, if -Xmx is set to 8g, -Xmn should be set to 1g. -Xmx{N} -Xms{N} -Xmn{N/8} For Rational DOORS Next Generation only: The -Xmn value should be 33% of the -Xmx value. For example, if the -Xmx size is 4gb, the -Xmn should be 1365m. In addition, for large deployments you should increase the Xmx value in the repotools files from the default 1500M to 8192M or higher. This increase in the Xmx value is necessary to improve performance and avoid out out memory errors during the execution of repotools -reindex all command. For more information on how to adjust the repotools command, see the technote link in the More information column.	If you run Jazz Team Server in Apache Tomcat as a Windows service, see Running in Apache Tomcat as a Windows service (64-bit). Setting up a WebSphere Application Server   Technote: Running the "repotools-jts -reindex all" or "repotools-rm -reindex all" command results in Java out of memory CRJZS5856E errors in Rational DOORS Next Generation   Sizing and tuning guide for Rational DOORS Next Generation 6.0: configuration management   Migration guide for Rational DOORS Next Generation 6.0

Optional: Stage a test environment for the upgrade process

You can set up a test environment to verify the upgrade process with real data before you upgrade your production server. You must be careful to maintain the public URL in the test environment to avoid issues with absolute URL links between the test environment and Jazz Team Server and other applications that are in production.

Before you begin

• If your production environment uses IBM WebSphere Application Server, you must deploy the Rational solution for Collaborative Lifecycle Management (CLM) applications on the test WebSphere Application Servers in addition to the steps in this procedure.
• Ensure that you have a backup copy of the production databases for all the applications for which you want to test the upgrade process.
• You can also stage your test environment by using virtual machines. If you use virtual machines, use the same number of virtual machines as in the production installation to replicate the deployment pattern.

About this task

The Rational solution for CLM applications are uniquely identified on a network by their public URL, which is also known as a front-side URL or public URI root. The server and applications generate absolute URLs for resources that are used in stored artifacts, mail notifications, feeds, web access, and for stable resource identification across all applications. These URLs ensure uniform access to all resources that are stored in various repositories and provide consistent query results for artifacts.

These URLs also create requirements when you test the upgrade process by using real production data in a staged environment. The persisted URLs in the repositories refer to artifacts by their production public URL. These references occur for cross-application links, such as a link between a test artifact and a work item, and can also occur for artifacts that are stored in a single application repository with self-referencing URLs. Ensure that the repositories for the test environment and the actual production are isolated from each other.

The ideal setting for a staged environment is a completely isolated subnet with no visibility to the real production server. Where such a setup is not possible, you can use simpler techniques with caution.

Consider the following techniques which provide both isolation and a useful testing environment. The techniques are listed in increasing order of complexity. For each technique, your must first restore a copy of the production database to a test database server. Maintain the same configured public URL for each application and the Jazz Team Server.

Option 1: Test all server applications on one server

You can test everything on one server if the applications to test are hosted on the same server in the production environment and if the test server has enough resources.

• Edit the hosts file on the test server. You can configure an alias for the server by adding the following entry to your system hosts file: 127.0.0.1 qualified.hostname. Substitute qualified.hostname with the fully qualified host name that is used in your production public URL. The hosts file is in the following location:
  • C:\windows\system32\drivers\etc\hosts
  • /etc/hosts
  • Run the CFGTCP command and then enter option 10

Note: Modifying the hosts file is only for testing purposes in a staging environment.

Option 2: Test with multiple servers

You can use this option if you have multiple applications on different servers.

• Record how the public URLs for each server map to the IP addresses of the test servers that are used.
• Edit the hosts file on each test machine by using mappings for all of the test machines that act as staging servers.

Option 3: Separate the subnet

This option provides the greatest isolation, but is the most complex.

This option provides the greatest isolation, but is the most complex.

• Place the test servers and test clients behind a router with no access to the production network.
• Configure a DNS server within this subnet and map the public URL host names to the IP addresses of the test servers that you are using.

Testing clients

To validate your staging environment, you must connect clients to the staged server, for example, a web browser or the Rational Team Concert rich client. The connections must resolve to the hosts in the staging environment and not the production environment. You should either run these clients on one of the servers in the staging environment, or use a dedicated client workstation that includes all the host mappings and is not used in any production environment.

Procedure

The following procedure is for staging a server that hosts Jazz Team Server and the Change and Configuration Management application. Repeat the procedure for each additional staging environment or application.

1. Restore the backup of the production database to the staging database server.
2. Make a copy of the production installation directory of the application and the Jazz Team Server that is being upgraded and paste it into the same location on the staging server.

   Note: If your production environment is configured to use a folder outside the installation path to store the full-text index, you should also copy and paste this folder to the staging server.

3. Important: Replace the database connection parameters in the teamserver.properties file in the server/conf/app directories to point to the connection parameters for the staging copy of the databases.
   • Update the connection string value of com.ibm.team.repository.db.jdbc.location for the application databases.
   • Update the connection string value of com.ibm.team.datawarehouse.db.jdbc.location to modify the connection to the data warehouse database.

   This step is crucial so that when you run the upgrade, you connect to the test copy of the production databases.

4. Edit the hosts file on the staging server so that all URLs point to the staging server and not the production server.

   Example:

   Staging server

   IP address staging server rtc.example.org

   If any of the production servers being upgraded have friend relationships configured to other production servers that are not being staged, add a host entry for those systems and route them to a nonexistent IP address. Example:

   dummy IP address for non_staged_production_server non_staged_production_server_hostname.example.org

   Repeat this process for each non-staged friend relationship. Example:

   dummy IP address for non_staged friend server non_staged friend production server

5. Start the staging server. To check the configuration, create a comment in your production installation and verify that you do not see it in the staging environment.
6. Stop the staging server.
7. Install the new version of Jazz Team Server and applications on your staging server.
8. Follow the upgrade procedure in this guide to upgrade your installation to the new version.

Install the Rational solution for CLM version 6.0

After you install the new version 6.0 applications, ensure to apply the latest interim fix to your installation before you continue with the upgrade. This ensures that your new version 6.0 applications are up-to-date. To check if there are any interim fixes available for your product, visit Fix Central on IBM Support Portal page.

New applications in version 6

If you installed the new applications that ship with CLM version 6.0 such as Global Configuration Management, Data Collection Component, Lifecycle Query Engine, Report Builder, Rational Engineering Lifecycle Manager, or Link Index Provider, after the upgrade is complete run the setup wizard to register these new applications with Jazz Team Server.

Obtain licenses

You must obtain new licenses for version 6.0 applications. Version 6.0 applications do not work with version 5.0.x licenses. However, version 5.0.x applications work with version 6.0 licenses.

If you previously used floating, token, or authorized user single install licenses, install their version 6.0 counterparts. Your existing user license assignments will be kept during installation of version 6.0 licenses.

To update your token licenses:

1. Log into https://hostname.example.com:9443/jts/admin and click Server > License Key Management.
2. In the Floating License Server section, click Add and upload your version 6.0 license file.
3. After upload is complete, there will be 2 entries in the Floating License Server section. Hover over the version 5.x license entry and click the red X icon to delete the entry. If a warning message is shown, click OK.
4. Go to Users > Client Access License Management, select a token license, and confirm that the list of users that had the version 5.x licenses is present.

For more information about licenses, see Managing licenses.

Verify the upgrade

After the upgrade process is complete, use this checklist to determine whether each step was successful.

	Verification task	More information
	Verify that these application configuration files are copied from previous installation to version 6.0: For Jazz Team Server: JTS_6.0_install_dir/server/conf/jts/teamserver.properties For the Change and Configuration Management application: CCM_6.0_install_dir/server/conf/ccm/teamserver.properties For the Quality Management application: QM_6.0_install_dir/server/conf/qm/teamserver.properties For the Requirements Management application: RM_6.0_install_dir/server/conf/rm/teamserver.properties For the Rational Engineering Lifecycle Manager application: RELM_6.0_install_dir/server/conf/relm/teamserver.properties For the Data Collection Component application: DCC_6.0_install_dir/server/conf/dcc/teamserver.properties
	Verify that each teamserver.properties file contains this information: The properties that were copied from the previous version of the teamserver.properties file. A valid, distinct URL in the com.ibm.repository.server.webapp.url property. The URL for the version 6.0 application must be the same as the one that was used in the previous version. Valid database vendor entries. Ensure the database that is specified in each application's teamserver.properties file exists.
	Verify the application servers: Verify that 6.0_install_dir/server/tomcat/conf/tomcat-users.xml contains the information from previous version. If you are using an LDAP registry or you disabled HTTPS or FORM authentication, verify this information: The 6.0_install_dir/server/tomcat/conf/server.xml file contains these code snippets: <Realm className=org.apache.catalina.realm.JNDIRealm ...> </Realm> The 6.0_install_dir/server/tomcat/conf/server.xml file does not contain these code snippets: Realm className=org.apache.catalina.realm.UserDatabaseRealm resourceName=UserDatabase ...> </Realm> If you had other custom settings in the server.xml file, verify that those settings are copied to the 6.0_install_dir/server/tomcat/conf/server.xml file. Verify that web.xml file has the correct <security-role> tags: For Jazz Team Server: JTS_6.0_install_dir/server/tomcat/webapps/jts/WEB-INF/web.xml For Change and Configuration Management application: CCM_6.0_install_dir/server/tomcat/webapps/ccm/WEB-INF/web.xml For Quality Management application: QM_6.0_install_dir/server/tomcat/webapps/qm/WEB-INF/web.xml For Requirements Management application: RM_6.0_install_dir/server/tomcat/webapps/rm/WEB-INF/web.xml For Rational Engineering Lifecycle Manager application: RELM_6.0_install_dir/server/tomcat/webapps/relm/WEB-INF/web.xml For Data Collection Component application: DCC_6.0_install_dir/server/tomcat/webapps/dcc/WEB-INF/web.xml Make sure that these applications are deployed and started: jts.war ccm.war qm.war rm.war converter.war clmhelp.war relm.war dcc.war rs.war	Deploying and starting the server
	Check the server log files: Check these server log files to verify that they contain the post-upgrade information: If you are using a Tomcat server, the log files are in the 6.0_install_dir/server/logs directory. If you are using a WebSphere Application Server, the log files are in the /logs\logs directory.
	Check the public URLs: If you upgraded Jazz Team Server, or any of the CLM applications, make sure that the public URL on the application's status summary page is the same as the URL that was used in the previous version.
	Check the links on the Jazz Team Server Administration page: In a web browser, go to the Administration page of Jazz Team Server at https://hostname.example.com:9443/jts/admin and make sure that no errors are displayed.	Jazz Team Server administrative web interface
	Check the links on the application's Administration page: In a web browser, go to the Administration page of the application at https://hostname.example.com:9443/application context root/admin and make sure that no errors are displayed.	Application administrative web interface
	Run diagnostics on each server and verify that the diagnostics completed successfully: Open a browser and log on to the admin page, for example, https://host.example.com:9443/jts/admin Click the Diagnostics link. It is also a good practice to run the database statistics after the upgrade to help with server performance. For more information about the database stats command, see the planning checklist table in this document.
	Check users, licenses, and link artifacts: Inspect users and licenses Check linked artifacts Check the web client Check indexing by using search Check Rational Team Concert Eclipse or Visual Studio clients	Verifying users, licenses, and link artifacts
	Check application artifacts: Check all projects are listed and can be navigated to Check that all dashboards are available and widgets are working Find and view existing artifacts and verify that the editors open properly In Change and Configuration Management application, verify work items and release plans In Quality Management application, verify test plans, test cases, test suites, and test scripts In Requirements Management application, verify requirements, collections, folders, and graphical artifacts In Requirements Management application, verify that you can display and edit graphical artifacts