Written by
Lorina Balan
, Digital Marketer
On November 28th, we hosted our live webinar, “A hands-on guide to migrating from Confluence: Why it’s more than just a technical shift,” where participants gained actionable strategies for transitioning their knowledge base to XWiki. Led by Ștefana Nazare, Product Owner of Pro Apps and a seasoned Confluence migration expert, the session provided attendees with essential tools and insights to ensure a smooth migration.
In this webinar, we covered practical approaches and real-world advice to make migrations efficient and stress-free. Here's a summary of what was discussed:
- An overview of the migration process, including what to expect at each stage.
- How to plan your migration effectively by prioritizing content and defining objectives.
- Tips to handle tricky elements like macros, permissions, and unique data structures.
- Strategies to minimize disruptions, reduce downtime, and preserve workflows during the transition.
- A live demo of the Confluence Migrator Pro, showcasing its capabilities to simplify the process.
- Expert insights during the Q&A session, addressing specific use cases and challenges.
Below you can find out more about the key takeaways, watch the recording, and read the transcript from the Q&A session.
Key takeaways
Migrating from Confluence to XWiki is a multifaceted process, but with the right tools and strategies, it can be an opportunity to unlock new possibilities for your organization. During the webinar, we explored not just the how but also the why behind a successful migration. Here are the standout insights:
#1 Plan ahead for success. From deciding on deployment environments to addressing macros, permissions, and plugins, thoughtful preparation ensures a smoother process. For example, reviewing your macro usage in Confluence helps avoid surprises and sets the stage for a successful transition.
#2 The Confluence Migration Toolkit simplifies even the toughest migrations, offering features like link mapping, batch migration for large instances, and support for permissions and attachments. These tools are equipped to handle everything from small wikis to multi-terabyte setups.
#3 Adapt to challenges with flexibility. Migrating isn’t a one-size-fits-all process. Whether handling tricky plugins or dealing with unsupported macros, XWiki offers both built-in solutions and the flexibility to customize for your unique needs.
#4 Build for the long term. With XWiki, you’re investing in an open-source platform that evolves with your organization. No vendor lock-in, no surprise changes—just the freedom to scale, customize, and innovate as your business grows.
With these insights, your migration can be more than a data transfer—it’s a chance to build a better, more flexible collaboration platform.
For those looking to go even deeper, XWiki offers a wealth of resources to support your migration journey. Whether you’re just getting started or looking to optimize your process, we recommend exploring these valuable tools:
Q&A session
Q1: We are migrating away from Jira at the same time as Confluence. Are you planning to offer macro/plugins for alternative systems, especially Open Project?
Yes, we do plan to have an integration with OpenProject. This has been discussed throughout the year, and development is expected to start in December or January. The integration will offer a way to handle macros and links between XWiki and OpenProject, similar to Jira-Confluence functionality. However, migration from Jira to OpenProject may still involve re-creating filters or custom fields, as a full identical migration is complex. Once completed, we’ll announce recommendations.
Q2: I know how to see what macros are available in my Confluence instance. Is there a way to see what macros are actually in use in my Confluence installation?
Yes, this can usually be done through the "Macro Usage" section in Confluence's administration settings. This feature lists all macros in use, the number of times they appear, and the specific pages where they are used. This list is particularly helpful when planning a migration, as it helps identify which macros will work out of the box in XWiki and which may require custom solutions.
Q3: My Confluence server crashed. It’s a small wiki, 50 pages, Windows updates. I was able to restore and get it running, but Confluence isn’t working anymore. What should I do?
For this type of issue, we recommend reaching out directly to us at contact@xwiki.com. Our team will need more details to investigate and assist, as the issue may require examining logs or specific configurations.
Q4: Does the Confluence Migration Toolkit trial last one month? Does it work with all the options?
Yes, the trial lasts for one month and provides access to most features. However, the Confluence Migrator Pro is limited to migrating up to 30 pages per run. If you try migrating a space with more than 30 pages, only the first 30 pages will be migrated. You can perform multiple migrations to test the tool's suitability.
Q5: Can we start at the Gold level and then drop to the Silver level after migration is complete?
While you can technically downgrade from Gold to Silver, it is not recommended for instances that involve Confluence migration. After migration, XWiki instances tend to be more complex due to bridge macros and imported plugins. The Gold support level ensures these complexities are addressed, whereas Silver does not cover migration-related issues, such as problems with bridge macros or custom plugins.
Q6: What is the maximum size of the import file?
There is no specific restriction on the maximum import file size. By default, attachments are capped at 100GB, but this can be adjusted in the XWiki instance's administration settings. For larger migrations, we recommend ensuring sufficient memory and storage. In cloud instances, temporary resource increases can be requested during the migration process. On-premise setups should allocate at least three times the size of the export in storage and adjust JVM memory accordingly.
Q7: We rely heavily on two-way links between Confluence pages and Jira issues. Is there a way to migrate such links?
- Existing links: Absolute links to Jira issues in Confluence pages will be migrated as-is and remain clickable.
- Jira macros: Links created using Jira macros are not currently preserved, but they can be converted into text-based references during migration.
- Alternatives: XWiki offers a Jira macro that allows integration and display of Jira data, such as issue lists or statuses, within XWiki pages. Additionally, we are working on an OpenProject integration, which will provide similar linking and issue-tracking capabilities.
Q8: I’m currently in the migration phase with trial licenses. The problem is I can no longer open or import PDF or open text files. What extensions are necessary for this to work?
If you're using Confluence macros like "view PDF," they should be converted to the “view file” functionality in XWiki. For attachments, make sure you import them along with the content. If you can't access PDFs, check that you're using the Pro Macros extension, as it handles PDF viewer functionality.
Q9: How do I assess whether all my Confluence data is compatible with XWiki?
Standard content such as text, titles, and commonly used macros (e.g., info or warning) is generally compatible and will migrate without issues. However, compatibility challenges can arise with third-party plugins and macros. The public documentation for the Confluence Migration Toolkit includes a detailed list of supported macros and suggestions for handling unsupported ones.
Q10: What common errors occur when migrating from Confluence to XWiki, and how can they be avoided?
Common issues include broken links when migrating content in batches, which can be fixed with scripts. Plugins, especially third-party ones like Scroll Versions and Content Formatting macros, may also cause issues. To avoid these, we recommend thoroughly reviewing your macros and plugins in advance, following a detailed migration plan, and use tools like the URL mapping feature to ensure link continuity.
Q11: Can live content syncs from Confluence be migrated? What about plugin compatibility?
XWiki has a replication application that can synchronize content between XWiki instances. While not identical to Confluence’s sync capabilities, it offers a viable alternative. Plugin compatibility depends on the specific plugin. Many Confluence macros have equivalents in XWiki, but some third-party plugins may require custom solutions.
Q12: Can Jira links and dynamic content like issue tracking be preserved in XWiki? What are the alternatives?
Jira links can be migrated, but XWiki doesn’t support Jira macros in the same way Confluence does. If you move away from Jira, we recommend transitioning to OpenProject, where we plan to develop an integration for more effective linking.
Q13: What’s the estimated complexity and time required for migration?
Answer: Migration timelines vary based on the size and complexity of the Confluence instance. For example:
- Small instances (e.g., 10GB) might take a few days.
- Large instances with plugins and custom work (e.g., 2TB) could take months. Key factors include the number of spaces, users, pages, and the plugins/macros involved.
Q14: How do I verify that all data was successfully migrated? Are there logs or reports to identify problematic pages or attachments for manual migration?
XWiki generates detailed logs and migration reports. These logs list errors, such as issues with specific pages, missing users, or broken links. Pages with errors or missing elements can be identified and manually addressed. Additionally, history retention allows you to roll back changes or reattempt migration for specific spaces.
