Extension Manager Application

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

Description

The Extension Manager allows you to:

  • download extensions from a remote repository to a local repository
  • install, upgrade, downgrade and uninstall any type of extension as long as you have a handler
  • browse the list of 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 about to install is compatible or not with the current XWiki Enterprise instance
  • check whether there are newer versions of the installed extensions
  • access the history of the extension-related actions and replay history records

You can install an extension on the whole farm or only the main wiki. Starting with version 8.0 each feature has its own version which by default is the version of the extension. This can be useful when some embedded extension is not in sync with the extension or in case for some reason a new version of an extension starts from version "1.0".

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. To add more repositories, go to the Extension Module documentation page.

It is also possible to add a constraint on where an extension should be installed (only root namespace etc.). For Maven, you can do it by using the <xwiki.extension.namespaces> custom property. For more details, please refer to this page.

Access the Extension Manager

For an administrator user there are 2 ways of accessing the Extension Manager. The first one is by clicking on "More applications", then on "Install new applications" in the "Applications" panel to the left. 

ExtensionManagerApplicationsPanel.png

The second possibility is by clicking the DrawerMenuIcon.png button to open the drawer menu, then on "Administer Wiki".

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
  • check for updates for the installed extensions
  • access the history of the extension-related actions and reuse the recorded upgrade decisions made with Distribution Wizard

Actions.png

If you wish to install an extension on a specific sub-wiki, you need to access the Extension Manager of that sub-wiki. The steps are the same as for the main wiki.

Install an Extension from the Main Wiki

When using Extension Manager from the main wiki, it is now allowed to install or upgrade an extension which requires upgrading or installing a farm level dependency. Moreover, the wizard automatically prompts to install on farm a new dependency that is indicated as constraint. 

Note that this is still not possible to do from a sub-wiki in the standard UI but any script with Programming Rights can enable the option in the install request. 

To install an extension, go to the Extension Manager home page from the main wiki and click on "Add Extensions". You may browse through the list of available extensions by typing the extension name or a keyword. 

There are 3 extension categories:

  • local extensions which are cached locally and remain cached even after uninstalling them
  • installed extensions (included in the local ones)
  • core extensions

Starting with version 8.3, the Extension Manager displays only recommended extensions by default. This is why you will notice 2 more options in the drop-down list:

  • Recommended Extensions

NewExtensionsDropDown.png

  • All Remote Extensions with a corresponding button that should be used in case no recommended extension is found for the provided search.

AllRemoteExtensions.png

Hit "Enter" to display the results or click the new search button - this one was added in order to improve the user experience, given that in previous versions you had to use the "return" key. Note that the ratings are displayed in Extension Manager in read-only mode - in order to rate an extension you need to access the XWiki Extensions Repository.

SearchExtension.png

More information about each extension is available in the "Description" tab by clicking on "Show Details". 

You will notice some extra information like the group ID, the artifact ID or the list of stable releases that can be downloaded from the configured extension repositories. Also, the "Sources" link redirects to the source code on GitHub. 

ExtensionDetails.png

The "Dependencies" tab lists extensions or packages you have to install in order for the current one to function correctly. For the already provided dependencies, you will notice that some of them are marked as "Provided", whereas others are "Installed as dependency". This differentiation was introduced in order to distinguish between the extensions that have been installed directly by you or by a different user and the ones that have been installed as transitive dependencies.

DependenciesTab.png

If the extension version is incompatible with your wiki instance, you will see a red status message. To find a compatible version, you can either use the Advanced Search or click on the "Description" tab and choose one of the "Stable versions".

Supposing you want to install the version 8.1 of the "FAQ Application", click on "Install" and you will be prompted about the new extension. 

ApplyExtension.png

A very important detail you should take into account is that by clicking on "Install" the extension will only be installed on the main wiki. 

ApplyExtensionMainWiki.png

Should you decide to install it on the sub-wikis too, just click on "Install on Farm". In both cases, click on "Continue" to confirm and start installing the extension. 

ApplyExtensionSubwiki.png

Since the process is asynchronous, you will soon see a progress bar. Also, the install log is progressively displayed in order for the user to receive constant feed-back.

InstallProgressBar.png

