Confluence Repository Client

Name	Atlassian Plugin Repository
Vendor	Adaptavist.com Ltd (Website)
Authors	Dan Hardiker
Homepage	http://confluence.atlassian.com/display/CONFEXT/Confluence+Repository+Client
Issue Management	http://developer.atlassian.com/jira/browse/APR
Categories	Administration
Version	2.0.15
Availability	Confluence v2.9-m5 to v2.9-m5
State	Stable
Support
License	Freeware / Open Source (3-Clause BSD)
Price	Free
Release Docs	http://confluence.atlassian.com/display/CONFEXT/Confluence+Repository+Client
Java API Docs	n/a
Download Source	http://svn.atlassian.com/svn/public/contrib/repository/atlassian-plugin-repository/tags/atlassian-plugin-repository-2.0.15
Download JAR	atlassian-plugin-repository-confluence-plugin-2.0.15.jar

Compatibility With Confluence

Plugin Version	2.4.5	2.5.8	2.6.2	2.7.3	2.8.0	Tested
2.0.8						David Chui (Oct/19/2007)
2.0.12						Jonathan Nolen (Dec/4/2007)
2.0.13						David Chui (Apr/15/2008)
2.0.14 1						David Chui (Jul/10/2008)

¹ – Will only be compatible with Confluence 2.9 onwards.

Description

Display all available plugins from the Atlassian Plugin Repository in Confluence and install, upgrade or delete them with one click. The Confluence Repository Client is pre-installed on Confluence 2.3 and newer, and a recommended install for older Confluence versions. The confluence repository client provides an intuitive interface for plugin browsing, installation, upgrading and uninstallation within the Administration Console.
Plugins in the repository are easier to audit because you can get answers to the common questions through a single interface:

• Where did it come from?
• Who made it?
• What license is it under?
• What version am I using?

The Plugin Repository contains detailed information about each plugin, allowing the repository client interface to clearly indicate which versions of which plugins are compatible with the specific version of Confluence you have installed.

Install Instructions

If you're using Confluence 2.3 or later, the Plugin Repository Client is already installed. If you choose to reinstall it, reinstall it through the upload on the plugin manager. If you're using Confluence 2.2, you can install a previous version of the Plugin Repository Client using the Confluence's default plugin manager.

To access the Repository Client prior to Confluence 2.2 go to the plugin manager and then manually alter the URL in your web browser from: http://www.example.com/admin/plugins.action to http://www.mysite.com/admin/repository/plugins.action.

If your server uses a proxy to access the internet then you must configure web proxy support if you have not done so already.

Features

The repository client contains four tabs:

• Available Plugins - this lists all available plugins and allows you to get additional information about each one, install, upgrade and uninstall, etc.
• Upload - this allows you to upload a plugin either using HTTP Upload (like the Plugin Manager) or by providing a URL to fetch.
• Preferences - This tab allows users to set view preferences.
• Admin - this tab allows admins to set the URL to the plugin repository and set some default filters (for example, only show stable plugins)

Available Plugins

The plugins list is the main interface for locating, installing and upgrading plugins:

Along the top of the page, you'll see three items (from left to right):

• Status filter (defaults to "All Plugins"):
  • Set to "Installed Plugins" to list plugins which have been installed
  • Set to "Outdated Plugins" to list installed plugins for which updates are available
  • Set to "Available Plugins" to list plugins which are available, but have not yet been installed
• Search - quickly find what you're looking for:
  • Quickly locate plugins by searching on their title, description, vendor and other details. Just type what you are looking for and let Confluence do the rest
  • The search results are filtered by the status filter (as discussed above), so if you want to see all installed plugins from Adaptavist.com, for example, set the filter to "Installed Plugins", enter "Adaptavist.com" in to the search box and click the search button.
• Categories list - filter by category:
  • Simply choose the desired category from the list and only plugins relating to that category will be displayed.
  • Note that plugins can exist in more than one category to make them easier to find

Under the filter options, the list of plugins matching the current filter settings is shown in a table:

• Plugin Name
  • Displays the name of the plugin (linked to the detailed information page), the plugin vendor (linked to their website if applicable)
  • Click the icon to expand the information display showing plugin description, click the icon to hide it again.
