It’s been 6 months since the initial release which was only tested on Confluence 3.0. This time I’ve added a new dashboard section, full support for Confluence 3.1 & 3.2 and a pile of macro parameters as requested by Guy Fraser. The release notes are here. Confluence 3.3 is just around the corner, so I’ll add an update for that when it comes out.

Thank you

The Confluence community has shown a great deal of support and encouragement since the plugin was originally released. For example, Atlassian blogged about it before I got a chance to. So thanks to all for your support.

The plugin was name checked by Sherif Mansour – Atlassian’s Product Manager for Confluence in the Confluence State of the Union presentation at Atlassian Summit 2010 at the start of the month. Watch it all, but concentrate especially around 5:10!

This week Google approved the plugin for their Google Analytics Application Gallery — take a look here. The Apps Gallery has only been going for about a month so I’m really excited about being a part of it. The slight name change and new logo were done to fit in with the Application Gallery Policy.

In the future

The next release should support Confluence 3.3 and also complete tracking of all pages in a space — not just those with a URL starting /display/spaceKey/ — based on this hack :

// Add a page-level custom variable to record the space-key
if (typeof jQuery('meta[name=confluence-space-key]').attr("content") == 'string')
{
  pageTracker._setCustomVar(
    1, // This custom var is set to slot #1 of 5

    // The name acts as a kind of category for the user activity
    'confluence-space-key',    

    // This value of the custom variable
    jQuery('meta[name=confluence-space-key]').attr("content"), 

    3 // Sets the scope to page-level
  );
}

— If you want to use this hack now, try out this custom Google Analytics report which will allow you to take advantage of it now.

I’d also like to add full space specific tracking for attachments too.

A quick demo

And finally, this is what the new version looks like:

Related Posts

• Tracking Atlassian Confluence usage with Google Analytics
• 4 Useful Tips on Google Analytics Reporting for Confluence
• Announcing: Google Analytics plugin for Confluence – original release

This website and one or two others I run recently experienced what appeared to be a denial-of-service attack.

Looking at the access logs, I could see several tens of thousands of requests all originating from a range of amazonaws.com IP addresses. All with the useragent “bitlybot”.

This post is a quick postmortem of what went wrong and why.

So what happened?

I’ve been happily using the excellent bit.ly URL shortening API on the Readability Test Tool website for over a year with no problems at all. Whenever a user checks the readability of a web page using the Readability Test Tool, a convenient “tweet this” link is provided for the results page.

My bit.ly link also innocently appended a query string — &utm_source=twitter&utm_medium=retweet — so that I can track click-throughs from Twitter in Google Analytics.

Looking back at this, it wasn’t that clever a thing to do, but it only took a couple of minutes to implement, so was very little effort for a nice bit of analytics/measurement return.

All was good for a year. Google Analytics tracking worked well. There were no problems. Indeed looking back at the access logs, the bitlybot user agent had not so much as sniffed the website once in that time.

One day, something changed. Overnight bitlybot started crawling my website for all the links it had created over the year. Unfortunately for every link it crawl, it also created another link appending more parameters to the query string.

Which it then crawled. Creating another link with more appended query parameters. Ouch.

e.g.

http://www.read-able.com/check.php?uri=http%3A%2F%2Fwww.example.com%2F&utm_source=twitter&utm_medium=retweet
http://www.read-able.com/check.php?uri=http%3A%2F%2Fwww.example.com%2F&utm_source=twitter&utm_medium=retweet&utm_source=twitter&utm_medium=retweet
http://www.read-able.com/check.php?uri=http%3A%2F%2Fwww.example.com%2F&utm_source=twitter&utm_medium=retweet&utm_source=twitter&utm_medium=retweet&utm_source=twitter&utm_medium=retweet

And so on.

What did I do?

Initially I ranted on Twitter.

Then I removed the “tweet this” link to prevent further bit.ly URLs from being created. This wouldn’t stop things for while, but would at least prevent the problem from getting any worse.

Then I edited robots.txt:

