Assigning Version IDs in Rational Team Concert
Prior to Rational Team Concert (RTC) 5.0, resources that were checked-in did not display a unique ID to reference. In this article, we explain why you may want to assign version IDs and describe how to assign them to historical data. It is not required to assign version IDs unless you want them. When assigning IDs, we will demonstrate how to assign them in a single server environment and in a distributed environment. Last, we will describe how to update version IDs after they were assigned.
Table of Contents
Why Assign Version IDs
The upgrade to RTC 5.0 does not assign version IDs during the upgrade to minimize downtime. If you want version IDs on your existing data, they will have to be assigned after the upgrade to RTC 5.0. If your RTC environment uses distributed SCM, the version ID assignment tool must be run on all the servers. The assignment is run while the server is online and has a minimal impact on performance. Users are free to use RTC as normal during the assignment process.
It is not necessary to assign the IDs immediately after upgrade. Any new versions checked-in after the upgrade are assigned IDs while pre-existing versions will not have any IDs. The number of IDs required for the pre-existing versions are reserved in case IDs are assigned later. For example, if there are 30 pre-existing versions of a file before an upgrade to RTC 5.0, the IDs 1 through 30 will be reserved. New check-ins will have their IDs assigned starting at 31.
How to Assign Version IDs
Assigning version IDs requires that the server be online. Running the repotools command to assign the IDs must be performed by someone with administrative rights. The assignment process is different depending on whether your RTC configuration uses distributed SCM or not.
Assigning Version IDs in a Single Server Environment
For a single server, the assignment is simple. The command is run like this:
repotools -createVersionIDs adminUserId=<admin_username> adminPassword=<admin_password>
This will create version IDs and the time it takes depends on the number of pre-existing versions and your server hardware. It may take a few hours and the server is usable during this time.
Assigning Version IDs in a Distributed Environment
For distributed servers, repotools must be run on one server at a time. Each time the repotools command is executed output from the version assignment will be used as the input to running the command on the next server. This will ensure that the version IDs will be uniquely assigned and a version existing across several servers will have the same ID. The following image is an example distributed setup that will be assigned IDs.
If there is a server that has a main development stream or a stream that you consider to be the origin, this may be chosen as the first server. Assigning IDs to this server first will allow the users on that server to benefit from the IDs as soon as possible. For the example setup above, the servers have been numbered 1-3. Consider Server 1 to be the server that contains the main development stream. This will be assigned IDs first. The other servers are of equal importance but numbering them is important to the order the servers are assigned version IDs.
Assigning version IDs to Server 1 in the distributed environment requires specifying an output file. This output file will be used in assigning IDs to the subsequent servers. To create the output specify the consolidatedVersionsOutputFile option when assigning the IDs.
repotools -createVersionIDs consolidatedVersionsOutputFile=<outputVersionIDs> adminUserId=<admin_username> adminPassword=<admin_password>
Copy the output file to the next server so it can use it when assigning version IDs. To use this data for the next server, use the existingVersionsInputFile option when assigning the IDs.
repotools -createVersionIDs existingVersionsInputFile=<inputVersionIDs> consolidatedVersionsOutputFile=<outputVersionIDs> adminUserId=<admin_username> adminPassword=<admin_password>
The command is almost the same as you would run on Server 1. The difference is specifying an existing versions input file with the existingVersionsInputFile option. You still specify an output file so that Server 3 can use the consolidated version data from Server 1 and Server 2.
Copy Server 2‘s output file to Server 3. With the output file from Server 2, Server 3 can be assigned IDs. Use the same command that was run on Server 2. When the IDs are assigned to Server 3, the version ID assignment is complete.
Updating Version IDs After They Were Assigned
Sometimes it is necessary to update the version IDs after the initial assignment. This may be required if you have to update another server in a distributed SCM environment.
No Consolidated Versions File
If you assigned version IDs without creating an output file, you can create one from the last server that had version IDs assigned. This is done with the exportVersionIDs command. It will export the version IDs from that server to an output file. The command is executed like this:
repotools -exportVersionIDs consolidatedVersionsOutputFile=<outputVersionIDs> adminUserId=<admin_username> adminPassword=<admin_password>
For example, Server 1 has finished assigning version IDs and the consolidatedVersionsOutputFile option was not specified. The version IDs can be exported so that Server 2 can continue with the version ID assignment.
Missing Version IDs
Occasionally, a user may notice a missing version ID in a database where you already assigned version IDs. This can occur if a new version without a version ID was accepted into the database while IDs were initially assigned. These versions with blank IDs will not cause any issues.
If you want to fill in these blank IDs, the administrator can run the version ID assignment on the server with missing version IDs. In a single server environment, run the version ID assignment with the createVersionIDs option. In a distributed server environment, re-run the version ID assignment one by one on each of the servers. For example, run the version ID assignment on Server 1 with the option to create the consolidated versions output file. Copy this file to Server 2 and run repotools to create version IDs with the file specified for the existingVersionsInputFile. If you want to fix the existing versions to ensure that each file version has the same ID on every server, set the replace option to ‘yes’. This option may change the existing version IDs. Note that existing version IDs should never be changed if you are using the data for auditing purposes.
About the author
Timothy is a member of the Jazz SCM development team and was one of the developers that implemented this feature.
Copyright © 2014 IBM Corporation
Yes