Extension Manager Application
|Install/update/remove Extensions in/from the wiki|
|License||GNU Lesser General Public License 2.1|
Table of contents
This application provides an UI to manage the extensions within a wiki. It is build on top of theand is accessible from the . Extensions are mainly XARs (e.g. , ) and JARs (server side code including especially and ).
Searching for an Extension
XWiki uses by default the following extension repositories:
You can register more repositories, following the. You can even create your own XWiki extension repository using the . The Search UI will take all the registered repositories into account.
There are two ways to search for a extension.
The search bar has an input where you can type keywords and a drop down list where you can select the type of extension to search for.
You can search through:
- All extensions: from all registered repositories, except the Maven based repositories like or your local Maven repository. For these you'll have to use the .
- Installed extensions
- Local extensions: these are cached extensions; whenever you install an extension it is cached locally and remains cached after you uninstall it; you'll notice that local extensions include all installed extensions
- Core extensions: these are extensions bundled with XWiki Enterprise; most of them are jars packed within the XWiki Enterprise war.
If you know the id and the version of an extension you can use the advanced search form. The id of a Maven extension is created like this: groupId:artifactId. Note that the advanced search looks in all the registered repositories, ignoring the simple search filters.
The extension display shows you the extension title, version, status, authors and summary and it allows you to perform some actions on the extension.
You can find more about an extension by clicking on the "Show details" button.
The description tab provides various information like the extension license and repository. The extension id can be used with the advanced search. The feature information represents either old identifiers that the extension had or identifiers of extensions that are repackaged/bundled by this one. The extension type is currently one of XAR or JAR. And you can also retrieve the list of stable versions.
Since version 6.4, EM is capable of displaying ratings for each extension.
An extension can have dependencies. The dependency tab lists both upstream and downstream direct dependencies.
You can see the status of a dependency and follow the link to get more information (e.g. determine transitive dependencies). The dependency status is also color coded:
- green for installed and core dependencies
- yellow when a different version is installed or provided
- red when the dependency version is not compatible with the current state of the wiki (e.g. an older version is provided)
Starting with 7.0RC1 you can view the local changes that have been made to the wiki pages of an installed extension and its transitive dependencies. This can help you review your customizations to a XAR extension before doing an upgrade. In 7.1M1 we added a summary that can help you navigate the changes. For each document we display the previous and the next version. The previous version (left) is the id of the extension that provides the document (it can be a transitive dependency). The next version (right) is the version of the document from the database at the moment when the diff was computed. Changes are grouped in 4 categories: Page properties (title, parent, syntax, content, etc.), Attachments, Objects and Class properties.
The progress log tab shows information about the action that is currently performed on the extension or the last action that was performed. You can see for instance what happened when an extension has been installed.
Depending on the type of an extension, you can perform the following actions. Note that the system will currently perform only one action at any time. You can click install on more extensions but they will be put in a queue and installed one after another. This is true for all users, meaning that if an user is upgrading an extension and a different user wants to install another extension, the install job will be put in a queue and executed after the upgrade triggered by the first user is done.
Also, it is important to understand that actions are performed asynchronously. After you trigger and action you can close your browser and the process will continue to run on the server. When you reopen the browser and go back to the extension you'll either see the action still running (if it's a long process) or see its progress log.
If an extension is not already installed then you should be able to install it. Of course, you can't install a core extension because it is already available (core extension are bundled with XWiki Enterprise). The installation process has two main steps:
- the creation of the install plan: the extension manager will collect all the transitive dependencies of the extension you want to install and will determine if they all are compatible with the current state of your XWiki Enterprise. This step fails when the first incompatibility is encountered (e.g. if one of the dependencies is a newer version of a core extension). You cannot continue the installation on this version of the extension if this step fails. You can, however, go through the list of Stable Versions from the tab and find a compatible extension if it exists.
- the actual install: the extension manager will download all the transitive dependencies and will install them.
From the main wiki of a wiki farm you also have the option to install an extension on all the wikis.
Since 8.1 the UI will only propose what is allowed by the extension. For example if the extension indicate that it was only be installed root namespace, only "On Farm" will be proposed.
Starting with XWiki 7.0RC1 you can compute the changes made to the wiki pages of an installed extension. The transitive dependencies are taken into account automatically.
You can upgrade installed extensions but not core extensions. Core extensions are upgraded by upgrading the XWiki Enterprise war.
Similar to the install action, the upgrade has two steps: the creation of the upgrade plan and the actual upgrade.
When you upgrade a XAR extension and the extension manager fails to automatically merge your changes with the changes from the new version of the extension the extension manager will guide you to resolve the conflict. Notice that the upgrade log had been collapsed to leave more space for the merge conflict. You can expand it back by clicking on its label.
Currently you can choose which version to keep between:
- the previous version that was installed
- the current version with your changes
- the next version that you want to upgrade to
- the merged version, what the extension manager has managed to automatically merge between the current version and the next version.
In case there are many merge conflicts you can choose to automatically resolve all of them in the same way. The version you select for the current merge conflict will be used for all the following merge conflicts. So if you choose to keep the merged version for the current merge conflict then all the remaining merge conflicts will be resolved by keeping the merged version also (whatever that may be).
In order to help you choose the right action when a merge conflict occurs we let you compare the aforementioned versions.
Changes are displayed in the same way they are when you compare two versions from a document's history. Diffs are computed and displayed with the help of the. In the near future we hope to allow you to edit the merge.
Delete Unused Wiki Pages
Some wiki pages may not be needed any more after an upgrade, either because they were deleted in the new version of the XAR extension or becaue they were renamed. The Extension Manager asks you to confirm the removal of these unused wiki pages at the end of the upgrade process. You can select which pages to delete or keep. Note that the pages you have modified are not selected by default to prevent you from loosing your changes by mistake. You can rollback the deletion later if need be by going to the recycle bin.
You can install an older version of an extension even if a newer version is currently installed. Core extensions cannot be downgraded. In order to downgrade an extension you need to either search for one of its older versions using the advanced search or to search for the extension, click on the "List stable versions" button and then click on an older version number.
Installed extensions can be uninstalled. Core extensions cannot be uninstalled.
Delete Unused Wiki Pages
At the end of the uninstall process, if the extension being removed is a XAR extension (e.g. a wiki application, a wiki macro), you have to confirm the deletion of the extension's wiki pages. You can select which pages to keep and which pages to delete. The pages that have been modified are not selected by default so that those changes are not lost by mistake. You can rollback the deletion later from the recycle bin, if need be.
When an extension is invalid Extension Manager can try to repair it.
Starting with version 5.0 the Extension Manager Application has a new section that lists the available extension updates. This will help you keep all your extensions up to date.
Starting with version 7.1 the Extension Manager Application has a new section that shows the history of the extension-related actions (e.g. install, uninstall, repair, etc.) offering support for selective export, import and replay of history records. This basically means that an administrator can
- keep track of the extensions that are installed/uninstalled on his wiki (see who performed the action and when, in reverse chronological order, most recent first)
- perform a couple of actions (e.g. install/upgrade a group of extensions) on a single wiki and then replay those actions on multiple wikis
If theis not installed or not yet upgraded then you can access the new Extension History section using an URL like the following (the query string is important):
Prerequisites & Installation Instructions
We recommend using theto install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- org.xwiki.platform:xwiki-platform-extension-script 8.2.1