Extension Manager

This Extension Manager is a feature for installing, uninstalling and upgrading XWiki extensions.

Description

The Extension Manager allows you to:

  • download extensions from a remote repository to a local repository
  • install, upgrade and uninstall any type of extension as long as you have a handler
  • list the installed extensions
  • compare the extension versions
  • see a short description of each extension
  • see the list of dependencies for an extension
  • see if the extension you are willing to install is compatible or not with your current XWiki Enterprise Manager instance

You can install an extension on the whole farm or only on a particular sub-wiki.

At the moment, the Extension Manager supports the following repositories:

In order to be able to install extensions from the XWiki Public Nexus Maven Repository, you can use the Advanced search. If you want to add more repositories, please follow this link.

Access the Extension Manager

If you wish to install an extension on the entire farm, you will need to access the Extension Manager homepage of the main wiki. To do so, click on "Administer Wiki" in the "Wiki" menu located in the top menu bar.

AdministerWikiMenu.png

In the vertical menu to the left, click on "Extension Manager"

ExtensionManagerAdminMenu.png

to see the list of possible actions:

  • add extension
  • see the list of installed extensions
  • see the list of extensions that make the XWiki core

Actions.png

If you wish to install an extension on a specific sub-wiki you can either access its Extension Manager homepage (the steps are the same as for the main wiki) or use the "Advanced search" feature from the main wiki to specify the domain name of the sub-wiki.

Install an Extension from the Main Wiki

To install an extension, go to the Extension Manager and click on "Add Extensions". You may either browse through the list of available extensions by typing the extension name or a keyword or you may limit the results to:

  • local extensions which are cached locally and remain cached after uninstalling
  • installed extensions included by the local extensions
  • core extensions

Hit "Enter" to display the results.

SearchExtension.png

You may search for the extension ID and version by clicking on the "Advanced search" link. The ID of a Maven extension has the following syntax: groupId:artifactId. You may also choose on which sub-wiki to install your extension. Note that you need to fill in the domain name as it appears in the "Wiki Manager" livetable, not the pretty name. You may enter several domain names separated by commas.  

Note that if you don't specify anything, the extension will be installed on all the sub-wikis.

AdvancedInstall.png

In the results page, more information will be available for each extension in the "Description" tab by clicking on "Show Details".

ExtensionDetails.png

In other cases you will see an extra "Dependencies" tab listing the extensions or packages you will have to install in order for the current one to function. For the provided dependencies (i.e the XWiki Core extensions and packages) the extension status bar will be green.

DependenciesTab.png

If the extension version is incompatible with your wiki instance, you will see an yellow status bar and an yellow message announcing you that a newer version is already provided.

IncompatibilityMessage.png

Supposing you want to install the JIRA macro version 1.1, click on "Install" and you will be prompted about the new extension to be installed.

If you specified a particular sub-wiki in the "Advanced search" form, you will see the image below.

ApplyExtensionSubwiki.png

If not, you will get the following screen:

ApplyExtension.png

Click on "Apply" to install the extension. Since the process is now asynchronous, you will see the newly added progress bar.

InstallProgressBar.png

If successful, you will see a confirmation message in the "Progress" tab.

InstallationSuccessful.png

If you search again for the JIRA macro, you will notice an yellow extension status bar to the right  telling you that the version 1.1 is already installed.

InstalledExtension.png

Starting with XWiki Enterprise Manager 4.1, in case the extension job fails, the error message is extracted and displayed so that the user can click on it and access the stack trace.

ExtensionLog.png

See the Installed Extensions from the Main Wiki

To see the installed extensions, go to the Extension Manager and click on "Installed Extensions". You will then see the JIRA macro listed in the results page. Note that the extension status bar is green for the installed extensions. Also, the install plan has been updated to display the extensions just like in the dependency section.

If you chose to install the extension on the whole farm you will get the screen below.

InstalledExtensions.png

If not, you will an image resembling to the one below.

InstalledExtensionSubwiki.png

Upgrade an Extension

You can only use Extension Manager to upgrade the installed extensions. To do so, go to the Extension Manager homepage and click on "Add Extensions". Supposing you have previously installed the 1.1 version of the JIRA macro, if you search for it again, you will notice an "Upgrade" button. 

UpgradeExtension.png

If you click it, you will be notified about the version to which your extension will be upgraded (1.2 in our case).

UpgradeExtensionSecondStep.png

Note that at the moment it is not possible to downgrade an extension.

Merge Conflict Resolution UI

Supposing you have installed a XAR extension on which you have made some changes and you wish to upgrade it. Starting with XWiki Enterprise Manager 4.1, if the Extension Manager fails to automatically merge your changes with the ones from the newer version, it will guide you through the process of resolving the conflict. 

So, if for instance you have modified the version 1.1 of the Jira macro and you wish to upgrade to version 1.2 you will see a diff between the current version and the merged version of the macro in the "Description" tab after clicking on "Upgrade". This includes metadata, content and object changes.

MergeConflictResolutionDefault.png

You can also display a diff between the current version and the newer one or any other combination by clicking on "Show Changes". 

ShowChanges.png

If you choose to keep the merged version of the document (which will override some of your changes) click on "Continue". The other 2 options available in the "Merge Conflict" drop-down list are:

  • Keep only the new version of the document which will override all your previous changes
  • Keep the current version of the document with the mention that the extension might now work properly

MergeConflictDropDown.png

Uninstall an Extension

To uninstall an extension, go to the list of installed extensions then click on the corresponding "Uninstall" button. You will be prompted with the list of packages you are about to remove in the "Progress" tab. Note that the uninstall plan has also been updated to display the extensions just like in the dependency section.

UninstallExtension.png

Click on "Apply" to confirm but note that this will uninstall the extension from the whole farm. Since the uninstall process is now asynchronous, you will also see a progress bar.

UninstallProgressBar.png

If you want this to be done for a specific sub-wiki, you will have to follow the same steps, but via the Extension Manager of the sub-wiki in question.

Search for XWiki Core Extensions

The Core extensions are bundled with XWiki Enterprise Manager and they are available by going to the Extension Manager page and by clicking on "Core extensions". Note that you won't be able to uninstall or upgrade any of the core extensions using the Extension Manager. To upgrade a core extension, you will need to upgrade the XWiki Enterprise Manager WAR.

CoreExtensions.png

Search this space