On October 19th, we hosted our webinar “Introducing Confluence Migrator (Pro): Multi space import and other improvements”, where Ștefana Nazare, our Product Owner of Pro Apps and Confluence Migration Specialist, talked about:
- The newest migration tools we've developed in 2023, with an emphasis on the multi-space Confluence migrator;
- The necessary steps to take before and during the migration process;
- Your migration questions, to which she provided comprehensive answers to particular use cases.
Below you can find out more about the key takeaways, watch the recording, and read the transcript from the Q&A session.
Key takeaways
We are aware of the increasing need to migrate from Confluence these days. This is why we are continuously working on improving, maintaining and developing our migration tools so that you can benefit from a seamless transition experience. We've listened to your feedback and developed a new and improved Confluence Migrator on top of our existing essential kit of apps and macros. This is because one of our top goals is to make your migration as smooth and hassle-free as possible.
This webinar was the perfect opportunity to emphasize the main reasons why XWiki can be the open-source alternative to Confluence that you have been looking for. Additionally, we took the chance to explain what are the requirements you'll need to check for a successful migration to XWiki and gave an overview of our latest tools introduced this year. Finally, the migration demo and the Q&A session led us explore more in-depth some particular use cases and better explain the difference between our old and new Confluence Migrators. If you want to get a better understanding of the Confluence migration process, we recommend you to consult these resources as well:
Q&A session
Q1: How do I test the new Migrator?
The new Migrator can be installed from the Extensions Manager (Administration > Extensions) in your XWiki instance and a trial license can be applied from the License section (Administration > Extensions > Licenses). The trial license does have the limitation of allowing you to migrate only one space and 30 documents at a time and is available for one month. For offline XWiki installations, please contact us at sales@xwiki.com, and we will provide instructions on how to install the extension.
Q2: What's the difference between Confluence Migrator and Confluence Migrator (Pro)?
The Confluence Migrator is the old tool that allowed you to migrate one space at a time and perform numerous adjustments on the hierarchy, required in older versions of XWiki. In 2023, we focused on developing the new Confluence Migrator (Pro), which allows you to directly import your Confluence backup package and import multiple spaces at a time, including users, permissions (beta feature at the moment) and blog posts. Moreover, a detailed report of each migration is provided, allowing you to adjust pages affected by import issues, when required.
The Confluence Migrator (Pro) is now the recommended tool to be used to import data from Confluence to XWiki and is supported by our XWiki SAS dedicated teams. The single space Confluence Migrator is still available as a community extension and can be used for testing purposes, but it is not supported and not recommended for production usage.
Q3: Do you have the Task List macro supported?
Yes, we support both the Task List and the Task Report macros from Confluence through the Task Manager (Pro) application. In order to migrate inline tasks, Task List and Task Report macros, please make sure the Task Manager (Pro) is installed and has a valid license (trial or paid) before running the data import. This app can be now found in Confluence Migration Toolkit.
Q4: What issues should we expect during migration?
The most common type of error that we see in the import logs is caused by deleted pages on the Confluence side. If a page, version of a page or attachment has been deleted, a trail of that resource still exists in the entities.xml file and therefore XWiki tries to import it. If this type of error occurs, we recommend comparing the page in XWiki with its equivalent in Confluence, in order to make sure that no content is missing.
Another common error that may occur is related to the syntax used in Confluence. If you're using a special plugin for editing, such as block editing, it may produce a syntax that is not supported by XWiki. If this happens, the page can be modified on the Confluence side, or it can be recreated in XWiki using the available editing tools.
Q5: From where can I purchase the app?
You can purchase the app as part of a support plan. The Confluence Migration Toolkit is included in any Gold and Platinum support on-premises or Cloud plan. Moreover, all the other Pro Applications, such as the Task Manager (Pro) and Pro Macros, are included in this Toolkit as well.
1. Manual Purchase
If you would like to order technical support on premise or on Cloud (hosting and support) through a manual purchase order, please write us at sales@xwiki.com, mentioning your number of users, preferred deployment, size of your Confluence instance and company details. One of our Account Managers will get back to you as soon as possible with an offer.
2. Online Purchase
This method offers the most economical price, 23% discounted compared to the manual order. Moreover, if you're purchasing Cloud Gold or Gold Support on premise online in November 2023, you will benefit from an extra 15% discount.
To purchase Cloud online, please create a Cloud instance on try.xwiki.com, then click on “Buy XWiki Cloud” in your new instance. You will be redirected to the shop where you can select the number of users and service level and complete your purchase. For Gold level purchases, use the discount code “GoldConfluenceMigration” at checkout.
To purchase on premise technical support online, please go to the Extensions Manager in your XWiki instance and install XWiki Pro. Then, go to the Licenses section and click on “Buy” next to XWiki Pro. You will be redirected to the store, where you can make your users and plan selection, and then the shop, where you can finish the purchase. For Gold level purchases, use the discount code “GoldConfluenceMigration” at checkout.
Q6: Is there a list of supported macros to compare it to our Confluence instance?
On our website we have listed the most commonly used macros and their equivalent in XWiki. However, for a full comparison, please send us your list of macros (available in Confluence Administration > Macro usage) and we will get back to you with our input on each one of them.
Q7: Is the PDF export of multiple pages supported? It was not a couple of years ago.
Yes, we have a new technology for PDF export that allows you to select multiple pages and create an export of the respective pages. You can create other templates for PDF exports and customize them as needed.
Q8: Regarding macros that are not in XWiki, can we replace them by similar macros on all sites? Maybe an extension that goes through all pages to replace {{macro a}} by {{macro b}} would be great.
This feature is not yet available in a recommended tool such as the Confluence Migrator (Pro), but it is possible to achieve this by using snippets such as Bulk Replace. Please note that this snippet is not a recommended or supported feature. If you would like to have the need to replace certain macros addressed by an XWiki architect and further supported, along with any other migration assistance, please consider contracting consulting services.
Q9: Can users be imported using a full Confluence backup instead of space export? In the basic Confluence Migrator, users were not imported using space exports. If user import works, will the passwords also be imported? Can users use their old login?
With the new Migrator (Pro) you are able to import Confluence users and permissions (beta feature) using a backup package. Passwords will not be imported, therefore upon the first login the users will have to click on “forgot password” and create a new one using the link received on their email associated with the username. Please make sure an email server is configured with XWiki to allow for email sending.
Note that if the Confluence users are coming from a user directory such as LDAP or Azure AD, it is not necessary to import the users along with data. It is recommended to connect XWiki to the same user directory and the accounts will be created upon the first login.
Q10: How many spaces can be imported in one go? We have up to 300+ spaces to migrate.
It is not possible to give a definite answer as this depends on the resources allocated to the XWiki instance (memory and storage), along with the configuration (maximum import, timeout). In our tests and based on Client experience, we imported a maximum of 5-6 GB of data in one run. Please also note that if the package is very large, the analysis and import steps can take hours. If the instance is not restarted, the processes should run continuously, and you will be able to see the status on each migration on the Confluence Migrator (Pro) homepage.
Q11: If we have to split, how can I split the export in Confluence to let's say 30 spaces per export? Or can I upload multiple spaces and import them in one go?
We recommend making a list of all the spaces that you wish to import, along with their approximate size, then organizing them in sets of spaces based on links and size. For example, if we know that 10 spaces have about 500 MB each and that there are numerous links between them (for example, if they belong to the same department, say HR), we could mark them as spaces to be migrated in “HR migration”. Then, on the Confluence Migrator (Pro), we would upload the backup package, select it to start the migration, name the migration “HR migration” and wait for the analyzer to run. Once the list of spaces has appeared, we will select the 10 spaces identified previously and run the migration.
When we execute a migration, we make a list outside of Confluence and XWiki with the spaces, and we organize them usually by department, or organization or team that is ready to migrate first. Then, on the Confluence Migrator (Pro) side, the backup package has to be uploaded only once and each team or department can use it to migrate their data, in one or multiple batches, depending on the size of their spaces.
Q12: Can you tell us more about what the Permissions' migration would look like and how it maps to the Users & Rights section on XWiki?
Permissions migration is currently a beta feature in the Confluence Migrator (Pro) and can be tested. It allows you to migrate permissions along with users and content, or permissions alone. The permissions are taken from a Confluence XML server backup file and are applied on the same pages or spaces as they were in Confluence. Groups can be mapped to existing XWiki groups or created at the import step. Finally, it is not necessary to have the user already created on the XWiki side for the permissions' migration to run successfully.
Q13: Just to confirm, if we don't buy the Task Manager (Pro), any task reports/inline tasks will show “unknown macro”? Despite that, could we proceed with the rest of the migration?
Yes, that is correct. The Task Manager (Pro) is a separate application that allows you to manage tasks generally in XWiki. It was initially an application used for simple task management within XWiki, and then it was upgraded to also support migration from Confluence. If you're migrating from Confluence and you don't have this app, the inline tasks, Tasks Report and Task List macros will appear as unknown macros.
Q14: Are there other Confluence macros that the XWiki team is working on developing that we should keep in mind?
At the moment, the Pro Applications team is focusing on improvements on the Task Manager (Pro) and Confluence Migrator (Pro). However, some of the most recently released or updated macros are profile-picture, recently-updated, note, time and userList. The updates of each version can be found on the Confluence Migration Toolkit page in our store.
Macros can be developed upon request and can be sponsored by one or multiple Clients. If you are using a macro that must behave identically on XWiki as it did in Confluence, please reach out to us, and we will be glad to provide an estimate or resolution.
Q15: After we have finished migrating our spaces, do we need to continue paying for the Confluence Migrator (Pro) beyond the initial year license?
No, the purchase of the Confluence Migrator (Pro) offers a one-year license during which the Customer can migrate. Once the migration is done, the Confluence Migrator (Pro) is no longer needed and can be uninstalled. Compared to the other Pro Applications, that are commonly used daily, the Confluence Migrator (Pro) is an application that serves only the purpose of data migration and should not be used at length. Therefore, it has this universal price, independent of the number of users.
Q16: We are using the Confluence app “Comala Document Management” for workflows of documents. Is there a replacement for that in XWiki?
In terms of functionalities, we do have 2 applications in XWiki that can be used for managing workflows and publishing documents through a workflow.
- The Publication Workflow Application. This is the community extension, and it is also supported at the Gold and Platinum levels.
The Publication Workflow allows you to define a workflow where certain groups are contributors, moderators, publishers, viewers, and commentors. Then you can choose to create a document, assign it a certain workflow and then send it to review or moderation and the group that was assigned would receive the notification and would be able to take the document to the next step. And finally, the publishers can validate a document without publishing it or publish it to the new location. Moreover, the review UI allows you to set a review date and assignee for each published document.
- The Change Request Application, also a community extension supported at the Gold and Platinum levels.
The Change Request extension is more complex than the Publication Workflow as it allows users to request not only the edition of pages, but also creation and deletion. Furthermore, you can set individual users or groups as approvers, and they can approve changes or request further modification.
Q17: I imported a space and only a fraction of the pages were imported. Can you point me to the documentation on ways to address that?
This could have occurred for several possible reasons:
- If you imported the space with the Confluence Migrator (Pro) in trial mode, that would be normal as its trial mode is limited to one space per migration and up to 30 documents per migration.
- If your import was performed using a paid license for the Confluence Migrator (Pro), this would be addressed to the support team. For any purchased license, support, or support and hosting plan, the support team will address any instance in which an application or feature is not working as expected. Please reach out to the support team by clicking on the question mark icon in your instance – Report an issue
Q18: In the old Migrator it said to only use files below 1 GB, so that is fixed now as well it seems, isn't it?
For the new migrator, there's no specific limit for the backup package that is imported here. As mentioned previously, you just need to make sure that you have enough memory and storage on the XWiki instance. Moreover, depending on your XWiki distribution, please make sure the attachment upload limit is high enough.
Q19: Regarding PDF Export: Is there already a way to migrate existing PDF-Export templates which we use based on the popular K15 Scroll PDF Exporter?
Unfortunately, we do not have a default application for this, and we did not receive this request before. We would be happy to look into it and estimate its development upon request, if this is of interest to you.
Q20: Does the XWiki search pay attention to the permissions of the user using it?
Yes, and that is very important to mention here. Not only the search, but also the navigation bar, and generally speaking any macro that is listing pages or tasks will take into consideration the rights that the current user has. For example, if they are searching for a page that they don't have the right to see, that page will not be shown in the search results, neither in the search suggest nor in the main search page, no matter what filters they use. The same applies to the navigation bar. If there is a page that is not visible to the current user, the link to the page will not appear. And finally, in any list macro, such as “Recently updated” or “Task list” they will not see the link to the page as well.
Q21: Are “spaces” back? I saw XWiki had moved away from using this term in favor of “nested pages” a while ago, so I wanted to get the terminology correct. Thanks for your answer! I think it would be great to have a space directory/index.
We don't have a terminology that we enforce, and we don't have a company-level decision to call them “spaces”.
For us and for the users of XWiki outside the Confluence migration use case, we are still using first level pages or parent pages or nested pages and then children pages (the ones underneath).
However, when we're discussing with potential customers or customers that have migrated from Confluence to XWiki, we use the ​​​​​​term space more, referring to a root-level page, in order to ease a bit the introduction into XWiki.
Moreover, customers that migrate have the choice to either import all of their spaces into one wiki or create multiple subwikis. Pages and groups of pages can also be moved afterward to obtain any organization that works for you.
To sum up, both spaces and nested pages terms are accepted at the moment.
Q22: Are there any timelines for when we could expect the Permissions Migration feature to be moved from beta to recommended? It sounds very exciting!
It should become recommended between the beginning and the middle of November. As mentioned previously, most of the functionalities are available already, but we wish to test on more edge cases, larger sets of data and very difficult permissions setups, especially inherited permissions, before recommending it.
Q23: Is it possible to import a Confluence space or page again? If so, how is it handled?
Yes. We generally recommend keeping the configuration “DELETE EXISTING DOCUMENT Indicate if existing document should be deleted before importing the new one” to “true” so that the page is fully overwritten with the latest updates. In terms of procedure, if you have migrated most of the data and there is one space that contains a few pages that were updated, you can export only that space, or a few pages of that space, and use that export package in a new migration. At the import step, XWiki will see that the page exists and will overwrite it with the one in the package. Alternatively, you can choose not to delete existing documents and XWiki will import only the new versions.
Q24: We've noticed in our test imports that some links direct back to Confluence instead of within XWiki. I think this is part of how links can be created in Confluence (there are a couple of options: link to a page or link to a URL). Is there a way to check where these “broken” links are across an entire XWiki instance?
Yes, indeed, this is quite a common issue, depending on how the links were set and if they're relative or absolute. As part of Confluence Migration consulting, our architects are able to fix broken links. If you are interested in this service, please do not hesitate to write to us.
