Webinar overview: From Confluence to XWiki - Migration tools demo

01 Apr 2022 5 min read

On March 30, we held our webinar "From Confluence to XWiki: Migration tools demo", where we showcased our new migration tools, some tips and tricks about migrating to XWiki, and, finally, held a demo on how to use the dedicated migrator to do in just a few quick, easy steps. Below you can watch the recording and discover some key takeaways to have in mind from the Q&A session.

Key takeaways

We know that migrating to a new tool is never easy and can become discouraging if there are continuous hiccups slowing down the process. With the latest influx of users we have been welcoming from Confluence, we have invested time and effort into making it as easy as possible to transition through a set of dedicated tools.

In this webinar, we highlighted the reasons why XWiki can be the right Open Source alternative to Confluence for you and how we worked to make the migration process as easy as possible. With our dedicated automated migrator and Pro Macros, you can import your Confluence content, all the while maintaining the look and feel of your instance. Here are a few useful links to check out:

Q&A session

Q1: Can you compare the Visual Realtime Collaborative Editor plugin with the Confluence editor? What is the status?

A: XWiki does have a Real-time editor, but it is still an experimental module. It can be used from version 13.10 upwards and it is a priority of our roadmap. You can check it out here.

Q2: Regarding the admin access needed for migration - is it Space Admin access or global Confluence Admin access (for Server Ed.)? My interest would be to delegate the migration to the Space Owners.

A: For Cloud and Data Center, full admin access is needed on the Confluence side if you want to be able to connect to the Confluence instance and get the API token. However, if that isn't an option you can still use the migrator but skip Step 2 (analyzing the pages in Confluence). 

Alternatively, you can ask the administrator to provide an API token and use the same token on multiple profiles.

For the Server Edition, you can use your user and password. 

Q3: Are there limits when it comes to export size? (1GB XML?)

A: We do not impose an official size limit, but we recommend keeping them under 1GB. Importing larger than 1GB attachments can cause issues, usually due to memory and timeout. However, a server configuration (higher resources) can fix this issue on-premise. If you are using XWiki Cloud, feel free to contact our team who will accommodate your instance with more resources.

Q4: What about attachments - are they included during the migration? What about the attachment macro and "include" macro? These are not listed on the web page.

A: For the attachment macro, the option to display attachments in XWikk is supported across the migration. There are also other macros such as View File/View Office/PDF Viewer macros that are supported and will properly display the content. Regarding the "Include Macro", specific versions of it can be converted in XWiki. However, it is not included in the list because it already existed in XWiki with the same name and we didn't have to create any additional bridges.

Q4: We also make heavy use of the excerpt macro to enable content sharing. Is there a replacement for this?

A:  You can use the "Include Macro" which also offers the option to only show a section of a page (e.g.: separate by headings). The "Excerpt Macro" is something we can further develop on request if needed, but at the moment it is not available.

Q5: What is the maximum size of a space the tool can handle?

A: There is no specific size in terms of pages or attachments. With the configuration that we recommend in the official documentation, we support up to 1GB, and larger files would need increased resources (either on your side or by contacting our team if you have XWiki Cloud).

Q6: Does the PDF export of large hierarchical page structures work in the current version?

A: In XWiki, you can export by default in several formats: PDF, Office, or  XML/HTML if you wish to migrate pages to another XWiki instance. If you export as PDF, you can choose what wish to include in the export: cover, table of contents, header, footer, comments, and attachments. The default look and feel of the PDF is simple but can be customized based on your branding and needs. Exporting multiple pages in PDF is not fully supported at the moment, but several community extensions are available: 

Moreover, this requirement can be achieved using the include macro

Q7: Are all Confluence macros taken into account?

A: No, we defined the most common ones (based on requests from Confluence users) and worked on developing those. You can see a list of the supported macros here. These macros can be used as standalone and can bring value to any use case.

Additionally, if you need to know which macros that you are using in Confluence are also available in XWiki, you can contact us and share your macros list from the "Macros Usage" section from your Confluence instance (in the Administration section). However, be aware that the macros counter might not always be entirely reliable - for example, if you are using certain templates for your space, the "Create from template" plugin may appear multiple times. 

Q8: People have been doing their own templating for a special look & feel for their space. Is that style also migrated into XWiki?

A: It depends. If it's based on layout, columns, and sections, these will be kept in XWiki. If you are using certain templates that are only available in Confluence, the final result might not look identical but certain macros will be recognized. Differences might appear in look and feel in the case of more complex macros. 

