Applies to Collaborator 13.2, last modified on October 02, 2020

Collaborator seamlessly integrates with the IBM Rational ClearCase version control system. This section provides a general overview of integration preferences, ways to review files controlled by ClearCase, and so on.

About Integration

Using the built-in Collaborator IBM Rational ClearCase integration, you can quickly upload various files to the Collaborator server to create a review directly from the desktop client of your choice. The types of files you can upload include:

  • Files controlled by ClearCase that are checked out and checked in.
  • UCM changesets.

Collaborator also supports ClearCase UCM activities. The changeset associated with a ClearCase activity can be added to a review using the addactivity command in Command-Line Client. For each file in the activity, the latest version in the activity and the predecessor of the earliest version in the activity are uploaded to the review.

Note: Uploading activities for review generates file differences based on Multiple Version Changelists. Uploading activities is not supported by Rational ClearCase Remote Client.

ClearCase integration uses ClearCase client applications that are already installed on the client computer. That is, integration supports all protocols, authentication settings, proxies, and other configuration specifics.

Supported Versions

To enable the integration via GUI Client and Command-Line Client, you need the ClearCase command line client (cleartool.exe) to communicate with the server. We support the following versions:

  • Rational ClearCase and Rational ClearCase LT, versions 4.1 through 9.x.
  • Rational ClearCase Remote Client (CCRC), version 9.x.

Ways of Integration

You can enable the integration between Collaborator and ClearCase for GUI Client, Command-Line Client or Collaborator server.

GUI Client

To enable the integration:

  1. Start GUI Client.

  2. Click Add to create a new SCM configuration.

  3. In the subsequent SCM Configuration dialog, specify the local source code location.

  4. Select ClearCase in the SCM drop-down list.

  5. Several options will become available. These are specifically tailored to configure ClearCase integration.

    Option Description
    CCRC Server URL An URL of the ClearCase server. Required for remote connections.
    CCRC User Name A user-name you want to use to authorize on the ClearCase server. Required for remote connections.
    CCRC Password A password you want to use to authorize on the ClearCase server. Required for remote connections.
    Cleartool Executable A full path to the cleartool command line client (clearcase.exe).
    Update Snapshot View If selected, updates ClearCase snapshot views before uploading files to a Collaborator review.
    SCM Configuration: ClearCase
  6. Once ready, click Validate to make sure the integration is operational.

After that, a new configuration for ClearCase will appear on the main screen of the GUI Client.

Select it, then click on the corresponding button depending on what you want to do next:

Add to Review buttons
  • Add Changes – Upload files that you have checked out to the Collaborator server and add these to a review.

    Add Changes
  • Add My Activities – Upload files from selected activities that you own to the Collaborator server and add these to a review.

    Add activities which you own
  • Add Activities – Upload changes from a specific named ClearCase activity to the Collaborator server and add these to a review.

    Note: You cannot upload activities that have CHECKEDOUT versions, if you do not own these activities.
    Add activities by name
  • Add Versions – Upload versions of files in your working copy of ClearCase repository and add these to a review on the Collaborator server.

    1. Specify a name for a review or select the existing review.

    2. Click Next.

    3. In the dialog, you need to select one or more files in your checkout, which you have specified during the configuration.

      Select files
    4. Click Next.

    5. On the next page, there are files you have selected. You need to select versions of these files you want to add to the review.

      Enter the ClearCase versions of each file to the Before and After columns.

      Tip: To specify versions, you can use the local and LATEST keywords. To learn about ClearCase keywords, please see the ccollab addversions command description.
      Specify versions

      To fill the before and after versions for all files automatically, specify the needed version in the Autofill After versions and Autofill Before versions edit boxes, then click apply.

      To clear previously specified versions, enter an empty string to these edit boxes, then click Apply.

      Automatically fill in before/after values
    6. (Optional) Specify a branch you want to use:

      Specifying branch name

      You can input the absolute branch version path (for instance, \main\branch_new_1\sub_branch_new_1\1) or relative path (\sub_branch_new_1\1).

Command-Line Client

In the Command-Line Client, you can create a review for various activities and files controlled by ClearCase.

For example, to create a new review and add all changes in the add_new_scm_support activity, you can use the following command:

ccollab addchangelist new add_new_scm_support

Commands recommended for ClearCase

ccollab addchanges - Attaches locally-modified files to a review.

ccollab addchangelist - Attaches an atomic changelist to a review.

ccollab addversions - Attaches any 2 given versions to a review.

ccollab addactivity - Attaches file versions in a ClearCase activity to a review.

ccollab commit - Commit changes in the review.

There is an option for the addchanges command that allows local changes to be uploaded with a predecessor version in another branch as the previous version. For this purpose, use the --diffbranch option:

ccollab addchanges --diffbranch branch-name review file-or-dir [file-or-dir] ...

For example, to create a new review and add all changes in the current directory and below, and compare them to the predecessor versions in the \main branch, you would use:

ccollab addchanges --diffbranch main new .

You can also use the special branch name pre to refer to the predecessor branch. For example, to add the local changes to hello.c compared to the most recent predecessor version in the previous branch to review 45, you would use:

ccollab addchanges --diffbranch pre 45 hello.c

  • The addversions command will upload arbitrary versions of ClearCase files after they are checked in.

  • The addactivity command will upload UCM change sets for review.

In most cases, the Command-Line Client can automatically detect your ClearCase configuration. Try testing your configuration to verify the configuration is detected correctly.

If the Command-Line Client is unable to detect your ClearCase configuration or you want to override the detected settings, you can manually specify ClearCase settings using global options.