# Tell "bitlybot" not to come here at all
User-agent: bitlybot
Disallow: /

This did not work – bitlybot only checks robots.txt once a day, so this would not improve matters instantly.

Then I redirected the traffic to bit.ly:

if ($_SERVER['HTTP_USER_AGENT'] == 'bitlybot')
{
	header('Location: http://bit.ly/', true, 301);
}

That slowed it a bit. Admittedly, I was still blaming them at this point.

Then I reached out to @bitly.

They were very responsive. I sent them a detailed email with a section of access logs and they fixed it. Quickly.

They disabled my account, preventing me from causing any further mischief. They stopped bitlybot from it’s crawling activity and reported the progress back to me.

Each contact with bit.ly via twitter or email resulted in a positive response — they were very quick to respond and my websites were soon back to their usual somewhat diminutive volume of traffic.

Conclusions

• Bit.ly has excellent support – they are very responsive and my little server was soon back to normal
• Think before you write code that uses other people’s APIs – you may not fully understand the consequences of your actions
• My Google Analytics tracking parameters were added with little thought – I really ought to have tried a bit harder to weigh up the implications
• My small VPS does nicely thank you for the limited traffic that it experiences. Given some decent volumes of traffic it will fail.

{hide-wiki-markup}

One thing I love about Confluence is the way that you can browse other people’s pages and steal their superior layout ideas for your own wiki pages.

It’s dead easy to do. Go to the Tools drop down menu and click on the View Wiki Markup link. A new window will open containing the wiki markup for the page. You can now copy the bits you like and discard the rest. Your friends and colleagues will be impressed by your wiki skills and you can continue on your path to becoming a wiki ninja.

But what if you don’t want to share those wiki markup skills?
That’s not very collaborative, I know. But there are entirely valid reasons that you’d wish to disable this feature.

An example of this is use of the {sql} plugin. This is a really powerful plugin that allows you to query databases and tabulate the results in Confluence. Wrap this in a {chart} macro and you have an instant graph. Nice work! There’s a great blog post at Atlassian that use this to great effect.

Security

However, using this kind of markup on a public website is a bad idea. Exposing the structure of your databases to people you don’t know and can’t trust is somewhat short sighted. On a company intranet, the risk is still there, but hopefully it is not so dangerous. Even so, it’s really best not to show this information in the first place.

What can we do about it?

The best solution would be additional security in the product that allows editors to prevent others from viewing wiki markup. It would probably go in the Restrictions screen. This does seem somewhat like a paranoid feature request, but call me paranoid.

Another way is to use Javascript to remove the link from the DOM. This is not a replacement for good security, but will stop the casual user from accessing the wiki markup.

It is easily done in a user macro:

As a Confluence administrator, go to Confluence Admin | User Macros and click on Create a User Macro.

Fill out the form…
Macro name: hide-wiki-markup
Output: Macro generates HTML markup
Template:

<script type="text/javascript">
jQuery('#action-view-source-link').parent().hide(); /*Updated from .remove(); Aug 2010*/
</script>

How? Type part of a sentence in the search form, then sit back and wait for the concerns of the people to be revealed.

Are politicians…

Celebrities? Psychopaths? Corrupt? Drug tested?

Does David Cameron…

Smoke? Dye his hair? Where does David Cameron go at night?

Nick Clegg

Atheist. 30 women. Nuff said.

Is Gordon Brown…

A freemason? A liar? And erm, some others

Is Parliament…

Effective? Democratic? Now an irrelevant institution?

Is the treasury…

Printing money?

Is the government…

Hiding aliens? Making you fat? Watching my computer?

Do government…

Assassins exist? Officials pay taxes?

Does democracy…

Work? Exist? Encourage terrorism?

However, I’ve not been entirely happy because there wasn’t a method to allow complete tracking of all space specific Confluence pages using CGAP or the reports that I’ve previously described.

This has been documented elsewhere, but briefly, the problem is with…

