 | This BETA is Deprecated Perforce integration in the FishEye Plugin is out of BETA! Please make your way to the FishEye plugin page to download the JIRA FishEye Plugin v2.0. Updated Perforce integration documentation is available here. |
 | 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 JIRA FishEye/Perforce Plugin Beta
- 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
- Copy jira-fisheye-plugin-p4-beta-0.x.jar and atlassian-p4package-2007.12.14.jar into the WEB-INF/lib directory of the JIRA webapp.
- Remove any previous JIRA FishEye plugin jar files from the WEB-INF/lib directory, e.g jira-fisheye-plugin-1.4.jar
- Restart JIRA
- Create a project in JIRA (if you haven't already)
Integrate JIRA with FishEye
- In JIRA, navigate to Administration -> FishEye Configuration:
- press Setup FishEye
- In the FishEye URL enter the of your FishEye instance and press Update
- 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
- Import perforce-plugin.jobspec (provided in the plugin distribution) into Perforce using the p4 jobspec command.
- In JIRA, navigate to Administration -> FishEye Configuration:
- press Edit Primary Configuration
- in the Perforce section, set Enable Perforce Integration to Yes
- 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
Variable Description Example P4 Executable Full path to the P4 executable. /usr/bin/p4 or C:\Program Files\Perforce\p4.exe P4PORT The P4PORT to connect to, includes the hostname. localhost:1666 P4CLIENT The P4CLIENT to use. P4USER The P4USER to run as. P4PASSWD The P4PASSWD to use for the P4USER, if one has been set. Ticket file The P4TICKETS file name, see Ticket-Based Authentication info below. P4CHARSET (Optional) If specified, this will set the P4CHARSET parameter for all perforce calls made by JIRA. View Job Link (Optional) A link template specifying a P4WEB/P4DB server to link jobs to. Log Level The granularity of Perforce related log entries. System Root (Windows Servers only) Your Windows install folder. C:\Windows System Drive (Windows Servers only) Your system drive. C: 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. - press Update
- Test your Perforce connection status by pressing the Test Connection link.
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
- Add a Perforce Job custom field to JIRA
- Go to Administration -> Custom Fields -> Add Custom Field
- Select Job Checkbox and press Next
- Enter a Field Name and press Finish
- 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: |
|
Getting Started |
Support and Troubleshooting
|
Future Development |
Version History |
| 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. |
Comments (27)
May 06
Matthew Janulewicz says:
So far it's been very frustrating trying to get this plugin set up to connect to...So far it's been very frustrating trying to get this plugin set up to connect to Perforce. Suggestion: If I already have FishEye running and that connection is working, why not just re-use that?
I've set P4USER and P4PASSWD locally and it won't connect. I've tried ticket based authentication and that won't work. And I can tell it's working because when I change the name of the ticket file setting to a file that does not exist it complains that it can't find the file in my classpath, which is expected.
I have the log set to 'verbose' but all it ever tells me is:
2008-05-06 21:33:12,405 http-80-Processor24 ERROR [com.perforce.api.Debug] P4 exited with an Error!
2008-05-06 21:35:38,032 http-80-Processor24 ERROR [com.perforce.api.Debug] P4 exited with an Error!
2008-05-06 21:36:40,517 http-80-Processor25 ERROR [com.perforce.api.Debug] P4 exited with an Error!
How to I actually make it verbose?
I seem to remember the original P4 plugin was a pain in the a** to get working, too. Nobody, and I mean NOBODY, sets their password with an environment variable that's displayed in plain text and the ticket authentication seems half-baked and unnessary.
As I mentioned, the already-existing FishEye integration seems store the username and password and uses it on an as-needed basis. Within FishEye itself it does the same thing when connecting to Perforce. The extra hoops I have to jump through with this extraneous layer of configuration is not working for me.
Help!
May 07
Tim Pettersen says:
Hi Matthew, How to I actually make it verbose? Whereabouts are you seeing th...Hi Matthew,
Whereabouts are you seeing this message? Changing the log level should work, but may only be writing to the jira-p4.log file (which should be in the same directory as your JIRA logs).
Where is this being displayed in plain text for you? It should be masked in the JIRA config screens. As for setting the P4PASSWD variable, that's just the way that Perforce handles things. I strongly agree that this is definitely a clunky way of doing it, but unfortunately the API that they have released is just a wrapper for calls to their native p4 executable.
An interesting idea! At the moment FishEye doesn't expose any of it's own configuration information (beyond the names of the repositories) and it may pose security risks. Since JIRA needs access to the actual Perforce executable to update jobs we'd be retrieving Perforce login and path information from FishEye.
Currently, I think it makes more sense for JIRA to do the updates than to use FishEye as some kind of proxy for Perforce. FishEye uses Perforce in a read-only manner which is an entirely separate concern to JIRA, which only performs Job updates and deletions. However, sharing of Perforce login information could be a feature for the future.
As far as your connection problem goes, have you imported the Perforce jobspec shipped with the plugin yet? Details are above in the first step of the Integrate JIRA with Perforce section.
Hope this helps!
May 07
Matthew Janulewicz says:
I restarted Jira and the p4 log still doesn't show up anywhere. However... I wa...I restarted Jira and the p4 log still doesn't show up anywhere. However...
I was originally using the p4tickets file I had from when we ran the Perforce plugin. I was still logged in as the same person, still had the same valid ticket, etc. But I went ahead and logged out, then logged back in and copied the new ticket file to where the old one was and it seems to work.
Still no P4 log file, though
-Matt
May 15
Jamie says:
Where is this being displayed in plain text for you? It should be masked in the ...I don't think this is a fair comment. Perforce allows you to set different security levels depending on your security requirements. Only the most naivest of sites will allow people to login using the password set in P4PASSWD.
Most people will use ticket-based authentication. This allows you to get a ticket that's good for as long as your admin wants it to be. In fact it works the same way as authentication to jira's web services interface, except you don't need to worry about passing the ticket to perforce, as all the client programs will handle that for you.
When jira runs a perforce command it uses -P ticketvalue, which is unnecessary providing P4TICKETS is set or the ticket file is in the default location. There is also a bug in the ticket file parsing code which can cause problems.
cheers, jamie
May 15
Tim Pettersen says:
Hi Jamie, You're right, I was being a little rash. We don't use Perforce in any...Hi Jamie,
You're right, I was being a little rash. We don't use Perforce in anything like a production capacity and haven't implemented much more than what the basic Perforce distribution ships with out of the box.
The current level of integration in the FishEye-Perforce beta was more or less ported from the latest version of the existing Perforce plugin, but if you have any ideas for improved security or functionality - please let us know (either by commenting here or raising an issue) and we'll investigate.
Would you mind expanding on this?
cheers,
Tim
May 16
Jamie says:
Thanks for your three comments, very helpful. Bug in ticketparsing code, ok, I ...Thanks for your three comments, very helpful.
Bug in ticket-parsing code, ok, I should file this properly, but IIRC the problem is that it doesn't take account for the fact that there might be multiple tickets in the ticket file for that user, as they could be for different perforce servers. It just uses the first one it finds for the user. What this means is I had to reorder the ticket file to make sure the target p4 server was the top one.
Also, in p4 client 7.2 the ticket handling is a bit different, it will now store the actual FQDN of the host rather than the alias, eg perforce. I'm not sure if this will cause a problem (I haven't tested the new plugin on our prod server which has ticket-based security, only on instances with no password reqd).
I guess my point is you can save yourself some code by not using -P at all, providing P4TICKETS is set.
cheers, jamie
May 16
Tim Pettersen says:
Thanks a bunch an issue has been raisedThanks a bunch - an issue has been raised if you'd like to follow it. We should get on to this early next week.
cheers,
Tim
May 07
Aggelos T. Paraskevopoulos says:
Tim, I'm having trouble setting up the plugin. When I try the test the JIRAP4 c...Tim,
I'm having trouble setting up the plugin. When I try the test the JIRA-P4 connection from the configuration screen we get:
Problem connecting to Perforce: com.perforce.api.CommitException
Also I don't seem to find the jira-p4.log or any other trace plugin's logging in any of the other JIRA logs (atlassian-jira.log, catalina.out etc).
The job spec is applied to the Perforce server, the user name and password setup correctly, the port, client spec checked also.
Any ideas what to look for?
Cheers,
Aggelos
May 07
Aggelos T. Paraskevopoulos says:
Well, sometimes a nice restart (JIRA) fixes things. Everything works fine now. I...Well, sometimes a nice restart (JIRA) fixes things. Everything works fine now. I can see the log (jira-p4.log), I managed to add / delete the P4 Job from JIRA and the Fisheye issue tab panel brings the changelists (worked beforehand).
Thanks,
Aggelos
May 07
Tim Pettersen says:
Hi guys, Glad you've had some success! It does appear that the logging system c...Hi guys,
Glad you've had some success! It does appear that the logging system could use some work though - I'll be working on that today and will put a new beta build up tonight.
Thanks for the quick feedback, please let me know if you run into any other issues - I'll try to get them fixed ASAP
cheers,
Tim
May 08
Tim Pettersen says:
I've just uploaded BETA v0.3, the major fix being FISH166I've just uploaded BETA v0.3, the major fix being FISH-166 which revolves around logging and the Perforce configuration.
Also a bug which prevented blank passwords (which do appear to be allowed by Perforce) from being used has been fixed.
These fixes will hopefully facilitate easier configuration of the plugin.
The link at the top of the page has been updated! Thanks for the feedback guys, keep it coming
cheers,
Tim
May 15
Jamie says:
Two issues, I'll put them in separate comments. Firstly, there seems to be a f...Two issues, I'll put them in separate comments.
Firstly, there seems to be a formatting issue on the Crucible tab.
sss is the summary of the jira issue. I don't know where that title= stuff is coming from.
cheers, jamie
May 16
Tim Pettersen says:
Hi Jamie, Thanks for the bug report! I've raised an issue (FISH172Hi Jamie,
Thanks for the bug report! I've raised an issue (FISH-172) to deal with it. Would you mind leaving a comment, either here or on the issue, with the following details:
We appreciate your taking part in this beta!
cheers,
Tim
May 18
Tim Pettersen says:
Hi Jamie, This has been fixedHi Jamie,
This has been fixed. The problem was that the plugin was attempting to link the key DTT-1701 to a JIRA issue and a Crucible review, and subsequently failing at both and mucking up the HTML. The fix means that it will only be linked once (as a JIRA issue).
To avoid confusion between application instances at Atlassian, we have a convention of naming related projects slightly differently between instances. For example:
FE-123 is a http://jira.atlassian.com bug report/feature request etc for FishEye
FSH-123 is a http://support.atlassian.com support request for FishEye
FISH-123 is a http://developer.atlassian.com/jira bug/feature/support request for the JIRA FishEye Plugin
CR-FE-123 is a Crucible review raised against the FishEye project
This not only avoids the obvious link rendering problem, but allows for easier referencing of a particular project entity in any communication. So despite the fact that this issue has been fixed, it might be a good idea to migrate to different project keys across application instances.
cheers,
Tim
May 19
Jamie says:
Hi Tim, I'll give this a try. If this convention is recommended it might be goo...Hi Tim,
I'll give this a try. If this convention is recommended it might be good to document it, as personally, I thought the intuitive thing to do would be to give them matching names. Can see why this might be undesirable now you point it out though.
cheers, jamie
May 15
Jamie says:
Next problem. Rather than sticking the jar in I checked out fromNext problem. Rather than sticking the jar in I checked out from http://svn.atlassian.com/svn/public/contrib/jira/jira-fisheye-plugin/tags/jira-fisheye-plugin-p4-beta-0.3, which I assume was the correct tag.
I need to build the source because I want to customise the criteria under which the FE/CR panels are displayed, because I want to phase this in slowly, leaving the existing p4 integration as is for the majority of projects.
The problem is com.atlassian.jira.ext.fisheye.ExternalFishEyeConfig won't build because it can't find com.atlassian.studio.applinks... is that in a jar somewhere?
cheers, jamie
May 15
Tim Pettersen says:
Hi Jamie, There is indeed a jar file you need, I've attached it to this page ap...Hi Jamie,
There is indeed a jar file you need, I've attached it to this page and raised an issue to get it moved over to one of our public repositories.
cheers,
Tim
May 22
Evgeny Zislis says:
With the original Perforce JIRA plugin, it was possible to force job creation on...With the original Perforce JIRA plug-in, it was possible to force job creation on every issue creation.
Some of our users are using the Mylyn JIRA connector, and there is no checkbox there to select for creating a Perforce job, or not.
Creating it by default for every issue created in a project would be a workaround. How can it be done with this plug-in?
May 23
Tim Pettersen says:
Hi Evgeny, There is a custom field called Hidden Job Switch that was ported ove...Hi Evgeny,
There is a custom field called Hidden Job Switch that was ported over from the JIRA Perforce plugin. However, this morning I discovered a bug that prevented it from being set in the FishEye-Perforce plugin beta. I've fixed it (glad we're in beta at the moment) and the new beta with this fix included - v0.5 - will be released on Monday.
I'm not 100% sure this will be compatible with Mylyn though. Could you elaborate on how you previously forced job creation with the old Perforce plugin in a way that was compatible with Mylyn?
cheers,
Tim
May 27
Tim Pettersen says:
Hi again Evgeny, Apologies for the delay in the release of the v0.5. The rele...Hi again Evgeny,
Apologies for the delay in the release of the v0.5.
The release has been pushed back until tomorrow, Sydney time (Wedneday, 28/5/08) to allow for some more internal testing.
cheers,
Tim
May 29
Tim Pettersen says:
Another solution is to add a Create Perforce Job Function workflow postfunction ...Another solution is to add a Create Perforce Job Function workflow post-function to the Create Issue transition in your workflow.
This would probably be the most effective way to force Mylyn to automatically create a Perforce job for each JIRA issue.
cheers,
Tim
Jun 02
Evgeny Zislis says:
This is the solution I was using with the Perforce plugin as well.This is the solution I was using with the Perforce plugin as well.
May 29
Tim Pettersen says:
FishEye/Perforce Plugin Beta version 0.5FishEye/Perforce Plugin Beta version 0.5 has been released !
This release includes Perforce Job compatible project tab panels and the fix to the Hidden Job Switch fields described in the above comment thread.
We're nearing the end of the beta phase, so please upgrade your installations to the v0.5 and keep the feedback coming!
cheers,
Tim
Jun 02
Evgeny Zislis says:
Thanks\! Great job on this stuff, it solves the problem perfectly.Thanks! Great job on this stuff, it solves the problem perfectly.
Jun 03
Jamie says:
Please could you tag 1.5 in svn or give me the changelist number to pull from tr...Please could you tag 1.5 in svn or give me the changelist number to pull from trunk.
thanks
Jun 04
Tim Pettersen says:
I've replied over here:I've replied over here: http://confluence.atlassian.com/display/JIRAEXT/FishEye+for+JIRA?focusedCommentId=159516338#comment-159516338
cheers,
Tim
Jun 17
Tim Pettersen says:
Hi guys, Thanks for all your feedback! The BETA is now closed and all improveme...Hi guys,
Thanks for all your feedback! The BETA is now closed and all improvements have been incorporated into the JIRA FishEye Plugin version 2.0.
There are a bunch of new features and improvements that will interest all JIRA/FishEye users.
Additionally, a proper upgrade path has been implemented to allow users upgrading from the old Perforce plugin to automatically retain their workflows and custom fields. However please note that this means you will have to remove the old Perforce plugin when installing the FishEye plugin, from version 2.0 onwards. Customers upgrading from a beta version (0.1-0.5) of the FishEye-Perforce plugin to version 2.0 should be fine.
Please raise issues at http://developer.atlassian.com/jira/browse/JFEP - or leave a comment here if you have any further questions.
cheers,
Tim
p.s: For those hacking away at the source, the 2.0 tag is at http://svn.atlassian.com/svn/public/contrib/jira/jira-fisheye-plugin/tags/jira-fisheye-plugin-2.0