Crucible gadget tutorial

This tutorial will teach you how to write a simple gadget which can display information from Crucible on the JIRA dashboard.It uses the standard Fisheye/Crucible REST interface to retrieve information. Other gadgets you write may need to use a REST module to retrieve the specific information they require in the most efficient way.

Plugin Source

We encourage you to work through this tutorial. If you want to skip ahead or check your work when you are done, you can find the plugin source code on Atlassian Bitbucket. Bitbucket serves a public Git repository containing the tutorial's code. To clone the repository, issue the following command:

1
2
$ git clone https://atlassian_tutorial@bitbucket.org/atlassian_tutorial/fecru-gadget-tutorial.git

Alternatively, you can download the source using the Downloads page here: https://bitbucket.org/atlassian_tutorial/fecru-gadget-tutorial

Work through the Tutorial

To do this tutorial you will need an installation of JIRA 4.0 to act as the Gadget container.

First we'll write a trivial gadget which doesn't request any information from the gadget provider.

Declare the gadget in your atlassian-plugin.xml file:

1
2
<gadget key="trivial-gadget" location="gadgets/helloworld.xml"/>

Then create the gadget file at src/main/resources/gadgets/helloworld.xml. You can use any directory structure under src/main/resources for your gadgets.

The gadget specification, helloworld.xml contains this code:

1
2
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
    <ModulePrefs title="Crucible Tutorial Hello World Gadget" author_email="adent@example.com"
                 directory_title="Crucible Tutorial Hello World Gadget">
        <Require feature="minimessage"/>
        <Optional feature="dynamic-height"/>
    </ModulePrefs>
    <Content type="html">
<![CDATA[
        Hello,world!
]]>
    </Content>
</Module>

Install your plugin into Fisheye/Crucible, then add it to JIRA thus:

Log in to JIRA as an administrator.
Select the Dashboards, Manage Dashboards menu option.
Click 'create new dashboard'
Type a name in the 'Name' field and click add. (defaults are fine for everything else)
Click on the name of your new dashboard and you'll be taken to an empty dashboard which will allow you to add gadgets.
Click on 'add a new gadget' and click the 'Add Gadget To Directory' button - you will only see this if you are a JIRA administrator.
Paste the URL helloworld.xml into the text field and click 'Add Gadget'.
Your gadget will appear, highlighted in yellow, in the gadget directory. Click 'Add it Now' and then 'Finished'. You should now see your trivial gadget on your JIRA dashboard.

The URL your gadget is served from depends on the plugin module key of the gadget module, which is composed of the artifact group and id you specified when you created your plugin project (you can see these in your pom.xml), and the key you gave your gadget module (which you can see in atlassian-plugin.xml).

So in the URL above, the section com.example.crucible.gadget-tutorial:trivial-gadget is composed of:

group id	com.example.crucible
artifact id	gadget-tutorial
module key	trivial-gadget

To develop more complicated gadgets, see Gadget Development.