JIRA FishEye Plugin 2.0 - Perforce Job Integration

This document contains simple instructions for integrating Atlassian JIRA, Atlassian FishEye and Perforce. For a more detailed description of the plugin's features (including Crucible integration) check out the JIRA FishEye Plugin space: http://confluence.atlassian.com/display/JIRAEXT/FishEye+for+JIRA

Download and install the applications (if you haven't already)

• Download the latest version of the JIRA FishEye Plugin
• Download and install Atlassian JIRA (3.12.2+)
• Download and install the latest version of Perforce
• Download and install Atlassian FishEye (1.5+)

All applications must be running when you setup integration.

The JIRA FishEye Plugin can connect to any Perforce server on the network, but requires you to have a copy of the P4 executable installed on the same server as JIRA.

Install the plugin

1. Copy jira-fisheye-plugin-2.0.jar and atlassian-p4package-2007.12.14.jar into the WEB-INF/lib directory of the JIRA webapp.
2. Remove any previous JIRA FishEye Plugin jar files from the WEB-INF/lib directory, e.g jira-fisheye-plugin-x.x.jar
3. Remove any previous JIRA Perforce Plugin jar files from the WEB-INF/lib directory, e.g. atlassian-jira-perforce-plugin-x.x.x.jar
4. Remove any previous atlassian-p4package jar files from the WEB-INF/lib directory, e.g. atlassian-p4package-2006.12.5.jar
5. Restart JIRA
6. Create a project in JIRA (if you haven't already)

Integrate JIRA with FishEye

You may skip this step if you were already using the FishEye plugin. Your existing configuration should will have been copied over automatically.

1. In JIRA, navigate to Administration -> FishEye Configuration:
   1. press Setup FishEye
   2. In the FishEye URL enter the of your FishEye instance and press Update
   3. enter the key of the Project you wish to map to the FishEye repository, then press 'Update'.

Your JIRA instance is now connected to FishEye.

Integrate JIRA with Perforce

If you previously had the Perforce plugin installed, all of your custom fields and job-related workflows will be upgraded automatically. However, you will need to configure your connection to Perforce. The fourth column of the table below (perforce-jira-plugin.properties) shows the equivalent property name from your old perforce configuration file. You should be able to copy and paste the corresponding values from your configuration file straight into the FishEye Configuration screen.

1. Map your JIRA Issues to your Perforce Job Specification:
   • If you don't mind updating your job specification, import perforce-plugin.jobspec (provided in the plugin distribution) into Perforce using the p4 jobspec command.
   • If you have a custom jobspec that you want to keep, follow the instructions for Mapping Custom Fields.
2. In JIRA, navigate to Administration -> FishEye Configuration:
   1. press Edit Primary Configuration
   2. in the Perforce section, set Enable Perforce Integration to Yes
   3. Configure the settings for your Perforce instance:

      To authenticate with Perforce, you will need to specify either: P4USER and P4PASSWD; or P4USER and a valid ticket file The user must have read and write permissions in Perforce.

      Variable	Description	Example	perforce-jira-plugin.properties*
      P4 Executable	Full path to the P4 executable.	/usr/bin/p4 or C:\Program Files\Perforce\p4.exe	p4.executable
      P4PORT	The P4PORT to connect to, includes the hostname.	localhost:1666	p4.port
      P4CLIENT	The P4CLIENT to use.		p4.client
      P4USER	The P4USER to run as (must have read and write permissions)		p4.user
      P4PASSWD	The P4PASSWD to use for the P4USER, if one has been set.		p4.password
      Ticket file	The P4TICKETS file name, see Ticket-Based Authentication info below.		p4.ticketfile Ticket-Based Authentication Overrides any value in P4PASSWD To enable Ticket-Based authentication, use the Ticket File property to specify the name of the file to which p4 tickets are stored (as defined in the P4TICKETS environment variable). If the file is on the classpath, you can just specify the filename. Alternatively you may specify the full path to the file. The plugin will retrieve the ticket number associated with the user as specified in P4USER. The user must have already logged into the Perforce server with the 'p4 login' command.
      P4CHARSET	(Optional) If specified, this will set the P4CHARSET parameter for all perforce calls made by JIRA.		p4.charset
      View Job Link	(Optional) A link template specifying a P4WEB/P4DB server to link jobs to.		Similar to p4template.jobLink
      Log Level	The granularity of Perforce related log entries.		p4.debug_level
      System Root	(Windows Servers only) Your Windows install folder.	C:\Windows	p4.sysroot
      System Drive	(Windows Servers only) Your system drive.	C:	p4.sysdrive

   4. press Update
   5. Test your Perforce connection status by pressing the Test Connection link.

View Job Link formats

For P4Web:

 http://localhost:5050/@md\=c@[JOBNAME]ac\=111 

 http://localhost:5500/p4db/jobView.cgi?JOB=[JOBNAME] 

Alternatively, browse to a job in your preferred viewer and copy the URL. Replace the job name with the token [JOBNAME] as in the above examples and paste it into the View Job Link field.

Integrate FishEye with Perforce

Outside the scope of this doc, see: http://confluence.atlassian.com/display/FISHEYE/1.5+Perforce

Create a workspace / depot in Perforce

Outside the scope of this doc, see: http://www.perforce.com/perforce/doc.973/cmdguide/html/quicksta.htm

Test it all works

1. Add a Perforce Job custom field to JIRA
   1. Go to Administration -> Custom Fields -> Add Custom Field
   2. Select Job Checkbox and press Next
   3. Enter a Field Name and press Finish
2. Create a new JIRA Issue and select Yes for the Create Perforce job field.

If the above installation and configuration has been successful, you should see a P4 Job field in the upper section of the View Issue screen. If you have configured a View Job Link you should be able to click through to your P4WEB or P4DB server from the P4 Job field.

You should also see a FishEye issue tab panel. This replaces the old P4 Changes and P4 Job panels from the JIRA Perforce Plugin. Any Perforce commits referencing the issue/job key will show up under this tab.

This document is a quick setup guide. For a full explanation of the JIRA FishEye Plugin's features and functionality, check out the following links:

Bugs, Feature Requests & Improvements? If you've found a bug in the JIRA FishEye plugin or would like to request a new feature or improvement - please raise an issue in the JIRA FishEye Plugin project.