Hide last authors
Vincent Massol 11.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
Guillaume Delhumeau 5.1 2 {{toc/}}
Vincent Massol 11.1 3 {{/box}}
Guillaume Delhumeau 3.1 4
Vincent Massol 11.1 5 = History =
Guillaume Delhumeau 3.5 6
Vincent Massol 11.1 7 == Executive Summary ==
9 Up to XWiki 7.1, there has been 2 ways to organize content in XWiki:
Guillaume Delhumeau 14.1 10
Vincent Massol 11.1 11 * Wiki > Space > Page (which includes rights inheritance and administration features)
12 * Page > Child Page > Child Page of child Page > ... (which is used for hierarchical navigation purposes)
14 Note that both are independent: a page can have a parent Page in a different Space/Wiki than its own .
16 While this was working, we've found that it could create confusion for users, leading to questions such as:
Guillaume Delhumeau 14.1 17
Vincent Massol 11.1 18 * Should I create a sub-Wiki or a Space for my team?
19 * Which navigation should I put on my home page: list of Spaces or tree view of Pages?
20 * Can I set rights on a page that is under a space?
Keith Whittingham 15.1 22 At the same time, for a long time there have been discussions on the list about the future "new model" of XWiki, which would ideally include
Vincent Massol 11.1 23 Nested Spaces, offering the following features:
Guillaume Delhumeau 14.1 24
Vincent Massol 11.1 25 * Unified way to handle hierarchical navigation (Page > Sub-page > Sub-sub-page >...)
26 * Navigation reflected in URLs (.../PageA/PageB/PageC)
Keith Whittingham 15.1 27 * Inheritance of access rights (rights on PageA apply to PageB and PageC, unless defined otherwise. Rights on PageB supersede those on PageA
Vincent Massol 11.1 28 and also apply to PageC, and so on.)
30 In the end, we took the opportunity to move from the previous way to this new way of organizing pages in XWiki 7.2.
32 In an ideal world, going from the old model to the new one would imply a total rewrite of the model. However, in order not to break retro-compatibility with many existing features and applications we had to keep the concepts of "Page" and "Space" in XWiki while adapting them to emulate the Nested Pages feature. Here's what we've done to achieve this by default:
Guillaume Delhumeau 14.1 33
Vincent Massol 11.1 34 * We've hidden the parent-child feature(((
35 {{info}}
36 Even though it's hidden you can still turn it back on if you need it while you migrate your content to use Nested Spaces: set the ##core.hierarchyMode## property to ##parentchild## in the ##xwiki.properties## configuration file.
37 {{/info}}
38 )))
39 * When creating a new page, the system automatically creates ##Page.WebHome##, which creates a Space, though this is hidden in the URL (you only see .../Page/)
40 * For advanced users, we added the ability to create "Terminal Pages" which are pages that are not Spaces (as before). This is meant mostly for Application creators.
42 == Detailed Explanations ==
Guillaume Delhumeau 3.5 44 Before the introduction of the Nested Pages concept (in 7.2), the content in a wiki was organized like this:
Guillaume Delhumeau 14.1 45
Vincent Massol 12.1 46 * we had some **Spaces**, that you can conceptually consider like file system "folders"
47 * inside these spaces, we had **Pages**, where you were able to write content or store applications entries.
Guillaume Delhumeau 5.1 48
Vincent Massol 12.1 49 At that time, we couldn't have spaces inside spaces, so all pages were placed inside a top-level space. The pages were identified like this: ##NameOfTheSpace.NameOfThePage##.
Guillaume Delhumeau 3.5 50
Vincent Massol 12.1 51 Some pages were a bit special. They were the "home" pages of a space. Every time a user wanted to reach a space without specifying a precise page name, he'd be redirected to that space's home page. These pages were called "WebHome" (because at the very beginning of XWiki, "spaces" were called "web").
Guillaume Delhumeau 3.5 52
Vincent Massol 11.1 53 === Parent/Child relationship ===
Guillaume Delhumeau 3.5 54
Vincent Massol 12.1 55 The user was able to specify a **parent** page for each page he had created. This parent could have been any page, for example the page ##Movies.ItsAWonderfulLife## could have ##Directors.FrankCapra## as parent. Then ##ItsAWonderfulLife## was listed as ##Child## of ##FrankCapra##. This relationship was displayed in the //breadcrumb// at the top of each page. The user was able to navigate through this //hierarchy//.
Guillaume Delhumeau 3.6 56
Vincent Massol 12.1 57 Some applications used this parent/child relationship to organize their data. For them, this relationship is crucial.
Guillaume Delhumeau 3.7 58
Vincent Massol 11.1 59 === The introduction of the Nested Pages concept ===
Guillaume Delhumeau 3.8 60
Vincent Massol 12.1 61 In XWiki 7.2, due to frequent users demands, we have introduced the ability to create spaces under other spaces. It's the **Nested Spaces** concept. We suddenly had the ability to create a hierarchy of spaces to organize content.
Guillaume Delhumeau 3.8 62
Keith Whittingham 15.1 63 But we have also found some issues. What if a space has the same name as a page? Which entry should we render to the user when he reaches an URL where two entities match? Moreover, does it make sense to have a difference between a space and a page? Why couldn't pages have sub-pages inside of them?
Guillaume Delhumeau 3.8 64
Vincent Massol 12.1 65 We then have decided to switch to the **Nested Pages** concept. In theory, a page should now be able to have some sub-pages, because we don't need to have a distinction between a page and a space like we have between a file and a folder.
Guillaume Delhumeau 3.8 66
Vincent Massol 12.1 67 But this change was not possible to make at the API level because it would have required too much work that we could not afford at this time (and breaking backward-compatibility incidentally since it would have required a complete model change). So the decision was made to stick to the **Nested Spaces** implementation at the API level (for now), but to propose **Nested Pages** at the UI level.
Guillaume Delhumeau 3.8 68
69 How does it work?
Vincent Massol 12.1 71 Every time a user creates a page from the XWiki UI, he now actually creates a space (without knowing it ;)) with its ##WebHome## page. It means that all user-created page are called ##WebHome##.
Guillaume Delhumeau 3.8 72
Vincent Massol 12.1 73 Then, when the user wants to create a sub-page, for example ##FrankCapra## inside the page ##Directors.WebHome##, he actually creates a new space inside the space ##Directors## with its ##WebHome## page: ##Directors.FrankCapra.WebHome##. That's how we emulate it.
Guillaume Delhumeau 3.8 74
Vincent Massol 12.1 75 The notion of space has been removed from the UI. It's not mentioned anywhere, anymore. Everything seems to work as if we were really creating sub-pages, even if under the hood, we create sub-spaces.
Guillaume Delhumeau 3.8 76
77 {{info}}
Vincent Massol 12.1 78 That emulation should be temporary. At some point we'd like to refactor the core model of XWiki and discard the concept of spaces to only keep pages. Don't hold your breath though, this may be several years in the coming ;)
Guillaume Delhumeau 3.8 79 {{/info}}
Vincent Massol 12.1 81 Note that users still have the ability to create pages that are not named ##WebHome##. As a consequence, such pages (that are not the "WebHome" of their space) cannot have sub-pages. They're called **Terminal Pages**.
Guillaume Delhumeau 3.9 82
Vincent Massol 11.1 83 === Issue with the Parent/Child relationship ===
Guillaume Delhumeau 3.9 84
Guillaume Delhumeau 3.11 85 Now, it is clear that we have 2 different hierarchies in the wiki. One, made of sub-pages (sub-spaces in the reality), and one made with the old parent/child relationship. Then, clearly, it becomes confusing for the user. Which hierarchy should be displayed in the breadcrumb? What is the parent of page, the "container" page or the parent set in the field?
Guillaume Delhumeau 3.9 86
Vincent Massol 12.1 87 The choice has been made to drop the notion of parent/child relationship, since we can now really have children pages, implemented as sub-pages (with inherited rights, preferences, etc...).
Guillaume Delhumeau 3.9 88
Vincent Massol 12.1 89 It means that when the user wants to change the parent of a page, he actually needs to **move** this page under the new parent.
Guillaume Delhumeau 3.9 90
Vincent Massol 12.1 91 This concept is good in theory. But, how can you migrate existing content when you upgrade to XWiki 7.2+?
Guillaume Delhumeau 3.9 92
Vincent Massol 11.1 93 = Migration =
Guillaume Delhumeau 3.1 94
Vincent Massol 12.1 95 The idea is to convert your existing pages (most of them are terminal pages) into ##WebHome## pages under their own space. We call this "convert terminal pages to nested pages". This will then allows you to create sub-pages under any converted pages, which is impossible while they are terminal pages.
Guillaume Delhumeau 1.2 96
Vincent Massol 12.1 97 But that would be a shame to lose the parent/child relationships that the users have created between their pages. The users might want to preserve their carefully-crafted hierarchies. You might still want to have ##FrankCapra## as parent of ##ItsAWonderfulLife##.
Guillaume Delhumeau 1.3 98
Guillaume Delhumeau 3.12 99 To keep this information, the principle is to **move all the pages under their parents**, so the parent/child links **becomes a real hierarchy between pages**.
Guillaume Delhumeau 6.1 101 {{image reference="example.svg" width="600"/}}
Guillaume Delhumeau 5.1 102
Vincent Massol 12.1 103 To perform this conversion, we have developed an application called the [[Nested Pages Migrator Application>>extensions:Extension.Nested Pages Migrator Application]].
Guillaume Delhumeau 3.12 104
Vincent Massol 11.1 105 == Fix the hierarchy ==
Guillaume Delhumeau 1.2 106
Vincent Massol 12.1 107 However, your current page hierarchy may be messy. For example, some pages inside the space ##Proposal## could have ##Main.WebHome## as parent instead of ##Proposal.WebHome## which would be more logical. It happens when the user is invited to create pages in the space ##Proposal## directly from the main page.
Guillaume Delhumeau 1.3 108
Vincent Massol 12.1 109 It's important to identify such cases before applying the migration tool, because the tool won't be able to detect this kind of unwanted hierarchies.
Guillaume Delhumeau 1.4 110
Vincent Massol 12.1 111 In the previous example, the solution was to put manually the parent of all pages of the ##Proposal## space that had ##Main.WebHome## as parent, to ##Proposal.WebHome##. The following script is an example that can be used to migrate (you'll need to adapt it to your own needs):
Guillaume Delhumeau 1.4 112
113 {{code language="velocity"}}
Guillaume Delhumeau 2.1 114 #set ($xwql = "where doc.space in ('Proposal', 'Design', 'Improvements') and doc.parent = 'Main.WebHome'")
115 #foreach($r in $services.query.xwql($xwql).execute())
116 #set ($d = $xwiki.getDocument($r))
117 #set ($discard = $d.setParent('Proposal.WebHome'))
118 #set ($discard = $d.save())
119 * $r updated
120 #end
Guillaume Delhumeau 1.4 121 {{/code}}
Vincent Massol 11.1 123 == Nested Pages Migrator Application ==
Guillaume Delhumeau 3.1 124
Guillaume Delhumeau 8.1 125 To use the migrator application, you first need to upgrade your XWiki instance to a recent version (7.4.2+). Indeed, the migrator cannot create nested pages in an old XWiki instance where this concept did not exist!
127 {{warning}}
Vincent Massol 14.3 128 * We absolutely recommend making a [[backup of your instance and of your databases>>Documentation.AdminGuide.Backup]]. The migrator will modify a lot of existing pages and these changes cannot be reverted. If something goes wrong, the only solution will be to re-install your backup.
Vincent Massol 12.1 129 * Users should be invited to not change the wiki content during the use of the migrator.
130 * Nothing prevents another administrator to run the migrator at the same time as you, which could have bad consequences (collisions of actions, etc...). You should make sure that you are the only person using this tool during all the time of the process.
Guillaume Delhumeau 8.1 131 {{/warning}}
Vincent Massol 12.1 133 Go to the [[Extension Manager in your wiki>>extensions:Extension.Extension Manager Application]], and install the [[Nested Pages Migrator Application>>extensions:Extension.Nested Pages Migrator Application]]. Then go to the page ##NestedPagesMigration.WebHome##.
Guillaume Delhumeau 8.1 134
135 You will find the following page:
Vincent Massol 11.1 137 {{image reference="Migrator1.png"/}}
Guillaume Delhumeau 8.1 138
Guillaume Delhumeau 14.1 139 There are 3 actions:
Guillaume Delhumeau 8.1 141 * **compute a plan**: the migration first generate a plan of actions to perform. You can see what the migrator proposes to do and disable some actions, or modify the options, for example.
142 * **execute the plan**: when a plan has been computed and if you agree with its content, you can execute the plan: the pages will be moved as proposed.
Guillaume Delhumeau 14.1 143 * **detect breakages** {{info}}(since 0.7){{/info}}: detect the hierarchies that are broken if you don't run the migrator. [[Read the migrator page to have more information>>extensions:Extension.Nested Pages Migrator Application||anchor="HBreakagesDetection"]].
Guillaume Delhumeau 8.1 144
Vincent Massol 11.1 145 === Options ===
Guillaume Delhumeau 8.1 146
147 But first, let's talk about the options.
149 |=Option|=Description|=Default value (recommended)
Vincent Massol 12.1 150 |**Exclude hidden pages**|Check this option if you want to exclude hidden pages, usually containing technical data, from the migration.|**true**
151 |**Exclude pages having a class**|Check this option to not convert pages holding an xclass, because it can break applications based on these xclasses.|**true**
Guillaume Delhumeau 8.1 152 |**Do not move children**|Convert pages into Nested Pages (so they can have children) without moving them under their parent. The old hierarchy will not be preserved, but the rights and the preferences will remain the same.|**false**
Vincent Massol 12.1 153 |**Add redirection**|Add a redirection at the old location. So when a user goes to the old URL, he will be automatically redirected to the new one. It's good if you don't want to break bookmarks, for example.|**true**
Guillaume Delhumeau 8.1 154 |**Convert preferences**|By moving pages under their parents, the inherited preferences might change. If this option is enabled, the migrator will copy the old inherited preferences to the new location.|**true**
Keith Whittingham 15.1 155 |**Convert rights**|By moving pages under their parents, the inherited rights might change. If this option is enabled, the migrator will try to set the same rights at the new location.
Vincent Massol 12.1 156 \\{{error}}Unfortunately, this operation is complex, and the current algorithm is a bit buggy at the moment. This option should be used for debug reasons.{{/error}}
Guillaume Delhumeau 8.1 157 \\{{info}}You can still compute a plan with this option without executing it: the plan will list the locations were some rights will be modified, and then you should be able to find a solution for them manually.{{/info}}
Keith Whittingham 15.1 158 |**false**
Vincent Massol 12.1 159 |**Exclude classes**|Exclude pages holding some objects.|A list of classes that we have identified to be excluded. It's not complete, you should add the xclasses of your own applications!
Guillaume Delhumeau 8.1 160 |**Exclude pages**|Exclude a list of pages.|A list of pages that we have identified to be excluded.
161 |**Excluded spaces**|Exclude a list of spaces.|A list of spaces that we have identified to be excluded.
162 |**Included spaces**|Only pages containing in this list of spaces will be converted|empty
164 Note: you can select the classes to exclude by clicking on the "excluded classes" field:
Vincent Massol 11.1 166 {{image reference="excludedClasses.png"/}}
Guillaume Delhumeau 8.1 167
Vincent Massol 11.1 168 === Plan ===
Guillaume Delhumeau 8.1 169
170 Once the options have been carefully set, you can start the computation of a plan. This operation usually lasts about 10 seconds, but it could be more depending of the number of the pages and the complexity of the preferences, rights, and hierarchies. The logs of the operation are displayed in the page. If error happens, you will have some error entries in the logs.
172 {{info}}
173 While the plan is computed, nothing is changed in your wiki. It's safe.
174 {{/info}}
176 This is what a plan looks like:
Vincent Massol 11.1 178 {{image reference="plan.png"/}}
Vincent Massol 12.1 180 A plan is a tree of actions to perform in order to convert your pages. The tree is ordered as the resulting hierarchy would look like. If you click on the page name of each action (in bold), you will open the tree and see the children actions. You can close the tree by clicking again the page name.
Guillaume Delhumeau 8.1 181
182 Each line displays the target document (the new location of the page) and the original page (the current location of the page). It is displayed like this:
184 {{code}}
185 NewLocation.WebHome from Old.Location
186 {{/code}}
188 You can click on the old location to open the page (in a new window). It could be useful to look at the page you are about to move.
Vincent Massol 12.1 190 Some actions have the "(unchanged)" mention. It means the page will not be moved. They are present in the tree only to display their children when some of them have changed.
Guillaume Delhumeau 8.1 191
Vincent Massol 12.1 192 Each action has a checkbox. Only checked actions will be performed. So if you notice some changes that you don't want to perform, you can easily uncheck them. When you uncheck an action, it also affects its children. But you can also select the children one by one if you need to.
Guillaume Delhumeau 8.1 193
194 Other actions are available:
Guillaume Delhumeau 14.1 195
Guillaume Delhumeau 8.1 196 * **exclude page**: click on this button to add the page to the exclude list (in the options). The plan might be recomputed.
197 * **exclude space**: click on this button to add the space of that page to the exclude list (in the options). Then plan might be recomputed.
Vincent Massol 12.1 198 * **set parent**: click on this button to manually set a parent for that page. {{warning}}Note: this action will be performed immediately, not when the plan will be executed. It is a shortcut to help you changing the parent without having to navigate to the page.{{/warning}}
Guillaume Delhumeau 8.1 199
Vincent Massol 11.1 200 ==== Preferences ====
Guillaume Delhumeau 8.1 201
Vincent Massol 12.1 202 Some actions can contains preference changes. You can check or uncheck any change one by one. If they are checked, the preferences will be set to the new location. The original preference is also mentioned. When a preference line is present, it means that the preferences of the new location are not the same than the preferences of the old location.
Guillaume Delhumeau 8.1 203
Vincent Massol 12.1 204 You can either let the migrator set the new preferences according to the plan, or manually modify some preferences before or after the migration. In case you modified them before, you should restart the computation of the plan.
Guillaume Delhumeau 8.1 205
Vincent Massol 11.1 206 ==== Rights ====
Guillaume Delhumeau 8.1 207
208 Same as preferences, but for rights.
210 {{error}}
Vincent Massol 12.1 211 Remember, the current application is a bit buggy at the moment and you should not apply these changes!
Guillaume Delhumeau 8.1 212 {{/error}}
214 {{info}}
Vincent Massol 12.1 215 However, you can use this plan to identify where rights will be changed by the migration. Indeed, even if the proposed actions to fix them are bad, the algorithm is able to identify where rights problems happen. Save this list and you will be able to fix the rights issues by yourself after the migration.
Guillaume Delhumeau 8.1 216 {{/info}}
Vincent Massol 11.1 218 === Execute the plan ===
Guillaume Delhumeau 8.1 219
220 When you are ready, you can execute the plan.
Vincent Massol 11.1 222 {{image reference="PlanExecuting.png"/}}
Guillaume Delhumeau 8.1 223
224 {{warning}}
Vincent Massol 12.1 225 * Be patient. The process could be very long. It will use a lot of server resources, so we recommend to don't let users access the wiki during the process. (For example, you can temporary forbid remote connections to your servlet container and access XWiki through an SSH tunnel for yourself.)
226 * Since all logs are displayed in the page, even the browser can became slow. Note that we have experienced better performances using Chrome instead of Firefox.
227 * Some OutOfMemory errors could happen. To avoid them, we recommend to give a lot of memory to your XWiki instance during the execution of the migration.
Guillaume Delhumeau 8.1 228 {{/warning}}
230 **We highly recommend to perform migration tests on a staging server before doing it on a production instance.**
Vincent Massol 11.1 232 == What else? ==
Guillaume Delhumeau 8.1 233
234 Unfortunately, running the migrator is not enough. This is a list of actions that you need to perform:
Vincent Massol 12.1 236 * Since the pages have been renamed, pages doing {{code language="plain"}}{{include reference="..."/}}{{/code}} or {{code language="plain"}}{{display reference="..."/}}{{/code}} might not work. You should identify them and fix them.
237 * If you use the "SpaceDocs" or the "Spaces" panels, you should replace them by "Navigation", "Siblings" and "Children Panels".
238 * Some existing code may break slightly and may need to be adapted: code taking some user input and creating Spaces based on that will most likely display {{{"\."}}}, {{{"\:"}}} and {{{"\\"}}} in the UI. Unless the code already cleans the user input and removes {{{"."}}}, {{{":"}}} and {{{"\"}}}characters. So for example if a user enters a Space name of "my.space":
Guillaume Delhumeau 8.1 239 ** before 7.2: the code would create/display a Space named "my.space"
240 ** after 7.2: the code will create/display a Space named "my\.space"
Vincent Massol 12.1 241 * Various XWiki APIs that used to return a space name have been returning a space reference string (i.e. list of spaces separated by dots and escaped {{{"\."}}}, {{{"\:"}}} and {{{"\\"}}} characters). Code using those API may need to be updated. See [[XWiki 7.2 release notes>>xwiki:ReleaseNotes.ReleaseNotesXWiki72||anchor="HSpaceReferenceinsteadofSpacename"]] for more details (this content could be copied in a section of the migration guide).

Get Connected