• pages with punctuation in the title e.g. This page is bad for Analytics, isn’t it? (hover on the link to see the URI)
• short URLs e.g. /x/2Bq9Ag
• space administration e.g. /spaces/spaceadmin.action?key=spaceKey
• page edits e.g./pages/editpage.action?pageId=XXXX
• page creation e.g. /pages/createpage.action?spaceKey=spaceKey&fromPageId=XXXX
• add/view attachments e.g. /pages/viewpageattachments.action?pageId=XXXX
• page history e.g. /pages/viewpreviousversions.action?pageId=XXXX
• view wiki markup e.g. /pages/viewpagesrc.action?pageId=XXXX

…and so on. I think you get the picture.

For any page where there is a real interaction with the wiki — such as page creation or page edits, attachment viewing or uploading — it is very difficult associate that interaction to the space where the interaction took place. Damn. That’s the main point really. Wikis are for collaboration — editing and creating content — not just passively reading.

It really bugs me that the URIs in Confluence aren’t built up so that they always provide a context of where you are. But what can we do?

This post suggests 2 possible solutions to this problem:

1. A Javascript only method
2. A Javascript and velocity templating method

Both have their drawbacks, but they do let you get a little closer to understanding what your users are doing within your Confluence spaces. Try them out and please report back on your preference or your own alternative solution.

The Javascript only method

In this method, we track a custom variable in GA where possible, so that we can attach a page view to the corresponding Confluence space.

Atlassian handily provide the following (example) meta tag on every page that has an associated space:

<meta id="confluence-space-key" name="confluence-space-key" content="~cczdas">

We can check for that meta tag and pass it into a custom variable in Google Analytics.

In Confluence, go to Dashboard | Administration | Look and Feel | Custom HTML

Click on the “Edit” button and add this javascript snippet (with your tracker code) to the “At end of the BODY” section:

<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">

	window.onload = function(){
		try
		{
			var pageTracker = _gat._getTracker("UA-XXXXX-XX");

			// Add a page-level custom variable to record the space-key
			if (typeof jQuery('meta[name=confluence-space-key]').attr("content") == 'string')
			{
				pageTracker._setCustomVar(
				     1,                         // This custom var is set to slot #1 of 5
				     'confluence-space-key',    // The name acts as a kind of category for the user activity
				     jQuery('meta[name=confluence-space-key]').attr("content"), // This value of the custom variable
				     3                          // Sets the scope to page-level
				);
			}
		}
		catch (err) {}
	}

</script>

This means for each page, we’ve added a custom variable which can later be check against. We can now therefore easily check which page belongs to which space.

In Google Analytics, the custom variables report looks like this:

This doesn’t really tell us much, other than the number of page views for a space and a little more. To get at the real power of custom variables, we need to create a custom segment for each space. This will allow us to see all the interactions for the space.

Here’s a short video guide to creating custom segments for Confluence spaces:

Pros

• It’s really simple. Anyone with Confluence administration rights can cut and paste this code.
• It’s pure. This should not be affected by upgrades to the platform.
• It’s easily to support. Lots of people know Javascript.

Cons

• You’re moving into slightly advanced Google Analytics territory here.
• You’ll need to set up a separate custom advanced segment for each space. This may be somewhat dull.

I really like this approach, but haven’t managed to successfully add it into CGAP yet whilst maintaining access to historical data.

Javascript and velocity templating method

In this method, we trick Google Analytics into reporting the URL in a the format that works with content drill-down e.g.

• /pages/viewpage.action?pageId=XXXX becomes /display/spaceKey/Page+Title
• /x/2Bq9Ag (short URL) becomes /display/spaceKey/Page+Title
• /pages/editpage.action?pageId=XXX becomes /display/spaceKey/Page+Title/edit
• /pages/viewpageattachments.action?pageId=XXX becomes /display/spaceKey/Page+Title/view-attachments

We do this by adding a custom meta tag named “analytics.url.fix” from which we read the “fixed” URL using a little Javascript.

Edits

page.vmd in your theme:

## Add Google Analytics support for page edits, attachment views etc.
## Called by $!sitemeshPage.getProperty("page.googleAnalyticsUrlFix") in main.vmd
<content tag="googleAnalyticsUrlFix">
	#if ($mode == "view")
		<meta name="analytics.url.fix" desc="$req.contextPath/display/$page.spaceKey/$page.title" />
	#else
		<meta name="analytics.url.fix" desc="$req.contextPath/display/$page.spaceKey/$page.title/$mode" />
	#end
</content>

main.vmd in your theme:
Add after the title node in /html/head/title

## Call the googleAnalyticsUrlFix content tag in page.vmd, fail silently:
$!sitemeshPage.getProperty("page.googleAnalyticsUrlFix")

In Confluence, go to Dashboard | Administration | Look and Feel | Custom HTML

Click on the “Edit” button and add this javascript snippet (with your tracker code) to the “At end of the BODY” section:

<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
	window.onload = function(){
		try
		{
			var pageTracker = _gat._getTracker("UA-XXXXXX-X"); 

			// Test for the meta[name=analytics.url.fix] tag & fix the url
			if (typeof jQuery('meta[name=analytics.url.fix]').attr("content") == 'string')
			{
	 			// console.debug('corrected pageview');
	   			var pageUri = jQuery('meta[name=analytics.url.fix]').attr("content").replace(/\s+/gi, '+');
				pageTracker._trackPageview(pageUri);
			}
			else
			{
				// console.debug('default pageview');
				pageTracker._trackPageview();
			}
		}
		catch (err) {}
	}
</script>

Pros

• You don’t have to do anything on the Google Analytics side at all
• This is just great for the content drilldown screen in Google Analytics.
  • It means that pages with punctuation in the title can now be seen within their correct space.
  • The space owners can now be sure of the stats for viewing and editing pages within their space.
• This is great for the Google Analytics plugin for Confluence (CGAP)
  • All the page edits should be shown in the analytics report
  • It’s easily supportable. Lots of people know Javascript

Cons

• It’s a bit messy.
• You’ll have to apply this to every theme you support.
• Editing velocity templates isn’t everyone’s cup of tea.
• I’ve no idea what will happen when you upgrade Confluence.
• It niggles me that we’re sending incorrect (though easily readable) pageview data to Google Analytics.
• It still doesn’t tie everything to the space, just the page interactions

To my mind, this is less elegant, but provides pretty much instant results.

Which one to choose?

I really like the simplicity of the first solution. Just a little bit of Javascript to read a meta tag that’s already there. It’s likely to easily survive an upgrade. But I’m disappointed that as yet, I can’t get it to work nicely with CGAP.

For ongoing support reasons, I’d always say don’t mess with the platform. Don’t do anything which makes it more difficult to upgrade to the latest and greatest version. If you agree, then steer well clear of the latter option. If however, you absolutely have to start complete space specific tracking right now, no matter what, then the latter is then choice for you.

In the past, we’ve added Google Analytics to Luminis to track the interactions, but never managed to fully segment user roles. Until now.

Out of the box, Luminis has roles such as staff, student, faculty, ProspectiveStudent etc. Users can have one or more of these roles and other custom roles too. If we could capture all the roles and pass them onto Google Analytics, then we’d be able to fully segment the user types and gain a better understanding of how each segment uses Luminis.

This post aims to show how this is possible in just 3 steps:

1. XSL: Edit nested-tables.xsl to add a custom meta tag for the luminis roles
2. Javascript/jQuery: Read the custom meta tag and set a custom variable in Google Analytics
3. Google Analytics: Create custom segments to view traffic for specific Luminis roles

Edit nested-tables.xsl and add a custom meta tag to the header

We’ve seriously hacked at nested-tables.xsl over the years, so our version of the file is likely to be different to most. The main aim here is to find the html > head section and add a custom meta tag:

<!-- Dump all roles into a single meta tag as a comma separated value -->
<meta name="luminis.role">
   	<xsl:attribute name="content">
		<xsl:for-each select="//layout/cp:cpInfo/cp:cpProperty[@name='pdsRole']/child::*">
			<xsl:value-of select="concat(., ',')" />
   		</xsl:for-each>
   	</xsl:attribute>
</meta>

Read the custom meta tag and set a custom variable in Google Analytics

Our implementation of Google Analytics is a little complex, but this example I’ve based on the standard Google Analytics example code.

Using Javascript (infused with jQuery in our case), we can read the custom meta tag and set a custom variable.

<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">

	window.onload = function(){
		try
		{
			var pageTracker = _gat._getTracker("UA-XXXXX-XX");

			if (typeof $('meta[name=luminis.role]').attr("content") == 'string')
			{
				pageTracker._setCustomVar(
				     1,                                                // This custom var is set to slot #1 of the 5 available in GA
				     "luminis.role",                                   // The name acts as a kind of category for the user activity
				     ','+$('meta[name=luminis.role]').attr("content"), // The value of the custom variable (starting with a comma)
				     2                                                 // Sets the scope to session-level
				);
			}
			pageTracker._trackPageview();
		}
		catch (err) {}
	}

</script>

According to the documentation, it’s important to set the custom variable before tracking the page view.

Create custom segments to view traffic for specific Luminis roles

Sign in to Google Analytics and view your normal website reports.
Click on Advanced segments | Create a new advanced segment

Create a new segment where…
Custom variable (Value 1) contains ,staff,
AND
Custom variable (Value 1) contains ,faculty,

Note the surrounding commas – we’re using them as role delimiters.

Give the segment a name e.g. “Luminis roles: staff AND faculty”"

All done, but have patience

Your custom segment is now available from the advanced segment drop-down:

Custom variables seem to take longer to filter through to Google Analytics than normal data such as page views. So come back in a couple of days and try out your new advanced segment.

Update (12 April 2010):
Shortly after I published this post, the Google Analytics blog posted their webinar on Google Analytics custom variables.

Also, if you’re interested in creating advanced segments from custom variables, I’ve posted ayoutube video that steps through the process.

Please fix the search UI in Safari on the iPhone.

I’ve been using the iPhone for some time now and overall, the interface is really slick. The buttons are consistently placed and this gives a really strong user experience. Everything appears to be in the obvious place.

The trouble is, I like to search the web and it looks like you’ve forgotten your own iPhone user interface rules for this area.

Let me explain

In all your other applications, the primary action button is located top-right with a secondary action button top-left.

Here’s some examples:

You get the picture, right?

Over time the user learns this convention and without realising it assumes that the top-right button means “OK”, “Submit”, “Search” or whatever the primary action is.

Now, let’s have a look at the Safari search screen

What’s in the top-right button position?

It’s the “Cancel” button i.e. the secondary action.

Oh dear. How did that get there?

At first, I thought that I was at fault because I hadn’t properly learned the interface. Then I remembered one of the first observations you make when usability testing. Users blame themselves for the mistakes in the design of the interface.

That the reason I was making the mistake so often was precisely because I had learned the conventions of the user interface.

So what can we do?

The interface needs a subtle redesign. Nothing major, just an increment to correct the problem.

There are 2 options that immediately spring to mind

Option 1: Move the Cancel button to the top-left “secondary action” position

This should be really easy. The basic premise of the current design is left intact and the secondary action is returned to the correct place in the interface – the top-left position.

Option 2: Add a “Search” button in the top-right position and move the Cancel button to the top-left “secondary action” position.

We’ve got an additional button now, but it’s consistent with the overall design of the other apps you produce.

I know you’re really busy right now, especially with all the activity around the iPad, but please fit this into the next version of the OS. It is such a minor UI change, but would markedly improve the way the browser search interface works.

Best of luck with iPhone OS 4.0. I hope you bundle some of these ideas, but don’t worry too much about Flash.

David

P.S. If you can’t manage this for me, then I’d be happy to settle for Opera Mini being approved in the App Store instead – I quite like the idea of being able to browse 6 times faster than Safari.

