Nested Pages Migrator Application

Version 61.2 by Thomas Mortagne on 2022/10/31 00:08

cogHelper to convert terminal pages into Nested Pages.
Developed by

Guillaume Delhumeau

Active Installs292
8 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager


This application help you to convert all your existing pages into Nested Pages. Thanks to this, all your pages will be able to have children.

A more complete documentation have been written, which also explain why you need to migrate your pages. See NestedPagesMigration. And if you're wondering if you need to run this migrator or not, check this FAQ entry.

In order to not break existing hierarchy of pages, based on the parent/child relationship, this application moves the pages under its parent. So the parent/child relationship is replaced by a real location hierarchy.

You should upgrade your wiki to a version handling Nested Pages before using this application. It has been designed for XWiki 7.4.2+.

This is what the application looks like:

You can access it by going to the "NestedPagesMigration" page, or by clicking on the "Nested Pages Migration" icon on the application panel (the left bar, by default).


Simple Options

Exclude pagesExclude a list of pages.
Excluded spacesExclude a list of spaces.
Included spacesOnly pages containing in this list of spaces will be converted

Advanced Settings

These options are hidden by default. You can keep them unchanged since they will fit in most of the cases.

Exclude hidden pagesCheck this option if you want to exclude hidden pages, that usually contain technical data, from the migration.
Exclude pages having a classCheck this option to not convert pages holding a class, because it can break applications based on these classes.
Do not move childrenConvert pages into Nested Pages (so they can have children) without moving them under their parent. The old hierarchy will not be preserved.
Add redirectionAdd a redirection in the old location to the new one.
Convert preferencesPreserve the preferences of the page that could change otherwise since of their new location.
Convert RightsPreserve the preferences of the page that could change otherwise since of their new location. This option does not currently work and is there for test purpose.
Exclude classesExclude pages holding some objects.

Note: you can select the classes to exclude by clicking on the "excluded classes" field:

Breakages Detection (since 0.7)

The migrator can help you to decide if it's worth the effort of migrating your pages. It lists the pages that have their initial parent lost and for which it would be good to run the migrator on.

Example: If "Animals.Cat" had its parent field set to "Species.Mammal", it means that the breadcrumb is not showing that information anymore and that migration should be performed (since its hierarchical parent is Animals.WebHome).

All you need to do is to click on the "Detect Breakages". Note: the options (page exclusions, included spaces, etc...) are take into account so the detection will not be on the whole wiki.


Note: if A.WebHome has the parent Home.WebHome, and if A.B has A.WebHome for parent, then A.WebHome will be listed (since it will no longer have Home.WebHome without the migration) but A.B will not (because A.WebHome will remain the parent). However, the fact that Home.WebHome is the "grandfather" of A.B is lost too. You should remember this when you look at the results.

In other words, the Home.WebHome > A.WebHome > A.B hierarchy is lost but not listed by the tool.


Example of generated plan:

The plan is a tree, and you can open/close each branch by clicking on it. You can exclude pages from the conversion by clicking on the "exclude page" button. This action will recompute the plan except if you have enabled "Do not move children".

You can also set the parent of a page, manually. Then, the plan is computed again because it the results can be changed a lot.

Known issues

Pages with lots of revisions / attachments

Note that there's an issue at the moment when renaming pages having a lot of revisions/attachments since that takes a lot of memory and you could get an OutOfMemory. This issue is not strictly related to this migrator since it's a general issue but you may hit it when using it. The way to work around the issue is currently to give more memory to the JVM. In the future we need to fix the copy and rename features of XWiki so that they scale better.

Since this tool is using lots of rename operations to move pages around, it is impacted by XWIKI-17939, causing wikilinks between pages to break upon their move to their final location. If you're leaving the "Add redirects" checkbox checked in the advanced settings, you won't see the issue because the redirects will cover it.
Note that the prevalence of issue XWIKI-17939 is higher the usecase of migration than for XWiki Standard usage, because if content needs to be migrated, then it was created back when links were all untyped by default, which is not the case in recent versions of XWiki.

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

Release Notes




















  • Fix a dependency problem.
  • Better description in pom.xml files.


  • First version.


Dependencies for this extension (org.xwiki.contrib:application-nestedpagesmigrator-ui 0.9.0):

Get Connected