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:

Another Atlassian FedEx Day and a Confluence gadget on the way Another Atlassian FedEx Day and a Confluence gadget on the way Another Atlassian FedEx Day and a Confluence gadget on the way Another Atlassian FedEx Day and a Confluence gadget on the way

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:

Another Atlassian FedEx Day and a Confluence gadget on the way

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:

Another Atlassian FedEx Day and a Confluence gadget on the way

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:

Another Atlassian FedEx Day and a Confluence gadget on the way

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

Another Atlassian FedEx Day and a Confluence gadget on the way

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.🙂

Update on 1 Feb 2010: I’ve posted the “Atlassian FedEx Delivery Note” for my project on our documentation wiki now too. It contains the gadget code: ShipIt 13 Delivery – JIRA Tips Gadget. (Updated March 2013: FedEx Day is now called ShipIt Day.)

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 16 January 2010, in atlassian, Confluence, online help, technical writing, wiki and tagged , , , , , , , , , , , . Bookmark the permalink. 9 Comments.

  1. Way to go Sarah! Great job with your FedEx day gadget! I love FedEx season….

    • Hallo Randall
      Thanks! Yes, isn’t FedEx great? The best thing is how much you can learn in such a short space of time, and the weird ideas you can try out. There were some great projects demo’d on Friday afternoon. The reports will start rolling out this week, I’m sure.
      Cheers, Sarah

  2. Way to go Sarah!

    Am awaiting the promised full report.

    • Heh heh, thanks Anindita! I’ll post a link here once the write-up is done.

      Some time after that, I’m hoping to have time to fix up the code so that it works much better. This may have to wait until the next FedEx Day. I want to start with the ability to return all the child pages one at a time in sequence.

      But for now, I’m very happy that it returns anything at all.🙂

      Cheers, Sarah

  3. Very nifty Sarah! You could use the printable decorator to clean up the wiki page display, eg: http://whatever.com/display/FOO/bar?decorator=printable

    It strips out all the navigation, etc., leaving a very basic view of primarily just the content.

  4. I’ve posted the “Atlassian FedEx Delivery Note” for my project on our documentation wiki now too. It contains the gadget code:
    http://confluence.atlassian.com/display/DEV/FedEx+13+Delivery+-+JIRA+Tips+Gadget

    Update: The page has been renamed: https://confluence.atlassian.com/display/DEV/ShipIt+13+Delivery+-+JIRA+Tips+Gadget

  5. what happened to the {include-random} macro? Was it discontinued? I’d love to be able to use this now, but I can’t find it anywhere.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: