CQ2SVN uses the Clearquest Open API to communicate between Clearquest and Subversion. To date, we are supporting CQ2003 and Version 7.1 of Clearquest. Because the API has not changed since version CQ2001, CQ2SVN is expected to work on versions up to and including this version.
No, CQ2SVN is 100% client-independent meaning you can carry on using your favorite Subversion client. CQ2SVN installs one small executable and configuration files on the user's machine. No operating system or client modifications are required.
This is very easy to achieve. Upon setup, CQ2SVN will dynamically query your Clearquest database as if it was installed from the initiation of your project.
At present, we do not have an SAP integration.
You can customise the Clearquest side as you like. We supply 2 sample perl scripts for the Defect Tracking schema. If you want to use another configuration, you can customize these scripts freely.
Whilst we do not specifically test with 64-bit operating systems, most Clearvision products will run on most 64-bit variants of the supported operating systems.
On Vista and Windows 7 64-bit, you should be able to start the product normally.
On 64-bit Linux distributions such as Ubuntu or Debian, you will need to install the ia32-libs package, which installs a basic set of 32-bit libraries, allowing you to run Clearvision products. A similar procedure is required for Redhat Enterprise and Fedora.
Solutions for running 32-bit applications on 64-bit Linux vary slightly between the different Linux distributions. Please refer to the documentation of your distribution for details.
Yes, CQ2SVN will work on RHEL 6. However, a 'wrapper' is required for ClearQuest due to an incompatibility between a library that is present within RHEL 6 and one that is bundled with CQ2SVN. After you have setup CQ2SVN, if you recieve an error message which states 'Cannot find hostname' or an error to do with DNS problems, create a file called 'cv-clearquest' and add the following to the file:
#!/bin/bash unset LD_LIBRARY_PATH /full/path/to/clearquest "$@"
Apply executable rights to to the file 'cv-clearquest' and then tell CQ2SVN to use this file instead of the standard ClearQuest executable. To do this, locate your cq2svn_server.cfg configuration file and edit the ClearQuest path setting.
CQ2SVN uses the approved API calls to extract and update Clearquest records. These tasks are being performed by the CQ Administrator and in our tests, a license is NOT consumed. IBM has stated this is a bug in Clearquest and customers should accommodate for utilizing a license in the future.
Because CQ2SVN bridges the gap between two completely separate databases, it would theoretically be possible for a crash to cause a write to Clearquest and not to Subversion. However, the probability of this happening is minimal.
There are certain operations which can be modified after a Subversion commit. With regards to the CQ2SVN integration with Clearquest, the fields in Clearquest can be modified by a privileged user (typically your Clearquest administrator).
From the Subversion side, CQ2SVN writes into a Clearquest record ID in a revision property. There are various Subversion commands which allow us to query and report. Clearquest is very similar; with CQ2SVN writing the Subversion change set and Subversion revision ID into a Subversion tab. This can be easily queried and reported using Clearquest's reporting functionality.
CQ2SVN will allow the administrator to control the behaviour and allow the commit to pass through or fail.
Yes, anyone who is not logged on via CQ2SVN will automatically be excluded from choosing a Clearquest record to associate commits with.
There are two different configuration files. CQ2SVN client manages issues such as the compatibility of the user's name (Subversion and Clearquest require this). The server config file holds the value regarding 'commit on error'. This server config file is central and holds anything that is controversial and should not be changed by users.
In principle yes. However, on occasion there may be problems with LDAP user names being mixed-case (e.g. UserName) and ClearQuest user names being all lower-case (e.g. username).
If you come across this problem, you can customise get_cq_list.pl and convert mixed-case user names into lower-case user names for ClearQuest as follows:-
[...]
sub get_cq_list {
my ($cq_userid, $cq_superuser_id, $cq_superuser_password, $cq_db, $cq_dbset) = @_;
# BEGIN CUSTOMISATION: Convert user names to lower case
$cq_userid = lc $cq_userid;
# END CUSTOMISATION
my $session;
my $querydef;
[...]
At the moment, with CQ2SVN out-of-the-box, if you want to be able to use ClearQuest reports based on user ids, Subversion and ClearQuest user id's have to match.
However, you can customise get_cq_list.pl and map Subversion user names to ClearQuest user names.
Add the following code to the bottom of get_cq_list.pl:-
sub get_cq_user_name {
my ($svn_user_name, $mapping_file_path) = @_;
open FILE, $mapping_file_path or die $!;
while (<FILE>) {
$line = $_;
if ($line =~ m/^([^#]*?)=(.*?)$/) {
$old_user_name = $1;
$new_user_name = $2;
if ($old_user_name eq $svn_user_name) {
return $new_user_name;
}
}
}
print "Error: Cannot map Subversion user name '$svn_user_name' to a ClearQuest user name\n";
# Return svn_user_name as a fallback (please customise if you want different behaviour)
return $svn_user_name;
}
Then in the subroutine 'get_cq_list', customise the code as follows:-
[...]
sub get_cq_list {
my ($cq_userid, $cq_superuser_id, $cq_superuser_password, $cq_db, $cq_dbset) = @_;
# BEGIN CUSTOMISATION: Map Subversion user name to ClearQuest user name
my $mapping_file_path = "c:\cq_user_mapping_file.txt";
$cq_userid = get_cq_user_name($cq_userid, $mapping_file_path);
# END CUSTOMISATION
my $session;
my $querydef;
[...]
Then write a user mapping file and store it in the location specified in above customisation, e.g. 'c:\cq_user_mapping_file.txt' in this case. The mapping file should look as follows:-
# User mapping file for CQ2SVN # Syntax: subversion_user_name=cq_user_name # One entry per line fred=paul gerry=matt matt=andy ashley=martin
Yes you can. When you install CQ2SVN Subversion hooks, you need to change the pre and post-commit hooks such that CQ2SVN is only called for commits that relate to a particular locations in the Subversion repository.
A special Subversion command svnlook can be used in the hooks to retrieve information about what the user has committed, and you can then make decisions based on that information.
On a Linux system, you could write a hook as follows:-
#!/bin/bash
cd $1/hooks
CHANGES={{svnlook changed $1 --transaction $2}}
FILES={{sed "s/^...//" <<EOF
$CHANGES
EOF
}}
RUN_CQ2SVN="false"
for FILE in $FILES; do
case $FILE in
# Add your repository locations for which to run CQ2SVN hooks here
trunk/proj1/*) RUN_CQ2SVN="true";;
trunk/proj2/*) RUN_CQ2SVN="true";;
trunk/proj4/*) RUN_CQ2SVN="true";;
esac
done
if [ "$RUN_CQ2SVN" == "true" ]
then
$1/hooks/cq2svn-pre-commit $1 $2
fi
The commit time recorded in ClearQuest is the UTC (Coordinated Universal Time) time taken directly from Subversion. It is not the local time of the commit.
There can be users that commit to subversion without firing the CQ2SVN pop up. For example an Automated build or 3rd party program. CQ2SVN can be made to avoid firing on these commits. Firstly, the desired user must have a specified, and unique, SVN logon.
It should be noted that performing these modifications effectively bypasses CQ2SVN for the specified user and should nnot be used unless you fully understand the consequences. In order to achieve this you must edit to the hooks in your subversion repository as follows;
In Windows the hooks are represented as .bat files which in turn fire executables. The hooks can be edited using the following code.Pre Commit Hook:
FOR /F "tokens=*" %%i in ('svnlook author %1') do SET COMMITER=%%i
if "%COMMITER%"=="username" GOTO FINISHED
%1\hooks\cq2svn-pre-commit.exe %1 %2{
exit %ErrorLevel%
:FINISHED
exit 0
Post Commit Hook:
FOR /F "tokens=*" %%i in ('svnlook author %1') do SET COMMITER=%%i
if "%COMMITER%"=="username" GOTO FINISHED
svnlook author %1 >> c:\post_author.txt
%1\hooks\cq2svn-post-commit.exe %1 %2
exit %ErrorLevel%
:FINISHED
exit 0
This code sets the variable COMMITER as the current author of the commit, and then proceeds to only call the executable if the user is not the specified username. You should specify here the username that is intended to be ignored.
In Linux you can modify the hooks directly so they appear similar to this:
Pre Commit Hook:
REPOS="$1" TXN="$2" # Make sure that the log message contains some text. author=cmbridge SVNLOOK=/usr/bin/svnlook $SVNLOOK author "$TXN" "$REPOS" | grep "$author" > /dev/null if [ $? == 0 ]; then #Comitted by cmbridge user exit 0 else cd $1/hooks ./cq2svn-pre-commit $1 $2 fi
Post Commit Hook:
REPOS="$1" TXN="$2" author=cmbridgeSVNLOOK=/usr/bin/svnlook$SVNLOOK author "$TXN" "$REPOS" | grep "$author" > /dev/null if [ $? == 0 ]; then #Comitted by cmbridge user exit 0 else cd $1/hooks ./cq2svn-post-commit $1 $2 fi
Using these modified hooks will ensure they do not fire the CQ2SVN GUI popup. Allowing users to perform commits without Interruption.
No. The client does not require any parts of Clearquest to be installed.
In comparison to registering Subversion commits via a Clearquest record manually, CQ2SVN will obviously speed up the process in comparison with opening the Clearquest web client for example.
The amount of information that travels through communication channels is very small and a lot of this process is performed at the server end. As with a lot of multi-sited software, there will always be slight delays, but one should measure these in milliseconds rather than multiple seconds.
Each server instance of CQ2SVN can only point to a single Clearquest instance. It is possible to have a single Subversion repository call one of many CQ2SVN servers based upon either a username filter or a directory/file filter.
CQ2SVN uses TCP. We believe CQ2SVN is secure, working with Clearquest record ID's and file names rather than raw data. Further to this, you can configure the port that the CQ2SVN server listens on, and ensure this is the only incoming port that is required to be accessible by the client.
CQ2SVN allows for routing on any user defined port. The configuration files on the client and the server require a port number in order to communicate and would involve opening any relevant firewalls first.
A Record Type Family is a way of logically grouping together ClearQuest Record Types.
The main reason/advantage for creating a Record Type Family is that they give greater flexibility when you are querying your ClearQuest user database. When you define a ClearQuest query you must always specify the record type that the you are querying - therefore you are normally only able to query one record type at a time. However, a record type family can also queried and when you query a family the query will include all record types that are members of the family.
Example
Two Record Types exist;
- Defect
- Enhancement
- A Record Type Family is created called;
ChangeRecords
- Both the Defect record type and the Enhancement record type are added as members of the ChangeRequest family;
ChangeRequests
|_Defect
|_Enhancement
- Now any query defined to query the ChangeRequest family will automatically query both Defect records and Enhancement records.
When creating a Record Type Family you must consider;
When using different character sets, in particular when committing changes on a Linux platform to a ClearQuest server on Widows, some special characters placed in the commit message may not be translated correctly and appear differently in ClearQuest.
Please note that this does not cause any problems and is only an issue with the display of these special characters.
I'm getting the following error, what's the problem?
connection failed for reason: [Failure instance: Traceback (failure with no frames): <class 'twisted.internet.error.ConnectionRefusedError'>: Connection was refused by other side: 10061: Unknown error.
This is usually because there is a firewall blocking the port.
You may have a machine-specific firewall service protecting either the Client, Server or both machines. The easy way to test this is to disable any firewall services (such as http://www.microsoft.com/downloads/details.aspx?FamilyID=4454e0e1-61fa-447a-bdcd-499f73a637d1&DisplayLang=en) that are enabled and run CQ2SVN again. If this works, re-enable your firewall and try opening the port that you have configured (remember the client must talk to the server and the server has to be able to talk back to the client).
Other than machine-specific firewalls, you may also have a corporate network firewall which is monitoring traffic between 2 remote networks (eg you have a developer in Chicago who is trying to use a server in London). Consult your network security group for more information.
I'm getting the following error, what's the problem?
xlib: connection to ":0.0" refused by server xlib: No protocol specified Unable to access the X Display, is $DISPLAY set properly?
This is usually caused by a X server authentication issue. Try running the command xhost + and running the client again. You can put the command into the run_client.sh script above "$CQ2SVN_HOME/client/cq2svn_client -f $CQ2SVN_HOME/client/cq2svn_client.cfg" to prevent you having to run the command every time you start a new X server session.
I'm getting the following errors, what's the problem?
ERROR * ** update_cq.pl did not return a valid integer on stdout to indicate status, returned "". WARNING username cq2svn-post-commit: Issue Update failed for repos=C:\Repositories\sample rev=2 (status=1, reason=*** Could not update Clearquest issues, update_cq.pl failed with error status: 9). PLEASE INFORM YOUR SYSTEM ADMINISTRATOR!
This is usually caused by the CQ2SVN pearl scripts being located in a path containing spaces.
Please do not use a path name with a space such as c:\Program Files as CQ2SVN does not presently support paths with white spaces to the perl scripts.
I'm getting the following error, what is the problem?
ERROR cmd "['CQperl.exe', 'C:\\Clearvision\\cq2svn\\server\\get_cq_list.pl', 'tester']" FAILED (status=33, output="An error was detected retrieving information from the ClearQuest database. There is a reference to an object that does not exist: Object Type: Entity Object: This error was detected at: ClearQuest Core:adquerydef.cpp:2530 Recommendation: If you cannot determine how to resolve this issue, contact Rational Support and provide all the above information as well as a description of the context in which the message occurred. at C:\Clearvision\cq2svn\server\get_cq_list.pl line 55.")
The reason for this is a miss configured get_cq_list.pl script. Check your get_cq_list.pl file especially the line my $record_type = "Defect"; ensure the record type matches your ClearQuest schema.
The best approach to track the number and who is using the tool is via the log file. Write a small script to parse the log file looking for the following;
The user will need to switch to INFO log level to get the information required.
When a user logs in, the following message is displayed.
INFO >>> LOGIN userid="user1" from client at IP="192.168.1.56"
When the connection is closed, the following message is displayed:-
INFO <<< LOGOFF userid="svn" from client at IP="192.168.1.56"
After every logon message, a summary is displayed showing the users connected to the server at that time. This is probably the best information for the user to scan for as it gives clear information on who is connected at that particular point in time:-
INFO ... current users=['user1:192.168.1.56', 192.168.1.54', 'user2.192.168.1.18'], number_of_clients=3
In the example above, the same user user1 is connected from two different machines indicated by the two IP addresses, and a different user user2 is also connected.
NOTE - Ignore the field value 'number_of_clients=3', this is for internal use only.
A license is consumed every time a connection is made to the server i.e. if the same user logs in on two different clients, this will consume two licenses. The log file will record the user and the client IP address.
We recommend using NSSM (http://iain.cx/src/nssm/) to create a service on Windows.
On a Windows command prompt, type
nssm.exe install CQ2SVN
You can now start and stop the service from the windows service manager window.
Note that the CQ2SVN client should not be run as a service. Different users logging in will require their own clients, and for that reason it is better to run the client as a Startup application.