Once the progress bar has reached 100%, if you search for the "FAQ Application" in the installed extensions, then click on the "Description" tab, you will see the install log and a message saying the extension was installed globally.

InstallationSuccessful.png

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.

Starting with version 8.1, if an extension is installed only on a sub-wiki, you have the option to install it on the farm directly from the UI.

InstallFarmSubWiki.png

The Advanced Search

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.

AdvancedInstall.png

Click on "Search" to display the results.

ResultsAdvancedSearch.png

If you are not sure about the group ID and the artifact ID, go back to the "Add Extension" section and search for the extension you want to install. Next, click the "Show Details" button and you will find the necessary information in the "Description" tab. Also, the released versions of the extension are available by clicking on the "Stable versions" link.

GroupIDArtifactID.png

Browse the Installed Extensions from the Main Wiki

To see the installed extensions, go to the Extension Manager home page and click on "Installed Extensions". You will then see the FAQ Application listed in the results page with a green "Installed" status.

AllInstalledExtensions.png

If you chose to install the extension on the whole farm, you will see an "Upgrade on Farm" or an "Uninstall from Farm" button and the "Description" tab will display the message "Installed globally", as well as the date and the user who installed it (in this case it is the user "Administrator").

InstalledExtensions.png

If the extension has only been installed on the main wiki, you will only see an "Upgrade" or an "Uninstall" button and an "Installed on the following namespaces:" in the "Description" tab. Moreover, Extension Manager displays the date and the user(s) who installed the extension on each sub-wiki.

InstalledExtensionSubwiki.png

The user and date information is available only for extensions installed or upgraded from version 7.0, whereas extensions that are already installed have this information only if they were installed directly i.e. not as dependency.

For extensions marked as "Invalid" you will notice a "Repair" button due to the fact that starting with version 8.1 the Extension Manager automatically tries to repair any invalid dependency.

RepairExtension.png

Upgrade an Extension

You can only use Extension Manager to upgrade the extensions installed by the user, i.e. not the core extensions. Also, extensions installed on sub-wikis via the main wiki, can only be upgraded from the main wiki.

To upgrade an extension, go to the Extension Manager and click on "Add Extensions". Supposing you have previously installed version 1.5.6 of the Meeting Application, if you search for it again, you will notice an "Upgrade" button. In case you have installed the application on the sub-wikis too, you will see an "Upgrade on Farm" button.

The search results always display the most recent version of the extension which might not be compatible with the current XWiki runtime. To look for a compatible version, you can use the Advanced Search or the list of "Stable versions".

Click the "Upgrade" or the "Upgrade on Farm" button,

UpgradeExtension.png

then on "Continue" and you will be notified about the version to which your extension will be upgraded (1.6 in our case).

UpgradeExtensionSecondStep.png

If you then go to the installed extensions and search for the "Meeting Application", you will see that the new version is now 1.6.

UpgradeFinished.png

To see the differences between the old version (1.5.6) and the new version (1.6), click on "Uninstall from Farm", then on "Compute changes". Note that transitive dependencies are automatically taken into account. A job will be launched in order retrieve the local changes that have been made on the wiki pages of the extension.

ComputeChangesJob.png

Click the "Changes" tab to see more details: the "Summary" diff displays the type of entity that was modified - "Object", "Page property" (content, default language, class properties, attachments etc.) - and the number of elements added, removed or modified. In case there are several entities modified, click on each of them to display more details and to access the list of differences. 

The screen-shot below illustrates the differences between version 6.4.5 and 7.1.2 of the FAQ Application.

ComputeChanges.png

Downgrade an Extension

The Extension Manager comes with a new "Downgrade" feature which is available using the Advanced Search or by choosing the extension version from the list of "Stable Versions".

Extensions installed on sub-wikis via the main wiki, can only be downgraded from the main wiki.

Supposing you have installed the version 8.1 of the FAQ Application and you want to install version 8.0, go to the list of installed extensions and click on "Advanced search". Fill in the 2 text-boxes like in the image below,

SearchOlderMacroVersion.png

then click on "Search". You will be then notified that the version 8.1 of the application is already installed. 

Another possibility is to search for the FAQ Application in the extensions repository, click on the "Description" tab, then finally click on "8.0" under "Stable versions".

DowngradeFromStableVersions.png

