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

Authors: ChethnaShenoy, JohnVasta
Build basis: Requirements Management 7.0 and later

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

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

Note: This topic assumes that you have upgraded Jazz Team Server and all other applications except for the RM application and done 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.

Note: The jtsRepositoryUrl is the URL that is defined in the Jazz Team Server Shared Validity provider URL advanced property. If no URL is defined, then use the URL of the Jazz Team Server that the Requirements Management application is connected to.

Procedure for WebSphere Liberty Profile

1. 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:9443/jts -adminUserId admin_user_id -adminPassword admin_password

2. Enter E to execute step 0 (update config files).
3. When step 0 completes, enter a carriage return to stop the script execution.
4. Start the server.
5. Execute the rm_upgrade with the same options as before and enter 1 to resume the script at step 1 (export link validity data).
6. After step 1 completes, enter a carriage return to stop the script execution.
7. Stop the server.
8. Execute the rm_upgrade with the same options as before and enter 2 to resume the script at step 2 (add tables).
9. Start the server.
10. Execute the rm_upgrade with the same options as before and enter 3 to resume the script at step 3 (import link validity data).

Procedure for WebSphere Application Server

1. 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 updateAppServerFiles no -migrateLinkValidity
    -jtsRepositoryUrl https://host_name:9443/jts -adminUserId admin_user_id -adminPassword admin_password 

2. Enter E to execute step 0 (update config files).
3. When step 0 completes, enter a carriage return to stop the script execution.
4. Deploy the rm.war and converter.war applications in WebSphere Application Server.
5. Start the server.
6. Execute the rm_upgrade with the same options as before and enter 1 to resume the script at 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 and enter 2 to resume the script at step 2 (add tables).
10. Start the server.
11. Execute the rm_upgrade with the same options as before and enter 3 to resume the script at step 3 (import link validity data).

Option 2: Migrating the link validity data in a single-server topology using upgrade 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.

Note: This topic assumes that you have upgraded Jazz Team Server and all other applications except for the RM application and done 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.

Note: The jtsRepositoryUrl is the URL that is defined in the Jazz Team Server Shared Validity provider URL advanced property. If no URL is defined, then use the URL of the Jazz Team Server that the Requirements Management application is connected to.

Procedure for WebSphere Liberty Profile

1. Stop the server. 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

Note: RM application link validity migration will fail if the web.xml file is not available under path Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war\WEB-INF\web.xml. The error message “CRJAZ1888E Error updating web.xml file” will be displayed.

1. Start the server. Change to the Jazz_Install_Dir/server directory and enter the command:

   server.startup.bat

2. 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:9443/jts -adminUserId admin_user_id -adminPassword admin_password -noPrompt -noVerify -noStepPrompt -noEditor -noResumePrompt
   

3. 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
4. Stop the server. Open a command window, change to the Jazz_Install_Dir/server directory and enter the following command:

   server.shutdown.bat

5. Delete the directory Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war
6. 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\
      

7. Replace Jazz_Install_Dir/server\liberty\servers\clm\apps\rm.war\WEB-INF\web.xml file with C:\BackupRM\web.xml
8. Start the server. Change to the Jazz_Install_Dir/server directory and enter the command:

   server.sstartup.bat

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

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

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 restart the Websphere Application Server, run command:

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

External links:

• Interactive Upgrade Guide (procedure for distributed topology deployment)
• Requirements Management upgrade script reference information

Additional contributors: MichaelAfshar