Upgrading Rational Engineering Lifecycle Manager

To upgrade your version of Rational® Engineering Lifecycle Manager to the most recent version you will do a side-by-side installation of the new version.

Before you begin

If you are updating products integrated with Rational Engineering Lifecycle Manager, ensure that you follow the guidance in Upgrade your Rational Engineering Lifecycle Manager product stack

Procedure

  1. Install Rational Engineering Lifecycle Manager using the instructions in Install Rational Engineering Lifecycle Manager and the Lifecycle Query Engine. This will install:
    • Rational Engineering Lifecycle Manager v4.0.6
    • Jazz™ Team Server v 4.0.6
    • The Configuration Management application
    Important:
    • Ensure that you select a different package group and directory than the original install.
    • Ensure that you select the same context root as your previous install.
  2. If you are using WebSphere® Application Server, complete the following.
    1. Backup the WebSphere Application Server profile. Open a command prompt and change to the bin folder of the WebSphere Application Server installation directory. For example, C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\bin. Run the following command. Note that if the WebSphere Application Server security is turned on, you must also supply the user name and password:
      backupConfig.bat <Path to a new compressed file to create backup of profile> <WAS primary administrative user name> <WAS administrative password>
      For example, backupConfig.bat C:\WAS_backup\clm_40_profile.zip -username WAS admin -password WAS admin password.
    2. Uninstall the existing applications from WebSphere Application Server. To uninstall the application war files, go to each application server and perform the following steps.
      1. Log on to the WebSphere Application Server Integrated Solutions Console at https://hostname:9043/ibm/console/logon.jsp.
      2. Click Applications > Application Types > WebSphere enterprise applications.
      3. Stop and uninstall the following applications: relm.war, vvc.war, lqe.war, SPARQL_Gateway.war
      4. Save the changes to the master configuration when prompted.
    3. Update JAZZ_HOME and log4j.configuration custom properties.
      1. Log on to the WebSphere Application Server Integrated Solutions Console at https://hostname:9043/ibm/console/logon.jsp.
      2. Click Servers > Server Types > WebSphere application servers.
      3. Click the server name to open it. The default server name is server1.
      4. Under the Server Infrastructure section click Java and Process Management > Process definition.
      5. Under Additional Properties click Java Virtual Machine.
      6. Change the path for the Lifecycle Query Engine and SPARQL Gateway to the new location.
      7. Locate the Generic JVM arguments text field, and add this environment variable to the JVM startup process: -Dlqe.config.location=file://drive:\lqe_installation_folder\server\conf\lqe
      8. Under Additional Properties click Custom properties.
      9. Click JAZZ_HOME and update its value to file:///4.0.6_install_dir/server/conf. For example, file:///C:/PROGRA~2/IBM/JazzTeamServer_4.0.6/server/conf.
      10. Click log4j.configuration and update its value to file:///4.0.6_install_dir/server/conf/startup_log4j.properties. For example, file:///C:/PROGRA~2/IBM/JazzTeamServer_4.0.6/server/conf/startup.log4j.properties.
      11. If you are connecting to an Oracle database, ensure that ORACLE_JDBC_DRIVER_FILE is pointing to the correct JDBC driver file.
      12. Save the changes to the master configuration when prompted.
    4. Stop the WebSphere Application Server.
    5. Clean up the WebSphere Application Server temp directories. Go to each application server and remove the Rational Engineering Lifecycle Manager related contents from the following wscache and temp directories in the profile. Depending on previous installed applications, the following directories are present under profile and can be removed: relm_war, lqe_war, sparql, and vvc related data.
      WAS_profile_root\wscache (for example: C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\wscache)
      WAS_profile_root\temp (for example: C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\temp)
    6. Clean up the logs directory. Go to each application server and remove the Rational Engineering Lifecycle Manager related logs form the logs directory in the profile. A typical logs directory may be: C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\logs
  3. To migrate your database:
    Option Description
    Derby Delete the Derby databases that were installed with the upgrade, and replace them with the Derby files from the original installation.
    rm -rf $newRELMHome/server/conf/jts/derby/repositoryDB
    rm -rf $newRELMHome/server/conf/jts/indices
    rm -rf $newRELMHome/server/conf/relm/derby/repositoryDB
    rm -rf $newRELMHome/server/conf/vvc/derby/repositoryDB
    cp -R $oldRELMHome/server/conf/jts/derby/repositoryDB $newRELMHome/server/conf/jts/derby
    cp -R $oldRELMHome/server/conf/jts/indices $newRELMHome/server/conf/jts
    cp -R $oldRELMHome/server/conf/relm/derby/repositoryDB $newRELMHome/server/conf/relm/derby
    cp -R $oldRELMHome/server/conf/relm/indices $newRELMHome/server/conf/relm
    cp -R $oldRELMHome/server/conf/vvc/derby/repositoryDB $newRELMHome/server/conf/vvc/derby
    cp -R $oldRELMHome/server/conf/vvc/indices $newRELMHome/server/conf/vvc
    DB2® or Oracle For complete instructions, refer to the documentation supplied by your database vendor. The following is a sample process for DB2 that can be used as a guideline.
    1. Stop your old Jazz Team Server.
    2. In DB2, locate the databases used by the previous install of JTS applications.
    3. Back up each database used by a JTS application.
    4. Right-click the each database, and select Restore > Restore to new database.
    5. Type a name for the database and select the directory that contains the backup.
    6. Open the <JazzInstallDir>/server/conf/jts/teamserver.properties file.
    7. Replace the name of the Jazz database with the name that you provided, as shown in the following example.
      #
      # DB2 configuration
      #
      
      # Comment out above lines, uncomment the following three lines and customize example location to use DB2
      #com.ibm.team.repository.db.vendor = DB2
      #com.ibm.team.repository.db.jdbc.location=//localhost:50000/JAZZ:fullyMaterializeLobData=false;user=db2admin;password={password};
      #com.ibm.team.repository.db.jdbc.password=db2admin
    8. Repeat steps d-g for each database you need to restore.
    9. Save your changes.
  4. Upgrade the Configuration Management application using the vvc_upgrade.bat script. This will upgrade the configuration files, database files, and rebuild the text indices. For a detailed description of how to upgrade the Configuration Management application, refer to the upgrade guide available at: Interactive upgrade guide for Configuration Management An example of the parameters for Linux would be:
    cd $newRELMHome/server/
    upgrade/vvc/vvc_upgrade.sh -oldApplicationHome oldRELMHome/server/conf
    • If you are upgrading a distributed (multiple machine) installation topology, you will need to add the following parameter to the vvc_upgrade script: -oldApplicationHome oldRELMHome/server/conf -ignoreJTSVersionCheck
    • If you are using WebSphere Application Server, you need to add a parameter to the vvc_upgrade script telling it to not upgrade Tomcat:-oldApplicationHome oldRELMHome/server/conf -ignoreJTSVersionCheck -updateTomcatFiles=no
    Note: The Configuration Management application may also be installed with Rhapsody® Design Manager. When you are installing Rational Engineering Lifecycle Manager you will also be offered the option of installing the Configuration Management application - this is useful if you want to install the application on a different machine from Rhapsody Design Manager. Only one of these should be integrated with the Jazz Team Server. If you choose to install the component on multiple machines, be cautious when installing and upgrading the component that you are selecting the correct one.
  5. Upgrade Rational Engineering Lifecycle Manager by running relm_upgrade.sh
    $newRELMHome/server/upgrade/relm/relm_upgrade.sh -oldApplicationHome oldRELMHome/server/conf
    This will perform three upgrades. First is to upgrade the configuration files. Second is to upgrade the database files. Third is to rebuild the text indices.
    Note: You must set the previous version parameter in the relm_params script before running the upgrade script. A description of this parameter and the other available parameters can be found in: relm_upgrade script reference.
  6. Any configuration information for the Lifecycle Query Engine and the SPARQL Gateway component should be ported to the new install. You must manually copy the old versions to the new Jazz Team Server.
    rm -rf $newRELMHome/server/conf/lqe
    cp -R $oldRELMHome/server/conf/lqe $newRELMHome/server/conf/lqe
    rm -rf $newRELMHome/server/conf/SPARQL_Gateway
    cp -R $oldRELMHome/server/conf/SPARQL_Gateway $newRELMHome/server/conf/SPARQL_Gateway
  7. Edit the SPARQL Gateway properties to remove the DBLocation property. In the following file, remove the DBLocation line: $newRELMHome/server/conf/SPARQL_Gateway/SPARQL_Gateway.properties
  8. If you are using Oracle, ensure that the Oracle ojdbc.jar (JDBC Driver) is available in the following directory: $newRELMHome\JazzTeamServer\server\oracle
  9. If you are using WebSphere Application Server, deploy the relm.war, vvc.war, lqe.war, and sparql_gateway.war files. Restart WebSphere Application Server.
  10. Start the Jazz Team server.
  11. Open the LQE administration page https://server:port/lqe/web/admin. A message will display stating that the LQE is in upgrade mode and is unavailable. Click Start Upgrade. Once this completes the data sources will be available.
  12. Ensure that a credentials.txt file exists with the following content: adminUserId, adminPassword, repositoryURL, smartCard, certificateFile If it does not already exist, create the file. For example, the credentials file may look like the following:
    adminUserId=yourAdminUserId
    adminPassword=yourAdminPassword 
    repositoryURL=https://yourserver.com:9443/vvc 
    smartCard=<none>
    certificateFile=<none>
  13. Run the following command from your Configuration_Application_install_dir/server directory
    • Linux: ./repotools-vvc.sh -migration_vvc_updateResourcesCommand credentialsFile=credentials.txt
    • Windows: repotools-vvc.bat -migration_vvc_updateResourcesCommand credentialsFile=credentials.txt

