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 accordion menu on the left, click on "Extensions" and then:

  • again on "Extensions" in order to:
    • search for XWiki recommended extensions
    • install extensions
    • browse the installed extensions
    • see the list of extensions that make the XWiki core
  • on "History" to access the track of the extension-related actions or reuse the recorded upgrade decisions made with Distribution Wizard
  • on "Updater" to check for updates for the installed extensions

ExtensionManagerAdminMenu.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 in the main wiki, click on "Extensions" -> "Extensions" in the preferences page. You may browse through the list of available extensions by typing the extension name or a keyword in the text input and hitting Enter or clicking the magnifying glass button. 

There are 4 extension categories:

  • local extensions which are cached locally and remain cached even after uninstalling them; by default they include the extensions bundled with the standard XWiki distribution
  • installed extensions - in this category are the local extensions and the ones installed by users
  • core extensions
  • remote extensions published on http://extensions.xwiki.org

NewExtensionsDropDown.png

The Extension Manager displays only recommended remote extensions by default. In case no recommended extension is found for the provided search, you can browse the entire xwiki.org Extensions repository by clicking the "All Extensions" button and entering a keyword in the text input.

The ratings are displayed in read-only mode, so in order to rate an extension you need to access the XWiki Extensions Repository.

RecommendedExtensions.png

Let's take the Google Apps Application extension - by clicking on "Show Details" then on the "Description" tab 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. In case you are interested in what the source code looks like, click the "Sources" link which redirects to the corresponding GitHub repository. 

ExtensionDetails.png

The "Dependencies" tab lists extensions or packages you have to install in order for the current one to function correctly. In the case the the App Within Minutes application, you will notice that some dependencies 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".

IncompatibleExtension.png

Supposing you want to install the version 8.1.2 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.

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 on the "Home" namespace.

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.

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

Default Conflict Answer

When installing XAR extensions, you might get conflicts that are mostly caused by changes made locally to extension pages. In such cases, Extension Manager will try to choose the safest way to workaround the conflict but, provided you have enabled the extension conflict setup in the user preferences page, you will see a "Default Conflict Answer" screen in the install log allowing you to change the default behavior.

DefaultConflictAnswer.png

The "Successful Merge" option dictates how will Extension Manager handle a merge without conflict:

  • prompt the user and ask what to to
  • keep the document already found in the wiki
  • perform an automatic merge
  • install the document found in the new extension version
  • install the document found in the previous version of the extension

Similarly, the "Failing Merge" option lets you choose what will Extension Manager do in case of a merge conflict.

SucessfulMerge.pngFailingMerge.png

It is also possible that there is a local modified version of the extension in the wiki but with no previous version available. This is when the "Current Already Exist" option proves to be useful, because you can tell Extension Manager to:

  • prompt you and ask you what to do
  • keep the document already found in the wiki
  • install the document found in the new extension version

CurrentAlreadyExists.png

Finally, if an extension page exists in the previous version of the extension but that same page was deleted from the wiki, you may tell Extension Manager to:

  • prompt you and ask you what to do
  • keep the wiki situation as it is
  • install the document found in the new extension version
  • install the document found in the previous version of the extension

CurrentDeleted.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 "All Extensions" and search for the one you wish 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" in the drop-down list next to the search button. You will then see the recently installed 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 "Rose Anderson").

InstalledExtensions.png

If the extension has only been installed on the main wiki and then on individual sub-wikis, you will see an "Installed on the following namespaces:" message in the "Description" tab. Just like in the previous case, 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 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.

Start by accessing the Extension Manager's "Extensions" tab, select "All Extensions" or "Recommended Extensions" in the drop-down list and search for the extension you wish to upgrade. 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

Merge Conflict

When downgrading or updating an extension, the Extension Manager compares the original UI package with the current UI in the wiki, as well as the changes introduced between the original UI package and the new UI package and tries to merge those changes to produce a resulting document. In case of conflict, it provides 3 possible actions:

  • install the merged version
  • install the new version of the document which means the previous changes will be discarded
  • keep the current version 

MergeConflictOptions.png

Some changes that could trigger a conflict include:

  • A new page has been added to the wiki which is also a part of the new UI
  • A new feature or an improvement has been added to the wiki 
  • The page is a configuration page part of the UI, the default configuration has been changed in the wiki and the new UI has new default value for the same settings
  • The access right of a page from the UI has been changed in the wiki and the new UI has different default rights for the same page 

To help you choose an action, Extension Manager provides a diff for:

  • the previous version which is in fact the original version of the page in the old UI package
  • the current version of the page in the wiki
  • the new version of the page in the new UI package
  • the merged version - the version computed by the Extension Manager, containing a merge of local changes and the new UI changes

AvailableDiffs.png

The "Summary" displays the type of entity that was modified - "Object", "Page property" (content, default language etc.) and so on - 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.

DiffDetails.png

It is possible for the Extension Manager to not display the original version of the page. This usually happens when:

  • the page is new in the new version UI but it also exists locally in the wiki
  • the package of the original UI has not been repaired properly

The additional option "Resolve automatically"  you to resolve all the remaining merge conflicts automatically by choosing the same option as the one you select in the "Merge Conflict" drop-down list.

If necessary, you might be prompted to delete extension pages found in the wiki that have been removed from the new version because they have become obsolete.

DeleteOldPages.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".

Supposing you have installed the version 8.1.3 of the FAQ Application and you want to install version 8.1, go to the Extension Manager's "Extensions" tab and click on "Advanced search". Fill in the 2 text-boxes like in the image below, then click on "Search". 

SearchOlderMacroVersion.png

You will be then notified that the version 8.1.3 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.1" under "Stable versions".

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.3) and the new one (8.1). You might also be prompted to delete unused pages. 

Uninstall an Extension

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 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 Standard and they are available in the Extension Manager's "Extensions" tab if you select "Core extensions" in the drop-down list, then click the search button. Note that you cannot 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 Standard WAR.

CoreExtensions.png

The Extension Updater

The "Extensions" -> "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 "Extensions" -> "History" in the accordion menu from the wiki administration page.

ExtensionManagerHistory.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 "XWiki Standard Flavor" extension for the main wiki and the "XWiki Standard Flavor - Sub Wiki" extension on an sub-wiki. Additionally, you will see a record of each extension you upgraded with the Distribution Wizard. 

Main Wiki
ExtensionHistory.png
Sub-Wiki
ExtensionHistory2.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 revert a particular update, simply click the "Reset" button.

To replay the record, go back to the "History" screen, select an extension 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 Standard 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