JIRA Plugin Development Kit

JIRA Documentation

Index

As of JIRA 3.12, you can develop JIRA Plugins without downloading the JIRA Plugin Development Kit using our new, Maven 2-based plugin system. Please give the new plugin tutorials a try.

A full development kit for JIRA plugins bundled with JIRA API, dependencies and examples.

For more information, documentation and plugin tutorials, see our JIRA Development Hub.

Name JIRA Plugin Development Kit
Plugin Version 3.12
Product Version 3.12
Author(s) Atlassian
Home Page JIRA Plugin Development Kit
Download Location Please download the version applicable to your JIRA version
ZIP: jira-development-kit-3.12.zip - TAR: jira-development-kit-3.12.tar.gz - All versions
Download Source http://svn.atlassian.com/svn/public/atlassian/jira/jira-development-kit/trunk

Description/Features

A development kit for JIRA plugins with JIRA API, dependencies and examples.

Included in this version of the development kit are:

  • Seven example plugins with full source code and build scripts
  • Skeleton project templates for creating your own plugins
  • Full JavaDoc API documentation
  • All JIRA dependencies

Requirements

  1. Sun Java JDK 1.4+ : http://java.sun.com/j2se/downloads/index.html
  2. Apache Maven 1.0 : http://maven.apache.org/maven-1.x/start/download.html (Not Maven 1.1.)
  3. Atlassian-IDEA Maven Plugin
  4. A running instance of JIRA: either built from source or a standalone installation.

Maven is not strictly required to build your JIRA plugins, however, all of the example plugins have been developed with Maven as well as the template project. We highly recommend that you use Maven to build your plugins.

Instructions

  1. Copy the templates directory and rename it for your plugin
  2. Edit the project.xml for your plugin name
  3. in your new directory, run 'maven atlassian-idea' to generate IDEA project files.
  4. Launch your new project in IDEA by opening the $MY_PLUGIN_NAME.ipr file.
  5. Edit 'src/etc/atlassian-plugin.xml' for your project, as described in the documentation.
  6. Develop something cool!
  7. When you're ready to deploy, run 'maven jar' to build your plugin jar in the target directory
  8. Deploy it to your JIRA instance.

For more details on plugins, see the plugin guide.

Version History

Version Compatible Jira Version Comments
3.12 3.12 Updated development kit dependencies for JIRA 3.12.
3.11 3.11 Updated development kit dependencies for JIRA 3.11. The Lucene indexing library has been upgraded in JIRA 3.11 and this versions of the development kit will only work against JIRA 3.11 or better.
3.10 3.10 Updated development kit dependencies for JIRA 3.10
3.9.1 3.9 Updated development kit dependencies. Fixed CloseParentFunction. Tested against JIRA 3.8
3.8.1.2 3.8.1 Updated the project.xml to have correct dependencies. Tested against JIRA 3.8.1
3.8.1.1 3.8.1 Updated CloseParentIssueFunction to index properly and use correct method of transitioning. Tested against JIRA 3.8.1
3.8.1 3.8.1 Updated development kit dependencies. Tested against JIRA 3.8.1
3.8 3.8 Updated development kit dependencies. Tested against JIRA 3.8
3.7.1 3.7.1 Tested against JIRA 3.7.1
3.7-beta2 3.7-beta2 Updated development kit dependencies. Tested against JIRA 3.7-beta2
3.6-1 3.6.x The 3.6 development kit was incomplete and broken, this release fixes up these issues
3.6 3.6.x Updated development kit dependencies. Tested against JIRA 3.6
3.5 3.5.x Updated development kit dependencies. Tested against JIRA 3.5
3.4-r3 3.4.2 Updated development kit dependencies. Tested against JIRA 3.4.2
3.4-r2 3.4.1 Updated development kit dependencies. Tested against JIRA 3.4.1
3.4-r1 3.4 Added custom field example that links to Confluence. Tested against JIRA 3.4
3.3rev1 3.3.* Fixed example report to be compatible with JIRA 3.3
3.3 Redundant. Use 3.3rev1 Updated for JIRA 3.3 and with new versioning scheme. (versioning now matches major JIRA versions)
0.5 3.2.* Added RPC client example and updated for JIRA 3.2 (including examples)
0.4.1 3.1.* Update for JIRA 3.1.1
0.4 Pre 3.1 Added workflow tutorial
0.3   Added reports tutorial
0.2   Initial public release

