Upgrading manually from version 2 to 3.0.1

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

  1. Review the topics in the section on Planning the deployment and upgrade as needed.
  2. 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
  3. Shut down the version 2 server.
  4. 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.
  5. During installation, select Use Rational Team Concert 2.x context root to preserve the /jazz context root.
  6. At the end of installation, select None for Which program do you want to start.
  7. 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.
  8. 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.
  9. 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.)
  10. Open a command window and go to the <3.0.1CCM_install_dir>/server directory.
  11. Run the following command to add tables to the database:
    repotools-jazz -addTables
  12. 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.
  13. 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.
  14. 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 
  15. Run the following command to rebuild text indexes:
    repotools-jazz -rebuildTextIndices
  16. Run the following command to rebuild Lucene and RDF indexes:
    repotools-jazz -reindex
  17. 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.
    1. 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.
    2. 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.
  18. 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.
  19. If you are using Apache Tomcat, see Setting up Apache Tomcat.
  20. 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.
  21. 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.


Feedback