Migrating the Requirements Management application link validity data in a single-server topology

Authors: ChethnaShenoy, ChasePatterson, UmaShankar
Build basis: Requirements Management 7.0 and later

Note: IBM issued an alert, Review DOORS Next Link Validity defect impacting Lifecycle Query Engine reports before upgrading to 7.0 or 7.0.1, on 7th July 2020 to ensure that link validity customers apply the latest Interim fix before upgrading.

IMPORTANT NOTE: If you do not have link validity data on your server then you must not do the steps on this page but instead follow these instructions Additional steps related to link validity data migration can be skipped during the migration

You can use the Requirements Management (RM) application upgrade script to migrate the link validity data.

The steps on this page only apply if upgrading from a 6.x release to a 7.x release.
Do not follow the steps here if the RM server you are upgrading from is not a supported 6.x release.
Supported 6.x releases are as follows: 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.6.1.

The instructions below are for Microsoft Windows. For UNIX users, use ./server.startup and ./server.shutdown instead of server.startup.bat and server.shutdown.bat. This also applies to repotools-rm.bat, where ./repotools-rm.sh should be used.
Note: For IBM i, you should follow the steps in this document even if the JTS that LQE is registered with is not on the same application server as the RM server you are upgrading.

Option 1: Migrating the link validity data in a single-server topology using upgrade script with interaction

Note: Use this method to migrate link validity data with an upgrade wrapper script that automates some of the manual steps. The script is run in a command window and you follow on-screen prompts for each step of the upgrade.

For the migration task to complete successfully, Jazz Team Server must be running. In a single-server topology where both the RM application and Jazz Team Server are installed on the same server, you must interrupt the script execution and shut down and restart the server multiple times. As a result, do not use the -noStepPrompt during manual upgrade.
However, you can use the following parameters in a silent upgrade: noPrompt -noVerify -noEditor -noResumePrompt

Important: It is assumed that you have upgraded and deployed Jazz Team Server and the Global Configuration applications prior to the Requirements Management application and performed all the necessary pre-upgrade steps.

Tip: To make the workflow easier, you can have two console windows open for controlling the server and repeatedly interrupting the script execution.

Important: For a multi-JTS environment, the text https://host_name:port/jts should be replaced with the URL specified in the Advanced Admin property, Shared Validity Provider URL, of the JTS that the RM is registered with. If no URL is defined, then use the URL of the JTS that the RM application is registered with. This JTS should already be upgraded to 7.x and running. The Shared Validity Provider URL is usually set to the URL of the JTS that the LQE is registered with, but use the URL specified in the Advanced Admin property for the upgrade commands.

Procedure for WebSphere Liberty Profile

1. Stop the application server, if it is running.
2. Open a command window, change to the Jazz_Install_Dir/server directory and enter the following command:

   upgrade\rm\rm_upgrade.bat -oldApplicationHome Old_Jazz_Install_Dir\server\conf -migrateLinkValidity 
   -jtsRepositoryUrl https://host_name:port/jts -adminUserId admin_user_id -adminPassword admin_password

3. Enter E to execute step 0 (update config files).
4. After step 0 completes, when prompted enter a carriage return, "hit [Enter]", to stop the script execution.
5. Start the server.
6. Execute the rm_upgrade with the same options as before; enter 1 to resume the script at step 1; then enter E to execute step 1 (export link validity data).
7. After step 1 completes, enter a carriage return to stop the script execution.
8. Stop the server.
9. Execute the rm_upgrade with the same options as before; enter 2 to resume the script at step 2; then enter E to execute step 2 (add tables).
10. After this step completes, enter a carriage return to stop script execution. Otherwise, the script will wait for user to start the link validity import operation
11. Start the server.
12. Execute the rm_upgrade with the same options as before; enter 3 to resume the script at step 3; then enter E to execute step 3 (import link validity data).
13. Stop the server.

