How to migrate from the V2 Perl base-ClearCase/ClearQuest Integration to the Change Management Integration

Answer

The Change Management Integration (CMI) supports a two-step process for migrating from the V2 Perl integration to CMI. In the first step, a new utility, cmi_migrate.pl, is used to generate a file listing all versions that require task associations. In the second step, the clmutil utility is run in migrate mode to parse the generated file and create the task associations on the versions and to update the links tab on the ClearQuest records. The migration does not remove the CrmRequest hyperlinks that were created by the V2 integration, but it is recommended that the V2 integration be disabled after the migration process has been completed.

ClearQuest Web Configuration

This utility will be available as a testfix for ClearCase 8.0.0.10 and 8.0.1.03.

We recommend that the VOB be locked -nusers for the User running the utility, so that other users do not accidentally generate new hyperlinks that will then have to be parsed. You must run the utility in a view, using ratlperl. Note that you may need to modify your PATH to include /opt/rational/common/bin.

> ratlperl cmi_migrate.pl

The cmi_migrate utility will request that you enter the desired mode; enter “base” to migrate from the V2 perl integration. The cmi_migrate utility will then request that you enter the vobtag of the VOB you wish to migrate, the name of an existing temp directory, and names for two files it will generate (default names are suggested). It will then parse the V2 integration's config.pl file, and store extracted information in a file with the (default) name cmi_migration.txt, in the specified temp directory.

At this point you can choose to enter CMI configuration information for all of the brtypes that require migration, or you can quit the utility and modify the cmi_migration.txt file manually. If you choose to quit, you can run the script again to resume the migration process. If you choose to continue, you will be prompted for a description for the CMI provider, a query uri, and a name for the provider. Once the configuration is complete, cmi_migrate will create attribute types required by CMI, will run the mkcmprovider command to configure the VOB and the participating brtypes, and will generate a migration version information file with the (default) name cmi_migration_versions.txt, that will contain entries for all VOB element and directory versions that require task associations in CMI.

Running clmutil in migrate mode

Once the migration version information file has been generated, you can use the clmutil utility to generate the actual task associations. This utility must be run as root on UNIX or as Privileged User on Windows. It is installed in <ClearCase-home>/bin

If your VOB has ACLs enabled, you must ensure that User has permissions to modify elements. For example, you may use the cleartool chpolicy command to add permissions for root to the DefaultPolicy:

> cleartool chpolicy -nc -kind element -add User:root -permission Full DefaultPolicy

You must be set to a view when you run clmutil in migrate mode. Any user can preview its actions by running:

> clmutil cmi_repair -verbose -preview -migrate -repair_file <migrate_versions_file_pname>

The migrate_versions_file_pname must be the full path to the version information file generated by cmi_migrate.pl. In preview mode clmutil will list all of the CMI actions that would be attempted.

Before creating the task associations, you must use the cmiregister command to store the necessary credentials for CMI. As root or Privileged User run

> cmiregister add -cq -name <provider-name> -userdb <database-name> -dbset <dbset-name> -username <username> [-password <password>]

Supply a password only if one is needed by your ClearQuest installation.

To perform the actual work, run the utility as root or Privileged User, in a view, without the -preview option:

> clmutil cmi_repair -verbose -migrate -repair_file <migrate_versions_file_pname>

You will see output for each association that is created. After the utility completes, you can describe a version on an instance of a participating brtype to view the associated tasks, and you can check the Links tab on the ClearQuest record to view the version information. The migration process does not remove the hyperlinks that used as artifacts for the V2 Perl integration.