The categories
Confluence add-ons have different behaviour based on how they are loaded by Confluence. The add-ons themselves are the same, but based on how they are loaded, they may or may not be upgraded, or may not be disabled, or may not be uninstalled. This chart should explain how plugins can be loaded by Confluence, and the ramifications for each choice.
The category any particular add-on is in can vary with Confluence version or circumstance. The examples mentioned here describe the way particular add-ons are loaded by default in Confluence 2.8.
The information on this page does not apply to Confluence OnDemand.
Category | Description | Example |
---|---|---|
Static | cannot be installed or upgraded without a Confluence restart |
|
Core | Included with Confluence and cannot be uninstalled. The classes and plugin.xml are not bundled into add-on distribution JAR files, but are mixed in with Confluence source on the main classpath. Additionally, the plugin.xml definitions are not called "atlassian-plugin.xml" as they are everywhere else, but are named for the add-on, e.g., "basic-macros.xml". We would like to separate some of them out and turn them into Bundled add-ons. | Admin Sections |
WEB-INF/lib | Confluence also places some add-on JAR files inside WEB-INF/lib. They are inserted during the build process by Maven. These add-ons, likewise, cannot be uninstalled. In ancient times, this was the only way to install add-ons, so users were also free to install add-ons here. We now discourage this installation method, however. As of version 3.0, most of the JAR files in this directory are library dependencies, not add-on files. |
|
Dynamic | the opposite of static, these can be installed/upgraded while Confluence is running |
|
Bundled | Bundled add-ons can be administered from the Manage Add-ons page in the application's Administration Console. You can upload or disable them there. Bundled add-ons are included in a ZIP archive of JAR files called atlassian-bundled-plugins.zip, which is on the main Confluence classpath, in a resources directory - | Office Connector |
Uploaded | Installed by the user via the plugin repository or the Universal Plugin Manager. These add-ons are stored in the database and then copied to the $CONFLUENCE_HOME/plugins-cache folder on each Confluence node. | could be anything |
To summarise the relationships of categories in the table, all add-ons are either Static or Dynamic. Static add-ons can be further categorised into Core or WEB-INF/lib. Dynamic add-ons are divided into Bundled and Uploaded.
Use of the categories in Confluence
Within Confluence, the Core and WEB-INF/lib categories are not actually named as such, and they don't map neatly to other names (though they do map, as will be explained). They are used here because of the logical distinction they provide.
In Confluence, some of the Core add-ons are called "System Add-ons". Add-ons can be designated as "System" by adding a flag to the add-on manifest file. To do this, system=true
should be added to the top-level atlassian-plugin
element of the manifest file. The manifest file is generally called atlassian-plugin.xml
, but it could have another name; the Core add-on files do.
All the Core add-ons were once labeled "System", but the convention has faded over time. If an add-on is designated as "System", it cannot be enabled/disabled in the Manage Add-ons page. However, it will show up in the Plugin Repository Client, where it can be disabled; allowing disabling there is probably incorrect behavior.
Static add-ons that are not marked as "System" (any remaining Core and WEB-INF/lib plugins), are simply called Static in Confluence. There is no way to tell the WEB-INF/lib and Core add-ons apart from within Confluence. You just have to figure out where the classes are.
Members of the other specific categories—Bundled and Uploaded—can be determined. We can tell which add-ons are Bundled and which add-ons are Uploaded, so we know which add-ons are Uploaded though this specific term is never used in the Confluence UI. Instead, they are called Dynamic.
Updating add-on versions
- Core add-ons cannot be upgraded.
- WEB-INF/lib add-ons can be upgraded by replacing the JAR in WEB-INF/lib and restarting Confluence.
- Bundled add-ons can be upgraded using the Universal Plugin Manager or from the Plugin Repository Client. A new add-on JAR is uploaded and stored as an Uploaded add-on. Confluence compares the version number with the Bundled add-on and uses the newer.
- Uploaded add-ons are upgradable using the Universal Plugin Manager or from the Plugin Repository Client. When a new add-on JAR file is uploaded, the previous version is discarded from the database and the
$CONFLUENCE_HOME/plugin-cache
directory.