Upgrading offline to 3.0.1 manually

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

  1. 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.
  2. 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
  3. 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.
  4. Stop the IBM Rational Requirements Composer version 2 server.
  5. 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:
  6. Export the data from your existing IBM Rational Requirements Composer version 2 database.
    1. Change to the IBM Rational Requirements Composer version 2 RRC2InstallDir\server directory.
    2. 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.

    Note:
  7. 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.
  8. If you have not installed the Jazz Team Server version 3.0.1, install the Jazz Team Server. Do not run the setup wizard.
  9. 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.

    Note: If you are using an Oracle or SQL Server database, be sure to copy the database driver to the correct location. For details, see Setting up an Oracle database and Setting up a SQL Server database.
  10. 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.

  11. At the end of the installation, select None for Which program do you want to start, click Finish, and then click Exit.
  12. 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.
  13. 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.

  14. 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.
  15. Verify your repository data and configuration files. For details, see Verifying the configuration files during the upgrade.
  16. 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.
  17. If you created a security certificate for use with the previous release, copy the certificate or create one. See Configuring security certificates for details.
  18. 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.
  19. 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.
  20. After the backup is complete, continue with the steps in online migration. See Online migration upgrade steps.

Feedback