Running the RM upgrade script for version 5.0

When you upgrade to version 5.0 of the Requirements Management (RM) application from a release of version 4.x, you must run the RM upgrade script for version 5.0. This article outlines the steps to run the script, provides sample input and output, and describes steps that require special attention.

Before you begin

• When you upgrade, your first step must always be to follow the interactive upgrade guide. This article focuses on the "Upgrading the Requirements Management application" step in the upgrade guide. Before you follow the steps in this article, complete all of the steps before the "Upgrading the Requirements Management application" step.
• You can use the upgrade script only if all of the following conditions are met. To confirm that you can use the script in your environment, check the interactive upgrade guide.
  • Jazz Team Server (JTS) was upgraded to version 5.0
  • All applications are installed on the same server OR the applications are distributed and you can mount shared directories between servers
  • Your server is not running on a double-byte character set Windows server
• Make sure that Jazz Team Server is shut down.
• Copy the teamserver.properties file from JTS_5.0_install_dir\server\conf\jts to RM_5.0_install_dir\server\conf\rm, replacing the existing file.

If you do not plan to use the upgrade script, see Migrating the RM application to V5 from V4.x: Tips, common problems, and workarounds.

About this task

The following procedure contains the steps to use the upgrade script to upgrade a 4.0.6 server to version 5.0. The details of the environment in this example are as follows:

Throughout the process, the upgrade script prompts you to provide and confirm input values, as shown in the following image.

Procedure

To upgrade the Requirements Management application:

1. Log in as a user who has administrative privileges and open a command prompt.
2. Go to the RM_5.0_install_dir\server directory and enter this command:

      upgrade\rm\rm_upgrade.bat -oldApplicationHome RM_4.0.6_install_dir\server\conf
      

   
   Exceptions:
   • If the requirements management context root is not /rm, set the following variables before you run rm_upgrade:

            set JAZZ_PROVISION_PROFILES=5.0_install_dir\server\conf\rdm\provision_profiles
            set JAZZ_CONTEXT_PATH=rdm
            

   • If your Jazz Team Server context root is different from the defaults, use the oldJTSContextRoot and newJTSContextRoot parameters to ensure that the RM configuration files are correctly upgraded. For example:

            upgrade\rm\rm_upgrade.bat -oldApplicationHome RM_4.0.6_install_dir\server\conf -newJTSHome JTS_5.0_install_dir\server\conf -oldJTSContextRoot jazz1 -newJTSContextRoot jts2
            

3. As shown in the next image, you are prompted to enter a JDBC location, which is the location of your new RM database. That database was created in a previous step of the interactive upgrade guide. RM-specific data will be copied from your Jazz Team Server database to the new RM database. The format of the connection string will vary by vendor:
   
   

   DB2	//localhost:50000/RM50:user=db2inst1;password={password};
   SQL Server	//localhost:1433;databaseName=RM50;user=jazzDBuser;password={password}
   Oracle	thin:jazzDBuser/{password}@//localhost:1521/ORCL

   
   
   
   
4. After you enter and confirm your database connection string, you are prompted to enter the password for the database user that is specified in the connection string. In this case, the user is db2admin and the password is Rat1onal.
   
   
   
   
5. If you configured a data warehouse, you are prompted to enter the JDBC location. Because the data warehouse connection string is already written to the teamserver.properties file that you copied from Jazz Team Server before you ran the upgrade script, the value is pre-filled and you can press Enter to accept the default value shown. If the value is not pre-filled, enter the JDBC location by using the vendor specific format as shown in the previous table.
   
   
   
   
6. Enter and confirm the password for the database user that is specified in the connection string for the data warehouse:
   
   
   
   
7. When you are prompted to enter the new indices directory to use to store the RM indices, accept the default value, which will store the indices in the version 5.0 JAZZ_HOME/server/conf/rm/indices directory. If you want to specify an absolute path for the index files, ensure that the path is different from the path for the Jazz Team Server indices. A later step in the upgrade script will reindex the RM data to store the indices in the specified directory.
   
   
   
   After you confirm the indices location, the teamserver.properties file is configured by using the values that you specified in previous steps.
   
   
   
   
8. Verify that the values in the teamserver.properties file are correct. If you notice problems with any of the properties, correct them and save the file. Otherwise, close the editor and the upgrade script will continue.
   
   Figure 1. Notification that the file was merged successfully
   
   
   Figure 2. The teamserver.properties file
   
   
   Figure 3. Updating the database schemas
   
   
   Figure 4. Confirming that you want to update the database tables
   
   
   Figure 5. Starting the migration of the local RM project to RM project associations
   
   
   Figure 6. Initializing the publishing service
   
   
   Note: In the next step, the application has been finalized. Although the text in red suggests that you must run the finalize command, you do not need to run that command when you are using the upgrade script. That text comes from the underlying command that is being run by the upgrade script.
   
   
   
   
9. At this point, you can reindex the RM data. The RM indices will be created in the directory that you specified in the "Enter RM Root Index Directory" step. You can also skip the reindex step; however if you do, the data will be reindexed when you start the server. At that point, you cannot use the application until the indices are built.
   
   
   
   
   
   
   
10. Start the server or servers for the applications that host linked data (ie - CCM/QM/JTS), and then log in to the Jazz Team Server application. By doing so, you ensure that the Jazz Team Server application is initialized and is ready to process requests.
    
    
    
    
11. Enter the ID and password of a user with the JazzAdmin role on the server. If the default ADMIN/ADMIN user ID and password are enabled (Tomcat only), you can accept the defaults. Otherwise, specify a valid user ID and password for a valid user in your directory with the JazzAdmin role.
    
    
    
    
    
    
    The project back links that point to the RM server are updated. At this point, all applications that reference the newly upgraded RM server must be up and running. These applications may be at either 4.x or 5.0.
    
    Please make sure that your 4.x licenses have been replaced with 5.x licenses or you will receive the following error:
    

    ERROR(s):  One or more remote project links could not be updated.  Please ensure that all linked applications server are online, check your username and password, and ensure that the user you are using has a valid license in the target application(s).

    
    Log in to the JTS application before completing this step to ensure there are no errors on the status page. If the upgrade is successful, the following message is shown.
    
    
    

Related topics: Migrating the RM application to V5 from V4.x: Tips, common problems, and workarounds

External links:

• interactive upgrade guide

Additional contributors: None