Perforce Installation & User Guide

1. Introduction

The Rally Connector for Perforce inspects the contents of a check-in comment and creates a changeset in Rally associated to the Rally artifact, creates changes for each affected file, and optionally updates the state of the Rally artifact. For example, if a developer checks in two files with the commit message "Fixed DE17", the Perforce Connector would create a changeset for the check-in revision, create two change objects for the affected files, link the changeset to the defect, and set the state of defect 17 as fixed.

The diagram below shows the objects that are created/modified when a check-in occurs with a Rally ID (such as S123, DE17, TA123) in the commit message. No objects are created if the formatted ID in the change message is not found in Rally.

1.2 Features

The connector can link to and modify tasks, defects and user stories contained in Rally. To change the state of a Rally artifact enter the ID for the story followed by the state you wish to change in your commit message.
Example: "Extremely important fetching feature done. S123 Completed"

The connector makes the following changes to Rally:

1. Depending up the artifact type, the "status" field is changed to the new status specified in the check-in comment (note "Completed" in the above example). The "status" fields on the artifacts are:
   • Defect: The "State" field.
   • Story: The "ScheduleState" field.
   • Task: The "State" field.
2. Creates an SCMSystemRepository object if one does not exist in Rally based on the <SCMRepositoryName> value in the config file.
3. Creates a Changeset object in Rally associated to the artifact with message, revision, commit timestamp and URI populated. Note screenshot (click to enlarge):
   
4. Creates a Change object in Rally for each affected file associated to the changeset with action, filename path, base, extension and URI fields populated. Note screenshot:
   

The connector automatically sets the ToDo value of a task to 0 if the commit message contains a task ID and a state of completed.

2. Pre-installation requirements

Click on the Contact Support link at the bottom of any page in Rally to open a support case to obtain the Rally Connector for Perforce. Once you've received a response and obtained the installation package, proceed with the following tasks.

2.1 Software and hardware requirements

The following are the hardware and software requirements to install and run the Rally Connector for Perforce.

1. A Rally subscription. Most build and changeset data will not show in Rally until a workspace administrator enables the build and changeset flag by editing the workspace.
2. Access to your Perforce server.
3. The Ruby programming language and Ruby gems (libraries) installed.
4. The Ruby gem "rally_rest_api", version 1.0.3 (the connector will not work with earlier versions; discussed in installation steps below).
5. This connector has been tested on Perforce 2009.1 only.

3. Installation

Basic installation steps

1. Install Ruby & the Rally Connector for Perforce code.
2. Setup the config.xml for Perforce.
3. Run the config_test.rb to validate the config file is setup correctly.
4. Setup p4torally.rb to be executed by the Perforce trigger.

3.1 Install Ruby and the Rally Connector to Perforce

1. Install the Ruby programming language. Make sure the user running your Perforce server is given access to the Ruby installation.
2. Install the builder and rally_rest_api (version 1.0.3 or greater) Ruby Gems by entering the following from a command window (answer yes to any questions about installing required dependencies):

   gem install builder -y gem install rally_rest_api -y

3. Save the RallyConnectorForP4-x-x.zip file locally (on your machine) into the directory where you want to install the connector. Navigate to this install directory and extract the RallyConnectorForP4-x.x.zip file you just saved.

3.2 Setup the config.xml file

Edit and save the config.xml file, entering the appropriate values between each begin and end tag.

1. Set <RallyUserName> to the Rally user's login name you want to use for the updates in Rally.
2. Set <RallyPassword> to the Rally user's password. The first time the connector runs, it will encode your password and re-write (update) the XML file for added security.
3. Set <RallyBaseUrl> to the URL you use to log into Rally. For most users, the expected URL is rally1.rallydev.com or trial.rallydev.com.
4. Set <RallyWorkspaceName> to the name of the Rally Workspace where you want to update artifacts.
5. Set <SourceControlUrl> the URL you use to reference the Perforce web UI. For most users, this URL is similar to perforce.company.com:8080. Defaults to "http://" for the prefix.
6. Set <RallySCMRepositoryName> to any name of your choosing for the Rally SCMRepository object. The first time the connector runs, the connector automatically creates a new Rally SCMRepository object with the Name attribute set to the user specified name.
7. Set <UserDomain> to your company domain name such as acme.com. This tag determines what Rally user is used to populate the author field when creating the changeset object.
8. Optional - Set <CommitterUserLookupField> to a field name on the User Object in Rally. This will tell the connector to look up the commit user's name via that User Object field in Rally and to link the changeset Author to a user in Rally. For example, committer is user123 and the Rally user is user@rallydev.com with MiddleName set to user123. Note: If no users are found and the UserDomain element is set, the lookup will also try that association.

