VersionOne Perforce Integration

Table of Contents

Description

The VersionOne Perforce Integration (V1Perforce) creates a record of Perforce changesets in VersionOne, so the development team can quickly view all of the code changes for a story or defect. This visibility can be useful when tracking down defects or performing code reviews.

Once V1Perforce has been installed, development team members include a story, defect, task or test ID, such as “B-01454”, or "TK-01002" in their Perforce commit messages. V1Perforce checks each commit message for IDs and creates a changeset within VersionOne for each story or defect matching the entered IDs. A changeset is the collection of changes for a single revision in Perforce. The changesets for each story or defect are viewable on the details page of that item in VersionOne. Additionally, V1Perforce has the capability to create link on the changeset in VersionOne that navigates to the changeset in a Perforce repository viewer.

System Requirements

VersionOne: 7.1 or above

Integration Server:

Operating System—Windows 2003, 2008
Framework—Microsoft .Net 2.0 SP1

Perforce Server:

Perforce Version 2003.2 - 2008.2

Downloads

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

Installation

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

1. Determine Install Location

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

2. Extract Files

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

3. Configure

Open the file VersionOne.ServiceHost.exe.config in a text editor, change the configuration parameters, and save your changes. For a complete description of each configuration parameters, see Hosted Service Details.

Table 1. V1Perforce Configuration Parameters

Parameter	Description
Port	Name of Machine hosting Perforce and the Perforce listen port
View	Perforce View to watch for changes.

ApplicationUrl	VersionOne installation URL
Username	User that will access VersionOne
Password	Password for the username above
IntegratedAuth	VersionOne security setting
URL	URL for your repository viewer

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

Commit a change to your Perfroce repository with a message of “test”. You should see the following output:

[Info] Publishing ChangeSet: #, "test"; No References found.
[Info] No Change Set References. Ignoring Change Set: #

Commit a change to your Perforce repository with a message of “B-01001”. You should see the following output:

[Info] Publishing ChangeSet: #, "B-01001"; references: B-01001

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 will run under the account NT AUTHORITY\Local Service. Local Service must be given access privileges to the directory where the V1Perforce 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.

Hosted Service Details

V1Perforce utilizes three hosted services within the V1 Service Host framework in order to perform the integration. Each service performs a specific function and is configured by changing values in VersionOne.ServiceHost.exe.config.

P4ReaderService

The P4ReaderService watches the Perforce repository for new changesets and publishes changesets that contain messages matching the specificied regular expression to the ChangeSetWriterService.

Table 2. P4ReaderService Configuration Parameters

Parameter	Description
Port	Name of Machine hosting Perforce and the Perforce listen port
UserName	User name for Perforce. If using Windows Integrated Security, leave empty.
Password	Password for Perforce. If using Windows Integrated Security, leave empty.
View	Perforce View to watch for changes.
ReferenceExpression	A regular expression which the service will attempt to match in the commit message.

Example 1.

<P4ReaderService class="VersionOne.ServiceHost.SourceServices.Perforce.P4ReaderHostedService, VersionOne.ServiceHost.SourceServices" >
	<Port>localhost:1666</Port>
	<View>//Depot/..</View>
	<ReferenceExpression>[BD]{1}-[0-9]+</ReferenceExpression>
	<User>UserName</User>
	<Password>Password</Password>
</P4ReaderService>

P4ReaderServiceTimer

The P4ReaderServiceTimer triggers the P4ReaderService every N milliseconds.

Table 3. P4ReaderServiceTimer Configuration Parameters

Parameter	Description
Interval	The interval, in milliseconds, between events raised (via publishing the IntervalSync)
PublishClass	Contains the class and its' assembly that that the TimePublisherService will publish at every interval. For Subversion integration using P4ReaderService, it must be set as in the example below.

Example 2.

<P4ReaderServiceTimer class="VersionOne.ServiceHost.Core.Services.TimePublisherService, VersionOne.ServiceHost.Core">
	<Interval>60000</Interval>
	<PublishClass>VersionOne.ServiceHost.SourceServices.Subversion.P4ReaderHostedService+P4ReaderIntervalSync, VersionOne.ServiceHost.SourceServices</PublishClass>
</P4ReaderServiceTimer>

ChangeSetWriterService

The ChangeSetWriterService listens for changesets published by the SubversionReaderService and updates VersionOne with the results. If a ChangeSet exists with a matching reference, it is updated to reflect the Log message from the source change, and any relationships to Workitems.

Table 4. ChangeSetWriterService Configuration Parameters

Parameter	Description
ApplicationUrl	The URL for your VersionOne application
Username	The VersionOne account username, if using native VersionOne security. If using Windows Integrated Security, leave empty.
Password	The VersionOne account password, if using native VersionOne security. If using Windows Integrated Security, leave empty.
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.
ReferenceAttribute	The VersionOne attribute that will be used as a reference for the story or defect. In most cases it should be set to Number (ID).
ChangeComment	The change comment put into history for any modifications the service makes in VersionOne
Name	The name for the changeset link within VersionOne. {0} is replaced with the changeset id.
URL**	The URL for the changeset link within VersionOne. {0} is replaced with the changeset id.
OnMenu	Sets the "Add to Menu" checkbox for the changeset.
AlwaysCreate	False to only create a ChangeSet Asset if there are related workitems. True to always create ChangeSets.

* When using the integrated authentication security setting, V1Perforce will login to VersionOne using the Windows domain user under which the executable is running if both the username and password parameters are blank. If the username and password is entered, you must specify the windows domain account in the form "User@FullyQualifiedDomainName". If you are unsure what the fully qualified domain name is, see the Domain name shown on the 'Computer Name' tab in the My Computer...Properties dialog.

** V1Perforce replaces "{0}" with the revision number. If you do not have a repository viewer delete the whole link section.

Example 3.

<ChangeSetWriterService class="VersionOne.ServiceHost.SourceServices.ChangeSetWriterService, VersionOne.ServiceHost.SourceServices">
	<Settings>
		<ApplicationUrl>http://localhost/VersionOne/</ApplicationUrl>
		<Username>admin</Username>
		<Password>admin</Password>
		<APIVersion>7.1.0.0</APIVersion>
		<IntegratedAuth>false</IntegratedAuth>
	</Settings>
	<ReferenceAttribute>Number</ReferenceAttribute>
	<ChangeComment>Updated by VersionOne.ServiceHost</ChangeComment>
	<Link>
		<Name>ChangeSet: {0}</Name>
		<URL>http://p4web:8080/@md=d&amp;cd=//&amp;c=3IB@/{0}?ac=10</URL>
		<OnMenu>True</OnMenu>
	</Link>
	<AlwaysCreate>false</AlwaysCreate>
</ChangeSetWriterService>