Cq2Svn QuickStart

Overview

Welcome to Clearvision's Change Integration for ClearQuest, integrating Subversion, Git and Mercurial repositories with the ClearQuest change management system.

This guide aims to get you started quickly within a typical environment. For full instructions covering the various configuration options and trouble shooting, please refer to the Administration Guide.

Note that within this guide Windows file paths are used. If installing on Linux, please substitute /opt or another suitable install locations for c:\Program Files in the instructions below.

Request a License

Evaluation License

Evaluation licenses can be requested from the clearvision website: http://www.clearvision-cm.com

A link to the license request form for a product can be found on the product's download page. To request a license we need some information about the machine that you will be running the server on. To get this information, you can run the get_license_info program on the machine you want to use as the server (the get_license_info program can be found within the tools directory of the installation directory). This will retrieve and present system information from the machine.

Once the license request form has been completed and submitted, an email will be sent to the registered email address containing the license infomation. This information will need to be inserted into the server config file.

Note that this license will only work on a particular server machine, on a particular port, and will allow a maximum number of users. The license is time-limited so it is recommended that Evaluation licenses are not requested until needed.

Full License

Once a license has been purchased, you will receive an email containing a link to the online full license generator. A similar form will need to be filled in as for an evaluation license. Once the form has been completed and confirmed a full license will be emailed. Any evaluation license details in the config file will need to be replaced by the full license.

Licenses are tied to the hardware as well as the IP address of the machine used for the server. It is therefore necessary to ensure these details will not change as this will leave the license invalid.

License Request for Clearvision CQ2SVN:
     Evaluation: yes/no
     IP Address: 192.168.64.1
           Port: 54322
    MAC Address: 00-50-56-C0-00-05
          Users: 50
        Company: Your Company name here
  Email Address: yourco@yourco.com
    Expiry Date: 2008-03-31
        Product: CQ2SVNv2

The get_license_info executable is run from a Command Prompt.

Set Up ClearQuest

This example assumes that you are using the SAMPLE database with the 'Defect Tracking' schema.

  1. Use the ClearQuest Designer to edit your schema e.g. Defect Tracking.
  2. Add a MULTILINE_STRING field called cq2svn_integration in the Defect record, for example.
  3. Edit the Defect_Base Form and add a tab. The tab can be any name, however we recommend the name 'Subversion'.
  4. Save and upgrade your databases as normal.

ClearQuest Configuration

  1. edit the perl scripts (get_cq_list.pl and update_cq.pl) which are in the cq2svn\server folder to use your ClearQuest database schema and user settings

CQ2SVN Server

  1. On the CQ2SVN Server, unpack the zip file into c:\cq2svn_server ( Please DO NOT use any path name with a space, such as c:\Program Files, as there is an issue with any path that includes spaces for the perl scripts)
  2. Configure the cq2svn_server.cfg file in the server folder
  3. On Linux, make the cq2svn_server executable chmod +x /opt/Clearvision/cq2svn/server/cq2svn_server
  4. Optionally create a shortcut on the desktop to cq2svn_server.exe (you can use the -f flag to choose the config file)
  5. Make sure that this machine has a copy of the CQPerl ClearQuest API installed (by installing ClearQuest)

Subversion and/or Git Repository Hooks

  1. unpack the zip file into c:\Program Files on the Subversion or Git repository machine
  2. Copy the contents of c:\Program Files\Clearvision\CQ2SVN\subversion_hooks or c:\Program Files\Clearvision\CQ2SVN\git_hooks folder to the hooks directory of your Subversion or Git repository
  3. Configure the cq2svn_hook.cfg file in the hooks folder of your repository
  4. On Linux, make the cq2svn hooks and the Subversion/Git hooks executable, eg chmod +x $MY_REPO/hooks/*
  5. optionally configure the batch/shell files for any local (non CQ2SVN) hooks that you might be using (if you have no local customisation, then no editing should be required)

CQ2SVN Clients

  1. On a client machine start changeintegration_client.jar from the client directory in the installation. On most systems you will be able to double-click this. You can also start the client with java -jar changeintegration_client.jar.
  2. The client will take you through a configuration procedure. Please provide the options that match your server configuration.

Verify your setup

You should now be ready to use CQ2SVN. To test your configuration:

  1. Start the CQ2SVN Server
  2. Start the CQ2SVN client on your client machine
  3. Make sure that you have some records in the 'assigned' state in ClearQuest.
  4. Edit a file in a Subversion working copy on your client machine
  5. Commit the file (making sure that you use the right user name)
  6. You should see a window pop up on your client with a list of CQ records for you to select: select one and click Ok

To check that CQ2SVN has worked:

What Next?

The Administration Guide should be your next step. There you will find much more detail on setup and configuration options and a Troubleshooting guide.

In particular, please note that CQ2SVN is shipped with configuration options set to 'enforcing mode'. There are a number of options in the hook and server configuration files that allow a more permissive setup which may be more applicable to your organization.