Skip to Content

Changes for page XWiki Migrations

Last modified by Agnease on 2026/05/25 16:46
From version 11.1
edited by Agnease
on 2026/05/25 16:46
Change comment: There is no comment for this version
To version 9.1
edited by Agnease
on 2026/05/25 12:59
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -28,11 +28,11 @@
28 28   #set ($migrationReasonItems = [{
29 29   'title': 'Preserve structure',
30 30   'icon': 'sitemap',
31 - 'content': 'Keep spaces, hierarchies, navigation, page relationships and entry points understandable after the move.',
31 + 'content': 'Keep spaces, hierarchies, navigation and page relationships understandable after the move.',
32 32   'items': [
33 33   'Space and page hierarchy mapping',
34 34   'Navigation and landing page planning',
35 - 'Search and findability considerations'
35 + 'Related content and category structure'
36 36   ]
37 37   },{
38 38   'title': 'Protect continuity',
... ... @@ -46,11 +46,11 @@
46 46   },{
47 47   'title': 'Improve maintainability',
48 48   'icon': 'database',
49 - 'content': 'Use the migration as an opportunity to clean up content, introduce metadata and redesign what should not be copied as-is.',
49 + 'content': 'Use the migration as an opportunity to clean up content, introduce metadata and prepare better structures.',
50 50   'items': [
51 51   'Templates and structured data',
52 52   'Metadata and tagging strategy',
53 - 'Manual cleanup recommendations'
53 + 'Content cleanup recommendations'
54 54   ]
55 55   }])
56 56  
... ... @@ -60,8 +60,8 @@
60 60  
61 61   <p class="section-intro">
62 62   Documentation platforms usually contain years of accumulated knowledge, links, attachments, permissions,
63 - templates, macros and habits. A successful migration should preserve what matters, reduce broken navigation
64 - and improve how the knowledge is organized and maintained in XWiki.
63 + templates and habits. A successful migration should preserve what matters while improving how the knowledge
64 + is organized and maintained in XWiki.
65 65   </p>
66 66  
67 67   <div class="pathways">
... ... @@ -119,9 +119,8 @@
119 119   <h2 id="migration-sources-title">Common migration sources</h2>
120 120  
121 121   <p class="section-intro">
122 - Each source system has different export formats, content models, permissions and limitations.
123 - The migration approach depends on the quality of the source data, the expected XWiki structure
124 - and the amount of conversion, cleanup or redesign needed.
122 + Each source system has different export formats, content models and limitations. The migration approach
123 + depends on the quality of the source data, the expected XWiki structure and the amount of transformation needed.
125 125   </p>
126 126  
127 127   <div class="services-grid">
... ... @@ -150,13 +150,13 @@
150 150   'content': 'Decide spaces, page hierarchy, templates, metadata, permissions, naming rules and navigation strategy.'
151 151   },{
152 152   'title': 'Run a sample migration',
153 - 'content': 'Migrate a representative subset of content to identify formatting, macro, link, attachment and structure issues.'
152 + 'content': 'Migrate a representative subset of content to identify conversion issues and validate the approach.'
154 154   },{
155 155   'title': 'Refine conversion and cleanup rules',
156 156   'content': 'Adjust mappings, formatting, link handling, attachments, macros, categories and content cleanup decisions.'
157 157   },{
158 158   'title': 'Execute and validate the migration',
159 - 'content': 'Run the migration, review key content areas, verify attachments, links, redirects and navigation, and document remaining follow-up work.'
158 + 'content': 'Run the migration, review key content areas, verify attachments and links, and document remaining follow-up work.'
160 160   }])
161 161  
162 162   <section id="migration-process" class="split-section" aria-labelledby="process-title">
... ... @@ -172,8 +172,8 @@
172 172   </p>
173 173  
174 174   <p>
175 - Migrations are best handled iteratively: assess the source, run a sample migration, validate links,
176 - attachments, formatting and important spaces, adjust the conversion rules and then proceed with a controlled migration plan.
174 + Migrations are best handled iteratively: assess the source, run a sample migration, validate the result,
175 + adjust the transformation rules and then proceed with a controlled migration plan.
177 177   </p>
178 178   </div>
179 179  
... ... @@ -203,9 +203,9 @@
203 203   'icon': 'lock',
204 204   'content': 'Review and mapping of access rights where the source system contains meaningful permission rules.'
205 205   },{
206 - 'title': 'Cleanup and validation',
207 - 'icon': 'check-square-o',
208 - 'content': 'Post-migration review of important spaces, broken links, attachments, formatting issues and content needing manual cleanup.'
205 + 'title': 'Metadata strategy',
206 + 'icon': 'tags',
207 + 'content': 'Tags, categories, templates, XWiki classes or structured data to improve long-term maintainability.'
209 209   }])
210 210  
211 211   <section aria-labelledby="included-title">
... ... @@ -213,9 +213,8 @@
213 213   <h2 id="included-title">What can be included</h2>
214 214  
215 215   <p class="section-intro">
216 - The exact migration scope depends on the source system and the quality of the exported content.
217 - A migration engagement can include technical conversion, information architecture, permission review,
218 - cleanup recommendations and post-migration validation.
215 + The exact migration scope depends on the source system and the quality of the exported content. A migration
216 + engagement can include both technical conversion and practical information architecture work.
219 219   </p>
220 220  
221 221   <div class="widgets">
... ... @@ -233,6 +233,59 @@
233 233   </div>
234 234   </section>
235 235  
234 + ## IMPORTANT CONSIDERATIONS
235 + #set ($migrationConsiderationItems = [{
236 + 'title': 'Macros and special content',
237 + 'icon': 'code',
238 + 'content': 'Source-specific macros, embeds, widgets or dynamic content may require conversion, replacement or redesign.'
239 + },{
240 + 'title': 'Links and redirects',
241 + 'icon': 'link',
242 + 'content': 'Internal links, external references, old URLs and bookmarks should be reviewed to reduce broken navigation.'
243 + },{
244 + 'title': 'Search and findability',
245 + 'icon': 'search',
246 + 'content': 'Content organization, titles, metadata and navigation affect how easily users find migrated knowledge.'
247 + },{
248 + 'title': 'User adoption',
249 + 'icon': 'user',
250 + 'content': 'A technically successful migration still needs clear navigation, familiar entry points and user guidance.'
251 + },{
252 + 'title': 'Validation effort',
253 + 'icon': 'check-square-o',
254 + 'content': 'Important spaces and high-value content should be reviewed after migration to catch conversion issues.'
255 + },{
256 + 'title': 'Cutover planning',
257 + 'icon': 'clock-o',
258 + 'content': 'Timing, source freeze, final migration, redirects and communication should be planned before go-live.'
259 + }])
260 +
261 + <section class="services" aria-labelledby="considerations-title">
262 + <div class="container">
263 + <h2 id="considerations-title">Important migration considerations</h2>
264 +
265 + <p class="section-intro">
266 + Not every element from the source system maps perfectly to XWiki. The migration plan should distinguish
267 + between what can be converted automatically, what needs manual cleanup and what should be redesigned.
268 + </p>
269 +
270 + <div class="services-grid">
271 + #foreach ($entry in $migrationConsiderationItems)
272 + <article class="service">
273 + <div class="service-icon" aria-hidden="true">
274 + <i class="fa fa-$entry.icon"></i>
275 + </div>
276 +
277 + <div class="service-body">
278 + <h4>$entry.title</h4>
279 + <p>$entry.content</p>
280 + </div>
281 + </article>
282 + #end
283 + </div>
284 + </div>
285 + </section>
286 +
236 236   ## RELATED SERVICES
237 237   #set ($relatedMigrationServiceItems = [{
238 238   'title': 'XWiki Development & Integrations',
... ... @@ -251,7 +251,7 @@
251 251   <h2 id="related-title">Related XWiki services</h2>
252 252  
253 253   <p class="section-intro">
254 - Migration work often connects with custom development, support and long-term platform maintenance.
305 + Migration work often connects with custom development, support and upgrade planning.
255 255   </p>
256 256  
257 257   <div class="resource-grid">
... ... @@ -273,8 +273,8 @@
273 273   <h2 id="cta-title">Planning a migration to XWiki?</h2>
274 274  
275 275   <p>
276 - Send a short description of the source system, approximate content volume, export options, expected timing
277 - and the type of XWiki structure you want to achieve. A sample export or representative content area is often enough to start.
327 + Send a short description of the source system, approximate content volume, export options and the type of
328 + XWiki structure you want to achieve. A sample export or representative content area is often enough to start.
278 278   </p>
279 279  
280 280   <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Discuss a migration</a>