Upgrading offline to 3.0.1 using the upgrade script

This topic describes how to upgrade IBM® Rational® Requirements Composer from version 2 to version 3.0.1 by using the rm_upgrade script.

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 allows 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 plan to upgrade multiple products, see Upgrade order to help you decide what to upgrade first.

Important: To use the upgrade script in a distributed environment where you install the Requirements Management (RM) application separately from the Jazz™ Team Server, the upgrade script must be able to access the drive or file system where RM is installed. On Windows, for example, the mount must be in this form: mounted drive letter:\server\conf. An absolute path, such as \\<machine name>\JTS301InstallDir\server\conf will not work. The mounted drive must be configured with read-write-execute privileges for the administrator account.

You can follow these upgrading instructions for using the upgrade script if you have a single server deployment or if you are have a distributed deployment and you can mount a drive from Jazz Team Server and Requirements Management.

If you are using a distributed network deployment and you are not allowed to mount the drive or if you are an advanced administrator and you plan to complete each step manually, then you can follow the Upgrading offline to 3.0.1 manually instructions. The manual steps detail what the scripts are performing.

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 contains a space, you must surround the parameter with double quotation marks, for example, "C:\Program Files\IBM".

Procedure

  1. Review this topic Understanding the deployment and upgrade process. 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 the 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 requirements for your application, see system requirements. Verify the following information in the current 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:
    com.ibm.team.repository.server.webapp.url=https\://hostname.example.com\:9443/jazz
  3. Download the IBM Rational Requirements Composer software and any other applications in the Rational solution for Collaborative Lifecycle Management (CLM) to install from the appropriate project page on Jazz.net. For instructions, see Downloading the product installation media.
  4. Stop the IBM Rational Requirements Composer version 2 server.
  5. Back up the 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 requires 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 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 selection 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. Failure to select this option will result in a failed upgrade. For details, see Understanding the deployment and upgrade process.

  11. At the end of 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. Run the offline upgrade script. Open a new command window from the location where you installed the Jazz Team Server version 3.0.1, navigate to JTS301InstallDir\server, and run the upgrade\rm_upgrade.bat upgrade script on Windows or the upgrade/rm_upgrade.sh upgrade script on AIX or Linux systems. When the script runs, it will use the language setting of the compute locale.
    Note: You can run the script by specifying all the arguments on the command line. Alternatively, if you are going to rerun the upgrade script multiple times, you can also edit the script parameters file and run an abbreviated command line. See Step 14 for instructions about the parameters file.
    Important:
    • Although the script file is located under the upgrade directory, it must be run from the server directory. Also if your path contains spaces, ensure that you enclose the path name in double quotation marks.
    • If you used floating licenses in 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.

    If you installed the Jazz Team Server version 3.0.1 together with the RM application, and this upgrade is for the first or only application you are upgrading, the command syntax is as follows:

    Windows:

    upgrade\rm_upgrade.bat -oldApplicationHome RRC2InstallDir\server\conf -importFromFile c:\tmp\export.tar -createJTSTables 

    AIX or Linux:

    ./upgrade/rm_upgrade.sh -oldApplicationHome RRC2InstallDir/server/conf -importFromFile /tmp/export.tar -createJTSTables 
    Note: The -createJTSTables parameter applies to installations where you are installing the Jazz Team Server version 3.0.1 and any of the Collaborative Lifecycle Management products for the first time. You do not have to include this parameter in the command if you are installing the RM application by itself, because the Jazz Team Server version 3.0.1 exists elsewhere. 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 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.

    Windows:

    JTS301InstallDir\server upgrade\rm_upgrade.bat -oldApplicationHome RRCS2InstallDir\server\conf -importFromFile c:\tmp\export.tar -newApplicationHome RRC301InstallDir\server\conf -jtsURL https://fully qualified domain name:port/jts

    AIX or Linux:

    JTS301InstallDir/server ./upgrade/rm_upgrade.sh -oldApplicationHome RRCS2InstallDir/server/conf -importFromFile /tmp/export.tar -newApplicationHome RRC301InstallDir/server/conf -jtsURL https://fully qualified domain name:port/jts
    Note:
    • If you have a distributed deployment and have not configured the Jazz Team Server version 3.0.1, you can add the -createJTSTables parameter to the preceding command line example.
    • The -jtsURL parameter is the Public URI of the Jazz Team Server. By default, the Jazz Team Server public URI is derived from the application public URI. 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.

    For more details about command-line options, type one of these commands:

    Windows: upgrade\rm_upgrade.bat -help

    AIX or Linux: ./upgrade/rm_upgrade.sh -help

    Because of the amount of information to migrate, offline migration can take a long time to complete.
    Attention: During offline migration, you must review the prompts that display the contents of the merged files, specifically the database connection that is specified in the teamserver.properties file and edit the merged files if necessary.

    This script completes the following tasks:

    1. Updates the version 3.0.1 configuration files as follows:
      • Runs the -migration_rm_updateConfigurationFiles command and updates the configuration and Tomcat files. Enter [E] to execute the command, [S] to skip the step, or hit [Enter] to cancel the script execution.
        Important: Do not modify the properties to connect to the data warehouse database, even if they are currently set to Derby. Only use the server setup wizard to modify these properties.
        Note: If you have not already installed 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 that you created earlier in Step 9.
      • After the configuration files are merged successfully, enter [C] to continue. A Notepad window (or a vi editor on the AIX or Linux systems) opens in which you can verify the Jazz Team Server teamserver.properties file. Verify that the Public URI root denoted by the com.ibm.team.repository.server.webapp.url property is correct. Also verify that the database properties are correct. When done, save your changes, if any, and close the editor to continue the script execution.
      • 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 3.0.1.
      • Merges the content of the version 2 server.xml and web.xml (LDAP settings) files with version 3.0.1.
    2. Imports the exported RM version 2 data from the .tar file into the Jazz Team Server version 3.0.1 database by using the repotools-jts -import Windows command or ./repotools-jts.sh -import AIX or Linux systems command.
      Note:
      • Importing large repositories for the Requirements Management application 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 made to the configuration files, see Rational Requirements Composer changes.
  14. Optional: As an alternative to the previous step, you can open the scripts parameters file, modify the default values, and run an abbreviated form of the command line. For detailed information about these values, see rm_upgrade.

    The English and translated versions of the parameters files are located in the JazzInstallDir\server\upgrade\params\rm_params.bat directory on Windows or the ./params/rm_params.sh directory on AIX or Linux systems.

    1. To get the exact name of the parameters file for your language, from the JazzInstallDir\server\upgrade directory, run the locale.bat -rm -showParamFileName command on Windows and the ./locale.sh -rm -showParamFileName command on AIX or Linux systems.
    2. Open the rm_params file, or a translated version of it, for editing and specify values for each parameter. One parameter that must be set is the path to the OLD_APPLICATION_HOME directory. Ensure that the path does not contain any spaces. However, if any file name or file path parameter does contain a space, you must surround the parameter with double quotation marks. For example, set OLD_APPLICATION_HOME="C:\Program Files\IBM\RRCS2002\server\conf". See JazzInstallDir\server\upgrade\doc\rm_help.txt file for information about each parameter.
  15. Verify that your repository data and configuration files were updated. For details, see Verifying the configuration files during the upgrade and -migration_rm_updateConfigurationFiles.
  16. After the offline migration is finished, back up the Jazz Team Server version 3.0.1 database and entire server directory to a location different from where you backed up the version 2 database. Back up before you continue to the 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.
  20. After the backup is complete, continue with the steps in online migration. See Online migration upgrade steps.

Feedback