This page last changed on Mar 15, 2010 by rkrishna.
This page contains instructions for how to set up a ClearCase repository in FishEye, a configuration reference and a list of known issues.
If you also have Crucible, once configured you will be able to run Crucible reviews on code from your ClearCase repository.
On this page:
Requirements
The instructions on this page require the following applications:
- IBM ClearCase 2003.06.10 or later
Setting up a ClearCase Repository
When adding or managing a ClearCase repository, carry out the following steps:
1. Open FishEye's 'Add Repository' dialog, by choosing 'Administration' > 'Repository List' > 'New'.
2. Set your repository details, as described below.
ClearCase Repository Details
Field |
Description |
Allowed values |
Name |
A name chosen by you to be displayed in the list of FishEye repositories. |
Free text |
Description |
A description for this repository, if required. |
Free text |
Repository Type |
Defines the repository type; these instructions apply to ClearCase, so select ClearCase. |
ClearCase |
Enable Immediately |
Defines whether the repository will be accessible in FishEye right away. |
Yes / No |
UCM |
Indicates whether the underlying ClearCase repository uses UCM or Base ClearCase. |
Yes / No |
Integration Streams Only |
Specifies whether FishEye should index content that has been delivered to development and streams or only integration streams. It is recommended that users choose 'Yes' for this option. |
Yes / No |
Auto Create View |
If set, FishEye will create views for each VOB being indexed. If not set, FishEye will use an existing view (which has been specified in the View Location field) |
True/False |
View Location |
If Auto Create View is set, the location of a directory accessible to the FishEye instance where views can be created. If Auto Create View is not set, the location of an existing ClearCase view |
A system path |
View Storage Location |
The location where view storage files are stored. |
A system path |
VOB to Include |
A drop down list displaying all the non-UCM VOBs found in the ClearCase installation. If users only require that FishEye index a single VOB, they should select the VOB to index from this drop down list |
Auto populated |
VOB Includes |
Specifies the pattern that should be used to determine whether a VOB should be included in the indexing logic. Multiple inclusion patterns can be separated with a comma |
Free text |
VOB Excludes |
Specifies the pattern that should be used to determine whether a VOB should be excluded from the indexing logic. Multiple exclusion patterns can be separated with a comma |
Free text |
UCM Project To Include |
A drop down list displaying all the UCM Projects found in the ClearCase installation. If users only require that FishEye index a single UCM Project, they should select the Project to index from this drop down list |
Auto populated |
UCM Project Include Patterns |
Specifies the pattern that should be used to determine whether a UCM Project should be included in the indexing logic. Multiple inclusion patterns can be separated with a comma |
Free text |
UCM Project Exclude Patterns |
Specifies the pattern that should be used to determine whether a UCM Project should be excluded from the indexing logic. Multiple exclusion patterns can be separated with a comma |
Free text |
Screenshot: Adding a ClearCase Repository

