Knowledge management
Confluence to Polybase: A Practical Migration Guide
Moving from Confluence is a knowledge management project. The work is complete when people can find an authoritative document, understand who owns it and use it in the project where it matters. A folder of exported pages is a starting point, not the acceptance criterion.
This guide sets out a controlled Confluence-to-Polybase migration for teams that want documentation closer to conversations and tasks. Polybase supports DOCX import, shared document editing and full-text document search. The process below concerns reviewed documents; it does not imply a native Confluence space importer or automatic preservation of macros, permissions and page history.
1. Audit the knowledge you actually need
Ask each team to identify its essential operating documents: onboarding instructions, product specifications, customer handover notes and current procedures. For every page, record the source URL, owner, audience, last review and intended destination. Separate the person who created a page from the person accountable for its accuracy today.
Assign one of four outcomes: move, revise, merge or archive. Two conflicting procedures should be resolved before transfer; otherwise the new workspace inherits the same uncertainty. Start with a bounded set of frequently used documents whose owners can inspect the result.
2. Choose an export and test the document format
Confluence Cloud offers individual-page Word and PDF export through the page menu. Atlassian notes that Word exports require Microsoft Word and that unpublished page changes are excluded. Confirm the published content before exporting and consult the documentation for your edition.
For an editable Polybase document, open the Word export in Microsoft Word and save a genuine DOCX file, then test it with Polybase’s DOCX import. Renaming an extension is not conversion. Inspect headings, tables, images and links on a small sample before processing the rest. Keep a separate reference export where your retention policy requires one.
A PDF can preserve a useful reading copy, but it is a different deliverable from an editable knowledge-base page. Define which documents need ongoing collaboration and which only need to remain available for reference. For large spaces, agree on the conversion and validation method before committing to a bulk move.
3. Map page structure, macros and relationships
Design the destination around how people retrieve knowledge. A product team may need specifications beside project discussions; an operations team may need a procedure library with a clear owner for each document. Preserve useful hierarchy while removing abandoned branches and duplicate landing pages.
The table below is a review plan, not a list of automatically migrated features. Embedded Jira reports, dynamic macros and included pages deserve particular attention: visible content may be only a snapshot of something that previously updated live.
| Source element | Planned treatment | Acceptance check |
|---|---|---|
| Space and page tree | Destination channels, folders and documents | Readers can navigate to the right document |
| Text, headings and tables | Reviewed DOCX import | Meaning and essential layout are preserved |
| Macros and embedded reports | Recreate, replace or retain a dated reference | Readers understand whether the content is live |
| Attachments and internal links | Move required files and maintain a URL map | Files open and links reach the intended destination |
| Comments and version history | Separate reference or agreed preservation method | Required decision history remains accessible |
4. Rebuild permissions before inviting readers
Treat exported content and access rules as separate concerns. Define the intended audience in the new workspace and test ordinary member, restricted member and guest accounts where those roles are relevant. A successful check must show both that an authorized person can read the page and that an unauthorized person cannot.
Do not rely on matching group names between platforms. Record which people or teams should have access and check the destination settings directly. Pay special attention to a restricted child page moved beneath a widely visible folder. Review any file-sharing links separately from document access.
5. Repair links and establish the new source of truth
Maintain a source-to-destination URL register. Use it to update links from active project briefs, onboarding checklists, task descriptions and frequently used reference pages. Where you control the old page and can retain access, add a clear relocation notice. Do not promise automatic redirects for URLs controlled by another platform.
Choose a final editing window for each group of pages, capture changes made after the first export and ask content owners to approve the destination. Make the old version read-only where your configuration permits. Tell readers where future corrections belong so two competing versions do not continue to evolve.
After launch, ask a teammate who did not perform the migration to find the current procedure, identify its owner and follow its links. Measure unsuccessful searches, broken links and unowned pages. Review these exceptions regularly until the library works for its readers, rather than using document count as the only measure of completion.
- Each essential document has an owner and an agreed review date.
- Headings, tables and linked files have been checked on representative pages.
- Access checks include people who must not see restricted material.
- Active inbound links point to the new source or a clear relocation notice.
- Content owners approve the final version and know how to report a problem.
Frequently asked questions
Can a Confluence space be imported into Polybase in one click?
This guide does not describe a one-click space importer. It uses reviewed document conversion and DOCX import. Page hierarchy, macros, attachments, permissions and historical records require separate planning and validation.
Will Confluence macros and page history remain editable?
Do not assume that a document export preserves live macros or the original revision history. Decide which elements must be recreated and which can remain as reference material. Verify the chosen method with representative content.
Should Jira and Confluence be migrated together?
They can share a migration plan, especially when tasks link to specifications. Keep separate acceptance checks for tasks and documents, and maintain one URL register so relationships can be repaired even when the two systems move at different times.