Click on "Downgrade" or on "Downgrade on Farm" in case you have installed the application on the sub-wikis too,

DowngradeExtension.png

then on "Continue" to confirm.

ConfirmDowngradeExtension.png

Just just in the case of upgrade, you can use the "Compute Changes" feature to generate a diff between the old version (8.1) and the new one (8.0). You might also be prompted to delete unused pages. 

DeleteUnusedPages.png

Uninstall an Extension

Extensions installed on sub-wikis via the main wiki, can only be uninstalled from the main wiki.

To uninstall an extension, go to the list of installed extensions then click on the corresponding "Uninstall" button or on the "Uninstall from Farm" button in case you have installed the extension on the sub-wikis too. 

UninstallExtension.png

In the "Progress" tab, you will be prompted about the list of packages you are about to remove. Click on "Continue" to confirm.

UninstallProgressBar.png

You will then be prompted about the list of spaces and pages that are about to be deleted. By default all of them are selected, except for the case when there are modified pages. These ones will be left unselected so you won't lose your changes.

UninstallUnusedPages.png

Click on "Continue" to confirm removing all the selected items.

To uninstall the extension only from a specific sub-wiki, follow the same steps, but using the Extension Manager of that sub-wiki.

Search for XWiki Core Extensions

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

CoreExtensions.png

The Extension Updater

The "Extension Updater" section lists available updates for the installed extensions. To begin looking for newer extension versions, click on "Check for updates" or on "Check for updates on farm".

CheckForUpdates.png

ExtensionUpdaterRecompute.png

The "Invalid Extensions" are incompatible with your current distribution and they have compatible new versions; these ones require an upgrade or a downgrade and are marked by a red status bar. The extensions marked by a yellow message still work with your current distribution but there are newer versions available.

To upgrade an extension, click on the corresponding "Upgrade" or "Upgrade on Farm" button and follow the on-screen instructions. In case the displayed information is outdated, just click again on "Check for updates" or on "Check for updates on farm".

ExtensionUpdater.png

Extension History

Extension History is a new feature that records and displays extension-related actions like installing, upgrading, downgrading, repairing and uninstalling. Moreover, administrators can replay them at any time and even export them in order to replay the same decisions on another sub-wiki.

To access the Extension History, click on the link with the same name from the vertical menu in the wiki administration page.

ExtensionManagerAdminMenu.png

The feature is particularly important when performing an upgrade with the Distribution Wizard: in case you have a large number of sub-wikis on your farm and most of them were created from the same template, it is enough to record the merge conflict decisions on one wiki, then to simply replay them on all the others. To learn more, please refer to this link.

Finally, an administrator can keep track of the extension changes on the wiki and thus know at any time who performed an action and when. If you installed or upgraded the wiki with the Distribution Wizard, the Extension History should display a record of the "the "XWiki Enterprise Flavor - Main wiki" extension for the main wiki and the "XWiki Enterprise Flavor - Sub Wiki" extension on an sub-wiki. These are the default sets of pages installed starting with XWiki Enterprise 8.x. Additionally, you will see a record of each extension you upgraded with the Distribution Wizard. 

ExtensionHistory.pngExtensionHistory2.png

If you click on the name of the extension, you will be redirected to its description - to access a detailed diff, click on "Uninstall", then on "Compute changes", as previously explained

ExtensionRecordsDetailsHistory.png

and finally on the "Changes" tab.

ExtensionRecordsDiff.png

To replay the record, just select it from the list, then click on "Replay". Under "Replay Options" you have the possibility to replay the imported records using the wiki's original users, rather than the current user by selecting the "Preserve the users" option.

By default, the "Namespaces" input only contains the domain name of the current wiki, but you can replay the record on multiple wikis at the same time, provided you have Programming Rights. In case there are merge conflicts that don't have an answer for in the recorded history file, then you will be prompted to answer them.

ReplayRecordOptions.png

Click on "Continue", then on "Start" to confirm re-installing the "XWiki Enterprise Flavor - Sub-Wiki" extension. Details about the installed or modified extensions are available in the Replay Log.

ReplayRecordConfirm.png

To replay a history record from another sub-wiki, click on "Showing records from Local History" and upload an XML file from your computer.

UploadHistoryRecords.png

      

Search this space