Inclusion/Exclusion Settings
The following points provide guidelines for the settings which may need to be applied in order to restrict the number of ClearCase Projects/VOBs indexed by FishEye.
- If you want all the VOBs/UCM Projects within your environment to be indexed, then you don't need to add any additional information on the Edit Repository screen. This is the default behaviour.
- If you want several VOBs/UCM Projects to be included (but not all), then you should include appropriate details in the VOB Includes/Excludes fields
- If you only wish for a single VOB/UCM Project to be indexed, then you should select the specific VOB/UCM Project from the 'VOB to Include' or 'UCM Project to Include' drop down list. This will force FishEye to only index the selected VOB/UCM Project.
View Creation
As part of the repository scanning logic, FishEye will create a view for each Project (for ClearCase UCM environments) or VOB (for Base ClearCase) using the locations defined in the 'View Location' and 'View Storage Location' fields. This is required in order for the underlying 'cleartool' commands to be executed in the correct context. Please note that FishEye will not perform updates on these views - it is intended that these views will remain unpopulated.
Indexing Logic
It may be helpful to understand how FishEye's ClearCase support carries out indexing.
UCM ClearCase
The ClearCase support will attempt to index all the available content within a ClearCase environment. The logic works as follows (ClearCase specific terms are underlined see definitions):
- All PVOBs that are available are identified.
- For each PVOB, find all the Projects contained within the PVOB.
- For each Project, find all the Activities that have been delivered to the project.
- Find the Versions that were included in each Activity and index the Version information.
- Any Labels attached to Versions are also indexed.
PVOB stands for Project Versioned Object Base.
Base ClearCase
The logic for the Base ClearCase support is similar to the UCM ClearCase support,
- All non-UCM VOBs that are available are identified.
- Find the check-ins for each VOB and index the version inforamtion.
- Any Labels attached to Versions are also indexed.
Allocating Time for Repository Scanning
The initial scan of a repository is a time and resource intensive operation, more so if the ClearCase repository being indexed is large (both in terms of the number of ClearCase projects and the number of change sets included in each project). In the Atlassian test environment (running in a virtual machine), each commit included in a change set would take approximately one second to complete (the time taken in a non-VM environment seems to be slightly faster at approx 700ms). You can use these numbers to estimate the time it will take to scan your repository; it could take many hours or possible days to complete.
Changes included in 2.1.3
Config.xml schema changes
The structure of the underlying schema for the ClearCase configuration config.xml file has changed. The effect of this is that for repositories created prior to version 2.1.3, the VOB/UCM Project Inclusion rules won't appear in the Administration UI. However, the previously entered values for these fields will still be used as part of the repository scanning logic.
In order for these fields to be displayed in the Administration UI, the values for these fields should be re-entered.
Interactive invocation of cleartool commands
As a performance improvement measure, a number of the cleartool commands executed by FishEye as part of the repository scanning logic are now executed in 'interactive' mode. That is, a cleartool process (one per repository) is kept open for the duration of the indexing process.
The execution of commands in interactive mode can be disabled by adding a 'disableInteractiveProcess' attribute to the specific ClearCase repository defined in the config.xml file.
Performance Improvements
Subsequent indexing operations for Base ClearCase repositories will take the last indexed date into account, so the 'cleartool lshistory' output will only include those changes that have not already been indexed.
Changes included in 2.1.2
In the first release, the include/exclude rules for VOBs and Projects were handled by the 'Include/Exclude' rules item on the administration page. Based on feedback received during initial version testing, this has been updated to provide additional flexibility:
- The VOBs which are indexed can be controlled via the 'VOB to Include' and 'VOB Include/Exclude Patterns' fields.
- Similarly, the UCM Projects which are indexed can be controlled via the 'UCM Project to Include' and 'UCM Project Include/Exclude Patterns' fields.
- The Include/Exclude rules on the Administration page now apply to files/directories that are indexed within a ClearCase VOB/Project. The values entered into these fields perform the matching logic as defined on the Allow (Process) page
Known Issues
There are a number of known issues with ClearCase support in FishEye. These are listed below.
- Currently XML files cannot be viewed as 'Annotated' source. By default, ClearCase using a specific type manager to store XML files. This type manager does not support the 'cleartool annotate' command, which is used by the logic in FishEye that displays the Annotated source.
Further to this, by default ClearCase treats any files not defined in the 'default.magic' file as 'compressed' (for instance, property files are not included in the default.magic file). Only text-based type managers can be annotated (and hence, can be displayed via the 'Annotated Source' link). The type manager can be updated by performing the following steps:
1. Update the default.magic file to include appropriate rules that specify the type manager to use for files of a given naming convention (this will take effect for newly created elements)
2. Modify the type manager for existing elements through the 'cleartool chtype' command.
Further information on the ClearCase type manager is available on the following pages:
Type Manager white paper
cleartool chtype command reference
cc.magic reference
- There is a known bug with earlier versions of ClearCase that limit the cleartool output to 64K of data. This may affect projects that contain a large amount of changes included in a changeset. This bug can be fixed by upgrading ClearCase — see this page for more information.
Feedback and Support
Please raise a support ticket to seek assistance with FishEye ClearCase support.
|