Screenshots

Labels:

plugins plugins Delete
Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.
  1. Mar 30, 2005

    Mariano Alonso Ortiz says:

    I haven't seen any example of a workflow validator, could it be possible to have...

    I haven't seen any example of a workflow validator, could it be possible to have one?

    I have tried to implement a plugin for a Validator that restricts the maximum issue priority for reporters belonging to a given user group. The parameters of that validator are the choosen maximum priority and the group which is restricted to that maximum. When adding the plugin to Jira 3.0 I get a ClassCast Exception when I add the validator to the workflow (it is also noticeable that velocity template to input parameters is not shown when this happens), but the same code works for a condition which performs a similar job.

    Can someone help me? I can share the code with those interested, and when fixed it could be added to this kit if the author considers it appropiate.

    Thanks.

    1. Mar 30, 2005

      Mariano Alonso Ortiz says:

      The code has been attached in a file called jiraplugin.tar.gz

      The code has been attached in a file called jiraplugin.tar.gz

    2. Mar 30, 2005

      Mariano Alonso Ortiz says:

      I'm sorry, I made a mistake. My validator factory did not implement the appropia...

      I'm sorry, I made a mistake. My validator factory did not implement the appropiate interface. Now that is fixed. But when I create a issue that does not match the validator criteria I get a weird exception. How can I transform the exception into a nice and user friendly message?

      Thanks again

  2. Mar 31, 2005

    Scott Farquhar says:

    Mariano, Please post your support questions to our online support system:

    Mariano,

    Please post your support questions to our online support system:

    http://support.atlassian.com/

    Cheers,
    Scott

  3. Apr 02, 2005

    Mariano Alonso Ortiz says:

    Thank you very much, Scott. For people interested in tracking this issue, here...

    Thank you very much, Scott.

    For people interested in tracking this issue, here is the URL.

    http://jira.atlassian.com/browse/JRA-6313.

    Though I could not make validator to show a user friendly advisory on create issue screen, the plugin works showing an exception. Maybe the code is useful to be included in a future plugin sdk.

  4. Jun 22, 2005

    Tom Chiverton says:

    jiracom:JiraCreateSearch may be useful to read in conjunction with the dev kit.

    JiraCreateSearch may be useful to read in conjunction with the dev kit.

  5. Sep 19, 2005

    Mike Doustan says:

    Here is a stupid question ... How do I install/configure the Jira development ki...

    Here is a stupid question ...

    How do I install/configure the Jira development kit so I can use it?

    Thanks,
    Mike

    1. Sep 19, 2005

      Keith says:

      Hi Mike, Once the JIRA Dev Kit has been unzipped, you should have a directory st...

      Hi Mike,

      Once the JIRA Dev Kit has been unzipped, you should have a directory structure as displayed above. In order to compile a particular examplee, navigate to the example directory of interest - e.g.

      ../examples/plugin-report-sample

      and execute the following command:

      maven jar

      The example plugin report will be compiled and a jar file is created in the target directory - e.g.

      ../examples/plugin-report-sample/target/atlassian-jira-plugin-report-example-1.1.jar

      This jar can be placed in the JIRA WEB-INF/lib directory in order to enable it within JIRA.

      Let us know if you have any further questions.

      Regards,
      Keith

  6. Nov 25, 2005

    Michal Szklanowski says:

    Hi guys, I have some comments as for the version naming. For me, personally, it'...

    Hi guys,

    I have some comments as for the version naming. For me, personally, it's a little bit misleading to call the JIRA development  kit jira-development-kit-3.4-r2.zip while it applies for 3.4.1 version of Jira. Can it be just called jira-development-kit-3.4.1.zip? Would be so easier...

    1. Nov 27, 2005

      Jeff Turner says:

      Michal, You're right, it should be called jiradevelopmentkit3.4.1.zip (the vers...

      Michal,

      You're right, it should be called jira-development-kit-3.4.1.zip (the version reflects the JIRA version the plugin was tested with).

  7. Feb 09, 2006

    decan says:

    I haven't seen any example of creating a new project tab panel, could it be poss...

    I haven't seen any example of creating a new project tab panel, could it be possible to have one? Thanks

    1. Feb 09, 2006

      Jonathan Nolen says:

      I'll see what we can do. Cheers, Jonathan

      I'll see what we can do.

      Cheers,
      Jonathan

  8. Feb 23, 2006

    Chris Houghten says:

    I also would have liked to see a new project tab panel example/tutorial. Now tha...

    I also would have liked to see a new project tab panel example/tutorial.

    Now that I have muddled through it and created one, I would like to know if there is a place specifically for developers to post tutorials for other developers.

    Not using IDE or Eclipse, the process for even getting started on plugin development took some time and it would have been nice to have information on plugin creation that completely avoids discussing IDEA, Eclipse, and Maven.

    Iw there is no dedicated place for this type of developer input, I will be posting on my personal web site, but I would prefer if it was on the atlassian site. The JiraDev forum doesnt seem a very good place as the threads will get lost in the sea of questionos and answers.

    1. Feb 23, 2006

      Jonathan Nolen says:

      I'm about halfway through a tutorial for a project tab, but we'd love to have yo...

      I'm about halfway through a tutorial for a project tab, but we'd love to have yours as well. Please post it in the JIRA Community Space space. In the future, it may get incorporated into the official documentation, but that's a good place to start.

      And let me encourage you to share your new plugin in the JIRA Plugin Library if it is something that might be useful to others.

      Cheers,
      Jonathan

  9. Apr 19, 2006

    Asgeir S. Nilsen says:

    {{jmock1.0.1.jar}} is missing from {{jiradevelopmentkit3.6.tar.gz}}, causing bui...

    jmock-1.0.1.jar is missing from jira-development-kit-3.6.tar.gz, causing build errors in several test cases.

    1. Apr 21, 2006

      Dylan Etkin says:

      Hi Asgeir, There were quite a few problems with the 3.6 dev kit. I have updated...

      Hi Asgeir,
      There were quite a few problems with the 3.6 dev kit. I have updated it with 3.6-1 and this should sort you out. Thanks for reporting.
      Dylan

  10. Aug 09, 2006

    Mikko Levonmaa says:

    Will the development kit be updated to maven2? Cheers, Mikko 

    Will the development kit be updated to maven2?

    Cheers,

    Mikko 

    1. Aug 10, 2006

      Nick Menere says:

      Yes it will.... We are currently migrating Confluence to Maven 2 and once that ...

      Yes it will....

      We are currently migrating Confluence to Maven 2 and once that is done we will start moving Jira (piece by piece). I don't think we have a timeframe for this yet.

      Cheers,
      Nick

  11. Nov 22, 2006

    Thomas von Rymon-Lipinski says:

    Hi guys, I don't know if I make something wrong, but the installation fails ever...

    Hi guys,

    I don't know if I make something wrong, but the installation fails everytime I try it.
    I followed the instructions until I arrived at number 3. Yes I know, not very far.
    At number 3 maven downloads some packages and try to build.
    Now the Error:

    BUILD FAILED
    
    File...... C:\Dokumente und Einstellungen\Dohmmy\.maven\cache\atlassian-idea-plu
    
    gin-3.5.1\plugin.jelly
    
    Element... j:import
    
    Line...... 49
    
    Column.... 76
    
    null:-1:-1: <null> Could not parse Jelly script
    
    Total time: 3 seconds
    
    Finished at: Wed Nov 22 11:58:50 CET 2006

     After a short look at the given plugin.jelly I noticed that maven had searched for a file named project.jelly:

    <j:import file="${template.dir}/project.jelly" inherit="true"/> 

    There is no project.jelly at the template dir and so no project.jelly in the used folder for the new template...

    Now my question: Is there anything wrong in what I'm doing or is this a known bug or or or...

    Thanks,

      Thomas

    1. Nov 23, 2006

      Yuen-Chi Lian says:

      Hi Thomas, May I know the steps you've taken to install the {{atlassianidea}} p...

      Hi Thomas,

      May I know the steps you've taken to install the atlassian-idea plugin? Problem seems to lie somewhere there.

      Also, please see:

      Cheers,
      Yuen-Chi Lian

      1. Nov 23, 2006

        Thomas von Rymon-Lipinski says:

        :) That's exactly the page from which I downloaded the plugin and I followed the...

        That's exactly the page from which I downloaded the plugin and I followed the installation instructions given there.

        I downloaded the jar file and tried both ways, copy to the plugin folder of maven and 'maven plugin:install'. Second way ended wtih BUILD SUCCESSFUL.

        Perhaps it's an version conflict?

        atlassian-idea-plugin-3.5.1
        jira-development-kit-3.6-1
        atlassian-jira-enterprise-3.6.5-standalone
        idea-6.0.2
        maven-1.0.2 

        Thanks,

          Thomas
         

        1. Nov 27, 2006

          Yuen-Chi Lian says:

          Problem fixed. The {{maven plugin:install}} command is only required for the sv...

          Problem fixed.

          The maven plugin:install command is only required for the svn checked-out. If you download the binary from http://repository.atlassian.com/atlassian-idea-plugin/plugins/, you only need to copy it to the maven's plugin/ directory (unpacking is unnecessary).

          Cheers,
          Yuen-Chi

  12. Dec 06, 2006

    Yudong Song says:

    I downloaded the Maven 2.0.4 and jiradevelopmentkit3.61.zip. Installed the Maven...

    I downloaded the Maven 2.0.4 and jira-development-kit-3.6-1.zip. Installed the Maven and unzipped the development kit. Then went to the one of the example directory, e.g., C:\jira-development-kit-3.6-1\examples\plugin-customfield-sample, and run mvn jar, andit failed with the following error message:

     C:\jira-development-kit-3.6-1\examples\plugin-customfield-sample>mvn jar
    [INFO] Scanning for projects...
    [INFO] ------------------------------------------------------------------------
    [ERROR] BUILD FAILURE
    [INFO] ------------------------------------------------------------------------
    [INFO] Invalid task 'jar': you must specify a valid lifecycle phase, or a goal i
    n the format plugin:goal or pluginGroupId:pluginArtifactId:pluginVersion:goal
    [INFO] ------------------------------------------------------------------------
    [INFO] For more information, run Maven with the -e switch
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: < 1 second
    [INFO] Finished at: Wed Dec 06 12:23:49 EST 2006
    [INFO] Final Memory: 1M/2M
    [INFO] ------------------------------------------------------------------------

    Please tell me what else I have to do to build the jar file for the examples.

     Thank you very much.

    Yudong Song

    1. Dec 06, 2006

      Donna McGahan says:

      Yudong, You need to use Maven 1.x not 2.x for JIRA development:

      Yudong,

      You need to use Maven 1.x not 2.x for JIRA development:

      http://maven.apache.org/maven-1.x/start/download.html

      Cheers,
      Donna

      1. Dec 06, 2006

        Yudong Song says:

        Thanks, Donna. Yes, I just downloaded the 1.0.2 and It start to build, but faile...

        Thanks, Donna. Yes, I just downloaded the 1.0.2 and It start to build, but failed because of the invalid target release. Not sure what the release number it is.

        Thanks for your quick response.

        Yudong

        1. Dec 06, 2006

          Donna McGahan says:

          Yudong, Sounds like you may have an issue with your build.properties file. Perh...

          Yudong,

          Sounds like you may have an issue with your build.properties file. Perhaps you can post this problem on our JIRA developer forum at http://forums.atlassian.com? Please include the error you are getting and the maven command you are running.

          Thanks,
          Donna

    2. Dec 07, 2006

      Vincent Thoulé says:

      Hi Yudong, If you are interested by using Maven 2 for JIRA Development, I try t...

      Hi Yudong,

      If you are interested by using Maven 2 for JIRA Development, I try to establish a way to work with it.

      See https://svn.atlassian.com/svn/public/contrib/jira/atlassian-jira-parents, where a POMs files are available to install (maven 2 goal) JIRA into your local maven 2 repo.

      See sample implementation with https://svn.atlassian.com/svn/public/contrib/jira/jira-kaamelot-plugins/trunk/jira-plugin-kaamelot-parent

      Cheers,
      Vincent

      1. Dec 07, 2006

        Yudong Song says:

        Thank you very much, Vincent. I&nbsp;was able to deploy the custom filed plugin ...

        Thank you very much, Vincent. I was able to deploy the custom filed plugin examples successfully yesterday with the Maven 1.0.2. I'll try the Maven 2.0 late.

        We are currently using Eclipse 3.2 (EclipseCallisto) as our IDE. I am more interested in how to set up the JIRA plugin development environment within eclipse 3.2 without external tools. So we can develop and test the plugin, and other web applications within the eclipse. I prefer to have a single development environment (eclipse and ant) without Maven. Currently I am doing some testing, or prototype for developing some web applications by extending the JIRA, such as creating, seraching and updating issues through the JIRA SOAP interface. I am quite familiar with the standard web service development, so I was able to set up the development environment within my eclipse, get WSDL, generate the stubs, and talk to the JIRA server to get all the work done pretty quick and nicely without Maven. But, I am not sure how to set up the JIRA plugins, e.g., custom fields, mail notification, etc. development environment in eclispe. The documents about the JIRA eclipse IDE on your support page is not very clear.

        It'll be greatly appreciated if you can have a skeleton (e.g., custom field plugin examples) eclipse project setup without Maven, so I can import it to my eclipse, test, debug it within my eclipse without any external tools and scripts. We currently use Subversion. I have atlassian-jira-enterprise-3.6.5-standalone installed on my desktop.

        Thank you very much.

        Yudong

  13. Dec 07, 2006

    Yudong Song says:

    Is the JIRA Plugin Development Kit for the latest JIRA 3.7beta2 available or the...

    Is the JIRA Plugin Development Kit for the latest JIRA 3.7-beta2 available or the current Plugin Kit works for the 3.7 beta version?

    thanks,

    1. Dec 08, 2006

      Nick Menere says:

      Sorry about this, it will be available on Monday. Cheers, Nick

      Sorry about this, it will be available on Monday.

      Cheers,
      Nick

      1. Dec 10, 2006

        Andreas Knecht says:

        I've just put up the development kit for JIRA 3.7beta2. See the download links a...

        I've just put up the development kit for JIRA 3.7-beta2. See the download links above. Enjoy!

        Cheers,
        Andreas

  14. Dec 11, 2006

    Yudong Song says:

    I got the 3.7 development kit, compiled the customfield example, deployed to the...

    I got the 3.7 development kit, compiled the custom-field example, deployed to the 3.7 beta 2. I tried to modify the custom-field example to display the editable field for "Administrators" role. It did not show the editable field for the user with "Administrator" role (The Administrator role is set correctly), instead it shows the read-only field. I am not sure if the change I made in the template is correct or not. Attached is the template I modified to try to test the role (not group):

    edit-jiraadminonlytext.vm:

    #controlHeader ($action $customField.id $customField.name $fieldLayoutItem.required $displayParameters.noHeader)

    #if ($authcontext.user.inRole('Administrators'))    <==== here what velocity command I should use for Role?
    <input type="text"
    name="$customField.id"
    value="$!value" />
    #else
    #if($value && $value != "")
    #set ($displayValue = $

    Unknown macro: {value}
    )
    #else
    #set ($displayValue = 'N/A')
    #end
    <span title="This field is editable only by JIRA administrators">$!displayValue</span>
    <input type="hidden"
    name="$customField.id"
    value="$!value" />
    #end
    #controlFooter ($action $fieldLayoutItem.fieldDescription $displayParameters.noHeader)

    Please help.

    1. Dec 11, 2006