Metadata Plugin

Name	Metadata Plugin 2
Vendor	Andy Armstrong
Authors	Andy Armstrong, Kelsey Grant
Homepage	http://confluence.atlassian.com/display/CONFEXT/Metadata+Plugin
Issue Management	http://developer.atlassian.com/jira/browse/META
Continuous Integration	n/a
Categories	Content Macros
Most Recent Version	2.1.0
Availability	Confluence v2.7 to v2.10
State	Stable
Support
License	Freeware / Open Source (BSD)
Price	Free
Release Docs	http://confluence.atlassian.com/display/CONFEXT/Metadata+Plugin
Java API Docs	n/a
Download Source	http://svn.atlassian.com/svn/public/contrib/confluence/metadata-plugin/tags/2.1
Download JAR	metadata-2.1.0.jar

This plugin now accessible through the Confluence Repository Client.

This documentation has not yet been updated for version 2.0. The new features are described as part of the Codegeist submission.

This extension won an honorable mention in Atlassian's Codegeist competition for 2006.

Description/Features

This plugin allows the user to attach metadata to any page in Confluence and to then generate reports and statistics using it.
The largest problem that we've had using Confluence at Pantero is that information has to be replicated on multiple pages. For example, it is extremely common to repeat information from a number of pages onto a summary page. The children and contentbylabel macros allow a page to reference a set of related other pages, but these summaries are restricted to just a link to the page and optionally an excerpt. I found myself instead manually building these summary tables but they quickly get out of date.

I strongly believe that data should only live in one place and that other pages that need to show the same information should reference the data rather than copy it. I decided to write a plugin that makes it easy to reference snippets of data from one page on other pages. The Metadata Plugin can generate these summary tables automatically to contain as many columns of metadata per page as make sense. In fact, multiple pages can now present the same list but with more or less detail as appropriate. See the examples for more details.

In some ways, what I've implemented is a glorified 'excerpt' macro. Instead of there being just a single magic excerpt, though, the user can create as many pieces of metadata as they like. There are two basic macros for adding metadata to a page:

1. metadata - lets the user add a single piece of metadata
2. metadata-list - allows the user to enter a number of values at once
   The remainder of the macros are provided to present metadata data on other pages. The simplest of these, metadata-from, shows a single metadata value from a specified page. The more interesting macros are those that aggregate data from a number of sources to dynamically build up tabular reports, dashboards, charts and other useful statistics. In some ways these macros treat Confluence like one giant Excel spreadsheet where data can be gathered from anywhere and presented.

In addition to the report macros, the Metadata Plugin provides two other ways to access the metadata. Firstly, all metadata is indexed and can be searched by keyword. Secondly, an experimental remote API has been provided so that the metadata can be accessed by other applications.

Usage

The plugin provides the following new macros:

metadata macro

The basic macro lets you attach a single piece of metadata to a page.

{metadata:Author}[~andy.armstrong]{metadata}

would render simply as:

Andy Armstrong

but would also attach "Author" as a piece of metadata to the page. Note that the metadata is stored as unrendered Wiki markup, so in this case the value "[~andy.armstrong]" is stored for the "Author" metadata. The reporting macros then render the markup into the page they are used on. This usually works very well because links, emoticons etc can be used.

If you don't want the metadata on the page you can use the "hidden" parameter.

{metadata:Author|hidden=true}[~andy.armstrong]{metadata}

metadata-list macro

This macro allows the user to attach multiple pieces of metadata to a page with one macro. The main purpose of this is to make it allow a user to add metadata more concisely and to make the Wiki markup easier to read.

The following usage:

{metadata-list}
|| Name              | Metadata Plugin |
|| Version           | 1.0 |
|| Product Versions  | Confluence 2.x |
|| Author(s)         | Andy Armstrong |
{metadata-list}

adds four pieces of metadata to the page, as well as rendering the following output:

An optional orientation=horizontal parameter changes the rendering to be horizontal. It will then render as follows:

metadata-from macro

This is the simplest macro to get a piece of metadata from another page onto the current one.

The Metadata Plugin was written by {metadata-from:Metadata Plugin|Author}.

would pull the 'Author' metadata from the 'Metadata Plugin' page and hence would show as:

The Metadata Plugin was written by Andy Armstrong.

The Metadata Plugin was written by {metadata-from:Author}.

pulls the 'Author' metadata from the current page.

metadata-report macro

This macro shows metadata from matching pages in a tabular report. By default it shows the children of the current page, but it has an optional label attribute to match all pages with the specified label.

The basic format is:

{metadata-report:Page,Author(s),Version}

would then show the following table (assuming two children):

To show a table of all pages with the 'codegeist' label you can instead use:

{metadata-report:Page,Author(s),Version|label=codegeist}

Note that "Page" is an 'internal' metadata keyword that produces a link to the page in question. Internal keywords have lower priority than explicit metadata values but are provided for convenience. See the list of internal metadata for more details.

The report can provide totals for certain columns using the totals argument. Say that each entry had a number of lines of code stored under "LOC", then this would show the totals:

{metadata-report:Page,Author(s),Version,LOC|label=codegeist|totals=LOC}

Finally, the macro allows the report to be sorted in different orders. The default ordering is by page, but a sort=XXX parameter can be specified.

{metadata-report:Page,Author(s),Version,LOC|label=codegeist|totals=LOC|sort=LOC desc}

metadata-calculate macro

This macro returns a single value by totalling up any float or integer metadata. This result can be shown directly or can be used as input to another statistics macro.

The simplest example is to include a single total on the page.

We have {metadata-calculate:Days Remaining} days remaining.

which then shows as:

We have 800 days remaining.

