Upgrading Rational Engineering Lifecycle Manager running with WebSphere Application Server

To upgrade Rational® Engineering Lifecycle Manager, install the new product version, update configuration files, add, or update tables in existing database repositories, and migrate your data to version 5.0.1.

Before you begin

Procedure

  1. Install Rational Engineering Lifecycle Manager.
    This step installs:
    • Rational Engineering Lifecycle Manager 5.0.1
    • Jazz™ Team Server 5.0.1
    • Configuration Management application 5.0.1
    Important:
    • Select a different package group and directory than the original installation.
    • Select the same context root as your previous installation.

      If you upgrade from Rational Engineering Lifecycle Manager version 5.0 or older versions, your existing Jazz Reporting Service or SPARQL Gateway context root is SPARQL_Gateway, and your application file name is SPARQL_Gateway.war. When you install Rational Engineering Lifecycle Manager 5.0.1, select the custom context root option, and enter SPARQL_Gateway in the Application context root values field.

  2. Configure your application server.
    1. Ensure that your old server is running.
    2. Back up the WebSphere® Application Server profile.
      1. Open a command prompt and change to the bin directory of the WebSphere Application Server installation directory.
      2. Run this command. If the WebSphere Application Server security is turned on, specify the user name and password.
        Tip: The directory path to the compressed file must exist before you start the backup process.
        • Linux
          backupConfig.sh <Path_to_a_new_compressed_file_to_create_backup_of_profile> -username <WAS_primary_administrative_user_name> -password <WAS_administrative_password>
          For example:
          backupConfig.sh /root/WAS_backup/relm_50_profile.zip -username <WAS_admin> -password <WAS_admin_password>
        • Windows
          backupConfig.bat <Path_to_a_new_compressed_file_to_create_backup_of_profile> -username <WAS_primary_administrative_user_name> -password <WAS_administrative_password>
          For example:
          backupConfig.bat C:\WAS_backup\relm_50_profile.zip -username <WAS_admin> -password <WAS_admin_password>
      The command shuts down the server before starting the backup process.
    3. Uninstall the existing applications from WebSphere Application Server.
      1. Start the server.
      2. Log on to the WebSphere Application Server Integrated Solutions Console at https://host_name:9043/ibm/console/logon.jsp
      3. Click Applications > Application types > WebSphere enterprise applications.
      4. Stop and uninstall the following applications: relm.war, relmhelp.war, vvc.war, lqe.war, SPARQL_Gateway.war.
      5. Save the changes to the master configuration when prompted.
    4. Update JAZZ_HOME and log4j.configuration custom properties.
      1. Log on to the WebSphere Application Server Integrated Solutions Console at https://host_name: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 Jazz Reporting Service 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_dir/server/conf/lqe

      8. Under Additional properties click Custom properties.
      9. Click JAZZ_HOME and update its value to file:///<new_version_install_dir>/server/conf.

        For example, file:///C:/PROGRA~2/IBM/JazzTeamServer_5.0.1/server/conf.

      10. Click log4j.configuration and update its value to file:///<new_version_install_dir>/server/conf/startup_log4j.properties.

        For example, file:///C:/PROGRA~2/IBM/JazzTeamServer_5.0.1/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.
    5. Set the Jazz Reporting Service shared library.
      1. On the administrative console, go to Environment > Shared libraries.
      2. In the list, click JRS Shared Library.
      3. Change the class path from the existing Jazz Reporting Service installation location to the new one.

        For example: 5.0.1_install_dir/server/conf/SPARQL_Gateway/SharedLibrary

      4. Under Class Loading, ensure that Use an isolated class loader for the shared library is selected. Click Apply, and Save.
    6. Stop WebSphere Application Server.
      • Linux Run the stopServer.sh command.
      • Windows Run the stopServer.bat command.
    7. Clean up the WebSphere Application Server temp directories.

      Remove the Rational Engineering Lifecycle Manager related content from the wscache and temp directories in the profile. Depending on what applications were installed, these directories might be in the profile, and can be removed: relm_war, lqe_war, sparql, and Configuration Management application-related data.

      • Linux
        WAS_profile_root/wscache (for example: opt/IBM/WebSphere/AppServer/profiles/AppSrv01/temp/wscache)
        WAS_profile_root/temp (for example: opt/IBM/WebSphere/AppServer/profiles/AppSrv01/temp)
      • Windows
        WAS_profile_root\wscache (for example: C:\IBM\WebSphere\AppServer\profiles\AppSrv01\wscache)
        WAS_profile_root\temp (for example: C:\IBM\WebSphere\AppServer\profiles\AppSrv01\temp)
    8. Clean up the WebSphere Application Server 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 is :
      • Linux opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs
      • Windows C:\IBM\WebSphere\AppServer\profiles\AppSrv01\logs
    9. Start your WebSphere application server.
      • Linux Run the startServer.sh command.
      • Windows Run the startServer.bat command.
  3. Migrate or back up 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 database back-up process for DB2® that can be used as a guideline.
    1. Ensure that your old Jazz Team Server is stopped.
    2. In DB2, locate the databases that are used by the previous installation of Jazz Team Server applications.
    3. Back up each database that is used by a Jazz Team Server application.
    4. Save your changes.
    For more information about backing up and restoring the database, read the documentation for the Rational solution for Collaborative Lifecycle Management.
    SQL Server

    The following is a sample database back-up process for SQL Server that can be used as a guideline.

    • Ensure that you have the correct user name and password.
    • Ensure that you backed up your database before you started the upgrade process.
    • Confirm that the Java Database Connectivity (JDBC) driver is installed, and you are using sqljdbc4.jar. In version 5.0.1 JRE version 5.0 is no longer supported. Only JRE version 6.0 and 7.0 are supported.
    • Ensure that the SQL service is started.
    For complete instructions, refer to the documentation supplied by your database vendor.
    Oracle Ensure that the Oracle JDBC driver ojdbc.jar is available in the $newRELMHome/JazzTeamServer/server/oracle directory.
  4. Upgrade the Configuration Management application.

    Run the vvc_upgrade script to upgrade the configuration and database files, and to rebuild the text indices.

    This is a parameters example:
    cd $newRELMHome/server/
    upgrade/vvc/vvc_upgrade.sh -oldApplicationHome oldRELMHome/server/conf
    • If you upgrade a distributed (multiple server) installation topology, use the following parameter with the vvc_upgrade script:
      -oldApplicationHome oldRELMHome/server/conf -ignoreJTSVersionCheck
    • To skip the Tomcat upgrade, add the following parameter to the vvc_upgrade script:
      -oldApplicationHome oldRELMHome/server/conf -ignoreJTSVersionCheck -updateTomcatFiles=no
    Tip: The Configuration Management application can also be installed with Rhapsody® Design Manager. When you are installing Rational Engineering Lifecycle Manager, select the Configuration Management application if you want to install the component on a different machine than your Rhapsody Design Manager system. Integrate only one Configuration Management application with the Rational Engineering Lifecycle Manager. If you choose to install the component on multiple servers, ensure that you select the correct component for installing and upgrading.
  5. Upgrade Rational Engineering Lifecycle Manager.
    Run the relm_upgrade.sh command to upgrade configuration and database files, and to rebuild the text indices.
    $newRELMHome/server/upgrade/relm/relm_upgrade.sh -oldApplicationHome oldRELMHome/server/conf
  6. Port the Lifecycle Query Engine and the existing Jazz Reporting Service or SPARQL Gateway configuration information to the new product version.
    Copy the contents of the SPARQL_Gateway directory in the old installation to the new SPARQL_Gateway directory.
    cp -R $oldRELMHome/server/conf/SPARQL_Gateway/* $newRELMHome/server/conf/SPARQL_Gateway
    If you are upgrading from version 5.0 to 5.0.1, proceed to Step 7.
    If you are upgrading from version 4.x to 5.0.1, use a text editor to add the following properties to $newRELMHome/server/conf/SPARQL_Gateway/SPARQL_Gateway.properties.
    • support.query.editing=false
    • support.db.derby=false
    • support.dwse=false
    • query.results.limit=3000
    • query.results.cache.timeout=300
    • user.account.cache.timeout=480
    Remove app.properties from SPARQL_Gateway
    rm $newRELMHome/server/conf/SPARQL_Gateway/app.properties
    Rename SPARQL_Gateway.properties to app.properties.
    mv $newRELMHome/server/conf/SPARQL_Gateway/SPARQL_Gateway.properties $newRELMHome/server/conf/SPARQL_Gateway/app.properties
    Rename SPARQL_Gateway_runtime.properties to app_runtime.properties. (By default, SPARQL_Gateway_runtime.properties does not exist, but you can create the file if you need to configure the connection timeout setting.)
    mv $newRELMHome/server/conf/SPARQL_Gateway/SPARQL_Gateway_runtime.properties $newRELMHome/server/conf/SPARQL_Gateway/app_runtime.properties
  7. Deploy the relm.war, relmhelp.war, vvc.war, lqe.war, and SPARQL_Gateway.war files.
    1. From the WebSphere Application Server administrative console, select Applications > Application types > WebSphere enterprise applications.
    2. On the Enterprise Applications page, click Install.
    3. In Path to the new application, select $newRELMHome/server/webapps/relm.war, and click Open.
    4. Select Fast Path, and then Next.
    5. Accept the default values, and click Next in the setup wizard. On the Map context roots for Web modules page, enter the context root /relm. Then, click Finish.
    6. A message states that relm.war installed successfully. Click the Save directly to the master configuration.
    7. Install the Rational Engineering Lifecycle Manager documentation, relmhelp.war. Use the steps a-f above. Use $newRELMHome/server/webapps/relmhelp.war for the path, and /relmhelp as the context root.
    8. Install the Configuration Management application, vvc.war. Use the steps a-f above. Use $newRELMHome/server/webapps/vvc.war for the path, and /vvc as the context root.
    9. Set up your WebSphere application server for the Lifecycle Query Engine, and deploy the lqe.war file.
    10. Install the Jazz Reporting Service application, SPARQL_Gateway.war. Use the steps a-f above. Use $newRELMHome/server/webapps/SPARQL_Gateway.war for the path. Use SPARQL_Gateway as the context root.
    11. Add the Jazz Reporting Service library reference.
      1. Go to Applications > Applications types > WebSphere enterprise applications, and click SPARQL_Gateway_war in the application list.
      2. In the Reference section, click Shared library references.
      3. Select the check box next to SPARQL_Gateway_war, and click Reference shared libraries.
      4. Select JRS Shared Library, and click the right arrow.
      5. Click OK. Then, click OK again to save your settings to the master configuration.
    12. Ensure that the Jazz Reporting Service class loading order is configured correctly.
      1. Go to Applications > Applications types > WebSphere enterprise applications, and click SPARQL_Gateway_war in the application list.
      2. In the Detail Properties section, click Class loading and update detection.
      3. In the Class loader order section, select Classes loaded with local class loader first (parent last).
      4. Click OK, and Save to master configuration.
    13. Restart WebSphere Application Server.
  8. If you upgrade from version 4.x, upgrade the Lifecycle Query Engine.

    Open the Lifecycle Query Engine administration page https://relm_host_name:port/lqe/web/admin. A message states that the Lifecycle Query Engine upgrade is in progress, and that the application is unavailable. Click Start Upgrade. When the upgrade process completes, the data sources are available.

  9. Upgrade the Configuration Management application.
    1. Ensure that a credentials.txt file exists, and contains: adminUserId, adminPassword, repositoryURL, smartCard, certificateFile .

      If the file does not exist, create the file. A credentials file example is:

      adminUserId=yourAdminUserId
      adminPassword=yourAdminPassword 
      repositoryURL=https://yourserver.com:9443/vvc 
      smartCard=<none>
      certificateFile=<none>
    2. Run the repotools-vvc command from your Configuration_Application_install_dir/server directory.
      • Linux./repotools-vvc.sh -vvc_online_migrationCommand credentialsFile=credentials.txt fromVersion=<previous_version> logPort=52000 logLevel=DEBUG
      • Windowsrepotools-vvc.bat -vvc_online_migrationCommand credentialsFile=credentials.txt fromVersion=<previous_version> logPort=52000 logLevel=DEBUG
    3. Restart the Jazz Team Server.
    The Configuration Management application repotools command sends a request to the running Configuration Management application and waits for a response. If the repotools-vvc command stops immediately with an authorization error, verify that the server is running, and that the user ID and password in the credentials file are correct.
  10. Restart your application server.
    • Linux Run the stopServer.sh and the startServer.sh command.
    • Windows Run the stopServer.bat and the startServer.bat command.
  11. Restart your Rational Engineering Lifecycle Manager server to automatically upgrade migrated data to the format that is required in the new application version. This process is called online upgrade. Log on if you want to see the upgrade status page.

Results

When the online upgrade is successful, the web browser refreshes and opens the Rational Engineering Lifecycle Manager welcome page. If an upgrade step fails, examine the relm.log file to determine what caused the failure. If you have a large number of products defined in Rational Engineering Lifecycle Manager, the online upgrade takes a long time to complete (up to several hours).

What to do next


Feedback