What to do next

After you have upgraded any of the required software, the Lifecycle Query Engine may need to reindex its content. New vocabularies were added to the Lifecycle Query Engine in 4.0.3, and if you want the Rational Engineering Lifecycle Manager to use the data included in these vocabularies you will need to reindex the application.
Table 1. Overview of reindexing requirements by product
Product v1.x to v4.0.6 v4.0.3 to v4.0.6 v4.0.4 to v4.0.6 v4.0.5 to v4.0.6
Rational Team Concert™ Reindex is required Reindex is not required Reindex is not required Reindex is not required
Rational Quality Manager Reindex is required Reindex recommended. A new property called oslc:shortld has been added to all QM resources. If you want to use this property in any query, you must reindex. Reindex is not required Reindex is not required
Rhapsody Design Management Reindex is not required, but may remove duplicate index entries and help improve performance. Reindex if new data is to be used in queries. Reindex is not required Reindex is not required Reindex is not required
Rational DOORS® Reindex strongly recommended for production data. Reindex recommended if you have created queries against the mailto URI. Reindex recommended for production data. Reindex recommended if you have created queries against the mailto URI. Reindex is not required. Reindex is not required.
Rational DOORS Next Generation not applicable not applicable Reindex is not required Reindex is not required
Rational Engineering Lifecycle Manager Reindex is required Reindex is required Reindex is required Reindex is required
Jazz Team Server Users TRS (jts/trsUsers) Reindex is required. Reindex is not required Reindex is not required Reindex is not required

Feedback