• Payment - can be one of the following:
  • Free (self explanitory)
  • Donate (it's free, but you should consider donating to keep it that way)
  • Buy (it's commercial - click the link to show a price list and purchase online)
• Status - shows the current status of this plugin in respect to your Confluence installation:
  • Installed - installed and up-to-date
  • Outdated - installed, but there are new versions available
  • Available - not installed yet
  • Non Repository - a version is installed which is not in the repository
• Install - Install, upgrade or unistall a plugin
  • Install, upgrade, uninstall
  • When installing or upgrading, everything is automatic (ie. it downloads and installs for you, etc). Although the client (since 1.0.2) warns you of dependancies and (since 1.0.3) will do its best to check what has been downloaded is what you asked for - Confluence may break as if you had uploaded the plugins to the Plugin Manger yourself. Where it can, the client will error constructively allowing you to choose the best course of action for yourself. In general, things usually work - and if they don't its a bug with the client or the metadata.
  • If the Confluence Repository Clientencounters a password request when downloading the plugin (usually case with Commercial plugins), you will be prompted for a username and password.
  • If the plugin is installed into WEB-INF (or otherwise uninstallable) it will display "Manually Installed" where the actions would be.
• Enabled - if the box is ticked, the plugin is enabled, otherwise it's either disabled or partially disabled. You can enable or disable individual modules within the plugin from the plugin details screen (see later)

NB: You can click the table headings to sort the table. Click a second time to reverse the sort - those familiar with JIRA will know the drill.

Upload

There are several plugins that are not currently listed by the plugin repository which need to be manually uploaded either as a file or from a remote server URL:

Preferences

Admin

There are various settings on the "Configure" tab as shown below:

The most important of these is the "Repository Path URL" setting - without this, you'll see no plugins in the list and will get a fair amount of errors.
The *"Earliest Development State"*allows you to filter the plugin list to versions at or above a specific state: Alpha, Beta, Prerelease, Stable. By default "Prerelease" versions are shown. If you are running in a production environment, you will usually want to set this setting to "Prerelease" or "Stable".
The "Only Show Plugins Confimed as Working" setting allows you to restrict the list to only show plugin versions that are specifically known to work with your version of Confluence. It's important to note that in many cases, plugins will work with your version of Confluence but they might be marked as "unknown" compatibility if the plugin author hasn't been able to test with that specific Confluence version. As such, it's extremely useful if you find an "unknown" version of a plugin to work (or not work) with your Confluence that you let us know (by any means possible) so that we can update the repository to reflect this.
The "Hide Empty Categories" setting allows you to trim down the categories list by hiding categories that don't contain a plugin yet.

The "Automatically Refresh Cached Data" setting allows you select the interval at which the cached repository data will be looked up again. This defaults to 1 hour but is selectable from 5 minutes to Never (the latter which is what versions prior to 1.1 will be fixed to).

Plugin Details

When you click the name of a plugin on the plugin list, you'll be taken to the detailed view for that plugin:

General information and plugin module details are shown at the top of the display and from here you can disable or enable individual modules.
Near the bottom of the display a table clearly outlines all versions and shows which you have installed. Just like the plugins list, you can click the to expand the details shown for a specific version. This screen also allows you to quickly install, upgrade, downgrade and uninstall any version of the plugin.

Macros

These macros are available to Confluence instances ("clients") that have the Confluence Atlassian Plugin Repository v.2.0.13+ installed and configured to talk to a server that provides data about plugins.

{repository-plugin}

Displays rendered information from the metadata in the repository.

Parameter	Required	Values	Default	Notes
key	yes	plugin key, such as com.atlassian.confluence.extra.rsvp	(none)	The plugin to display data about.
profile	no	the key of one of the profiles configured locally	default	This profile will be used to get plugin data.
outputType	no	overview-table, version-grid, description	overview-table	Format of the macro output.
suppressHeader	no	true, false	false	Whether or not to include a header with the output. Only applies when outputType is version-grid or description.

{recentlyupdated-plugins}

Displays an ordered list of the plugins with the most recently released versions, according to the plugin metadata.

Parameter	Required	Values	Default	Notes
product	no	a name of a product that plugins can be written for and stored in the repository (in our case confluence or jira)	(all products)	Allows restricting results to those plugins for a particular product.
count	no	integer	10	Number of result plugins to return.
mode	no	table, list	table	Indicates the form in which to display the results

{popular-plugins}

Displays an ordered list of the most popular plugins. The popularity of a plugin is based on number of downloads of the plugin jar that have been recorded on the server.

Parameter	Required	Values	Default	Notes
product	no	a name of a product that plugins can be written for and stored in the repository (in our case confluence or jira)	(all products)	Allows restricting results to those plugins for a particular product.
count	no	integer	10	Number of result plugins to return.
range	no	one of two formats: year, month, week, or day an integer followed by y, m, w, or d (e.g. 6w)	month	The length of time from which to consider plugin downloads: one of the unit given, e.g. one month from the start or end date given integer number of units given (always goes back in time from today), e.g. 6w or -6w means the past six weeks
rangeStart	no	date in the form yyyy-MM-dd	depends on range and rangeEnd	Cannot be used with the second form of the range parameter.
rangeEnd	no	date in the form yyyy-MM-dd	today's date (if rangeStart is not given)	Cannot be used with the second form of the range parameter.
mode	no	table, list	table	Indicates the form in which to display the results

{download-stat}

Provides statistics about the number of downloads for each plugin.

Parameter	Required	Values	Default	Notes
product	no	a name of a product that plugins can be written for and stored in the repository (in our case confluence or jira)	(all plugins)	Allows restricting results to those plugins for a particular product. If both product and key are specified, then key will be ignored.
key	no	plugin key, such as com.atlassian.confluence.extra.rsvp	(all plugins)	Allows restricting results to those for a particular plugin. If both product and key are specified, then key will be ignored.
version	no	build number of the plugin specified by key	(all versions)	Allows restricting results to those for a particular version of a plugin. Can only be used if a plugin key (and not a product name) is provided.
range	no	one of two formats: year, month, week, or day an integer followed by y, m, w, or d (e.g. 6w)	month	The length of time from which to consider plugin downloads: one of the unit given, e.g. one month from the start or end date given integer number of units given (always goes back in time from today), e.g. 6w or -6w means the past six weeks
rangeStart	no	date in the form yyyy-MM-dd	depends on range and rangeEnd	Cannot be used with the second form of the range parameter.
rangeEnd	no	date in the form yyyy-MM-dd	today's date (if rangeStart is not given)	Cannot be used with the second form of the range parameter.
increment	no	monthly, daily, yearly, weekly, total	daily	Size of the chunks of hits to return.
format	no	compact, full	full	Will be ignored unless increment equals total. In the compact mode, only the number of hits will be displayed. In the full mode, the number of hits are displayed in a table with the date range; the table is similar to other result tables displayed by the download-stat macro.

{confluence-status}

Displays the update status of Confluence.

Parameter	Required	Values	Default	Notes
update-only	no	true, false	false	If true, a result will only be shown if updates are required.
profile	no	the key of one of the profiles configured locally	default

{plugin-status}

Displays a list of plugins that need to be updated. Currently, this macro has a bug where it will cause a Confluence system error if someone who is not logged in tries to view it.

Parameter	Required	Values	Default	Notes
update-only	no	true, false	false	If true, a result will only be shown if updates are required.
profile	no	the key of one of the profiles configured locally	default	This profile will be used to get plugin data.

{plugin-repository}

Displays the table of plugin information that by default only appears in the admin section. Info that non-admins should not see is hidden from them.

Parameter	Required	Values	Default	Notes
profileKey	no	the key of one of the profiles configured locally	default	This profile will be used to get plugin data.

Release History

Version	Date	Author	Notes
1.0	11-Mar-2006	Adaptavist.com Ltd	Initial Version
1.0.1	12-Mar-2006	Adaptavist.com Ltd	CRC-1 Increased pre-Java5 compatabillity
1.0.2	12-Mar-2006	Adaptavist.com Ltd	CRC-2 Removed Uninstall link from Plugin Details page on Older/Newer versions as it was misleading Fixed some further pre-Java5 issues which affected Velocity templates which failed silently causing misrendering of License and Payment information. Added better handling of plugins installed manually into WEB-INF (actions are removed)
1.0.3	16-Mar-2006	Adaptavist.com Ltd	Better error handling Self-updating Wiki-markup in fields
1.1	18-Mar-2006	Adaptavist.com Ltd	Proxy support Auto-refreshing Unknown Confluence version handling
1.2	26-May-2006	Adaptavist.com Ltd	You can now Enable / Disable / Configure supported plugins and their modules. Much better error handling. File Upload and Manual URL Installation (see the new Upload tab) Added a new Debug tab so that you can test your proxy settings. Security & other bug fixes.
1.3.1	01-Feb-2007	Christopher Owen
2.0	13-Feb-2007	Adaptavist.com Ltd

Troubleshooting the Confluence Plugin Repository