Migration Is a Matter of When, Not If
Migrating from Confluence to xWiki is a decision that an increasing number of organizations are facing, particularly with the confirmed end of life for Confluence Data Center in March 2029. Whether you are moving proactively to gain the benefits of open-source flexibility or responding to Atlassian's licensing changes, the migration path from Confluence to xWiki is well-established. Over 100 organizations have successfully made this transition using xWiki's dedicated migration tooling, and the process, while requiring careful planning, is far less daunting than it might initially appear.
xWiki provides two migration tools: the free community Confluence Migrator, suitable for testing and small-scale evaluation, and the Confluence Migrator Pro, designed for production migrations and available to organizations with xWiki Business or Enterprise subscriptions. The Migrator Pro handles content, users, permissions, attachments, and macro conversion through a guided wizard interface. Combined with proper infrastructure — which is where MassiveGRID's managed xWiki hosting removes the burden of server administration — the migration becomes a structured, predictable project rather than an uncertain leap.
This guide walks through the complete migration process step by step, from initial audit through post-migration verification.
Step 1: Pre-Migration Audit
Every successful migration begins with a thorough understanding of what you are migrating. Skipping this step is the single most common source of delays and surprises during the actual migration. Take the time to build a complete picture of your Confluence environment before you touch any migration tooling.
Inventory Your Content
Start by documenting the scope of your Confluence instance. How many spaces do you have, and which are actively used versus archived or abandoned? What is your total page count, and how is it distributed across spaces? What is the total volume of attachments, and are there unusually large files (video recordings, design files, database exports) that may need special handling? How many registered users exist, and how many are active? These numbers will directly influence your infrastructure sizing, migration duration estimates, and the decision about whether to migrate everything at once or take a phased approach.
Map Your Marketplace Apps
Confluence deployments rarely run on the base product alone. Document every Marketplace app installed in your instance, what functionality it provides, which teams rely on it, and whether equivalent functionality exists in xWiki's extension ecosystem or as a built-in feature. Pay particular attention to apps that generate their own content types — diagramming tools, database-style structured data apps, and workflow engines — because this content may need special handling during migration. Our guide to Marketplace apps after Data Center EOL provides a mapping of common Confluence apps to their xWiki equivalents.
Document Customizations and Integrations
If your Confluence instance uses custom macros, user macros, custom themes, or integrations with other systems (LDAP/Active Directory, SSO providers, CI/CD pipelines, intranet portals), document each one. These customizations will need to be replicated or replaced in xWiki, and understanding the full scope early prevents unpleasant discoveries mid-migration. xWiki supports LDAP and Active Directory authentication natively, as well as SAML and OIDC-based SSO — which we cover in our xWiki LDAP and SSO guide.
Map Permission Structures
Confluence permissions — global permissions, space permissions, and page restrictions — are often more complex than organizations realize, particularly in instances that have been running for years. Export or document your permission structure before migration. The Migrator Pro handles permission migration, but you need to understand your starting point to verify the result.
Decide on Scope: Full or Phased
Based on your inventory, decide whether you will migrate your entire Confluence instance at once or take a phased approach. For smaller instances (under a few hundred spaces), a full migration is often practical. For large enterprises with thousands of spaces, a phased approach — migrating department by department or by space groupings — reduces risk and allows you to refine the process as you go. Each approach has trade-offs, and the right choice depends on your organization's size, risk tolerance, and timeline constraints.
Step 2: Prepare Your xWiki Environment
Before you can import Confluence content, you need a properly configured xWiki instance ready to receive it. There are two primary approaches to infrastructure.
Option A: Managed Infrastructure with MassiveGRID
MassiveGRID's managed xWiki hosting provides a production-ready xWiki environment on high-availability infrastructure, with the Java stack, database, and application server pre-configured and optimized for xWiki's requirements. This approach eliminates the need for your team to manage server provisioning, Java tuning, database administration, and ongoing maintenance. MassiveGRID's infrastructure spans data centers in Frankfurt, London, New York, and Singapore, supporting data residency requirements across major regulatory jurisdictions. For organizations focused on the migration itself rather than infrastructure management, this is the most efficient path.
Option B: Self-Hosted Deployment
If your organization prefers to manage its own infrastructure, you can deploy xWiki on your own servers or cloud instances. For a production deployment handling migration workloads, we recommend a minimum of 4 CPU cores, 8 GB of RAM (4 GB allocated to the Java heap), PostgreSQL as the database backend, and Java 11 or later. Storage should be provisioned generously to accommodate your attachment volume with room for growth. Our xWiki production installation guide covers the deployment process in detail.
Install the Migrator Pro Extension
Regardless of your infrastructure choice, install the Confluence Migrator Pro extension through xWiki's Extension Manager. This extension is available to organizations with an active xWiki Business or Enterprise subscription. For initial testing and evaluation, the free community Confluence Migrator can be used, though it lacks some of the advanced features (user mapping, permission migration, batch processing) that make the Pro version suitable for production migrations.
Step 3: Export from Confluence
The migration process begins on the Confluence side with a content export. The approach differs slightly depending on whether you are running Confluence Data Center/Server or Confluence Cloud.
Confluence Data Center and Server
Use Confluence's built-in Space Export functionality. Navigate to Space Settings for each space you want to migrate, select Content Tools, then Export. Choose the XML export format, and ensure that you include pages, blog posts, comments, and attachments. The export produces a ZIP file containing an XML descriptor and all attachment files. For large spaces, this export can take significant time and disk space — plan accordingly and ensure your server has sufficient temporary storage.
Confluence Cloud
Confluence Cloud also supports space export, accessible through Space Settings. The process is similar, though Cloud exports may have different size limitations. For very large Cloud instances, you may need to work with Atlassian support to obtain a complete export, or use the Confluence REST API for programmatic extraction. The Migrator Pro accepts the same export format regardless of whether it originated from Data Center, Server, or Cloud.
Export Best Practices
Export one space at a time rather than attempting a global export, as this gives you more control over the process and makes troubleshooting easier if an export fails. Verify each export by checking the ZIP file size and confirming that the XML file inside is well-formed. Store your exports on reliable storage with sufficient capacity — a large Confluence instance can produce hundreds of gigabytes of export data when attachments are included.
Step 4: Import into xWiki with Migrator Pro
The Confluence Migrator Pro provides a guided wizard that walks you through the import process. Each step in the wizard addresses a specific aspect of the migration, giving you control over how Confluence content maps to your xWiki environment.
Upload and Parse
Upload your Confluence export ZIP file to the Migrator Pro interface. The tool parses the XML content and builds an inventory of what the export contains: pages, blog posts, comments, attachments, users, and permissions. This parsing step gives you a preview of the migration scope before any content is actually imported, allowing you to verify that the export is complete and well-formed.
User Mapping
The wizard presents a user mapping interface where you align Confluence users with xWiki user accounts. If you have already configured LDAP or SSO authentication in xWiki, users may already exist and the mapping is straightforward. For users that do not yet exist in xWiki, you can create them during the migration or map multiple Confluence accounts to a single xWiki account where consolidation is appropriate.
Space Mapping
Confluence spaces map to xWiki spaces (also called wikis or sub-wikis depending on your xWiki topology). The wizard allows you to control the target location for each imported space, giving you the opportunity to reorganize your content hierarchy if desired. You can preserve the Confluence structure exactly or take the opportunity to restructure during migration.
Permission Migration
The Migrator Pro translates Confluence permission structures — space permissions and page restrictions — into xWiki's rights management system. Because the permission models differ between the two platforms, review the mapped permissions carefully. xWiki's permission system is hierarchical and granular, supporting inheritance patterns that may differ from what you had in Confluence. The wizard highlights any permissions that require manual attention.
Content Migration and Macro Conversion
This is the core of the migration: the actual transfer of page content, blog posts, comments, and attachments. The Migrator Pro converts Confluence's storage format to xWiki syntax, translating Confluence macros to their xWiki equivalents where possible. The migration progress is displayed in real-time, and any content that cannot be automatically converted is flagged for manual review.
Step 5: Understanding Macro Bridging
Confluence macros are one of the most nuanced aspects of any migration. Confluence and xWiki both use macro systems to embed dynamic content within pages, but the specific macros and their syntax differ. The Migrator Pro includes 31 bridge macros that handle the most common Confluence macro conversions automatically.
Common Macro Conversions
Confluence's Info, Warning, Note, and Tip panels convert to xWiki's message macros, preserving the visual distinction between information types. Code blocks convert to xWiki's code macro with language syntax highlighting preserved. The Table of Contents macro converts to xWiki's TOC macro. Expand/Collapse sections convert to xWiki's collapsible content components. Page includes and excerpts have direct xWiki equivalents. For most standard Confluence content, the macro conversion is seamless and requires no manual intervention.
Custom and Third-Party Macros
Macros from Marketplace apps require more attention. If a Confluence app provided a custom macro (for example, a diagramming macro from draw.io or a database macro from a structured data app), the Migrator Pro will preserve the content but may not be able to render it in xWiki's native format without the corresponding xWiki extension installed. During your pre-migration audit, you should have identified these dependencies, and the appropriate xWiki extensions should be installed before or during migration.
Handling Unmapped Macros
Any Confluence macro that does not have a direct xWiki equivalent or bridge macro will be preserved in its original form and flagged in the migration report. This does not mean the content is lost — it means it needs manual attention to either convert to an xWiki equivalent, replace with a different approach, or remove if the functionality is no longer needed. The migration report provides a complete list of these items, making it straightforward to work through them systematically.
Step 6: Post-Migration Verification
Importing content is only half the migration. Verification is what turns a technical data transfer into a trusted production system. Plan for a thorough verification process, and involve your end users — they know their content better than any automated check can.
Content Verification
Spot-check pages across every migrated space. Verify that text content, formatting, headings, tables, and inline images render correctly. Pay particular attention to complex pages with multiple macros, embedded content, or unusual formatting. Check that page hierarchy (parent-child relationships) is preserved correctly.
Attachment Verification
Confirm that attachments are accessible and intact. Open a sample of attachments across different file types (PDFs, images, Office documents, archives) to verify they are not corrupted. Check that inline images display correctly within pages. Verify that attachment versioning is preserved where applicable.
Permission Verification
Log in as users with different permission levels and verify that access controls are working as expected. Can restricted pages be accessed only by authorized users? Are space-level permissions enforced correctly? This step is critical for organizations in regulated industries where access control is a compliance requirement.
Link Verification
Internal links between pages should have been remapped during migration, but verify this by navigating through your content. Check that cross-space links work correctly. External links should be unchanged, but verify a sample to confirm they were not inadvertently modified during the format conversion.
Search Verification
Verify that xWiki's search index includes all migrated content. Search for known terms, page titles, and content within specific spaces. If search results are incomplete, the search index may need to be rebuilt — a routine administrative task in xWiki.
User Acceptance Testing
Before decommissioning Confluence, run both systems in parallel for two to four weeks. Ask representative users from each team to use xWiki for their daily work and report any issues. This parallel period catches problems that automated checks miss and gives users time to acclimate to the new platform before the old one is retired.
Step 7: How MassiveGRID Supports Your Migration
Migrating platforms is an infrastructure challenge as much as it is a content challenge. The xWiki application, the Java runtime, the database, the storage backend, and the network all need to be properly configured and optimized, both during the migration (which is resource-intensive) and for ongoing production use.
As an official xWiki hosting partner, MassiveGRID provides managed infrastructure specifically configured for xWiki deployments. This includes provisioning and configuring the server environment, optimizing the Java stack for xWiki's memory and performance requirements, configuring PostgreSQL with appropriate connection pooling and query optimization, and setting up the storage backend to handle your attachment volumes with room for growth.
During the migration itself, MassiveGRID's infrastructure can be temporarily scaled to handle the higher resource demands of large imports — additional CPU and memory for the Migrator Pro processing, additional I/O capacity for attachment transfers — and then right-sized for production workloads once the migration is complete.
Post-migration, MassiveGRID provides ongoing managed hosting with 24/7 monitoring, a 100% uptime SLA backed by high-availability infrastructure, automated backups, security patching, and performance tuning. Your team can focus on using xWiki rather than administering it. Our infrastructure operates across data centers in Frankfurt, London, New York, and Singapore, ensuring that your xWiki deployment meets your data residency and latency requirements.
Next Steps
If you are planning a migration from Confluence to xWiki, the most productive first step is to complete the pre-migration audit described in this guide. Understanding the scope and complexity of your Confluence environment will inform every subsequent decision, from infrastructure sizing to migration timeline to resource allocation.
To explore MassiveGRID's managed xWiki hosting and discuss how we can support your migration, visit our xWiki hosting page or contact our team directly. We have supported organizations through migrations of all sizes, and we are happy to share what we have learned about making the process as smooth as possible.
For a broader comparison of how xWiki and Confluence differ as platforms — beyond the migration mechanics — see our xWiki vs Confluence enterprise comparison. And if cost is a primary factor in your decision, our total cost of ownership comparison provides concrete numbers at various user scales.
Frequently Asked Questions
How long does a Confluence to xWiki migration take?
The duration depends on the size and complexity of your Confluence instance. A small instance with a few thousand pages can be migrated in a matter of days. A large enterprise environment with tens of thousands of pages, complex permissions, and extensive Marketplace app usage should plan for several weeks to a few months, including the parallel operation period. The technical import itself is typically faster than expected — the bulk of the time goes into the pre-migration audit, post-migration verification, and user acceptance testing.
What happens to Confluence macros during migration?
The Migrator Pro includes 31 bridge macros that automatically convert the most common Confluence macros to their xWiki equivalents. Standard macros like Info/Warning panels, Code blocks, Table of Contents, and Expand/Collapse sections convert seamlessly. Custom macros from Marketplace apps are preserved but may require manual attention or the installation of corresponding xWiki extensions. The migration report identifies every macro that needs manual review.
Can I migrate from Confluence Cloud, or only from Data Center and Server?
The Migrator Pro supports imports from both Confluence Cloud and Confluence Data Center/Server. The process is the same: export your spaces from Confluence in XML format, then import them through the Migrator Pro wizard. Cloud exports follow the same format as Data Center exports, so the import process is identical regardless of your source deployment.
Is the Confluence Migrator free?
xWiki offers two migration tools. The community Confluence Migrator is free and open-source, suitable for testing and evaluation. The Confluence Migrator Pro, which includes advanced features like user mapping, permission migration, and batch processing, is available to organizations with an active xWiki Business or Enterprise subscription. For production migrations, the Migrator Pro is strongly recommended.
Is the page hierarchy from Confluence preserved in xWiki?
Yes. Confluence's parent-child page relationships are preserved during migration. xWiki uses a hierarchical document model (Nested Pages) that maps naturally to Confluence's page tree structure. Spaces, parent pages, and child pages maintain their relationships, and xWiki's navigation reflects the same hierarchy your users are accustomed to.
What about attachments and images?
Attachments and inline images are included in the Confluence export and migrated along with page content. The Migrator Pro transfers all attachments to xWiki's storage backend and updates page references to point to the new locations. After migration, verify a sample of attachments across different file types to confirm integrity. Large attachment volumes may require additional storage provisioning on the xWiki side.
Can I migrate all spaces at once or do I need to go space by space?
Both approaches are supported. The Migrator Pro can process multiple space exports in sequence, allowing you to migrate everything in a single operation if desired. However, for large instances, we recommend a phased approach — migrating a few spaces at a time, verifying the results, and then proceeding. This approach is less risky, easier to troubleshoot if issues arise, and allows your team to refine the process as they gain experience with the migration tooling.
Written by MassiveGRID — As an official xWiki hosting partner, MassiveGRID provides managed xWiki hosting on high-availability infrastructure across data centers in Frankfurt, London, New York, and Singapore.