JIRA Perforce Plugin

This plugin has been verified to work with perforce version 2006-2

Description and Features

A plugin to integrate JIRA with Perforce. Currently the Perforce plugin connects JIRA with Perforce in two ways - firstly by linking issues with Perforce changes, and secondly with jobs. It can integrate with a Perforce server over the internet, network or locally.

	Change	Display change details in JIRA issue screen
	Web Linking	Connect JIRA to file entries, diffs, change lists and jobs to your Perforce Interface
	Jobs	Create, display and delete Perforce jobs through JIRA
	Create Job Workflow Post-Function	Create jobs automatically through a workflow transition post-function
	Job Searching	Search for JIRA issues with/without associated Perforce jobs
	Jobs with Custom Fields	Mapped JIRA custom fields to Perforce jobspec fields automatically populated on job creation
	Ticket-based Authentication	Perforce Server Ticket-based authentication support
	Unicode Support	Perforce Server internationalized mode support
	Change List Indexing Service	Automatice service to keep change lists up to date

Change Indexing and Linking

If change indexing is turned on:

• the plugin' show all changes ever made that reference an issue - this includes any change in which a given issue number is referenced. For example if your commit reads "I think this also might fix JRA-52", that commit will be linked to JRA-52.
• you can control how many changes are pulled from Perforce at any one time, so as not to overload your Perforce server during the initial data population.

Job Linking

If job linking is turned on:

• there is a custom field to select whether or not a given issue should have an associated Perforce job.
• you can view jobs associated with any issue within the JIRA interface, including the details of every change list attached to the job.
• from within JIRA you can query for issues with or without Perforce issues (useful for filters like "Show me which unresolved issues don't have Perforce jobs associated")
• from within your Perforce client you can filter jobs by JIRA-related meta data and browse to the related JIRA issues
• the Perforce job is constantly updated, always up to date with the latest changes in JIRA.
• use the 'Create Job' Post Function in order to create a job after completing a JIRA workflow transition. This post function can be used in conjunction with the the Perforce Job custom fields.

Perforce Web Linking

Up to version 1.1.14, this plugin supported two hard-wired link rendering mechanisms: one for P4Web and another for P4DB. Starting with version 1.1.15, it supports rendering links from URL templates. Using this method, you can link Perforce entities in JIRA to any web interface to Perforce.

You have to migrate your old link configuration to the new link templates. Please read on for details.

Link templates are regular Velocity templates and are configured in the perforce-jira-plugin.properties configuration file. For basic configuration, take a look at the comments in the configuration file. For more advance uses, please read the Velocity Manual.

Job Links

Template property in perforce-jira-plugin.properties:

p4template.jobLink=<a href\="http://localhost:5500/p4db/jobView.cgi?JOB\=$urlcodec.encode($job.name)">$job.getname</a>

Variables supported:

• ${job}
  

  is an instance of com.perforce.api.Job

Change Links

Template properties in perforce-jira-plugin.properties:

p4template.changeLink=<a href\="http://localhost:5500/p4db/changeView.cgi?CH\=$change.number">$change.number</a>
p4template.changeFileSubsetLink=Showing $changeMaxFileEntries of <a href\="http://localhost:5500/p4db/changeView.cgi?CH\=$change.number">$change.fileEntries.size() files</a>

Variables supported:

• ${change}
  

  is an instance of com.perforce.api.Change

• ${changeMaxFileEntries}
  

  is an Integer, this is the maximum number of files shown per change (-1 means "unlimited")

File Entry Links

Template properties in perforce-jira-plugin.properties:

p4template.fileLink=<a href\="http://localhost:5500/p4db/fileLogView.cgi?FSPC\={0};HIDEDEL\=YES">{1}</a>
p4template.revisionLink=&nbsp;<a href\="http://localhost:5500/p4db/fileViewer.cgi?FSPC\={0};REV\={1}">#{1}</a>
p4template.revisionDeleteLink=&nbsp;#{1}
p4template.diffLink=&nbsp;(<a href\="http://localhost:5500/p4db/fileDiffView.cgi?FSPC\={0};REV\={1};ACT\=edit">diff</a>)

Variables supported:

• ${fileEntry}
  

  is an instance of com.perfoce.api.FileEntry

• ${fileEntryDepotDirPath}
  

  is a String, this is the directory part of the full depot path

• ${fileEntryPreviousHeadRev}
  

  is a String, this is the revision previous to the HEAD

Special Variables

The extra variables

{0}

and

{1}

will be resolved to full depot path and revision.

The

$urlcodec.encode(...)

Velocity tool can be used to URL-encode strings in the templates. For samples, see the configuration samples in perforce-jira-plugin.properties.

Note: the client specified as 'p4.client' in the perforce-jira-plugin.properties should also be passed as a command line parameter to p4web.

Miscellaneous

Note that Perforce commit control (decides whether a commit will be accepted based on the issues in JIRA) is already supported by the JIRA Commit Acceptance Plugin. More features such as a workflow function to control job creation are coming soon.

Installation

See JIRA Perforce Plugin Installation.

Setup

See JIRA Perforce Plugin Setup.

Usage

Job Linking

Here is an ultra quick howto for setting up and operating Perforce-JIRA job linking:

1. Update your Perforce jobspec (using "p4 jobspec" as a Perforce admin) to the attached jobspec.
2. Add a new custom field called Perforce job of type Job Checkbox for each project, issue type or globally that you wish to associate with Perforce jobs.
3. When you create or edit issues, if you check the Create Job checkbox a job will be created in Perforce. It will be synchronised with every edit to the issue in JIRA.

