On November 9, we held our webinar "From Confluence to XWiki: Latest migration tools demo", where Ștefana Nazare, Product Owner of XWiki Confluence Migrator & Pro Applications:
- Highlighted the newest migration tools our team has developed in 2022;
- Went through a step-by-step migration guide covering different use cases;
- Discussed extensively your questions and the compatible macros that support the migration from Confluence to XWiki.
Below you can watch the recording, learn about the key takeaways, and read the transcript from the Q&A session.
Key takeaways
We know from first-hand experience that migrations can be an IT nightmare when not done properly, with adequate resources and support. This is why we have allocated time and effort to make transitioning from Confluence to XWiki as smooth as possible, by providing a dedicated migrator, as well as multiple macros that are commonly used with Confluence. Our aim is to ensure a smooth migration process for your team and organization by giving you full visibility for each step of the switch, including when dealing with macros.
In this webinar, we highlighted the reasons why XWiki can be the right Open Source alternative to Confluence for you, and we deep-dived into the latest improvements, discussing in-depth all the necessary steps to successfully complete your migration. Here are essential resources on the topic that you can check out:
- Confluence migrator
- Compatible macros list
- Confluence migration guides
- Confluence resources and services
- Pro Macros package
Q&A session
Q1: To test XWiki, I used a docker image already. After starting with an empty wiki I installed the Admin extension and the extension manager. From the extension manager, I installed the Confluence Migration tool. But without creating any website and without starting the migration I had a high CPU load. I noticed increasing and decreasing cache file size. How can this happen and how can I prevent this? This behavior prevents me from testing XWiki.
Unfortunately, it is difficult to answer this type of question without seeing the instance and the logs. It is not a common issue that we have heard of.
If you have a support contract you can raise any issue to the support team or to your dedicated Account Manager and they will investigate and fix the issue in the shortest time possible.
Q2: We have created several custom macros with Velocity templates in Confluence. What programming models are available for creating custom widgets in XWiki? What are the significant high-level differences between the way Confluence and XWiki work, especially from an advanced content creator perspective?
Extensibility and flexibility
XWiki allows you to create new features and customize existing ones, be they core features or extensions. Administrators have access to the full code and configuration files and can customize the product however they need.
Structured data
In XWiki, you have the option to create data structured (App Within Minutes) that allows you to create simple applications or forms or structured pages. For pages that have content and metadata, you can use the metadata to navigate across the instance and filter search results. For example, for SNCF, we have implemented a troubleshooting wiki in which pages are created using a structured page template, containing metadata fields for train series, error code and other information. This way, they can easily find the proper troubleshooting document based on the train's information. That is a unique feature of XWiki.
Scripting
- dedicated wiki editor and syntax highlighting
- REST API
- documentation, community, and forum
Administration
- fine-grained permissions system -> manage view, edit, comment, script, delete and admin rights per page, space, wiki or at the global level.
- full access and flexibility in managing installation, performance, upgrades, configuration, look&feel, authentication, and extensions.
Q3: Are the page hierarchies maintained after the import?
Yes, this is achieved through the "Nested Pages Migration", the last step of the Confluence Migrator. The nested pages migration is there to recreate the hierarchy that you have in Confluence.
Q4: Does the Importer work with sub-wikis?
Yes, this is one of the latest improvements done on the Confluence Migrator. You can now install the Confluence migrator at the farm level or on sub-wikis where you wish to import content from Confluence. This can be particularly useful if you prefer to map Confluence spaces to XWiki sub-wikis and manage them independently.
Q5: What is an appropriate alternative to the Page Properties and Page Properties Report Macro from Confluence?
The App Withing Minutes (Structured data) functionality allows you to create pages with metadata and then sort and filter those pages based on their information.
It is also possible to sponsor the development of the Page Properties and Page Properties Report macros in XWiki if you would like to have in XWiki the identical behavior as you did in Confluence. Other examples of bridge macros can be found in the Pro Macros bundle.
Q6: Can I combine OIDC login with LDAP group authorization?
The Active Directory application allows you to easily connect your Active Directory server to XWiki using a visual editor. A connection needs to be set between XWiki and Active Directory in order to synchronize their users and groups. Active Directory users will be able to authenticate in XWiki and a dedicated XWiki user will be created at the first login. Alternatively, users can also be imported.
As part of the configuration of the application, an OpenID Connect related object can be added to the profile of the newly created user, in case any OpenID Connect Authenticator is installed in the main wiki. However, the OpenID Connect authenticator has its own group membership synchronization system that can be enabled.
Q7: Can the import be entirely programmatic, like performed by calling REST API methods? We have a few hundred spaces and cannot migrate them manually.
This would be a great use case for the Pro Migrator, the future extension that will allow administrators to migrate multiple spaces at once, which will be released in early January.
Strictly speaking of REST APIs, according to your analysis it would not be possible to import entirely based on them as some resources are not easily accessible and it can cause compatibility issues depending on the Confluence version.
Two reasons why we prefer to have a migrator that allows you to import multiple spaces at once, but not everything at once:
- we need to make sure that we have enough resources and that we don't run out of memory or out of storage, which can happen if you have multiple large spaces,
- it's very important to have a report of what happened during the import so that we can fix potentially broken pages.
Q8: I apologize if this was already mentioned, but, is this an extension? If so, can someone please provide a link?
You can install the Confluence migrator in the Extension Manager of your XWiki instance.
Q9: Is there something like a matching table between Confluence Add-Ons and XWiki Extensions? I guess the extensions do not exist with the same name. Or maybe there are only similar but not identical extensions.
We have on our website a new page that lists the macros that we saw being used most on Confluence and their equivalent on the XWiki side.
On another note, usually, when we analyze Confluence migration projects we ask the Client to provide the full list of the Confluence add-ons that they are using and then we get back with the input on all the add-ons such as:
- Identical macro exists or supports migration;
- Alternative macro exists but the content will not be displayed properly upon import because further changes need to be done;
- No similar functionality exists.
Most commonly, at least a similar functionality exists if the identical macro does not.
Q10: Are Balsamiq Makros only displayed or can I edit them within XWiki?
For the moment they are only displayed, but the attachment of the image and Blasamiq file are also imported.
Q11: Since when does DrawIO exist? I imported it some months ago, but it was not working. Have the DrawIO macros been converted to the diagram macro?
The Drawio macro is one of the most recent from the Pro Macros package, available since September. If you want to follow the progress on the Pro Macros you can follow this repository as well. The macro allows you to display Drawio diagrams in XWiki and then, if you want to edit them, you can convert them to XWiki diagrams.
Q12: What about the Tasks feature from Confluence?
The Task module and the Task report macro are currently being developed. We expect them to be released in a couple of weeks.
Q13: We have many forms in our confluence pages via the Latex plugin. Is it possible to import these? Or is it planned for the future?
Unfortunately, it is not planned at the moment. We only saw one or two use cases where the Latex plugin was being used on the Confluence side. If needed, it can be developed upon request.
Q14: Is there a rule of thumb to check whether the installation is complex/big or not?
Simple migration:
- up to 30 spaces
- no custom features
- recent version of Confluence
- using commonly used macros
- less than 100 users
Complex migration:
- hundreds of spaces
- custom features or usage of lesser-known macros
- custom authentication
- multiple connections between pages
Q15: The size limit for space export is 1GB. Does this include Attachments? How can we migrate bigger spaces?
We recommend splitting large spaces into multiple exports of up to 1GB. Also, it is important to allocate at least 3-4 GB of RAM and 20 to 50 GB of storage if you plan to execute large migrations.
Q16: We are planning to migrate from Confluence to XWiki. Are there recommendations on things to avoid already or change before the migration activities will begin?
- Decide on the metadata and page assets that you would like to keep (history, attachments, creator)
- Decide if you will migrate the users and plan their migration
- Look at the macros that you are using and check if the most used ones are available in XWiki
- Setup an XWiki instance with enough resources to execute the migration
- Stop using the Confluence instance while executing the migration in order to prevent having to execute the migration on the same space multiple times
- Create a migration profile for each space and consult the results on the Step 2 report before importing the pages
Q17: We're migrating different spaces. What about links between those spaces?
Relative links between Confluence pages are properly imported and displayed into XWiki after the migration.
Q18: I use the Page Properties macro in several places. I don't see that listed on the Confluence macros alternative list.
The Page Properties and Pare Properties Report macros do not exist yet in XWiki. An alternative functionality is the App Within Minutes.
Q19: Are there Macros or extensions available that support multiple languages (i.e. English and German pages)?
XWiki can be configured to be a multilingual wiki. Learn more about how to set up multiple languages on your wiki on this documentation page.
