Distribution Wizard

XWiki Standard comes with the "Distribution Wizard" feature, which is triggered when you first access a wiki page in view mode after an upgrade or a new XWiki Standard installation.

In order for the Distribution Wizard to be triggered, you have to log in as administrator.

The installation guide has 3 steps:

  • the "Admin User" step allows to register your user as the wiki owner.
  • the "Flavor" step allows installing the default set of wiki pages recommended for the current version of the XWiki runtime.
  • the "Extensions" step handles the update of the already installed extensions.

When performing an upgrade, you can either trigger Distribution Wizard from the main wiki and upgrade all the farm or you can trigger it separately from each sub-wiki.

In the case of a clean install, when you first access any wiki page and log in as administrator, you will see an initialization screen. 

InitializeWiki.png

The process will take no more than a few seconds and once it reaches 100%, you will be redirected to Distribution Wizard actions menu:

DistributionWizardUpgrade.png

In case you haven't finished configuring the wiki, click on "Later" and you will be redirected to the wiki page you have accessed in the first place. The Distribution Wizard won't be triggered again unless the server is restarted.

The "Later" button has an additional option, "Replay recorded actions" which allows to replay a recorded upgrade or install performed on a different wiki. Please refer to the Upgrade a Sub-Wiki Using a Recorded Actions File section for more details.

Clicking on "Never" means you will be redirected to the wiki page you have accessed in the first place and the Distribution Wizard won't be triggered again unless you change your distribution. This is usually recommended when you plan to do a manual install. 

Click on "Continue" in order to get to the first step of the process.

Clean Install

Step 1 - Register the Administrator User

This step is displayed only for the WAR distribution and allows you to register your own user as the owner, meaning that you won't ever lose administration rights for that user, unless you change the owner. The reason is to avoid security issues because in older XWiki version we used to have a hardcoded Admin user with the password admin and administrators had to change it explicitly or they would risk anyone being able to connect to their instance.

Note that the main wiki owner now has Programming Rights by default, not only Administration Rights.

AdminUserStep.png

Click on "Register and Login" to create the administrator user, then on "Continue" to begin installing the new wiki.

AdminUserCreated.png

The "Admin user" step is skipped when upgrading your XWiki instance.

Step 2 - Install the User Interface

A flavor is a predefined collection of applications for specific use cases. By default, you will be prompted with 2 standard flavors:

  • the "XWiki Standard Flavor" - a default set of wiki pages containing both content and applications for the Main Wiki
  • the "Demo Flavor" for demonstrating XWiki and featuring several recommended Extensions installed by default

FlavorSelector.png

By clicking on the name of the extension, you are redirected to the documentation page on the xwiki.org Extensions repository. Supposing you wish to install "XWiki Standard Flavor", select it from the list and click on "Install this flavor".

If you then click on "Show Details", then on the "Stable Versions" link in the "Description" tab, you will be able to access all the previously released versions with links to the repository where each one is stored. Also, the "Sources" link points to the xwiki-platform-distribution-flavor-mainwiki source code on GitHub. Finally, the "Issues" link points to the list of known JIRA issues related to the "XWIKI" (XWiki Platform) project.

WARStableVersions.png

Should you decide to import the recommended set of wiki pages on the main wiki, click the "Install" button and the Install Plan Log will prompt you about the new extensions.

InstallPlanLog.png

Click on "Continue" to confirm and the Distribution Wizard will start resolving dependencies and install the extensions. The "Install Log" displays a detailed list of installed pages. 

ComputeInstallPlan.png

When the progress bar reaches 100%, go to the "Dependencies" tab to see the list of installed extensions which are marked by a green status bar then click on "Continue".

Step1Finished.png

Extensions are not marked as "Installed", but as "Installed as dependency". This is useful in order to distinguish between the extensions that have been installed directly (by you or a different user) and the extensions that have been installed as transitive dependencies.

In case you changed your mind, you can always uninstall the extension. The wizard will prompt you with the list of extensions to be removed after which you may click on "Continue" to confirm.

UninstallExtension.png

Farm Upgrade

Install the User Interface

Just like in the case of a clean install, after logging in as administrator, you will be redirected to Distribution Wizard actions menu with the same 3 buttons: "Continue", "Later" with the option to "Replay recorded actions" and "Never".

After clicking on "Continue", then on "Show Details" and on the "Dependencies" tab, the installed applications that are incompatible with the new version of the web application are marked by a red bar. The ones marked by a yellow bar (if any) are the extensions that still work correctly with your current distribution but for which there are newer versions available.

UpgradeStep1.png

Should you decide to download the recommended set of wiki pages on the main wiki, select the "XWiki Standard Flavor" and click the "Install this flavor" button,

UpgradeStandardFlavor.png

then on "Upgrade" so that the Distribution Wizard can start resolving dependencies. All this information is displayed in the Install Plan Log.

InstallPlanLogUpgrade.png

In the "Progress" tab, installed applications that are incompatible with the new version of the WAR are marked by a red bar. The ones marked by a yellow bar are the extensions that still work correctly with your current distribution but for which there are newer versions available. Click on "Continue" to confirm and the Distribution Wizard will start computing the upgrade plan and installing the extensions. 

ConfirmUpgrade.png

The "Install Log" displays a detailed list of installed or upgraded pages.

ComputeUpgradePlan.png

Once the upgrade process starts, there might be some merge conflicts reported. More details are available in the next section.

Finally, you can delete all the old or unused XWiki pages by selecting the "[WikiName]" case(s) and clicking on "Continue". By default, the wiki pages that have been modified are left unselected so that you won't lose your changes.

DeleteUnusedPages.png