Alternatively, with the 'Create Job' Post Function, it is possible to programmatically create a job after completing a specified workflow transition. In this case, it is possible to restrict the ability of creating a job manually and use the 'Hidden Job Switch' custom field. This field does not appear while editing an issue - but is set automatically by JIRA through the post function.

Change Indexing

The periodic indexing of change lists is done by a service, automatically installed into your JIRA instance by the plugin.

By default, this service checks Perforce for new changelists every 1 hour.

You can edit the period by editing the period of the Perforce Changed Indexing Service on the Administration > System > Services screen.

Refreshing data

If your index gets corrupted for any reason, or you wish to remove the index so that JIRA will reindex your depot completely:

1. remove the indexDir/plugins/atlassian-perforce-changes directory, where indexDir is your JIRA indexing directory.
2. restart JIRA.

JIRA Perforce Plugin Walkthrough

The JIRA Perforce Plugin Walkthrough discusses the functionality available in the plugin in more detail.

Troubleshooting

See JIRA Perforce Plugin Troubleshooting.

Licensing and Pricing

The Perforce plugin retails for $USD 1000 per server and requires a valid license. JIRA's licensing terms are also applicable to the Perforce Plugin. A Perforce Plugin commercial license entitles you to:

• Deploy a single instance of Perforce Plugin in a commercial environment on 1 server
• Free software maintenance for 12 months - including free upgrades and free email support (9am-6pm weekdays, Australian Eastern Standard Time)
• Full source code (under a developer source license which allows for broad customisation)

For more information about JIRA's licensing terms, please see here. For further details, please consult the Licensing FAQ or contact sales@atlassian.com.

If you wish to evaluate the plugin, you can generate a 30 day evaluation license file via the My Account section of the Atlassian website. Please save this file into JIRA's WEB-INF/classes directory.

Versions

You can download the JIRA Perforce Plugin via the Atlassian website.

Version	Author	Compatibility	Notes
1.0	Atlassian	3.1.x
1.0.2	Atlassian	3.2.x
1.0.4	Atlassian	3.3.x
1.1.1	Atlassian	3.4.1, 3.4.2, 3.4.3	Minor changes - custom field compatibility with JIRA 3.4.1
1.1.2	Atlassian	3.5, 3.5.1, 3.5.2	Minor changes - updated version numbers for JIRA 3.5
1.1.3	Atlassian	3.5, 3.5.1, 3.5.2, 3.5.3	Fix for PERF-21 - removed need for "-t" option	Atlassian JIRA (1 issues) Key Summary PERF-21 call to p4 with invalid option -t
1.1.4	Atlassian		Please use 1.1.5 when running with JIRA 3.6
1.1.5	Atlassian	3.6, 3.6.1, 3.6.2, 3.6.3, 3.6.4, 3.6.5	Minor changes - updates for service compatibility and licensing with JIRA 3.6
1.1.7	Atlassian	3.7	Fixed and Improved the reliability of connections with the p4 executable and improved diagnostic messages - updates for compatibility with JIRA 3.7	Atlassian JIRA (2 issues) Key Summary PERF-97 Perforce plugin closes stdout PERF-95 Changelist Indexing Doesn't Work, but Job Scanning Does
1.1.8	Atlassian	3.7	bug fix release	Atlassian JIRA (2 issues) Key Summary PERF-109 Need to be able to specify a change path to limit number of changelists in perforce PERF-113 Old index path used when importing data
1.1.9	Atlassian	3.8	3.8 compatibility release, no functional difference
1.1.10	Atlassian	3.7, 3.8	bug fix release	Atlassian JIRA (1 issues) Key Summary PERF-116 Error parsing mod time string
1.1.11	Atlassian	3.9, 3.10	3.9 compatibility release, no functional difference
1.1.12	Atlassian	3.10	Bug fix release	Atlassian JIRA (1 issues) Key Summary PERF-125 $req.contextPath is not a valid reference reported for view-jobcheckbox.vm
1.1.13	Atlassian	3.10	Bug fix release	Atlassian JIRA (1 issues) Key Summary PERF-127 Perforce plugin versions 1.1.12 and 1.1.11 do not work with a 1.4.2 JVM
1.1.14	Atlassian	3.11	Upgraded to use new indexing functionality in JIRA	Atlassian JIRA (0 issues) Key Summary
1.1.15	Atlassian	3.11	Bug fix release

The JIRA Perforce plugin does not work correctly with versions of the Perforce Server 2006.1 prior to build 2006.1/104454, in relation to job updates. Perforce has fixed this bug in version 2006.1/104454 of p4d. If you are using Perforce 2006.1 and are trying to use JIRA to create and update your Perforce jobs it is recommended that you upgrade Perforce. You will not need to upgrade the JIRA plugin. The original issue has the following symptom: It is possible to create a JIRA issue with an associated Perforce job - but subsequent updates to the issue (and hence the Perforce job) will result in this error: com.perforce.api.CommitException: error: Error in job specification.error: Date is a read-only always field and can't be changed from '2006/06/13 12:09:09'.error: The job may have been updated while you were editing. at com.perforce.api.Job.commit(Unknown Source) and the Perforce job will not be updated.

Please note that due to the bug JRA-10215 , P4 jobs will fail to be created within JIRA. This bug has been addressed in JIRA 3.6.2. For JIRA 3.6 and 3.6.1 users, please download and apply the patch as detailed in the bug report.

Known Issues

For a full list of known open issues - ask JIRA! 

Perforce Jobs created externally to JIRA are deleted on an issue edit/update if the Perforce job checkbox is not checked. The workaround is to limit job creation to within the JIRA UI - the issue is being tracked at PERF-89.

Screenshots

Screenshots (view as slideshow)
			Issue create screen showing optional creation of P4 job.		Viewing an issue with it's associated Perforce job and linked changelists.
	Issue navigator interface to query by perforce job.