Install/update/remove Extensions in/from the wiki

Description

This application provides an UI to manage the extensions within a wiki. It is build on top of the Extension Module and is accessible from the XWiki administration. Extensions are mainly XARs (e.g. XWiki applications, wiki macros) and JARs (server side code including especially components and script services).

Searching for an Extension

XWiki uses by default the following extension repositories:

• The xwiki.org Extensions Repository
• The XWiki Public Nexus Maven Repository

You can register more repositories, following the Extension Module documentation. You can even create your own XWiki extension repository using the Extension Repository Application. The Search UI will take all the registered repositories into account.

There are two ways to search for a extension.

Simple Search

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:

• Available extensions: from all registered repositories, except the Maven based repositories like XWiki Public Nexus Maven Repository or your local Maven repository. For these you'll have to use the Advanced Search.
• 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; most of them are jars packed within the XWiki WAR.

Advanced Search

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.

Extension Display

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.

Description

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.

Supporters and Support Plans

Rating

EM is capable of displaying ratings for each extension.

Dependencies

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)

Changes

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. 

There's a summary displayed, 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.

It's also possible to quickly revert the changes made to a document.

To get the "Changes" tab you first need to click the action menu (the arrow next to the default action, for example the arrow to the right of "Uninstall") and then select "Compute Changes". Once this is done you'll see a new "Changes" tab appearing as on the next screenshot.

Progress Log

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.

Extension Actions

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.

Install

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). 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 instance. 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 Description 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.

The UI only proposes what is allowed by the extension. For example if the extension indicates that it was only to be installed on the root namespace, only "On Farm" will be proposed.

Compute Changes

You can compute the changes made to the wiki pages of an installed extension. The transitive dependencies are taken into account automatically.

Upgrade

You can upgrade installed extensions but not core extensions. Core extensions are upgraded by upgrading the XWiki WAR.

Similar to the install action, the upgrade has two steps: the creation of the upgrade plan and the actual upgrade.

Conflict resolution

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 diff module. In the near future we hope to allow you to edit the merge.

Users who requested it in their profile get a chance to configure the automatic conflict resolution behavior before the install (tell Extension Manager to ask for everything, tell it to always use new version no matter what, etc..).

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.

Downgrade

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.

Uninstall

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.

Repair

When an extension is invalid Extension Manager can try to repair it.

Extension Updater

The Extension Manager Application has a section that lists the available extension updates. This will help you keep all your extensions up to date.

Automatically check for new versions of the server

The server can check if a new version of its distribution is available.

The version check can be enabled through the parameter extension.versioncheck.environment.enabled in xwiki.properties.

Extension History

The Extension Manager Application has a 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 the Administration Application is 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 the Extension Manager to 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). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

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:

1. Log in the wiki with a user having Administration rights
2. Go to the Administration page and select the Import category
3. Follow the on-screen instructions to upload the downloaded XAR
4. Click on the uploaded XAR and follow the instructions
5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-extension-ui 16.9.0):

• org.xwiki.platform:xwiki-platform-extension-script 16.9.0
• org.xwiki.platform:xwiki-platform-extension-index 16.9.0