This macro is more useful to present several totals in a single chart. For example, the following Wiki markup will produce a chart showing the number of days remaining in a set of releases:

{chart:title=Days remaining per release|width=500|height=200|dataOrientation=horizontal}
|| || 2.1 release || 2.2 release ||
|| Days Remaining
| {metadata-calculate:Days Remaining|label=2_1_release}
| {metadata-calculate:Days Remaining|label=2_2_release} |
{chart}

An optional function argument can be specified to control how the resulting number is calculated. This can be any of the following values:

metadata-matches macro

This macro totals up the number of matching pages which have a particular value for metadata. This result can be shown directly or can be used as input to another statistics macro.

Here's an example bar chart that can be produced by using metadata-matches within a chart macro.

{chart:type=bar|title=Release Status|width=500|height=200|orientation=horizontal}
|| || Tasks ||
|| Delayed | {metadata-matches:Status}Delayed{metadata-matches} |
|| In Progress | {metadata-matches:Status}In Progress{metadata-matches} |
|| Complete | {metadata-matches:Status}Complete{metadata-matches} |
|| Not Started | {metadata-matches:Status}Not Started{metadata-matches} |
{chart}

You can also see the same metadata in a pie chart:

{chart:title=Release Status|width=500|height=200}
|| || Delayed || In Progress || Complete || Not Started ||
|| Issues | {metadata-matches:Status}Delayed{metadata-matches}
 | {metadata-matches:Status}In Progress{metadata-matches}
 | {metadata-matches:Status}Complete{metadata-matches}
 | {metadata-matches:Status}Not Started{metadata-matches} |
{chart}

In addition, this macro allows for another metadata value to be calculated for each matching page. The following syntax will total up all of the days remaining on features for which I am assigned:

{metadata-matches:Owner|labels=2_2_new_feature|value-name=Days Remaining}
[Andy Armstrong]{metadata-matches}

By default this sums the values, but the same function parameter can be used as with metadata-calculate.

Using this mechanism you can produce bar charts showing how a particular value is broken down. Currently this is very manual so a new metadata-chart macro is currently being considered. In the interim this manual code:

{chart:type=bar|title=2.2 Release Load Balancing|orientation=horizontal}
|| || Andy Armstrong || David Dahan || Esther Jesurum || John Avery || Maya Dahan ||
|| Days Remaining
 | {metadata-matches:Owner|labels=2_2_new_feature|value-name=Days Remaining}
[Andy Armstrong]{metadata-matches}
 | {metadata-matches:Owner|labels=2_2_new_feature|value-name=Days Remaining}
[David Dahan]{metadata-matches}
 | {metadata-matches:Owner|labels=2_2_new_feature|value-name=Days Remaining}
[Esther Jesurum]{metadata-matches}
 | {metadata-matches:Owner|labels=2_2_new_feature|value-name=Days Remaining}
[John Avery]{metadata-matches}
 | {metadata-matches:Owner|labels=2_2_new_feature|value-name=Days Remaining}
[Maya Dahan]{metadata-matches} |
{chart}

produces the following chart:

Macro keywords

The following is a summary of all the keywords supported by the Metadata Plugin macros:

Metadata search

The Metadata Plugin provides a search extractor that will add each piece of metadata to the Confluence index. For example, you can make the query:

Author:Andy

which will return all pages that contain "Andy" in their author metadata. You can then combine this with other search syntax to do sub-searches.

Remote API

New in version 1.3 a prototype remote API has been implemented. Currently just one method has been provided:

/**
 * Returns all of the metadata values attached to the specified page.
 * @param token The token identifying the current user.
 * @param spaceKey The key of the space that the page belongs to.
 * @param pageName The name of the page.
 * @return An array of MetadataValue objects.
 * @throws RemoteException if the page cannot be found.
 */
MetadataValue[] getMetadataValues(String token, String spaceKey, String pageName) throws RemoteException;

MetadataValue is a simple bean that provides 'name' and 'value'.

This API has been exposed as secure XML-RPC and SOAP services. See the Confluence Remote API Specification for examples of using such a service.

Examples

Pantero uses the Metadata Plugin in a number of ways to make its Wiki content more dynamic. Some examples include:

There are all sorts of other kinds of structured data that could be usefully aggregated with the right combination of labels and metadata. Here are some we are considering:

• status reports
• meeting notes
• online documentation
• FAQs, tips and tricks, best practices etc
• sales leads

Version History

Screenshots

Screenshots
Test plan report generated from metadata	This shows Pantero's overall release status page which is entirely generated from metadata.	This shows metadata recorded for a particular release page.
This shows simple load balancing charts generated from metadata.

Issues/Ideas

This section describes some of the issues that arise using this plugin.

Metadata templates

• Kelsey's Idea for metadata templates

How can I access non-metadata in my reports?

All the macros support certain built-in metadata names for internal data structure:

It is straightforward to add more so let me know what else you'd like to see.

Why wouldn't I use JIRA for this kind of data?

This is a good question and is a best practice that we're trying to develop as happy users of both JIRA and Confluence. JIRA is excellent for issue tracking because of its formal semantics and its clear workflow model. Confluence is better for ad-hoc data because metadata can be attached to a page and then used in reports without any administrative changes. Confluence also works better for living documentation due to its Wiki nature (attaching images, designing the look of the page etc).

Shouldn't project planning be done in Microsoft Project (or equivalent)?

For large or formal projects a real project planning tool is probably a good idea. For small startups that already have Confluence (like Pantero) it is preferable to have a looser project plan that is more tightly integrated with technical documentation, proposals, meeting notes etc.

Reported issues

Here is the list of open issues reported against the Metadata Plugin. Please feel free to report bugs or propose improvements.