From version < 7.1 >
edited by Guillaume Delhumeau
on 2016/02/25
To version < 8.1 >
edited by Guillaume Delhumeau
on 2016/03/10
Change comment: Imported from XAR



Page properties
... ... @@ -83,4 +83,128 @@
83 83  
84 84  = Install Nested Pages Migrator Application =
85 85  
86 +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!
87 +
88 +{{warning}}
89 +Then, we hardly recommend to make a backup of your instance and of your databases. The migrator will modify a lot of existing pages and these changes can not be reverted. If something goes wrong, the only solution will be to re-install your back-up.
90 +{{/warning}}
91 +
92 +{{warning}}
93 +Users should be invited to not change the wiki content during the use of the migrator. How the migrator could convert pages that are currently edited?
94 +{{/warning}}
95 +
96 +{{warning}}
97 +Nothing prevents an other administrator to run the migrator in the same time than 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.
98 +{{/warning}}
99 +
86 86  Go to the Extension Manager, and install [[Nested Pages Migrator Application>>extensions:Extension.Nested Pages Migrator Application]]. Then go to the page ##NestedPagesMigration.WebHome##.
101 +
102 +You will find the following page:
103 +
104 +image:Migrator1.png
105 +
106 +There is 2 actions:
107 +
108 +* **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.
109 +* **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.
110 +
111 +== Options ==
112 +
113 +But first, let's talk about the options.
114 +
115 +|=Option|=Description|=Default value (recommended)
116 +|**Exclude hidden pages**|Check this option if you want to exclude hidden pages, that usually contain technical data, from the migration.|**true**
117 +|**Exclude pages having a class**|Check this option to not convert pages holding a class, because it can break applications based on these classes.|**true**
118 +|**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**
119 +|**Add redirection**|Add a redirection in the old location. So when the user will reach the old URL, she will be automatically redirected to the new one. It's good if you don't want to break bookmarks, for example.|**true**
120 +|**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**
121 +|**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 in the new location.
122 +\\{{error}}Unfortunately, this operation is complex, and the current algorithm is buggy. This option should be used for debug reasons.{{/error}}
123 +\\{{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}}
124 +\\|**false**
125 +|**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 classes of your own applications!
126 +|**Exclude pages**|Exclude a list of pages.|A list of pages that we have identified to be excluded.
127 +|**Excluded spaces**|Exclude a list of spaces.|A list of spaces that we have identified to be excluded.
128 +|**Included spaces**|Only pages containing in this list of spaces will be converted|empty
129 +
130 +Note: you can select the classes to exclude by clicking on the "excluded classes" field:
131 +
132 +image:excludedClasses.png
133 +
134 +== Plan ==
135 +
136 +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.
137 +
138 +{{info}}
139 +While the plan is computed, nothing is changed in your wiki. It's safe.
140 +{{/info}}
141 +
142 +This is what a plan looks like:
143 +image:plan.png
144 +
145 +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 strong page name of each action, you will open the tree and see the children actions. You can close the tree by clicking again the page name.
146 +
147 +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:
148 +
149 +{{code}}
150 +NewLocation.WebHome from Old.Location
151 +{{/code}}
152 +
153 +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.
154 +
155 +Some actions have the mention: "(unchanged)". 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.
156 +
157 +Each action has a checkbox. Only checked actions will be perform. 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 concern its children. But you can also select the children one by one if you need.
158 +
159 +Other actions are available:
160 +
161 +* **exclude page**: click on this button to add the page to the exclude list (in the options). The plan might be recomputed.
162 +* **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.
163 +* **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 going to the page.{{/warning}}
164 +
165 +=== Preferences ===
166 +
167 +Some actions can contains preferences 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.
168 +
169 +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 modify them before, you should restart the computation of the plan.
170 +
171 +=== Rights ===
172 +
173 +Same as preferences, but for rights.
174 +
175 +{{error}}
176 +Remember, the current application is buggy and you should not apply these changes!
177 +{{/error}}
178 +
179 +{{info}}
180 +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 happens. Save this list and you will be able to fix the rights issues by yourself after the migration.
181 +{{/info}}
182 +
183 +== Execute the plan ==
184 +
185 +When you are ready, you can execute the plan.
186 +
187 +image:PlanExecuting.png
188 +
189 +{{warning}}
190 +Be patient. The process could be very long. It will use a lot of server resources, so we recommend to don't let users accessing 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.)
191 +
192 +Since all logs are displayed in the page, even the browser can became slow. We have experienced better performances using Chrome instead of Firefox.
193 +
194 +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.
195 +{{/warning}}
196 +
197 +**We highly recommend to perform migration tests on a staging server before doing it on a production instance.**
198 +
199 += What else? =
200 +
201 +Unfortunately, running the migrator is not enough. This is a list of actions that you need to perform:
202 +
203 +* 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.
204 +* if you use the "SpaceDocs" or the "Spaces" panels, you should replace them by "Navigation", "Siblings" and "Children Panels".
205 +* Some existing code may break slightly and needs to be adapted: code taking some user input and creating Spaces based on that will most likely display "\.", "\:" and "
206 +" in the UI. Unless the code already cleans the user input and removes ".", ":" and "\" characters. So for example if a user enter a Space name of "my.space":
207 +** before 7.2: the code would create/display a Space named "my.space"
208 +** after 7.2: the code will create/display a Space named "my\.space"
209 +* Various XWiki API 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 "
210 +" characters). Code using those API may need to be updated. See XWiki 7.2 release notes for more details (this content could be copied in a section of the migration guide).
... ... @@ -1,0 +1,1 @@
1 +XWiki.gdelhumeau
... ... @@ -1,0 +1,1 @@
1 +97.5 KB
... ... @@ -1,0 +1,1 @@
1 +XWiki.gdelhumeau
... ... @@ -1,0 +1,1 @@
1 +44.7 KB
... ... @@ -1,0 +1,1 @@
1 +XWiki.gdelhumeau
... ... @@ -1,0 +1,1 @@
1 +31.5 KB
... ... @@ -1,0 +1,1 @@
1 +XWiki.gdelhumeau
... ... @@ -1,0 +1,1 @@
1 +157.2 KB

Get Connected