When the progress bar has reached 100%, go to the "Dependencies" tab to see the list of installed extensions which are marked by a green status bar then click on "Continue".

UpgradeStep1Finished.png

Merge Conflict

The Distribution Wizard 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. Unless a conflicting change is found, these operations are done transparently.

MergeConflict.png

Some changes that could trigger a conflict include:

  • A new document 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 document is a configuration document 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 document from the UI has been changed in the wiki and the new UI has different default rights for the same document

When a conflict occurs, the Distribution Wizard 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

To help you choose, Distribution Wizard provides a diff for:

  • the previous version which is in fact the original version of the document in the old UI package
  • the current version of the document in the wiki
  • the new version of the document in the new UI package
  • the merged version - the version computed by the Distribution Wizard, 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 Distribution Wizard to not display the original version of the document. This usually happens when:

  • the document 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

Also, it might happen that Distribution Wizard detects conflicts on user and group documents. In these cases, it is recommended to keep the current version, even when the diff does not show any change. As a general rule, when resolving a conflict:

  • XWiki class changes should always be installed
  • Group and User documents should always be preserved

The Distribution Wizard has an additional option, "Resolve automatically", which allows 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.

Upgrade Extensions

In order to upgrade extensions, the steps to follow are the same as for the Extension Updater feature of the Extension Manager application.

ExtensionStep.png

The icons displayed next to each link are meant to differentiate external URLs from internal links.

To begin looking for newer extension versions, click on "Check for updates" or on "Check for updates on farm".

CheckExtensionUpdates.png

The installed extensions are grouped in two categories:

  • 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

    InvalidExtensions.png

  • the "Outdated Extensions" still work with your current distribution but there are newer versions available; these ones are marked by a yellow status bar

    OutdatedExtensions.png

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

Report Step

XWiki has introduced a new last step in which the Distribution Wizard displays all the changes made to the wiki(s) so that you can perform rollbacks.

ReportStep.png

For each sub-wiki, the new pages are marked by the page_white.png icon and the upgraded ones are marked by the page_white_edit.png icon.

The available user options are:

  • delete a new page by clicking the cross.png icon
  • delete an upgraded page by clicking the cross.png icon or undo the changes by clicking the arrow_undo.png icon

AvailableActions.png

Upgrade Sub-Wikis

To upgrade a sub-wiki, login with an administrator account and access any sub-wiki page - similarly to the main wiki, the Distribution Wizard is launched. In order to complete the process, you will have to go through 2 steps:

  • the "Flavor" step allows installing the default set of wiki pages recommended for the current version of the XWiki runtime.
  • the "Extensions" step handles the update of the already installed extensions.

Step2Wikis.png

You now have 2 options: upgrade by clicking on "Continue" or simply replay a recorded plan in order to save time.

For the first case, select "XWiki Standard Flavor - Sub Wiki" in the "Flavor" screen and click on "Install this flavor", 

InstallSubWikiFlavor.png

then on "Upgrade" so that the Distribution Wizard starts computing the upgrade plan.

UpgradeSubWikiFlavor.png

Next, click on "Continue" to confirm and you will notice that just like for the main wiki, previous extensions that are incompatible with your current distribution are marked by a red bar because they require an immediate upgrade, while the ones that are still compatible are marked by a yellow bar.

Step2ConfirmInstall.png

You might be prompted to delete all the old or unused XWiki pages (if there are any) by selecting the "Wiki Name" case and clicking on "Continue". By default, the wiki pages that have been modified are left unselected so that you won't lose your changes.

DeleteUnusedSubWikiPages.png

Once the progress bar has reached 100%, go to the "Dependencies" tab and you will see 2 installed dependency extensions marked by a gray status bar:

  • XWiki Platform - Distribution - Flavor - Common
  • Wiki Application for subwikis

Step2SubWikiUpgraded.png

The process is similar for the remaining sub-wikis.

Upgrade a Sub-Wiki Using a Recorded Actions File

To upgrade a sub-wiki by applying the same decisions as for another previously upgraded wiki, access its home page with an administrator account which will launch the Distribution Wizard, click on "Later", then on "Replay recorded actions" in order to be redirected to the wiki's XWiki.ExtensionHistory page. 

ReplayRecordedActions.png

In this case, there are no history records for the current sub-wiki,

NoHistoryRecords.png

but Administrators can use the one from the main wiki by clicking on "Showing records from Local History" and uploading the corresponding XML file from your computer. The process of generating it is detailed in the Extension Manager documentation. Next, select the uploaded file and click on "Replay".

ReplayRecordedActionsConfirm.png

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 in the recorded history file, then you will be prompted to answer them.

ReplayOptions.png

Click on "Continue", then on "Start" to confirm the upgrade by installing the "XWiki Standard Flavor - Sub Wiki" extension.

ConfirmUpgradeSubWiki.png

Details about the installed or modified extensions are available in the Replay Log.

ReplayLog.png

Once the progress bar has reached 100%, refresh the wiki's home page and you may start using the new version.

  

Related Pages

Search this space

 

Most popular tags

Failed to execute the [groovy] macro
  1. access rights
  2. activity stream
  3. annotation
  4. attachment
  5. comment
  6. Document Tree Macro
  7. export
  8. Extension Manager
  9. Flamingo skin
  10. global user
  11. Groovy event listener
  12. group
  13. nested page
  14. search
  15. skin
  16. syntax
  17. user
  18. user profile
  19. velocity macros
  20. wiki
  21. wysiwyg
  22. XWiki Applications
  23. xwikiattachment_archive table
  24. xwikiattachment table
  25. xwikiattrecyclebin table
  26. xwikiproperties table

[Display all tags from this space]