Next Step: Continue on to the rest of the post-migration steps from the Interactive Upgrade Guide and resume your the upgrade after the Upgrading the Requirements Management application section.

Procedure for WebSphere Application Server

1. Stop the application server, if it is running.
2. Open a command window, change to the Jazz_Install_Dir/server directory and enter the following command:

   upgrade\rm\rm_upgrade.bat -oldApplicationHome Old_Jazz_Install_Dir\server\conf -newJTSHome New_Jazz_Install_Dir\server\conf updateAppServerFiles no -migrateLinkValidity 
   -jtsRepositoryUrl https://host_name:port/jts -adminUserId admin_user_id -adminPassword admin_password 

3. Enter E to execute step 0 (update config files).
4. When step 0 completes, enter a carriage return to stop the script execution.
5. Start the server.
6. Deploy the rm.war and converter.war applications in WebSphere Application Server.
7. Execute the rm_upgrade with the same options as before and enter 1 to resume the script at step 1 (export link validity data).
8. After step 1 completes, enter a carriage return to stop the script execution.
9. Stop the server.
10. Execute the rm_upgrade with the same options as before and enter 2 to resume the script at step 2 (add tables).
11. After this step completes, enter a carriage return to stop script execution. Otherwise, the script will wait for user to start the link validity import operation
12. Start the server.
13. Execute the rm_upgrade with the same options as before and enter 3 to resume the script at step 3 (import link validity data).
14. Stop the server.

Next Step: Continue on to the rest of the post-migration steps from the Interactive Upgrade Guide and resume your the upgrade after the Upgrading the Requirements Management application section.

Option 2: Migrating the link validity data in a single-server topology using upgrade wrapper script in silent mode

For the migration task to complete successfully, Jazz Team Server must be running. In a single-server topology both the RM application and Jazz Team Server are installed on the same server.

Procedure for WebSphere Liberty Profile

1. Stop the application server, if it is running. Open a command window, change to the Jazz_Install_Dir/server directory and enter the following command:

   server.shutdown.bat

2. Back up the following application file and directory into a folder path E.g. C:\BackupRM\RM\

   a.   Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war.zip
   b.   Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war
      

3. Back up the following template file and directory into a folder path E.g. C:\BackupRM\RMTemplate\

   a.   Jazz_Install_Dir/server\liberty\clmServerTemplate\apps\rm.war.zip
   b.   Jazz_Install_Dir/server\liberty\clmServerTemplate\apps\rm.war
      

4. Delete the following files and directories:

   a.   Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war.zip
   b.   Jazz_Install_Dir/server\liberty\clmServerTemplate\apps\rm.war.zip
   c.   Jazz_Install_Dir/server\liberty\clmServerTemplate\apps\rm.war
      

5. Retain only the file Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war\WEB-INF\web.xml and delete all the other files and folders inside directory Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war
6. Start the server. Change to the Jazz_Install_Dir/server directory and enter the command:

   server.startup.bat

7. From Jazz_Install_Dir/server directory, enter the following command to perform RM application database upgrade and link validity migration:

   upgrade\rm\rm_upgrade.bat -oldApplicationHome Old_Jazz_Install_Dir\server\conf -migrateLinkValidity -jtsRepositoryUrl https://host_name:port/jts -adminUserId admin_user_id 
   -adminPassword admin_password noPrompt -noVerify -noStepPrompt -noEditor -noResumePrompt
   

8. Back up files web.xml and web-backup.xml (E.g. web-1578991938493backup.xml) from path Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war\WEB-INF\ to path C:\BackupRM
9. Stop the server. Open a command window, change to the Jazz_Install_Dir/server directory and enter the following command:

   server.shutdown.bat