If set, the connector will lookup the Rally user based on the map to the Perforce user name. For example, myuser@domain.com username in Rally → myuser Perforce user name .

If not set, the connector will lookup the Rally user based on the Perforce user email. For example, myuser@domain.com username in Rally → myuser@domain.com Perforce user email.

The <Prefixes> element is used to specify any custom prefixes you have specified for your artifacts:

• <Defect> This element is used to specify the prefix you use for defect artifacts.
• <Story> This element is used to specify the prefix you use for story artifacts.
• <Task> This element is used to specify the prefix you use for task artifacts.

Example config.xml file:

After the first check-in comment which includes a Rally ID, the connector will rewrite the config.xml file to include the allowed state values for User Stories, Defects and Tasks. This will happen automatically as long as the connector script has write access to the file. This re-write will also add the <CachedStates> element to the file.

The <CachedStates> content in the config.xml file can remain untouched unless your Rally administrator modifies the allowed state values for User Stories and/or Defects. To force the next run of the connector to update the values stored in the config.xml file, modify it by deleting the text from the <CachedStates> tag to the closing tag </CachedStates>. The <CachedStates> content will be functionally equivalent to the following:

3.3 Test the config file

To test the config.xml file for completeness, issue this command:

The above script will test the network settings and the connection information in your config.xml file. The output from the command should be:

3.4 Setup Perforce trigger

The Perforce change-commit trigger is set up so the Rally connector process runs in the background for optimal performance. After the developer checks in code, the Rally connector immediately runs and updates the appropriate objects in Rally without the developer having to wait for the Rally web services requests to complete. Consequently, check the Rally log file for any errors.

Setting up the change-commit trigger on Unix:

The steps below assume all files are saved in the /opt/integrations directory. Your file paths may vary depending on your installation.

1. Create a shell script called RallyWrapper.sh that contains the command to run the p4torally.rb script. This command runs the process in the background and redirects standard error to the Rally_Connector_Error.log file. Ensure you specify the full path to Ruby and the p4torally.rb file. Example:

   #!/usr/bin/ruby cd /opt/integrations/P4ToRally/ ./p4torally.rb $1 $2 > ./Connector.log 2>&1

2. Verify the RallyWrapper.sh file is executable by entering this command:

   chmod u+x RallyWrapper.sh

3. Open the Perforce triggers file by typing "p4 triggers" and add the line below. Ensure you add at least one space to the beginning of the line so Perforce correctly interprets the trigger.

   rally change-commit //... "/opt/integrations/P4ToRally/RallyWrapper.sh %changelist% %user%"

4. Save the p4 triggers file. The connector is now installed.

Setting up the change-commit trigger on Windows:

1. Create a VBScript (RunP4ToRally.vbs) which contains commands to run the connector in the background.

   Set WshShell = WScript.CreateObject("WScript.Shell") set args = WScript.Arguments WshShell.Run("ruby C:\P4ToRally\p4torally.rb" & " " & args(0) & " " & args(1))

2. Create a batch file (RallyWrapper.bat) which contains commands to run the VBScript.

   C:\P4ToRally\RunP4ToRally.vbs %1 %2

3. From the start menu, select Run.
4. Enter p4 triggers into the text box.
5. On the bottom of the file that opens, add this line under the word Triggers:

   rally change-commit //depot/... "C:\P4ToRally\RallyWrapper.bat %changelist% %user%"

6. Save the p4 triggers file. The connector is now installed.

4.0 Known issues

5.0 Tip

1. Why are changesets not displaying in Rally?
   Verify your Workspace administrator has selected the Enable Build and Changeset option on the Edit Workspace configuration pop-up and verify there are no unexpected messages in the Rally_Connector_Error.log file. No errors are written to the console.
2. Debug output
   You can change the level of logging from the connector by including the following information in your configuration file:
   

   <Log>    <FileName>Rally_Connector_Error.log</FileName>    <Level>0</Level> </Log>

   Log level 0 will produce the maximum amount of output, with log level 5 producing the least. These levels are documented at http://corelib.rubyonrails.org/classes/Logger/Severity.html:

   • DEBUG   = 0
   • INFO    = 1
   • WARN    = 2
   • ERROR   = 3
   • FATAL   = 4
   • UNKNOWN = 5