Confluence Community Management Dashboard

Posted on 20 February, 2012 by Andrew Frayling

Here’s a simple guide to putting together a “Community Management” dashboard in Confluence to help keep track of content in a particular space to see when users last logged in, which pages may be in need of updating, which content was recently updated, etc.

For this dashboard I use 5 macros:

Last Login – custom user macro which I blogged about previously
Recently Updated
Old pages – custom user macro which I blogged about previously
Popular Labels
Contributors Summary

Layout the page as shown below with:

1 x Section
2 x Columns inside the Section, each 50% width
2 x Panels inside the first Column with the first Panel containing the Last Login Macro and the second panel containing the Recently Updated Macro
3 x Panels inside the second column with the first Panel containing the Old Pages Macro, the second Panel containing the Popular Labels Macro and the third Panel containing the Contributors Summary Macro

Macro Parameters

Last Login

No Parameters

Old Pages

Number of Days – 7

Popular Labels

Number of Labels to Display – 100
Restrict Labels to this Space Key – <Space Key>, e.g. TEST
Style of Labels – heatmap

Contributors Summary

Group By – Contributors
Columns to Display - edits,comments,labels,watches
Sort By – Edits
Space(s) - <Space Key>, e.g. TEST

Other Useful Plugins

I hope you find this useful for keeping track of content in your Confluence wiki and if you have any other tips or suggestions for how you keep track of content as a Community Manager, or know of any other useful content tracking plugins I would love to hear about them via the comments.

Adding Menu Items to JIRA

Posted on 18 February, 2012 by Andrew Frayling

The question “How do I add links to Confluence / My Website / My Blog / etc. to JIRA’s main navigation?” has been asked a few times over on Atlassian Answers so I thought I’d blog the solution I usually use, which is to create a simple plugin.

Plugin development can be a scary thought, but the Atlassian make things really easy and all you’ll need for this plugin is the Atlassian SDK and your favourite text editor.

Download and Install the Atlassian SDK

Download the Atlassian SDK and follow the installation instructions. For this plugin there’s no need to configure the SDK to work with an IDE as you can just use your favourite text editor, though for more advanced plugins it is definitely worth using an IDE.

Create the Plugin Skeleton

After installing the SDK run the following command to launch the interactive prompt to create the plugin skeleton:

atlas-create-jira-plugin

At the prompts enter the following information:

Create a plugin for?: 2 – Regular ‘ol JIRA 4 (or earlier)
Define value for groupId: com.<your company domain>.jira.plugins
Define value for artifactId: jira-menu-items
Define value for version: 1.0
Define value for package: com.<your company domain>.jira.plugins
Confirm values: Y

NB: for groupId and package substitute <your company domain> with the relevant value, e.g. com.networkedcollaboration.jira.plugins.

After entering the above values you should see:

[INFO] ------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------
[INFO] Total time: 3 minutes 13 seconds
[INFO] Finished at: Sat Feb 18 14:04:15 GMT 2012
[INFO] Final Memory: 35M/107M
[INFO] ------------------------------------------

and the SDK will have created a directory called “jira-menu-items” containing all of the necessary plugin files in the directory where you ran the “atlas-create-jira-plugin” command.

If the plugin skeleton fails to build check the Troubleshooting and FAQ documentation.

Test the Plugin Skeleton

Following a successful build it’s a good idea to check that the plugin skeleton deploys and installs correctly before adding your specific plugin functionality.

Change to the “jira-menu-items” directory and type:

atlas-run

It may take a while to run the first time as Maven downloads all of the project dependencies, but after a while you should see:

[INFO] [talledLocalContainer] Tomcat 6.x started on port [2990]
[INFO] jira started successfully in 140s at http://Andrew-Fraylings-MacBook-Pro.local:2990/jira
[INFO] Type Ctrl-D to shutdown gracefully
[INFO] Type Ctrl-C to exit

Visit http://localhost:2990/jira in a web browser, log in with admin/admin, select Administration -> Plugins -> Plugins and you should see:

Again, if you encounter any problems visit the Troubleshooting and FAQ documentation.

Adding Menu Items to the Plugin

Now that the skeleton plugin has been tested to ensure that it is all working correctly it’s time to add your details to the plugin meta data and actually add the menu items that you wish to include.

Open the jira-menu-items/pom.xml file and find the section that looks like:

<organization>
  <name>Example Company</name>
  <url>http://www.example.com/</url>
</organization>

change the <name> and <url> to reflect your details, e.g.:

<organization>
  <name>Networked Collaboration</name>
  <url>http://www.networkedcollaboration.com/</url>
</organization>

Also update the <description>:

<description>This is the com.networkedcollaboration.jira.plugins:jira-menu-items plugin for Atlassian JIRA.</description>

to provide a meaningful description for the plugin, e.g.

<description>This plugin adds a new top level JIRA navigation menu with links to the Networked Collaboration website, blog and wiki.</description>

Save the jira-menu-items/pom.xml file.

Next we need to add the plugin modules that will provide the actual menu items, which for this plugin are a Web Section and Web Items. Open the jira-menu-items/src/main/resources/atlassian-plugin.xml file in your favourite text editor and you’ll see it’s pre-populated with:

<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.name}" plugins-version="2">
  <plugin-info>
    <description>${project.description}</description>
    <version>${project.version}</version>
  <vendor name="${project.organization.name}" url="${project.organization.url}" />
  </plugin-info>
</atlassian-plugin>

After the closing </plugin-info> element, but before the closing </atlassian-plugin> element we need to add a <web-section>:

<web-section key="my-links-section" name="My Links Main Section" location="my-links-link" weight="10" />

Following the <web-section> item we add a <web-item> to define the top-level menu item:

<web-item key="my-links-link"
    name="Links on My Links Main Section"
    section="system.top.navigation.bar"
    weight="47">
  <label>Networked Collaboration</label>
  <link linkId="my-links-link">http://www.networkedcollaboration.com/</link>
</web-item>

The section=”system.top.navigation.bar” attribute defines that the menu item should be placed in the navigation bar, for details of all allowed locations see the Locations section of the Web Fragment documentation.

Following this top level menu item we add three more links for website, blog and wiki repectively:

<web-item key="website-link"
  name="Networked Collaboration Website"
  section="my-links-link/my-links-section"
  weight="10">
  <label>Website</label>
  <link linkId="website-link">http://www.networkedcollaboration.com/</link>
</web-item>

<web-item key="blog-link"
  name="Networked Collaboration Blog"
  section="my-links-link/my-links-section"
  weight="20">
  <label>Blog</label>
  <link linkId="blog-link">http://blog.networkedcollaboration.com/</link>
</web-item>

<web-item key="confluence-link"
  name="Networked Collaboration Wiki"
  section="my-links-link/my-links-section"
  weight="30">
  <label>Wiki</label>
  <link linkId="wiki-link">http://wiki.networkedcollaboration.com/</link>
</web-item>

Your complete atlassian-plugin.xml file should now resemble the following:

<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.name}" plugins-version="2">
  <plugin-info>
    <description>${project.description}</description>
    <version>${project.version}</version>
    <vendor name="${project.organization.name}" url="${project.organization.url}" />
 </plugin-info>

 <web-section key="my-links-section" name="My Links Main Section" location="my-links-link" weight="10" />

 <web-item key="my-links-link"
   name="Links on My Links Main Section"
   section="system.top.navigation.bar"
   weight="47">
  <label>Networked Collaboration</label>
  <link linkId="my-links-link">http://www.networkedcollaboration.com/</link>
 </web-item>

 <web-item key="website-link"
   name="Networked Collaboration Website"
   section="my-links-link/my-links-section"
   weight="10">
  <label>Website</label>
  <link linkId="website-link">http://www.networkedcollaboration.com/</link>
 </web-item>

 <web-item key="blog-link"
   name="Networked Collaboration Blog"
   section="my-links-link/my-links-section"
   weight="20">
  <label>Blog</label>
  <link linkId="blog-link">http://blog.networkedcollaboration.com/</link>
 </web-item>

 <web-item key="confluence-link"
   name="Networked Collaboration Wiki"
   section="my-links-link/my-links-section"
   weight="30">
  <label>Wiki</label>
  <link linkId="wiki-link">http://wiki.networkedcollaboration.com/</link>
 </web-item>
</atlassian-plugin>

Save the jira-menu-items/src/main/resources/atlassian-plugin.xml