10. Delete the directory Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war
11. Restore the backed-up files and directories

    a.   Copy C:\BackupRM\RM\rm.war.zip to Jazz_Install_Dir/server\liberty\servers\clm\apps\
    b.   Copy C:\BackupRM\RM\rm.war to Jazz_Install_Dir/server\liberty\servers\clm\apps\
    c.   Copy C:\BackupRM\RMTemplate\rm.war.zip to Jazz_Install_Dir/server\liberty\clmServerTemplate\apps\ 
    d.     Copy C:\BackupRM\RMTemplate\rm.war to Jazz_Install_Dir/server\liberty\clmServerTemplate\apps\ 
    e.   Copy C:\BackupRM\web-<number>backup.xml (E.g. web-1578991938493backup.xml) 
    to Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war\WEB-INF\
       

12. Replace Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war\WEB-INF\web.xml file with C:\BackupRM\web.xml

Next Step: Continue on to the rest of the post-migration steps from the Interactive Upgrade Guide and resume your the upgrade after the Upgrading the Requirements Management application section.

Procedure for WebSphere Application Server

1. To start Websphere Application Server if not already up, open a command window and enter the following commands. Replace WASInstallDir with the Websphere Application Server installation directory and server1 with the name of your server:

   cd WASInstallDir/AppServer\profiles\profile_name\bin
   startServer.bat server1
    

2. To uninstall RM application from WAS, run the following command substituting WAS_username with the WebSphere Application Server admin username, WAS_password with the admin user password, and pathToTheScript with the location with Jazz_Install_Dir/server/was

   wsadmin.bat -language jython -user WAS_username -password 
   WAS_password -f pathToTheScript/clm_undeploy_distributed.py rm,converter

3. To perform RM application database upgrade and link validity migration enter the following commands from the directory Jazz_Install_Dir/server

      cd Jazz_Install_Dir/server
      upgrade\rm\rm_upgrade.bat -oldApplicationHome Old_Jazz_Install_Dir\server\conf -newJTSHome New_Jazz_Install_Dir\server\conf updateAppServerFiles no -migrateLinkValidity 
   -jtsRepositoryUrl https://host_name:port/jts -adminUserId admin_user_id -adminPassword admin_password noPrompt -noVerify -noStepPrompt -noEditor -noResumePrompt
    

4. To install RM application from WAS, run the following command substituting WAS_username with the WebSphere Application Server admin username, WAS_password with the admin user password, pathToTheScript with the location Jazz_Install_Dir/server/was, and pathToWarFiles with the location =Jazz_Install_Dir/server/webapps

   cd WASInstallDir/AppServer\profiles\profile_name\bin
   wsadmin.bat -language jython -user WAS_username -password WAS_password -f pathToTheScript/clm_deploy_distributed.py nodeName server1 pathToWarFiles rm,converter
    

5. To shutdown the WebSphere Application Server, run command:

   cd WASInstallDir/AppServer\profiles\profile_name\bin
   stopServer.bat server1 -user WAS_username -password WAS_password
    

Next Step: Continue on to the rest of the post-migration steps from the Interactive Upgrade Guide and resume your the upgrade after the Upgrading the Requirements Management application section.

Option 3: Migrating the link validity data in a single-server topology using repotools script in silent mode

For the migration task to complete successfully, the Jazz Team Server must be running. In a single-server topology, both the RM application and Jazz Team Server are installed on the same server.

Upgrade using repotools scripts, WebSphere Liberty Profile

Open a command window with administrative privileges or shell and enter the following commands in sequence.
UNIX users need to set export DEFINE_INIT=-Dcom.ibm.rdm.repotools.06.linkvalidity.migration.enabled=true prior to running these commands.

1. Open a command window, change to the Jazz_Install_Dir/server directory and shut down the server if it is running.

      cd Jazz_Install_Dir\server
      server.shutdown.bat
   

2. Run the migration_rm_updateConfigurationFiles command:

      repotools-rm.bat -migration_rm_updateConfigurationFiles oldApplicationHome=Old_Jazz_Install_Dir\server\conf
   