Image credit: UK stamp

I recently started building Confluence plugins. The first one being my Google Analytics plugin for Confluence. This post outlines my “journey” into Confluence plugin development. It documents a beginner’s pitfalls when developing with the Atlassian Plugin SDK. Hopefully others can learn from, or at least laugh at my mistakes.

Where I was starting from:

• No experience of maven
• No understanding of how Confluence plugins work or how they are written
• Some experience of Java – Mainly uPortal/Luminis portal development for the University of Nottingham and some consultancy work e.g. for Astra Zeneca, Documentum and 3Com
• No experience of unit testing or integration testing in Java – oh dear
• I prefer UI work to real programming

Initial failure

I tried to setup a development environment for plugin development using Atlassian’s documentation a little before the beta release of version 3 of the Atlassian Plugin SDK. It was a pain. This was no fault of the documentation — it was really just to do with my schedules and available time to experiment.

The problem was two-fold:

1. I’d not done this before, so was clueless to what was involved
2. The setup was a complete ball-ache considering the time restraints

I was well aware of point 1 and the pain it was likely to cause. Point 2 seemed to be the old chestnut – install and configure the exact correct versions of the software you need in the correct sequence, then start.

Wait. I don’t know what that means, see point 1. Yes, I’ve got maven installed on my MacBook! Woo! Let’s go. Hang on, it’s not the correct version. Where do I get that from?

In many ways, it reminded me of my initial experience of building and installing Apache 1.x on Solaris SPARC boxes back in the day:

cd /path/to/apache/source; make; make install;
Oh. Wrong version of make. Where do I get that from? Hmmm.
Install correct version of make. Damn, make needs the correct version of gcc. Where do I get that from?
And so on. Moving further and further away from the problem you’re trying to solve.

So, I stopped there. No shiny Confluence plugins for me. I’ve got plenty of other things to do anyway thank you very much.

Reboot

Then Atlassian released the Plugin SDK beta and all this nastiness was removed. Everything you need to build an Atlassian plugin was bundled in one place. Refreshing. All commands have been wrapped and so are prefixed with atlas- to prevent conflict with whatever else you’ve got installed.

For the impatient, this really drives down the barriers to entry for plugin development.

Following the documentation for installing the Plugin SDK was a piece of cake. It just worked.

• Download
• Unzip
• Add some environment settings. Edit ~/.profile and add:

  PATH=$PATH:.
  PATH=$PATH:$HOME/
  PATH=$PATH:$HOME/bin
  PATH=$PATH:$HOME/atlassian-plugin-sdk/atlassian-plugin-sdk-3.0-beta3
  PATH=$PATH:$HOME/atlassian-plugin-sdk/atlassian-plugin-sdk-3.0-beta3/bin
  export PATH
  

• Start building a plugin

Starting out to build your Atlassian plugin is documented here. It’s a fairly straightforward set of instructions.

You start by doing something like this:

mkdir ~/projects/davidsimpson.me/
mkdir ~/projects/davidsimpson.me/confluence
cd  ~/projects/davidsimpson.me/confluence

atlas-create-confluence-plugin
...
...
...
When prompted
Define value for groupId: : me.davdsimpson.confluence.plugins
Define value for artifactId: : googleanalytics
Define value for version:  1.0-SNAPSHOT: :
Define value for package:  me.davdsimpson.confluence.plugins: :
Confirm properties configuration:
groupId: me.davdsimpson.confluence.plugins
artifactId: googleanalytics
version: 1.0-SNAPSHOT
package: me.davdsimpson.confluence.plugins

Then type…

cd googleanalytics
atlas-run

…and sit back. If maven doesn’t fall over for lack of memory at this point, you’re laughing. Go away, have a beer or two. This may take some time.

On your return, maven will hopefully have finished dragging all manner of nonsense from Australia and installed a working copy of Confluence, together with an empty plugin onto your computer. Nice. Next, write some code.

