clm_server_rename.pl
Synopsis
- cqperl clm_server_rename.pl -username username -password password [ -dbset dbset ] -dbname dbname -oldprefix oldprefix -newprefix newprefix [ -remapconfigfiles | -preview number | -update ] [ -help ] [ -man ]
Description
Starting in the version 4.0 products for the Rational ClearQuest solution for Collaborative Lifecycle Management (CLM), administrators can change the public URI of a Jazz Team Server or a Rational solution for CLM application after deployment by using the server rename operation. Such changes require corresponding updates to the Rational ClearQuest solution for CLM resources that are based on the URI. For the ClearQuest Bridge, these artifact links for the Rational solution for CLM product resources (IBM Rational Team Concert, IBM Rational Quality Manager, and IBM Rational DOORS Next Generation) are stored in ClearQuest Web server configuration files and in OSLCLinks records in the ClearQuest user database.
- Structural links describe relationships between resources or artifacts and are required to maintain traceability and data integrity.
- Embedded links are URIs that can be included in a text field or node of a resource.
Embedded links can be either anchored links or plain text links.
- Anchored links are displayed to a user as navigable hyperlinks. For example, in a rich text widget, these links are declared as such and are usually stored in a structure like <a href=...>.
- Plain text links are URIs that are typed into a text widget but are not rendered as navigable hyperlinks.
Rational ClearQuest provides the clm_server_rename.pl tool to remap URI structural links that are stored in Rational ClearQuest Web configuration files and in OSLCLinks records. Use the tool to remap the protocol, host name, port number, and application context of structural links.
Running the tool
You must have local administrator privileges and Rational ClearQuest Super User privileges to run the clm_server_rename.pl tool.
The tool is located in this directory in the cqweb.war file:
- WAS_profile_home\installedApps\nodecell\TeamEAR.ear\cqweb.war\WEB-INF\classes
The cqperl.exe program is located in the directory where Rational ClearQuest is installed.
Before running the clm_server_rename.pl tool, it is a good practice to set the TEMP environment variable to a directory where you have write access. Otherwise, ensure that you have write access in the directory where you are running the tool.
You must run the tool several times.
- Reconfigure cross-server communication only on the Rational
ClearQuest Web server. For each solution for CLM
cross-server friend for which you have reestablished cross-server communication, run the tool with
the -remapconfigfiles option. For each Rational solution for CLM
cross-server friend for which you have reestablished cross-server communication, run the tool with
the -remapconfigfiles option. This updates the Rational
ClearQuest Web server configuration files.Important: When you use this option, you must run the tool from the directory where the tool is installed.
For example, if ClearQuest is integrated with IBM Rational Team Concert and IBM Rational Quality Manager, and both the Jazz Team Server for Rational Team Concert and the Rational Quality Manager server are renamed, then you must run the tool with the -remapconfigfiles option twice: once for remapping the URIs for the Rational Team Concert artifact links, and once for remapping the URIs for the Rational Quality Manager artifact links.
- For each Rational solution for CLM cross-server friend
for which you have reestablished cross-server communication, run the tool again with the
-update option. This updates the URI artifact links that are stored in ClearQuest
OSLCLink records.
For example, if ClearQuest is integrated with IBM Rational Team Concert and IBM Rational Quality Manager, and both the Jazz Team Server for Rational Team Concert and the Rational Quality Manager server are renamed, then you must run the tool with the -update option twice: once for remapping the URIs for the Rational Team Concert artifact links, and once for remapping the URIs for the Rational Quality Manager artifact links.
- If your deployment includes Rational ClearQuest MultiSite, you must repeat the previous step for each replica where the affected Rational ClearQuest OSLCLinks records are mastered. The tool reports the OSLCLinks records that are mastered remotely.
See Remapping URIs after renaming a CLM server for complete procedure details.
See the Options and arguments section for a description of the command-line options.
Limitations
The clm_server_rename.pl tool only remaps structural links that are stored in Rational ClearQuest Web server configuration files and in OSLCLinks records. The tool does not remap embedded links that are stored in Rational ClearQuest records. Such embedded anchor links can be included in record attachments or in fields such as descriptions or notes. Depending on the schema, these fields might become read-only after submission or after a note is added. This means that the embedded anchor links will remain broken after running the tool. You can write code to fix these links, if required.
An example of an embedded anchor link that remains broken after running the tool involves the Rational solution for CLM integration between Rational ClearQuest and Rational Quality Manager. When a Rational Quality Manager artifact is linked to a ClearQuest record, Rational Quality Manager inserts a URI link to the artifact in the record-description field.
Options and arguments
- -username username
- Logon name of an administrative user with Super User privileges.
- -password password
- Password of an administrative user with Super User privileges.
- -dbset dbset
- Name of the database connection.
- -dbname dbname
- Name of the user database.
- -oldprefix oldprefix
- Specifies an existing URI string. The URI format must start with http and include the application context followed by a slash (/).
- -newprefix newprefix
- Specifies a new URI string to replace the existing URI string specified by the -oldprefix option. The URI format must start with http and include the application context followed by a slash (/).
- -remapconfigfiles
- Important: When you use this option, you must run the tool in the directory where the tool is installed.
Remaps Jazz Team Server public URI artifact links for the Rational ClearQuest solution for CLM applications. Specifically, this option remaps URIs that are stored in Rational ClearQuest Web server configuration files. The tool makes a copy of the configuration files before remapping the URIs.
After running the tool with this option, you must restart the Rational ClearQuest Web server. Then, cross-server communication on the web server is reconfigured and users can create new URI links to the Rational solution for CLM artifacts. However, following existing links to the Rational ClearQuest Solution for CLM artifacts will not work until you run the tool again with the -update option.
- -preview number
- Displays a preview of the changes that will be made to the number of OSLCLinks records in the Rational ClearQuest database that contain the oldprefix URI string. Also reports the total number of OSLCLinks records that contain the oldprefix URI string. No changes are made to the user database when this option is used.
- -update
- Updates Jazz Team Server public URI links for the Rational
ClearQuest solution for CLM artifacts. Specifically,
this option updates URIs that are stored in Rational
ClearQuest OSLCLink records.
When the tool is run with the this option, the tool captures the changes to OSLCLinks records in a log file. If the TEMP environment variable is set, the log file is written to the specified directory; otherwise, the log file is written to the directory from where you are running it, provided you have write access. The following file-naming convention is used for the log file:
- clm_server_rename_yyyymmdd_hhmmss.txt
where:
- yyyymmdd
- Date when the tool is run, specified as year, month, and day
- hhmmss
- Time when the tool is run, specified as hour, minute, and seconds
For example, clm_server_rename_20120405_211711.
Examples
- For the server named MyCQWebServer, remap Jazz Team Server URI artifact
links in the Rational
ClearQuest Web server
configuration files that match the URI string specified next.
C:\was_profiles\MyCQWebServer\installedApps\Node02Cell\TeamEAR.ear\cqweb.war\WEB-INF\classes>cqperl clm_server_rename.pl -username admin -password secret -dbset 7.0.0 -dbname SAMPL -oldprefix https://clm7.mycompany.com/ccm/ -newprefix https://clm7.mycompany.com/jazz/ -remapconfigfiles
Started: Remapping URIs in config file friendsconfig.rdf.
Completed: Remapping URIs in config file friendsconfig.rdf.
Started: Remapping URIs in config file project-area-links.rdf.
Completed: Remapping URIs in config file project-area-links.rdf.
Started: Remapping URIs in config file oauth-consumers.rdf.
Completed: Remapping URIs in config file oauth-consumers.rdf. - Preview five OSLCLinks records in the Rational
ClearQuest database that match the URI string
specified next and what the records would look like if the application context is changed from
jazz to
ccm.
cqperl clm_server_rename.pl -username admin -password secret -dbset 8.0.0 -dbname SAMPL -oldprefix https://servername.com:9443/jazz/ -newprefix https://servername.com:9443/ccm/ -preview 5
- Change the protocol in the URI in Rational
ClearQuest OSLCLinks records that match the URI
string specified next from http to
https.
cqperl clm_server_rename.pl -username admin -password secret -dbset 8.0.0 -dbname SAMPL -oldprefix http://servername.com:9443/jazz/ -newprefix https://servername.com:9443/jazz/ -update
- Change the server name in the URI in Rational
ClearQuest OSLCLinks records that match the URI
string specified next from servername to
newservername.
cqperl clm_server_rename.pl -username admin -password secret -dbset 7.0.0 -dbname SAMPL -oldprefix http://servername.com:9443/jazz/ -newprefix https://newservername.com:9443/jazz/ -update