3. Start the server and export the Link Validity data by connecting to the Jazz Team Server:

      server.startup.bat
      repotools-rm.bat -rmExportLinkValidity repositoryURL=https://host_name:port/jts adminUserId=admin_user_id adminPassword=admin_password
   

4. Set the environment variable to enable link validity migration and shut down the server

      set DEFINE_INIT=-Dcom.ibm.rdm.repotools.06.linkvalidity.migration.enabled=true
      server.shutdown.bat
   

5. Run the repotools-rm.bat -addTables to perform the main RM upgrade

      repotools-rm.bat -addTables noPrompt
   

6. Start the server and import the Link Validity data by connecting to the Jazz Team Server:

      server.startup.bat
      repotools-rm.bat -rmImportLinkValidity repositoryURL=https://host_name:port/jts adminUserId=admin_user_id adminPassword=admin_password
   

7. Stop the server

      server.shutdown.bat
   

Next Step: Continue on to the rest of the post-migration steps from the Interactive Upgrade Guide and resume your the upgrade after the Upgrading the Requirements Management application section.

Upgrade using repotools scripts for WebSphere Application Server

Open a command window or shell and enter the following commands in sequence.

1. Shutdown the Websphere Application Server if it is running. Open a command window and enter the following commands. Replace WASInstallDir with the Websphere Application Server installation directory and server1 with the name of your server

      cd WASInstallDir\AppServer\profiles\profile_name\bin
      stopServer.bat server1 -user WAS_username -password WAS_password
   

2. Change to the Jazz_Install_Dir/server directory and enter the migration_rm_updateConfigurationFiles command

      cd Jazz_Install_Dir\server
      repotools-rm.bat -migration_rm_updateConfigurationFiles oldApplicationHome=Old_Jazz_Install_Dir\server\conf updateAppServerFiles=no
   

3. Start the server and export the Link Validity data by connecting to the Jazz Team Server:

      cd WASInstallDir\AppServer\profiles\profile_name\bin
      startServer.bat server1
      cd Jazz_Install_Dir\server
      repotools-rm.bat -rmExportLinkValidity repositoryURL=https://host_name:port/jts adminUserId=admin_user_id adminPassword=admin_password
   

4. Set the environment variable to enable link validity migration and shut down the server

      cd WASInstallDir\AppServer\profiles\profile_name\bin
      stopServer.bat server1 -user WAS_username -password WAS_password
      set DEFINE_INIT=-Dcom.ibm.rdm.repotools.06.linkvalidity.migration.enabled=true
      cd Jazz_Install_Dir\server
   

5. Run the repotools-rm.bat -addTables to perform the main RM upgrade

      repotools-rm.bat -addTables noPrompt 

6. Start the server and import the Link Validity data by connecting to the Jazz Team Server:

      cd WASInstallDir\AppServer\profiles\profile_name\bin
      startServer.bat server1
      cd Jazz_Install_Dir\server
      repotools-rm.bat -rmImportLinkValidity repositoryURL=https://host_name:port/jts adminUserId=admin_user_id adminPassword=admin_password
   

7. Stop the server

      stopServer.bat server1 -user WAS_username -password WAS_password
   

Next Step: Continue on to the rest of the post-migration steps from the Interactive Upgrade Guide and resume your the upgrade after the Upgrading the Requirements Management application section.

Workarounds and Limitations

• When you migrate to version 7.x, you might encounter problems during the migration. For instance, the following error message is displayed in the repotools_rm_upgrade.log file:

2020-04-29 09:40:33,882 [] [] main No link validity content applicable to current DN server.

See Migration from version 6.x to version 7.x fails with an error message: No link validity content applicable to current DN server for more details.

External links:

Interactive Upgrade Guide | Requirements Management upgrade script reference information | repotools addTables | rmExportLinkValidity command reference | rmImportLinkValidity command reference

Additional contributors: PaulEllis, UmaShankar