Another Atlassian FedEx Day and a Confluence gadget on the way

A few months ago I wrote about my first Atlassian FedEx day ever. Now I’ve survived another. Plenty of dust, sweat and tears, and plenty of laughs, later, I have a brand new Confluence gadget to boast about. Well, actually I have 3 halves of a Confluence gadget and lots of lessons learned.

My aim for this FedEx Day was to learn more about developing gadgets. I’ve created a gadget before, but it was a generic Google gadget and not specifically an Atlassian gadget. Of course, if I can get a useful gadget working too, that would be awesome.

I’m part way there.

My JIRA Tips Gadget

Just so you know: It’s nowhere near ready yet.

The user story: People want to see JIRA hints and tips on their JIRA dashboard, rather than having to find their way to our documentation. We want the hints and tips to be housed on our documentation wiki, so that we can update them easily. People also want to see Confluence hints and tips on their Confluence dashboard, and Crucible hints, and so on.

The solution: Develop a “Tips” gadget for each product, starting with the JIRA Tips Gadget.

• The gadget gets the tips, one at a time, from our documentation wiki, affectionately known as CAC.
• On CAC, we have a set of tailored tips for JIRA, another set of tips for Confluence, etc. These tips can be part of the documentation too, provided they keep the required (minimalist) format. We’ll store them as children of a particular page, so that the gadget knows where to get them.
• People can:
  • Add the JIRA Tips Gadget to their JIRA dashboard.
  • Add the Confluence Tips Gadget to their Confluence dashboard (by customising their Dashboard welcome message) or a wiki page.
  • Add any of the “Tips” gadgets to iGoogle, Gmail, etc.

Things I learned the hard way

FedEx tip 1: Don’t shut down your environment at the end of day 1. I made that mistake, and then spent two hours getting it back on Friday morning.

FedEx tip 2: Don’t install a Confluence plugin containing a gadget module that refers to a gadget spec residing on the same Confluence instance. I stored my gadget spec (XML file) as an attachment to a Confluence page. That seemed handy.  But the startup procedure found the gadget plugin and went looking for the gadget spec. It waited and waited and waited… Eventually I reinstalled Confluence and recreated all my configuration and data. Hence the two hours on Friday morning.

How far did I get?

The plan was to start with a very simple gadget and gradually make it more complex:

1. First a URL-type gadget that does a straight grab of content from a page.
2. Then an OpenSocial gadget (i.e. an HTML-type gadget), but still grabbing the HTML off the page.
3. Lastly a full-blown OpenSocial gadget using the Confluence REST API.

1. The URL-type gadget

This is a quick and dirty solution using:

• A gadget with content type=”url”.
• An {include-random} macro in Confluence.

On my JIRA dashboard, the gadget shows a random tip on each refresh:

The gadget XML is very very simple:

<?xml version="1.0" encoding="UTF-8"?>

<Module>

<ModulePrefs title="JIRA tips (URL gadget)"

height="400"

scrolling="true">

<Require feature="dynamic-height"/>

</ModulePrefs>

<Content type="url" href="http://my.Confluence.Server:8090/display/MYSPACE/MYPAGE" />

</Module>

In Confluence, we have:

• A parent page with the following content:
  {include-random:MYPAGE|nopanel}
• And a number of child pages, each one containing a single tip.

It’s not an OpenSocial gadget, but rather a gadget with a content type of “url”. The URL given is the address of the Confluence page that contains the {include-random} macro.

2. The HTML-type gadget grabbing HTML from a Confluence page

This is a quick and dirty solution using:

• A gadget with content type=”html”, i.e. an OpenSocial gadget, but without REST. Instead it just gets the HTML from a Confluence URL. Next stage would be to parse the HTML to isolate the content of the wiki page.
• An {include-random} macro in Confluence.

On my JIRA dashboard, the gadget currently shows the HTML for the full page and without special styling:

If it’s worth pursuing this type of gadget, I need to:

• Parse the HTML to get only the page content.
• Apply a style sheet.

3. The OpenSocial gadget using Confluence REST API

This is supposed to be the final, walking talking solution using:

• A full OpenSocial gadget.
• The Confluence REST API, rolling through all the child pages of a given parent page.
• Something to convert the wiki markup into HTML.

At the moment, it’s still a quick and dirty solution using:

• A full OpenSocial gadget.
• The Confluence REST API, returning a single page.
• HTML markup in the Confluence page content.

My REST gadget returns the page body as wiki markup. Here it is on my JIRA dashboard:

I don’t have time in FedEx to parse the wiki markup. So I cheated completely and put the HTML directly onto the Confluence page. So here’s what the gadget shows now in JIRA:

Of course, the Confluence page looks like nothing on earth:

I’d like to pursue the REST solution. I still need to:

• Retrieve the child pages of the given page.
• Render the wiki markup.

Bits and pieces

At the moment all three of my gadgets consist entirely of Javascript, XML and HTML. So the whole gadget is contained in the XML gadget spec. None of them (yet) requires a plugin. Gadget XML can be served from anywhere. I’ve stored mine as attachments to a Confluence page and serve them from there.

Phew

That’s Atlassian FedEx Day for you — quick and dirty and fun. Within the next few days, I’ll post a full report on our documentation wiki (CAC) that will probably include the gadget code (if I’m feeling brave enough to expose that to the world). I hope you’ve enjoyed reading about it and learned something along with me.