To manually configure the Command-Line Client to use ClearCase, execute the following command:

ccollab set scm clearcase

ClearCase-specific Options

Option

Description

--ccrc-server-url <value>

CCRC server URL (for ClearCase Remote Client integration only).

--ccrc-user <value>

CCRC username (for ClearCase Remote Client integration only).

--ccrc-passwd <value>

CCRC password (for ClearCase Remote Client integration only).

--clearcase-exe <value>

Full path to the "cleartool" command-line client.

--clearcase-update-snapshot

Whether to update ClearCase snapshot views prior to uploading files for review.

Eclipse Plug-in

Eclipse Plug-in seamlessly integrates with the IBM Rational ClearCase SCM Adapter plugin or with the open source ClearCase plugin for Eclipse. With this, you can upload locally modified files to a review directly from your preferred plugin.

To learn more, please see Add to Review Wizard.

Web Client

Collaborator administrator can configure the Collaborator server to communicate directly with ClearCase repositories. Server-side integration allows users to upload committed atomic changelists (activities in terms of ClearCase) from the Web Client without having to install and configure client-side tools.

To upload changelists:

  • Log in to Web Client.

  • Create a new review, or open an existing one.

  • Scroll to the Review Materials section of the Review Screen.

  • Click Upload button and then select the item corresponding to the desired repository.

    Note: Item titles are specified by your Collaborator administrators and they will vary from those in the image below.
    Uploading changelists via Web Client
  • In the ensuing dialog, specify the IDs of desired changelists. Separate multiple IDs by space character.

    Uploading changelists via Web Client
  • Click Attach to upload the specified changelists to the review.

To enable the feature, your Collaborator administrator will need to perform the following actions:

  1. Install and configure a ClearCase client on the Collaborator server.

  2. Log in to Collaborator server.

  3. On the Collaborator main toolbar, click ADMIN, and then select Version Control from the tree on the left. Then switch to the Version Control Servers tab.

    This tab lists available version control server configurations. They could be created manually, as described bellow, or could be created automatically when one of the client programs uploads files from a server that does not match any of the currently configured servers.

  4. Select "ClearCase" from the SCM System drop-down list and click Create.

  5. Specify the values for the following properties:

    Server-side integration with ClearCase

    Click the image to enlarge it.

    Option Description
    Title The title is displayed to users, so it should be something that everyone will understand, even if they are going through proxies, VPNs, or other such things. When a version control server entry is created automatically, this is filled in with the URL the client used to connect to the ClearCase server.
    Attach changelists from browser If enabled, this feature lets users select committed revisions to review directly from the web browser, without having to install any client programs.
    Cleartool Executable A full path to the cleartool command line client (clearcase.exe).
    Update Snapshot View If set to "True", Collaborator will update ClearCase snapshot views before uploading files to a review.
    Clearcase View Path Full path to the Clearcase view or vob directory.
  6. Click Test Connection to verify that the connection between Collaborator server and your Clearcase server is established successfully and is trusted. For example, you might need to generate and/or accept trust certificates and so forth.

  7. The Client Configuration Mapping section defines correspondence between files uploaded by the various Collaborator clients and this server-side Clearcase configuration.

    Specify Java-style regular expressions to map changelists uploaded from our client tools to this Clearcase server:

    Option Description
    Server host name Pattern Match on the server host URL.
  8. Press Save to create configuration and enable server-side integration with this ClearCase repository.

Support for ClearCase Remote Client (CCRC 9.x only)

Collaborator integration with CCRC uses Rational Change Management Server API. When running the Collaborator client installer, there is an edit field you can use to specify the location of the Rational CM API JAR files on your system. The required files are:

  • remote_core.jar
  • stpcc.jar
  • stpcmmn.jar
  • stpwvcm.jar

These files are installed by the ClearCase Remote Client in the Rational Shared Resource directory. The directory should look similar to one of the following:

C:\Program Files\IBM\IMShared\plugins\com.ibm.rational.teamapi_9.0.0.vNNNNNNNN

/opt/eclipse/plugins/com.ibm.rational.teamapi_9.0.0.vNNNNNNNN

Launch Collaborator client installer with administrator privileges, find the location of the Rational CM API JAR files on your system and specify it in the CM API Directory field during the installation. The installer will copy these JAR files to the following subdirectory under the Collaborator client installation directory:

<Collaborator Client>/ui/plugins/com.smartbear.collaborator_13.2.xxxx

After that, the Collaborator client would become able to use Rational Change Management Server API.

If using the RPM installer, you will have to manually copy these JAR files to the correct subdirectory.

Once installed, create a ClearCase SCM configuration using the same connection parameters to the ClearCase CM server as your ClearCase Remote Client. These are your user-name and password, and the ClearCase TeamWeb services URL. For example, if your ClearCase server host name is cc-server, the default server URL would be:

http://cc-server:16080/ccrc

Be careful to specify your connection parameters correctly. These parameters are not authenticated up front, instead calling back when server activity must take place. If the authentication is wrong, a cascade of errors can occur which can exhaust the RPC connections to the CM server.

Technical Details and Limitations

Collaborator does not guarantee that Diff Viewer will display correct comparison results for the following cases:

  • If you add several diffs (non atomic changelists) to the same review.

Known Issues

ClearCase Remote Client views can get corrupted in a way that causes the CM API to generate exceptions when trying to upload CCRC files to a review. We do not know the cause of these exceptions, but selecting Refresh > Repair >Vob Tag Directories from the view context menu in the CCRC client, or deleting and recreating the view, fixes this condition.

See Also

Integration With Repository Hosting Services
SCM Configuration
Source Control Integrations

Highlight search results