I like to run before I can walk. It seems like much more fun to attempt something that’s harder. You do fall over a lot more often though. So rather than some kind of silly little hello world or equivalent plugin, my first plugin was an integration of Google Analytics with Confluence using the Google Analytics API to fetch data from Google. It requires some additional JARs from Google.

Google doesn’t have a public maven repository to my knowledge and I’d no idea how to get these JARs added into maven. Luckily, people had already written about parts of this, so I put 2 and 2 together.

Add Google Analytics JARs to maven:

atlas-mvn install:install-file -DgroupId=com.google.gdata \
    -DartifactId=gdata-core \
    -Dversion=1.0 \
    -Dpackaging=jar \
    -Dfile=/path/to/gdata-core-1.0.jar \
    -DgeneratePom=true

atlas-mvn install:install-file -DgroupId=com.google.gdata \
    -DartifactId=gdata-analytics \
    -Dversion=2.0 \
    -Dpackaging=jar \
    -Dfile=/path/to/gdata-analytics-2.0.jar \
    -DgeneratePom=true

atlas-mvn install:install-file -DgroupId=com.google.collect \
    -DartifactId=google-collect \
    -Dversion=1.0 \
    -Dpackaging=jar \
    -Dfile=/path/to/google-collect-1.0-rc3.jar

Edit the Project Object Model (POM) to add the dependencies

Edit the pom:

vi ~/projects/davidsimpson.me/confluence/googleanalytics/pom.xml

Add this bit to the end of the dependencies node:

<!-- Add Google Analytics dependencies: -->
   <dependency>
       <groupId>com.google.gdata</groupId>
       <artifactId>gdata-core</artifactId>
       <version>1.0</version>
   </dependency>
   <dependency>
       <groupId>com.google.gdata</groupId>
       <artifactId>gdata-analytics</artifactId>
       <version>2.0</version>
   </dependency>
<dependency>
	<groupId>com.google.collect</groupId>
	<artifactId>google-collect</artifactId>
	<version>1.0</version>
</dependency>

Next, fire up your IDE

My chosen IDE is IntelliJ IDEA.

• Open the pom.xml in IntelliJ IDEA (File | Open project)
• Override/set the maven home directory:

  /Users/davidsimpson/atlassian-plugin-sdk-3.0-beta3/apache-maven

• Set the JDK for build as 1.5 or 1.6
• Start editing the plugin

Hiccups

It’s not all straightforward. Here’s some of the annoyances that I came across.

Maven needs more memory

I needed more memory for maven. Not really a problem – append to ~/.profile:

MAVEN_OPTS=-Xmx512m
export MAVEN_OPTS

Annoying warnings on atlas-run

I noticed this on running atlas-run – it probably shouldn’t be there:

[WARNING] Using platform encoding (MacRoman actually) to copy filtered resources, i.e. build is platform dependent!

Of course, someone has already blogged about it — Red Leopard — and it’s easily fixed by editing the POM to add the correct encoding.

<properties>
    <confluence.version>3.0.2</confluence.version>
    <confluence.data.version>3.0</confluence.data.version>

    <!-- Fix for MacRoman warnings on build -->
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>

Now, we have no nasty warnings.

The macro browser icon

I love the Macro Browser in Confluence. It’s a nice step forward in the evolution of the UI. So as a result, I wanted my macro to have a shiny icon in the macro browser. That damn Macro Browser icon ate up several hours of my life. Looking at the comments on the documentation page, several other people have had a whole load of fun getting their pretty icon to show up too.

The macro browser icon: What we're aiming for

Could I get the Macro Browser to show my plugin’s icon. No. I followed the documentation. It did not work. I looked again. This time I really paid attention. Was it my fat fingers? Was I just being stupid? (Probably.) I ignored this for a while — maybe it would be better after a night’s sleep.

Everything seemed to work a whole lot better when I dropped the beta and moved to version 3.0.2 of the Plugin SDK.
Note: I had to update my ~/.profile to point to the new version of the SDK and update the references to maven in Intelli-J at this point.

I also followed a different tack on getting the macro browser icon to work