Reload the Plugin to Test Changes

Now that we’ve added the relevant menu items to the plugin we need to reload it to test the changes and make sure everything is working correctly. With Atlassian’s FastDev this is really easy, just visit http://localhost:2990/jira/plugins/servlet/fastdev in your browser and hold <SHIFT> + Refresh to reload the plugin and after a few seconds you should see:

After the plugin as been successfully reloaded visit http://localhost:2990/jira and you should see:

Success

Bonus Points

The above solution adds the menu items for all users whether they are authenticated or not. If you want to restrict the menu items so that only authenticated users can see them you can do this by adding the following line to the first <web-item> in jira-menu-items/src/main/resources/atlassian-plugin.xml :

<condition class="com.atlassian.jira.plugin.webfragment.conditions.UserLoggedInCondition" />

e.g.

<web-item key="website-link"
   name="Networked Collaboration Website"
   section="my-links-link/my-links-section"
   weight="10">
  <condition class="com.atlassian.jira.plugin.webfragment.conditions.UserLoggedInCondition" />
  <label>Website</label>
  <link linkId="website-link">http://www.networkedcollaboration.com/</link>
</web-item>

Save the jira-menu-items/src/main/resources/atlassian-plugin.xml file again, reload the plugin by visiting http://localhost:2990/jira/plugins/servlet/fastdev and holding <SHIFT> + Refresh and now anonymous users will not see the extra menu items:

For details of all of the permissions that are available for you to restrict menu items see the API documentation.

Packaging the Plugin

When you’re happy that you’ve included all the links and permissions that you wish and have tested that everything is working correctly you’re ready to package the plugin so that it can be installed on your live JIRA server. To do this just change to the “jira-menu-items” directory and type the following command:

atlas-package

After a short wait you should then see:

[INFO] -------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] -------------------------------------------
[INFO] Total time: 41 seconds
[INFO] Finished at: Sat Feb 18 16:47:22 GMT 2012
[INFO] Final Memory: 66M/123M
[INFO] -------------------------------------------

and there will be a jira-menu-items-1.0.jar file in the jira-menu-items/target/ directory which you can deploy via Administration -> Plugins -> Plugins -> Install.

Confluence Last Login User Macro

Posted on 11 February, 2012 by Andrew Frayling

If you need to keep track of when users have last accessed Confluence here’s a handy user macro for producing a list of the last login dates of users who have access to a Confluence space.

To create the macro:

1. Login in to Confluence as a Confluence Administrator
2. Select Browse -> Confluence Admin
3. Select User Macros -> Create a new user macro
4. Enter the information as provided below:

Template:

## Macro title: Last Login
## Macro has a body: N
## Body processing: Selected body processing option
## Output: Selected output option
##
## Developed by: Andrew Frayling
## Date created: 11/02/2012
## Installed by: <your name>
## Macro to display the last login date of users who have access to the current space
## @noparams

#set($containerManagerClass = $content.class.forName('com.atlassian.spring.container.ContainerManager'))
#set($getInstanceMethod = $containerManagerClass.getDeclaredMethod('getInstance',null))
#set($containerManager = $getInstanceMethod.invoke(null,null))
#set($containerContext = $containerManager.containerContext)
#set($loginManager = $containerContext.getComponent('loginManager'))
#set($users = $userAccessor.getUsers())

<table class="confluenceTable">
  <tr>
    <th class="confluenceTh">User</th>
    <th class="confluenceTh">Last Successful Login</th>
  </tr>

#foreach($user in $users)
  ## list the last login date of users who can view the current space
  #if ($permissionHelper.canView($user, $space))
    <tr>
      <td class="confluenceTd">#usernameLink($user.name)</td>
    #if (!$loginManager.getLoginInfo($user).lastSuccessfulLoginDate)
      <td class="confluenceTd" style="background-color:#ff0000"><strong>NEVER</strong></td>
    #else
      <td class="confluenceTd">$action.dateFormatter.formatDateTime($loginManager.getLoginInfo($user).lastSuccessfulLoginDate)</td>
    #end
    </tr>
  #end
#end
</table>

You can then use the following macro when editing a page:

{lastlogin}

or select the macro from the Macro Browser:

With thanks to Sandro Herrmann from Communardo and Remo Siegwart from bitvoodoo for their answers to “How can I show the page permissions in the page itself?” and “Macro that produces a list of users’ last login date?” over at Atlassian Answers for the inspiration.

Tracking Old Pages in Confluence

Posted on 6 February, 2012 by Andrew Frayling

In order to keep track of content in Confluence, and maybe give page authors a bit of a friendly nudge to update pages , here’s how to create a simple user macro that lists pages in a Confluence space that have not been updated for a while.

1. Login in to Confluence as a Confluence Administrator
2. Select Browse -> Confluence Admin
3. Select User Macros -> Create a new user macro
4. Enter the information as provided below:

Template:

## Macro title: Old Pages
## Macro has a body: Y or N (N)
## Body processing: Selected body processing option
## Output: Selected output option
##
## Developed by: Andrew Frayling
## Date created: 05/02/2012
## Installed by: <your name>

## Macro to display pages that have not been updated for x days
## @param numdays:title=Number of Days|type=int|desc=Enter number of days to compare|required=true|multiple=false|default=7

#set ( $allPagesInSpace = $pageManager.getPages($space, true) )

## default value handler, set default to 7 days
#set ( $numdays = $paramnumdays )
#if(!$numdays)
#set ( $numdays = "7" )
#else
#set ( $numdays = $paramnumdays )
#end

## cast the number of days to an Integer
#set ( $Integer = 0 )
#set ( $intnumdays = $Integer.parseInt($numdays) )

## negative sign the number of days
#set ( $negativeDays = (-1 * $intnumdays) )

## get a calendar object so we can calculate the
## date we wish to compare with the page modification date
## e.g. $compareDate.add(6, -7) for pages modified over a week ago
#set ( $compareDate = $action.dateFormatter.getCalendar() )
$compareDate.setTime($content.getCurrentDate())
$compareDate.add(6, $negativeDays)

<p>Pages last updated before <strong>$action.dateFormatter.format($compareDate.getTime())</strong></p>

<table>
<tr>
<th>Page</th><th>Last Updated Date</th><th>Updated By</th>
</tr>

## loop through all the pages in the current space
#foreach($page in $allPagesInSpace)

## get a calendar object and for each page in space set it to last modification date
#set ($pagedate = $action.dateFormatter.getCalendar())
$pagedate.setTime($page.getLastModificationDate())

## only display pages last modified before the compare date
#if ($pagedate.before($compareDate))
<tr>
<td>#contentLink2($page true false)</td>
<td>$action.dateFormatter.format($page.getLastModificationDate())</td>
<td>#usernameLink($page.lastModifierName)</td>
</tr>
#end
#end
## end looping through pages in the current space

</table>

Then on any page in a space you can enter:

{oldpages|numdays=14}

where numdays is the number of days before which the pages in the current space were last modified, or select the macro from Insert -> Other Macros:

which will display a list of pages in the current space that were last modified before the specified number of days:

For something more automated there is the Confluence Archiving Plugin, but for a quick list of pages that might be in need of updating this user macro should do the trick.

Listing Users in a Confluence User Macro

Posted on 6 February, 2012 by Andrew Frayling

If you’re writing a Confluence user macro and need to display a list of links to user profiles there’s a handy Velocity directive you can use which displays a link using the user’s full name and has a nice hover pop-up to display their profile card:

#usernameLink(<username>)

where <username> is the username of the user you wish to link to. Using this in a macro to list all pages in a space and display the page titles with the user that last modified each page:

#set ( $allPagesInSpace = $pageManager.getPages($space, true) )

<ul>
## loop through all the pages in the current space
#foreach($page in $allPagesInSpace)
  <li>#contentLink2($page true false) - #usernameLink($page.lastModifierName)</li>
#end
</ul>

will result in:

As far as I can tell #userLink isn’t documented anywhere and I only found it by looking at the source code of some of the plugins that are bundled with Confluence. Hope this saves someone else some time if you have to do something similar.

Macro Parameters

Last Login

Recently Updated

Old Pages

Popular Labels

Contributors Summary

Other Useful Plugins

Download and Install the Atlassian SDK

Create the Plugin Skeleton

Test the Plugin Skeleton

Adding Menu Items to the Plugin

Reload the Plugin to Test Changes

Bonus Points

Packaging the Plugin

Related Links