Gadgets on Confluence wiki pages – oh, and in JIRA and iGoogle
A beta version of the next Confluence release is out. And guess what — it’s got gadgets. This is pretty cool, so I’m jumping the gun and telling you about it right now.
It’s still just a beta release: Confluence 3.1 Open Beta. The announcement is on the Atlassian News Blog, along with an invitation to try it out. So I got myself a copy and put some gadgets onto a wiki page.
Now, the gadgets I chose are perhaps not the most useful. 😉 The most usual business case would be to add gadgets published by other Atlassian applications. For example, you might want to add a gadget that displays some information from another Confluence site or from JIRA, Bamboo, FishEye or Crucible. (Those are other applications developed by Atlassian, the company I work for.)
But for me, the fun bit is that I can add the gadget that I created and blogged about 8 months ago.
The same 2 gadgets in 3 different applications
Here’s a screenshot of a Confluence wiki page with two gadgets. One is mine, displaying an up-to-date list of recent blog posts about technical writing from WordPress.com. The other gadget was created by Donna, our support diva, showing recent entries in a Jive discussion forum. (Click the image to enlarge it.)
Here are the same two gadgets on my iGoogle page:
And here they are in JIRA:
How do you add a gadget to a Confluence page?
Your Confluence page can display two types of gadgets:
- Internal — These are gadgets published by the same Confluence site as where they are displayed. Typically such a gadget would display information sourced from the Confluence site, such as an activity stream or a search function.
- External — These are gadgets published by another Confluence site, or a JIRA site, or even something totally different like Remember the Milk, a hamster in a wheel or a pet monkey. 🙂
If your gadget is external, the Confluence administrator needs to add the gadget to the list of available gadgets before you can add it to your Confluence page. This needs to happen only once for each gadget.
To make an external gadget available in your Confluence site:
- Log in as a Confluence administrator.
- Go to ‘Confluence Admin‘ and click ‘External Gadgets‘ in the left-hand navigation panel.
- Paste the URL of your gadget into the field labelled ‘Gadget Specification URL‘. The URL should point to the XML file that describes the gadget.
For example, take a look at the URLs for the two gadgets in my screenshots above. The URL for the WordPress gadget is:
And the URL for the Jive forums gadget is:
Friendly warning: I’m just using my gadget as an example here. It’s a total hack, so please don’t insert it into any Confluence sites that matter! You’ll get all sorts of weird display problems, plus potential security issues too.
To add a gadget (external or internal) to a Confluence page:
- Create a new page or edit an existing page.
- Put your cursor in the edit box where you want the gadget displayed.
- Click the ‘Insert/Edit Macro‘ icon in the toolbar.
- You’ll see the ‘Select Macro’ popup window. Enter some text into the search box at top right, to find the gadget you want.
- Click the gadget you want. You’ll see a preview of the gadget. Most gadgets also offer you some options to configure the gadget, such as width of the display, background colour, etc.
- Change the settings if you like, then click ‘Insert‘.
- Save the Confluence page.
Extra authorisation step (OAuth)
Some gadgets require extra authorisation, to reassure the publishing server that it’s OK to send its data to the server where the gadget is displayed. Gadgets use an authorisation protocol called OAuth. There are two parts to the authorisation, one performed by the administrator and one by the person adding the gadget to or viewing the gadget on the page.
- The administrator needs to set up the OAuth relationship between the gadget publishing server (called the provider) and the displaying server (called the consumer). This authorisation step needs to happen only once for each site. Once you’ve authorised one server to send information to another server, then you can add multiple gadgets from that server. For example, let’s say you want to display JIRA gadgets on a Confluence page. Your JIRA server needs to trust your Confluence server. So you’ll need to add Confluence as an OAuth consumer in JIRA. To do this, you will give JIRA the URL of your Confluence server. The instructions are in the JIRA documentation.
- When you add a gadget to a page, you will need to authorise the display of information under the authority of your user ID. Similarly, every user who views the page will need to authorise the display of the information under their user ID. The authorisation lasts for a while (a week or so, unless you revoke it). The gadget will display a ‘Log In and Approve‘ button. When you click the button, you will go to the login page of the site concerned. Log in and then approve the gadget’s access to the server’s information. Now you’ll see the gadget information displayed. There’s a full write-up in the Gadgets documentation.
Phew, I’m glad we’ve got that out of the way! 😉
Would you like to try it yourself?
Posted on 12 November 2009, in atlassian, Confluence, technical writing, wiki and tagged atlassian, Bamboo, Confluence, Crucible, documentation, fisheye, gadget, gadgets, JIRA, OAuth, technical documentation, technical writer, technical writing, wiki. Bookmark the permalink. 3 Comments.