VersionOne ClearQuest Integration

Table of Contents

Description

The VersionOne ClearQuest Integration (V1ClearQuest) creates defects in VersionOne based on defects in ClearQuest. Using this integration your organization can manage and triage defects reported by customers and promote them to VersionOne once you determine a fix is necessary.

Once the integraion is installed and configured, ClearQuest users can assign defects to VersionOne and they appear as Defects in the VersionOne repository. When the VersionOne defect is closed, the integration updates the ClearQuest repository to relfect this change.

System Requirements

Operating System — Windows 2003, 2008
Framework — Microsoft .Net 2.0 SP1
VersionOne — Tested with Release 9.0
ClearQuest — Tested with ClearQuest 7.0.1

Downloads

The latest version of V1ClearQuest is available at V1: Integration Downloads.

Installation

These installation instructions assume that ClearQuest is already installed, configured, and working properly.

1. Determine Install Location

V1ClearQuest can be installed on any server with network access to both your VersionOne installation and ClearQuest. Exact placement should be determined by your internal software management requirements. The integration server must meet the System Requirements stated above.

2. Extract Files

Download V1ClearQuest using the link above and extract it into a folder of your choice.

3. Configure

Configuration for the ClearQuest Integration is a 3 step process.

4. Start up

Open up the command prompt, navigate to your installation folder, and run the following command:

VersionOne.ServiceHost.exe

If you have configured your system properly, you should see several [Info] messages followed by a [Startup] message.

5. Test the Service

Create a defect in ClearQuest
Assign this Defect to VersionOne
Verify that the defect appears in VersionOne as a defect
Close the defect in VersionOne
Verify that the ClearQuest defect has been updated

Shut down the service host by pressing "Q" in the console window.

6. Install as a Windows Service

Run the following command from the console window:

VersionOne.ServiceHost.exe --install

This command installs the service so it will run under the account NT AUTHORITY\Local Service. Local Service must be given access privileges to the directory where the V1ClearQuest was installed so it can store its state and write to log files. Follow the steps below to change the security on the installation directory:

Right click the installation folder from Windows Explorer.
Select "Properties".
Select the "Security" tab.
Click the "Add" button.
Enter "Local Service" and click "OK".
Click the "Allow" checkbox for the "Full Control" row .
Click "OK" to save the changes.

For more information on how the Windows Service is configured see Service Host Configuration.

Configuration

ClearQuest Configuration

The VersionOne integration relies on States and Actions defined in the ClearQuest schema to process Defects. The ClearQuest schema allows you to customize your process model (a.k.a. workflow) for different types of change requests in the ClearQuest application. Because the schema customization is so flexible, we cannot describe every possible configuration. Therefore the instructions below describe how we customized our schema for testing. We realize that you may have different needs.

The following tables describe the States and Actions we used when testing V1ClearQuest.

Table 1. ClearQuest States Used by V1ClearQuest

State Name	Description
SubmitToVersionOne	Indicates that the Defect is waiting to be published to VersionOne
AssignedToVersionOne	Indicates that the Defect is available in the VersionOne applicaiton

Table 2. ClearQuest Actions Used by V1ClearQuest

Action Name	Description
AssignToVersionOne	Action used by ClearQuest users to assign a Defect to the VersionOne system. This action puts the Defect in the SubmitToVersionOne State
VersionOneAccepted	Action used by V1ClearQuest after the Defect is created in VersionOne. This action puts the ClearCase Defect into the AssignedToVersionOne State
Close	Action used by V1ClearQuest when the VersionOne Defect is closed

Here are the steps used to configure the States and Actions defined in the tables above

Launch ClearQuest Designer
Checkout the existing schema you want to update
Create a State called "SubmitToVersionOne"

Figure 1.
Set the StateType to "Not_Resolved"

Figure 2.
Create a CHANGE_STATE Action called "AssignToVersionOne"

Figure 3.
Set the Destination State to "SubmitToVersionOne" and the SourceState to "Open" and "Submitted"

Figure 4.
Validate the Schema
Create a State called "AssignedToVersionOne"

Figure 5.
Set the StateType to "Not_Resolved"

Figure 6.
Create a CHANGE_STATE Action called "VersionOneAccepted"

Figure 7.
Set the Destination State to "AssignedToVersionOne" and the SourceState to "SubmitToVersionOne"

Figure 8.
Validate the Schema
Modify the existing "Close" State and set "AssignedToVersionOne" as a valid SourceState

Figure 9.
Validate the Schema
Commit the Schema Changes
Upgrade existing database to the new Schema version

Figure 10.

Note

In addition to States and Actions, please note Mandatory fields. In our environment, the only mandatory field when closing a defect was "Resolution".

VersionOne Configuration

Add "ClearQuest" to the list of valid Source

Figure 11.
The integration needs a VersionOne text field to store the ClearQuest identifier. By default this is the Reference field. If you are already using this field, you'll need to create a custom text field and note the name.

ServiceHost Configuration

The configuration file for the V1ClearQuest is VersionOne.ServiceHost.exe.config. This section describes the elements in the ServiceHost configuration file.

The ClearQuestService element contains the ClearQuest configuration parameters. The following table describes these parameters:

Table 3. ClearQuest Configuration Elements