Additionally, you can extensively customize the look and feel of your XWiki instance - choose a new skin, customize the current one, set up rights, and more. You can take a look at our in-depth customization guide to learn more.

Q9: We have a relatively large Confluence instance with several hundred spaces. Would you advise migrating this into a large XWiki cluster or splitting them up over several XWiki instances? (on premise installation required)

A: In this case, we would need to know a bit more regarding your use case and the load on the server in order to make a recommendation. However, we do support clusters and can offer custom Cloud instances. It is also possible to only have one large XWiki instance with subwikis to organize all the content, but the requirements depend heavily on the use case.

Our general software and hardware requirements can be found here.

Q10: Can we run the migration assistant to migrate various Confluence spaces at once (or shall we migrate each space separately)?

A: At the moment, the migrator allows you to migrate one space at a time, as each migration profile is connected to a unique Confluence space. Multiple users may run migrations in parallel, on different migration profiles. 

Q11: What about user accounts and privileges (access to space and page)?

A: XWiki has a fine-grained rights management system. You can use it to manage view, edit, comment, script, admin and delete rights at multiple levels: global, subwiki, space, or page (we do not recommend managing rights per each page as it can become quite hard to follow). You can also set limitations such as CAPTCHA for comments and denying view rights to unregistered users). You can learn more about managing access rights in XWiki here

Q12: We also run Jira. People have used the integration between Confluence and Jira to have e.g. Jira diagrams are shown in Confluence (automatically updated). Is there a way of coupling XWiki with Jira in this manner?

A: XWiki does offer a Jira macro that allows connecting to a Jira instance and displaying issues with key, status, and summary. Showing charts is not yet available.

Q13: What about pages labels? Is there such a feature in XWiki and are they also part of the migration?

A: In XWiki, page labels are actually "tags", which you can add to a page. You can use tags to filter pages and view what we like to call a "cloud of tags" to find out what are the most prevalent tags on that specific instance. However, the tags that you import from Confluence will not show up in XWiki.

Q14: We have plenty of user macros (velocity). Can we create or migrate this also in/to XWiki?

A: Velocity macros are available in XWiki. If you have created custom macros on the Confluence side, you can recreate them in XWiki. Here is our guide on how to create macros in XWiki and how to use the velocity macro.

Q15: What do you do to validate the migration? Do users need to check page-by-page if everything is OK?

A: The validation actually happens during the migration itself (the checks at step 2 and step 5 which fix invalid sections). You can also take a look at the reports to see an overall summary of the import and validate which pages had issues. Additionally, you can check which macros are not available in XWiki with the List Macros tool from within the Migrator.

Q15 follow-up: Is there a way of doing incremental migrations?

A: If you would like to add pages from one space to another, then yes, it is possible. For example, if you have partially imported a space, it is possible to then import the rest through a new migration profile and choose whether to include them in the same space or at the home level (then move to the correct space). 

If you would like to migrate newer versions of pages previously imported, this can be done with the manual method of migration (filter streams convertor) so that the pages will be overwritten, not skipped. 

Q16: Do you support white/black listing of external target links?

A: Yes, it is possible if you have an XWiki Cloud instance and we can also make recommendations for it on-premise as well. If you are interested in our security policy and recommendations, you can check them out here.

Q17: We use draw.io macros in Confluence for diagrams - is this (or a similar one, with import) supported in XWiki?

A: In XWiki, we have a Diagram App based on Draw.io. It supports Gliffy meaning that when you import diagrams from Confluence, you will have the option to convert them into XWiki diagrams and further edit them. We also support the display of Balsamiq macros. For Draw.io, the bridge macro has not been created yet, but it can be developed on request.

Q18: According to the GitHub repository the Pro Macros look a little bit abandoned ever since the set of macros we have nowadays was added (and the details-macro was apparently removed?). Is there any kind of roadmap for the further development of the Pro Macros?

A: Regarding the "Details Macro", we had to remove it due to an issue between the macro on the Cloud version and the Confluence Server version. However, we will be working on a new one.

The already developed Pro Macros were sponsored and there is no new Confluence bridge macro included in our Pro Apps team's roadmap this year. We are more than happy to receive any kind of feedback and requests for further development. You can also contact us if you are interested in sponsoring any development for specific features, improvements, etc.

That is a wrap on our webinar on "Confluence to XWiki: Migration tools demo". If you have any other questions and would like to contact Ștefana, our speaker, and Confluence migration specialist, you’ll find her at: stefana.nazare@xwiki.com or you can book a call directly with her here.

You may also be interested in: