Repository tools command to run an online migration

Use the onlineMigrate command to run an online migration on a live server.

Important: IBM® Engineering Workflow Management is the only IBM Engineering Lifecycle Management application that supports online migration.

Before you begin

Before you start the Change and Configuration Management application upgrade, ensure that the database statistics are up-to-date. Databases generally manage statistics automatically; for example, in a scheduled overnight operation. However, to ensure that the database is fully optimized, you can manually run the statistics as follows:

Db2® database:

DB2 REORGCHK UPDATE STATISTICS ON TABLE ALL

Oracle database:

EXEC DBMS_STATS.GATHER_DATABASE_STAT

SQL Server database

EXEC sp_updatestats

This step is important for these reasons:

To ensure that the migration runs as quickly and efficiently as possible
To minimize online migration time
To reduce the offline outage time when the repotools -addTables command runs to finalize the database upgrade

Inaccurate or out-of-date statistics can cause the offline portion of the migration to run for an excessive amount of time.

Purpose

The onlineMigrate command can reduce server downtime during a migration by running a few of the database migration tasks while the old server remains active.

Tip: When you run the onlineMigrate command, it produces a configuration file in the Install_Dir/server directory called OnlineMigrateSettings.cfg. This file contains the numStatesPerRun and priority parameters that can be configured while the online migration is running. This eliminates the need to restart the onlineMigrate command in case you want to adjust the values. See the description of the numStatesPerRun and priority parameters in the following table.

Parameters

Attribute	Description	Required	Default
numStatesPerRun	The number of item states to process per iteration. Tip: Processing more states in an iteration than the default value requires more memory. Tip: To reduce the length of time that database locks are held, decrease this value. Important: For the Change and Configuration Management application, the primary consideration is the average size of the change history associated with a baseline, which depends on how often a team creates baselines. For example, suppose the `numStatesPerRun` value is `100`. If your team typically has 10 baselines per release, about 1000 history entries will be held in memory. In contrast, if your team does not frequently use baselines and change history is typically 100 or 1000 changes, 10,000 or 100,000 history entries might be held in memory, which can use a lot of memory.	No	`100`
priority	The priority parameter is used to introduce sleep cycles between transactions in the migration. It represents a percentage of the time online migration is active. You can specify a percentage value between `1` and `100`. The primary consideration is how much load the database can handle and how responsive the old server is. For example, if the priority value is `10`, the task for online migration runs 10% of the time and is idle the remaining 90%. As another example, if the priority value is `100`, the migration process will never sleep. Tip: To complete the online migration faster, increase this value. To improve performance on the server, decrease this value. Note that complete offline migration is equivalent to running the online migration at priority=100.	No	`50`
teamserver.properties	The path to the teamserver.properties file of the server that is running. This server is the original server database that contains the data to be migrated. Tip: Starting in version 5.0, the onlineMigrate command is available and runs from a new installation of each product. You must specify an absolute path to the `teamserver.properties` file of the old server. Otherwise, if you keep the path relative, such as `conf\ccm\teamserver.properties`, this command points to the `teamserver.properties` file in the new server installation instead of the old server. For an example of an absolute path, see the "Example" section.	No	conf/ccm/teamserver.properties
logFile	The path to the log file.	No	repotools-ccm_onlineMigrate.log
noPrompt	An option that runs the online migration without confirmation from the user. This option is useful for writing automated scripts.	No	Non applicable

Examples

For Windows
operating system Open a command prompt and enter this command:

cd C:\Program Files\IBM\JazzTeamServer\server\
repotools-ccm.bat -onlineMigrate numStatesPerRun=100 priority=50 logFile=repotools_onlineMigrate.log teamserver.properties=C:\Program Files\IBM\OLD_JazzTeamServer\server\conf\ccm\teamserver.properties

For Unix
operating systems Open a command line and enter this command:

cd /opt/IBM/JazzTeamServer/server/
./repotools-ccm.sh -onlineMigrate numStatesPerRun=100 priority=50 logFile=repotools_onlineMigrate.log teamserver.properties=/opt/IBM/OLD_JazzTeamServer/server/conf/ccm/teamserver.properties

Output

Before the new server is started, while the old server is running, the repotools -onlineMigrate command runs locally from the new server deployment. That command creates tables for new item types in the database and starts iterating through the item states from oldest to newest, creating new items and item states. A daemon process starts and iterates through the ITEM_STATES table. The process passes item states to the new type handlers. After all the states are processed, the repository tools command exits.

After each set of item states is processed, the repotools -onlineMigrate command outputs the percentage complete and the estimated completion time. This example shows the command output:

CRJAZ1442I The component model of "com.ibm.team.repository.tests.omtest" was updated from "1" to "2".
The user "ADMIN" has logged in to the database "repositoryDB".
@ID@I Starting online migration for the following models: {"com.ibm.team.repository.tests.omtest":"1"}
@ID@I New type handler "OnlineMigrationSimpleItemHandler" found for item type "SimpleOldType0".  Item DB ID = 22.
@ID@I New type handler "OnlineMigrationAuditableItemHandler" found for item type "AuditableOldType0".  Item DB ID = 21.
@ID@I Running online migration on 1,703 item states.  400 previously processed.  2 new type handlers. 
Type "AuditableLink", 1 of 3 item status previously processed.
Type "AuditableOldType0", 0 of 1,200 item status previously processed.
Type "SimpleOldType0", 399 of 500 item status previously processed.
Status: 500 of 1,703 processed (29% complete).  Estimated completion time:  9/23/13 3:00 PM.
Status: 502 of 1,703 processed (29% complete).  Estimated completion time:  9/23/13 3:00 PM.
Status: 504 of 1,703 processed (29% complete).  Estimated completion time:  9/23/13 3:00 PM.
Status: 507 of 1,703 processed (29% complete).  Estimated completion time:  9/23/13 3:00 PM.
Status: 509 of 1,703 processed (29% complete).  Estimated completion time:  9/23/13 3:00 PM.
Status: 511 of 1,703 processed (30% complete).  Estimated completion time:  9/23/13 3:00 PM.
Status: 513 of 1,703 processed (30% complete).  Estimated completion time:  9/23/13 3:00 PM.
Status: 515 of 1,703 processed (30% complete).  Estimated completion time:  9/23/13 3:00 PM.
Status: 517 of 1,703 processed (30% complete).  Estimated completion time:  9/23/13 3:00 PM.

Tip: To process additional item states that might accumulate after a previous run, you can run the Repository tools command to run an online migration command multiple times.

In addition, you do not need to wait until the online migration process is 100% complete. You can stop the online migration process at any time and continue with offline migration. For details about safely stopping the online migration process, see Repository tools command to stop an online migration.

On a production server, the online migration might never reach 100% completion because the online migration process does not process data that is less than a day old.