Name	Description
ClearQuestConnectionName	Name of ClearQuest connection to use
ClearQuestUsername	Valid user for the connection specified
ClearQuestPassword	Valid password for the Username specified
ClearQuestDatabase	Database instance on the specified conneciton
SourceFieldValue	The value to set in the VersionOne Source field. This must be a valid VersionOne Source
ClearQuestWebUrlTemplate	Template used for creating a VersionOne link to the ClearQuest defect
ClearQuestWebUrlTitle	Title on the VersionOne link
ClearQuestMandatoryFields	This element is used to specify ClearQuest Mandatory fields and the values to use when populating these fields
ClearQuestWaitedSubmitToV1State	ClearQuest State that indicates which Defects are ready for delivery to VersionOne
ClearQuestSubmitedToV1Action	ClearQuest Action to perform once a Defect is successfully created in VersionOne
ClearQuestSubmitedToV1State	ClearQuest State that indicates which Defects are in the VersionOne system
ClearQuestCloseAction	ClearQuest Action to perform when a Defect is closed in VersionOne

Example 1. ClearQuestService Element

<ClearQuestService disabled="0" class="VersionOne.ServiceHost.ClearQuestServices.ClearQuestHostedService, VersionOne.ServiceHost.ClearQuestServices" >
		<!-- Connection name for the ClearQust -->
		<ClearQuestConnectionName>Defect</ClearQuestConnectionName>
		
		<!-- User name for login to the ClearQuest-->
		<ClearQuestUsername>admin</ClearQuestUsername>
		
		<!-- Password for login to the ClearQuest-->
		<ClearQuestPassword>password</ClearQuestPassword>
		
		<!-- Database name in the ClearQuest-->
		<ClearQuestDatabase>SAMPL</ClearQuestDatabase>
		
		<!-- VersionOne 'Source' value to use when Defect was created from a ClearQuest defect.  Make sure this value exists in VersionOne.-->
		<SourceFieldValue>ClearQuest</SourceFieldValue>
		
		<!-- Links in VersionOne to ClearQuest defect (we replace #key# with ClearQuest defect id) -->
		<!-- http://domain:port/cqweb/#/<SchemaName>/<DataBase>/RECORD/#defectid#&format=HTML&noframes=true&recordType=Defect -->
		<!-- 
			 SchemaName - Schema name in the ClearQuest 
			 DataBase   - Database name in the ClearQuest 
		-->
		<ClearQuestWebUrlTemplate></ClearQuestWebUrlTemplate>
		<ClearQuestWebUrlTitle>ClearQuest</ClearQuestWebUrlTitle>
		
		<!--Mandatory field which need to be filled during change state of defect to close-->
		<ClearQuestMandatoryFields>
			<!--<Field name="<field name>"><Value></Field>-->
			<Field name="Resolution">Fixed</Field>
		</ClearQuestMandatoryFields>
		
		<!-- ClearQuest state that identifies ClearQuest Defects that are pending delivery to VersionOne -->
		<ClearQuestWaitedSubmitToV1State>SubmitToVersionOne</ClearQuestWaitedSubmitToV1State>

		<!-- ClearQuest Action performed after a VersionOne Defect is been created. -->
		<ClearQuestSubmitedToV1Action>VersionOneAccepted</ClearQuestSubmitedToV1Action>
		
		<!-- ClearQuest state used to indicate that a Defect exists in VersionOne  -->
		<ClearQuestSubmitedToV1State>AssignedToVersionOne</ClearQuestSubmitedToV1State>

		<!-- ClearQuest Action to perform when the VersionOne Defect is closed -->
		<ClearQuestCloseAction>Close</ClearQuestCloseAction>
			 
</ClearQuestService>

Table 4. ClearQuestServiceTimer Elements

Name	Description
Interval	Number of milliseconds to wait between polls to the ClearQuest system
PublishClass	Do Not Change

Example 2.

This example polls every 30 seconds

    <ClearQuestServiceTimer disabled="0" class="VersionOne.ServiceHost.Core.Services.TimePublisherService, VersionOne.ServiceHost.Core">
    <Interval>30000</Interval>
	<PublishClass>VersionOne.ServiceHost.ClearQuestServices.ClearQuestHostedService+IntervalSync, VersionOne.ServiceHost.ClearQuestServices</PublishClass>
</ClearQuestServiceTimer>

Table 5. DefectWriterService Elements

Name

Description

ExternalIdFieldName

Name of VersionOne field that holds the ID of the ClearQuest defect. Must be a text field

Settings

Name	Description
ApplicationUrl	VersionOne Application URL
Username	Valid VersionOne Username. This user must have authority to create defects in the VersionOne projects being processed.
Password	Password for specified user
APIVersion	The minimum application version required for this hosted service.
IntegratedAuth	False if using VersionOne native security, true is using Windows Integrated Security. If VersionOne is configured to use Windows Integrated Security, the account the service is running as must be a configured VersionOne user with a project role of Team Member or higher. Also, Username and Password should be empty if IntegratedAuth is true.

Example 3.

<DefectWriterService disabled="0" class="VersionOne.ServiceHost.DefectServices.DefectWriterHostedService, VersionOne.ServiceHost.DefectServices">
	<ExternalIdFieldName>Reference</ExternalIdFieldName>
	<Settings>
		<ApplicationUrl>http://v1host/VersionOne/</ApplicationUrl>
		<Username>admin</Username>
		<Password>admin</Password>
		<APIVersion>7.2.0.0</APIVersion>
		<IntegratedAuth>false</IntegratedAuth>
	</Settings>
</DefectWriterService>