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 or defect ID, such as “S-01454” 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

The following sequence diagram illustrates how V1Perforce interacts with Perforce and VersionOne.

System Requirements

• VersionOne: 7.1 or above, including Team Edition
• Integration Server:
  • Operating System—Windows 2003, 2008
  • Framework—Microsoft .Net 2.0 SP1
• Perforce Server: Version 2003.2 - 2011.1

Download

The latest version of V1Perforce is available from the VersionOne Community site

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 network access to both VersionOne and Perforce. 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 V1Perforce using the link above and extract it into a folder of your choice.
   
   
3. Configure
   Instructions for configuring V1Perforce are located below in the "Configure The Integration" section
   
   
4. Start integration
   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 integration
   To ensure the integration is working, perform the following steps:
   1. Commit a change to your Perforce 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: #
      

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

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

   3. 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 V1ClearQuest executable 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:

   1. Right click the installation folder from Windows Explorer.
   2. Select "properties".
   3. Select the "Security" tab.
   4. Click the "Add" button.
   5. Enter "Local Service" and click "OK".
   6. Click the "Allow" checkbox for the "Full Control" row .
   7. Click "OK" to save the changes.

Configuration

Configure the Integration

To configure V1Perforce you need to run the ServiceHost configuration tool

ServiceHostConfigTool.exe

The following section describes how to configure your Perforce integration using the use the configuration tool

1. Specify your VersionOne connection details on the General
   
   The following table describes the fields on this tab

   Field	Description
   Server URL	This is the URL to your VersionOne server
   Username	VersionOne user that will create defects
   Password	Password for the specified user
   Use Windows Integrated Authentication	Check this box if you VersionOne server is configured to use Windows Integrated Authentication

   When using the integrated authentication, V1Perforce will authenticate 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.

   If there's a proxy between this machine and the VersionOne instance, you'll also need to configure the following settings:

   Field	Description
   Use Proxy For Connection	Determines if the integration tries to connect through a Proxy
   Proxy URL	This is the URL to your Proxy Server
   Proxy Username	The username that will get you past this proxy
   Proxy Password	The password for the Proxy Username
   Proxy Domain	Name of Proxy Domain

2. Once the VersionOne parameters are entered, press Verify button to continue.
3. Specify how to create a VersionOne Change set and link it to Subverison on the Changesets tab.
   
   The following table describes the fields on this tab

   Field	Description
   Disabled	Check this box to disable ChangeSet creation in VersionOne.
   Change Comment	The VersionOne ChangeSet creation comment.
   Always Create ChangeSet	If checked, a VersionOne ChangeSet is created for each Perforce ChangeSet. If cleared, the VersioOne ChangeSet is only created if a VersionOne identifier can be found in the Perforce commit comment.

   The Link Properties section contains the following fields

   Field	Description
   Add To Menu	If checked, the link between VersionOne and Perforce is placed on the ChangeSet Details page tab menu. If cleared, there is no tab menu element for the link.
   Name	Friendly name for this link. Defaults to "ChangeSet {0}" and the {0} is replaced with the Perforce ChangeSet Identifier
   URL	Fully qualified URL to your web based Perforce Viewer. The Perforce ChangeSet identifier is set by putting {0} in the URL

4. Specify your Perforce connection details and how the integration will identify ChangeSets for VersionOne on the Perforce tab.
   
   1. Configure the Perforce connection (Connection Parameters)

      Field	Description
      Disabled	Check this box if you want to disable polling Perforce for ChangeSets.
      Path	Fully qualified URL to the Perforce repository monitored by this integration instance.
      Username	Valid Perforce user for the repository specified
      Password	Password for specified user
      View	Perforce View you want monitored by this integration instance

   2. Click Verify to ensure the connection parameters are correct.
   3. Configure how to identify ChangesSets

      Field	Description
      Regular Expression	This is the Regular Expression used to search Perforce commit comments for VersionOne identifiers.
      Poll Interval	Determines how frequently the integration polls Perforce looking for Defects.

      Here are some sample Regular Expressions: To Match S-01001 (Matches "S-01001") [A-Z]{1,2}-[0-9]+ To match #Reference (matches only "Reference") (?<=#)[a-zA-Z]+\b To match "V1:Reference" (matches only "Reference") (?<=V1:)[a-zA-Z]+\b

5. Save your changes and exit the program

Technical Details

VersionOne.ServiceHost.exe.config

VersionOne.ServiceHost.exe.config is the file that controls the behavior of VersionOne.ServiceHost.exe. Values in this file are set by the configuration tool (ServiceHostConfigTool.exe). This section is provided for informational use only. Users are discouraged from editing this file directly.

The P4ReaderService Element controls how the integration communicates with Perforce. The following table describes the elements nested under P4ReaderService.

The ChangeSetWriterService element controls how ChangeSets are created in VersionOne. The following table describes the elements nested under ChangeSetWriterService.

The P4ReaderServiceTimer element controls the Perforce poll frequency. The following table describes the elements nested under P4ReaderServiceTimer.