• Find a macro that has a custom icon in the macro browser
• Go to the Atlassian public subversion repository and browse to the source for that macro plugin.
• Copy the exact syntax from the atlassian-plugin.xml and paste into your macro’s own atlassian-plugin.xml
• Name the icon exactly the same as in the atlassian-plugin.xml and put it in the correct place in the directory structure

I’m not entirely sure whether it was the copy and paste approach that helped or moving away from the beta. It works now, so I’m not going to loose sleep on why.

Adding a configuring UI to the plugin

My plugin needed to store Google account credentials and display a list of Google Analytics sites, so you can choose the correct profile. How do you do that? Hmmm. Go back to the documentation. It wasn’t nearly detailed enough for my liking, so time to vent a little.

Again, it seemed the best way to learn was to find a plugin that has a similar kind of configuration to that you’re hoping for and start appropriating the code.

Unit testing and integration testing

This is a good idea. Period. Did I have a clue how to do it for Confluence? Of course not.

Again, the community helped out. Atlassian partners at Adaptavist, Comala Technology and Customware have written about this:

• Integration Testing of Confluence Plugins by Bo Wang
• Unit testing a Confluence Action by Edward Robertshaw
• Unit testing a Confluence Macro by Edward Robertshaw
• Confluence plugin integration testing by Roberto Dominguez

Browsing around the Atlassian public subversion repository was also a help. I’ve got to say that I’m an easy convert to testing. It just makes sense.

Update (2010-05-04): A nice feature of the SDK is running or testing your plugin against different versions of the product. This is straightforward:

# Integration tests for different versions
atlas-integration-test -v 3.0
atlas-integration-test -v 3.1
atlas-integration-test -v 3.2
# Run different versions of Confluence
atlas-run -v 3.0
atlas-run -v 3.1
atlas-run -v 3.2

Wrapping up

After a good deal of stumbling around, it turns out that I can write a Confluence plugin after all. Everything started working a lot better after I updated from the beta version, but that could just be coincidence. The documentation could be a little better to help the uninitiated but it was equally my fault for not learning to walk first. There is a lot of good information, but it is spread over a few different spaces.

My next step was to get the plugin added to Atlassian Plugin Exchange. It took a little while to get this done — maybe that’s best saved for a follow up post. The plugin is now available on Atlassian Plugin Exchange. I hope other people get some use out of it.

I’m pleased to announce the release of my first Confluence plugin — Google Analytics plugin for Confluence.

It lists Google Analytics reports for a particular Confluence space – from within that space. The current version has 10 reports and shows the first 20 results for each report.

• Top Content
• Depth of Visit
• Internal Search
• Browser and OS
• Browser Version
• Screen Resolution
• Network
• City
• All Traffic Sources
• Search Engine Keywords

Just before Christmas, Atlassian quietly approved the plugin on their Plugin Exchange website. Since then, Matt Hodges posted a great write up about it on the Atlassian website — Report Confluence Activity Using Google Analytics in the Wiki.

Screencasts and live demonstrations

I’ve done a couple of screencast demos on usage and configuration:

But better than that, it’s now out in the wild and you can try it for yourself on other people’s sites:

• Atlassian have installed it on their Confluence Sandbox
• Arne Schirmacher has posted a live demo on his Confluence site
• Another live demo on my personal Confluence space (using 1.2-SNAPSHOT)

What next?

• Download Google Analytics plugin for Confluence
• Setup Google Analytics on your Confluence site

If you’re using this plugin or have tried it out, I’d really like to know what you think of it.

• What improvements would you like made?
• What reports are missing?
• Where could the UI could be improved?

Please post a comment if you’ve got it installed.

Thanks

I’d like to thank the Confluence community for their help mainly via Atlassian Forums and some Atlassians for helping me out when I got stuck – particularly Shaun Hare, Keith Brophy, Jonathan Nolen and David Peterson.

Image credit: Google Analytics icon

Outlined are some thoughts behind reusable UI elements in the Luminis portal at the University of Nottingham.