SharePoint to Confluence Migration: The Complete Technical Guide

There is no native migration path from SharePoint to Confluence. Atlassian does not offer a one-click import tool, a migration wizard, or any built-in connector that actually moves SharePoint data into Confluence storage. The Atlassian Community is direct about this: Confluence is not a replacement for SharePoint, since SharePoint is more of a file sharing app and Confluence is a wiki. Therefore, there's no direct migration path for it.

Confluence Cloud's built-in import paths cover Word documents, Google Docs, OneDrive, HTML, and CSV-to-database workflows — not SharePoint itself. (support.atlassian.com) Every method available requires custom API scripts, a third-party enterprise tool, or a managed migration service.

This guide covers the real methods for migrating SharePoint content to Confluence Cloud or Data Center, the hard platform constraints on both sides, and the data-mapping decisions that determine whether your migration preserves content or silently drops it.

For a detailed breakdown of getting data out of SharePoint before starting any migration, see How to Export Data from SharePoint: Methods, Limits & Migration Prep.

Why SharePoint to Confluence Migration Is Harder Than It Looks

SharePoint and Confluence solve fundamentally different problems, and their data models are incompatible at the storage layer.

SharePoint is a document management and intranet platform. Content lives in multiple forms: .aspx modern pages composed of Web Part JSON structures (canvasLayout → horizontalSections → columns → webparts), document libraries containing .docx, .pdf, and .pptx files with versioned metadata columns, and lists backed by typed columns. The Microsoft Graph SharePoint API has a few key differences with the CSOM APIs. The site resource maps to SPWeb. The root site (SPWeb) in a site collection has a siteCollection facet, which contains information about the SPSite.

Confluence is a wiki-first knowledge base. The Confluence storage format stores the content of pages, page templates, blueprints, blog posts, and comments. This information is for advanced users who need to interpret or edit the underlying markup of a Confluence page. Every page body is XHTML-based XML stored in the body.storage.value field. The Confluence storage format is "XHTML-based." Technically, it's XML, since the storage format doesn't fully comply with the XHTML definition. For example, Confluence includes custom elements for macros and other features. The term "XHTML-based" highlights that much of the storage format is similar to HTML.

When you move from SharePoint to Confluence, you are not just moving files from one server to another. You are translating static documents and structured pages into dynamic wiki pages. If you dump SharePoint Word documents into Confluence as attachments, the content won't be natively editable or searchable, and it won't benefit from Confluence's page tree hierarchy or macro ecosystem.

The structural mismatch runs deep:

• SharePoint sites have no equivalent container in Confluence beyond Spaces
• Document libraries have no Confluence equivalent — files either become page attachments or must be converted to native wiki pages
• SharePoint lists must be rebuilt as Confluence tables, databases, or integrated via macros
• Modern page Web Parts have no macro equivalents in most cases
• SharePoint's permission inheritance model (site → library → item) doesn't map cleanly to Confluence's additive permission model (global → space → page restrictions)

The mismatch gets worse when SharePoint pages depend on non-text web parts, embedded Microsoft 365 components, or custom SPFx logic. Microsoft Graph can give you text web part HTML, but it does not convert SharePoint-specific web parts into Confluence macros or layouts. (learn.microsoft.com)

Understanding SharePoint's current architecture is critical before mapping to Confluence. See The Modern SharePoint Architecture 2026: Transitioning from Subsites to Hub Sites for context on how Hub Sites, associated sites, and subsites affect your migration plan.

The "Connector" Trap: Why Integration Isn't Migration

When you search for SharePoint-to-Confluence solutions, the most visible result is the SharePoint Connector for Confluence on the Atlassian Marketplace. This app connects Confluence with SharePoint & OneDrive, allowing teams to work across both platforms without switching tools.

This is not a migration tool. It embeds SharePoint document libraries and lists inside Confluence pages via macros. This can be useful if you want to surface SharePoint content in Confluence without rebuilding the structure or losing metadata and access controls. It also helps avoid duplication, since the files remain in SharePoint but are accessible from Confluence. If your goal is a full migration into Confluence storage, you'd still need a manual or custom migration approach.

The practical problems:

• You still pay for SharePoint. The data never leaves Microsoft's servers. You are maintaining two enterprise licenses.
• No native searchability. Confluence's global search cannot index the text inside embedded SharePoint documents.
• Vendor lock-in. If you cancel your SharePoint subscription or uninstall the connector app, every Confluence page relying on that macro breaks immediately.

Use a connector if you need a transition period or a permanent hybrid model. Do not use it if the business goal is to shut down SharePoint storage, move files into native Confluence search and editing, rewrite links to Confluence pages, or stop maintaining two systems. In those cases, integration is only step zero. (community.atlassian.com)

Method 1: Manual Export and Import (The Slow Path)

For small migrations (under ~50 pages), manual migration is sometimes the pragmatic choice. Here's the honest workflow:

1. Export content from SharePoint — Download .docx files from document libraries. For modern pages, copy rendered content from the browser.
2. Import Word documents into Confluence — Confluence Cloud supports importing a single .docx file as a new page via the UI (Create → Import Word document). This converts basic formatting but strips SharePoint-specific metadata.
3. Download and re-upload attachments — Every image, PDF, and embedded file must be manually downloaded from SharePoint and uploaded to the corresponding Confluence page.
4. Rebuild the page tree — Recreate the parent-child hierarchy in the target Confluence space.
5. Fix broken links — All internal links pointing to SharePoint URLs must be manually updated to point to the new Confluence pages.

Confluence Word import limits

Confluence Cloud's Word import has specific constraints: a 5 MB single-file limit, 100 MB for attachments on a single import, and bulk import of up to 30 files / 50 MB total, with each file capped at 10 MB. Word shapes are replaced with placeholders, so complex formatted documents still need QA. (support.atlassian.com)

What breaks during manual migration

• Internal links: Every hyperlink between SharePoint pages points to the old SharePoint URL and must be rewritten
• Embedded images: Images stored in SharePoint's SiteAssets library won't travel with copy-paste
• Metadata: Created date, modified date, author attribution — all reset to "you, right now"
• Version history: Lost entirely
• Page hierarchy: Must be manually recreated in the Confluence page tree

HTML import as an alternative

Confluence Cloud has an HTML importer: upload a .zip containing a folder of .html files, with page media in folders named after each page. It preserves basic headings, links, tables, and images, but iframe is unsupported, code blocks fall back to plain text, and page-to-page links become ordinary hyperlinks rather than true Confluence links. (support.atlassian.com)

Method 2: The Legacy UWC Route (And Why You Should Avoid It)

The Universal Wiki Converter (UWC) appears in nearly every forum thread about SharePoint-to-Confluence migration. It's an open-source tool Atlassian once recommended.

The reality is harsh. It won't export the attachments but will point to the attachments on SharePoint. The UWC creates links back to SharePoint rather than physically moving files. Install Confluence 4.0 - 4.3.7. Let us call this ConfluenceTemp. Upgrade ConfluenceTemp 4.3.x to the target version (or latest if moving to cloud).

The workflow requires installing a legacy Confluence 4.x instance as an intermediate step, running the UWC against that, then upgrading the temporary instance or exporting spaces to XML and importing into your target Confluence. This is a fragile multi-hop process that most teams abandon mid-migration.

Our recommendation: Treat UWC as historical context. It is not a viable path for modern SharePoint Online → Confluence Cloud migrations.

Method 3: API-Based Migration (Converting .docx to XHTML)

For engineering teams with the capacity to write and maintain custom scripts, an API-driven migration offers the highest control. The pipeline has three stages: extract, transform, load.

Stage 1: Extract content from SharePoint

SharePoint content lives in multiple endpoint families. Your extraction script needs to handle each type separately.

For document libraries (.docx, .pdf, .pptx):

Use the SharePoint REST API or Microsoft Graph API to enumerate and download files:

# List files in a document library via SharePoint REST API
GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('Shared Documents')/Files
Authorization: Bearer {access_token}
Accept: application/json;odata=verbose

You can retrieve a folder inside a document library when you know its URL. For example, you can retrieve the root folder of your Shared Documents library by using the endpoint in the following example.

To download individual files:

# Download a file's binary content
GET https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Shared Documents/doc.docx')/$value
Authorization: Bearer {access_token}

For modern SharePoint pages (.aspx):

Use the Microsoft Graph Pages API with the canvasLayout expansion:

# List all site pages
GET https://graph.microsoft.com/v1.0/sites/{site-id}/pages/microsoft.graph.sitePage
 
# Get a SharePoint modern page with its canvas content
GET https://graph.microsoft.com/v1.0/sites/{site-id}/pages/{page-id}/microsoft.graph.sitePage?$expand=canvasLayout

This method supports the $select and $expand OData query parameters to help customize the response. For general information, see OData query parameters. You can use the $expand=canvasLayout query string parameter to include the content of an item when retrieving the metadata of an item.

The canvasLayout response returns a JSON structure of horizontalSections containing columns containing webparts, where each text web part has an innerHtml property. You'll need to parse these and stitch the HTML fragments together.

For SharePoint lists:

# Get list items
GET https://{site_url}/_api/web/lists/GetByTitle('Policies')/items
Authorization: Bearer {access_token}
 
# Get list item attachments
GET https://{site_url}/_api/web/lists('{list-id}')/items({item-id})/attachmentfiles

Stage 2: Transform content to Confluence storage format

Confluence pages require content in XHTML-based storage format. You cannot POST raw Markdown or standard HTML. For .docx files, the conversion pipeline is:

1. Convert .docx → HTML using Mammoth or Pandoc
2. Clean and adapt the HTML to conform to Confluence storage format rules
3. Extract embedded images and prepare them for separate attachment upload

Mammoth is designed to convert .docx documents, such as those created by Microsoft Word, Google Docs and LibreOffice, and convert them to HTML. Mammoth aims to produce simple and clean HTML by using semantic information in the document, and ignoring other details. For instance, Mammoth converts any paragraph with the style Heading 1 to h1 elements, rather than attempting to exactly copy the styling.

import mammoth
 
with open("document.docx", "rb") as docx_file:
    result = mammoth.convert_to_html(docx_file)
    html = result.value          # The generated HTML
    messages = result.messages   # Warnings about unsupported elements

The HTML output from Mammoth needs post-processing before it's valid Confluence storage format:

• Remove any class or style attributes not recognized by Confluence
• Convert <img> tags with base64-encoded data to attachment references using <ac:image> macros
• Wrap tables in Confluence-compatible markup
• Replace <a href="sharepoint-url"> links with updated Confluence page links

For SharePoint modern pages, the innerHtml from text web parts is closer to standard HTML, but still needs sanitization and conversion to Confluence storage format tags.

Use Sharepoint Cloud API to get data and then convert it into xHTML and create pages. Or you can download the documents from Sharepoint and use some converters to save them as HTML and then convert this HTML into Confluence Cloud format and create pages.

Stage 3: Load into Confluence via REST API

Create pages using the Confluence Cloud REST API v2:

POST https://your-domain.atlassian.net/wiki/api/v2/pages
Content-Type: application/json
Authorization: Basic {base64(email:api_token)}
 
{
  "spaceId": "<target-space-id>",
  "status": "current",
  "title": "Migrated: Original Page Title",
  "parentId": "<parent-page-id>",
  "body": {
    "representation": "storage",
    "value": "<p>Your converted XHTML content here</p>"
  }
}

Upload attachments separately using the attachment API, then update <ac:image> references in the page body to point to the uploaded attachment filenames:

POST /wiki/rest/api/content/{page-id}/child/attachment

A note on timestamps and authorship: The Confluence v2 page-create schema does not document a createdAt field, even though page responses include createdAt and authorId. The blog post API does document createdAt, making it a better target for chronologically important SharePoint news posts where original publish-date preservation matters. For regular pages, store source author, date, and source URL in labels, a visible metadata table, or content properties as a workaround. (developer.atlassian.com)

API rate limits you'll hit

Enforcement of the new points-based API rate limits and tiered quota rate limits for Jira and Confluence Cloud apps will begin on March 2, 2026. This change is designed to ensure consistent performance and fair usage. Confluence Cloud uses a points-based model to measure API usage. Instead of simply counting requests, each API call consumes points based on the work it performs — such as the amount of data returned or the complexity of the operation.

On the SharePoint side, Microsoft Graph will return 429 Too Many Requests if you hit the tenant-level throttle. Both platforms require retry logic with exponential backoff.

Distribute requests over time: Spread your requests evenly throughout the hour, rather than sending large bursts at predictable intervals. Apply random jitter: Add a random delay to scheduled jobs to avoid many apps hitting the API at the same time. Coordinate across threads and nodes: Share rate limit status between threads or servers to prevent accidental quota exhaustion.

Engineering rerunnability from day one

For large migrations, build idempotency into the pipeline. SharePoint REST uses ETags for list items and documents — keep the SharePoint item ID plus ETag or last-modified value on the target side. This lets you skip unchanged items, avoid duplicates, and safely rerun delta syncs. Stamp every Confluence page with the SharePoint source ID and modified timestamp so you can detect what changed between runs without creating clones. (learn.microsoft.com)

Data Mapping: Translating SharePoint Architecture to Confluence

This is where most migrations fail silently. A sloppy mapping results in content that exists in Confluence but is unfindable.

Structural mapping

Coming from SharePoint 2016, it's tempting to copy libraries and folders 1:1, but Confluence works quite differently. Decide which SharePoint libraries/lists are still relevant and which can be archived instead of migrated. Next, redesign the structure. Map libraries/folders to Confluence spaces and page trees so that people can actually find things later, rather than mirroring a deep folder hierarchy.

Using CSV and Excel as staging formats

CSV and Excel are good staging formats, not full-fidelity migration formats. Use them for list data, metadata manifests, redirect maps, permission matrices, and content inventories. SharePoint can export list views to Excel or CSV, but CSV export is capped at 30,000 rows and is not available for document libraries. (support.microsoft.com)

On the Confluence side, databases can import CSV files, using the first row as field names and letting you match columns to existing fields. This makes CSV a solid target for SharePoint list data — but not for article bodies or rich page content. (support.atlassian.com)

A practical pattern: export list data to CSV, clean and normalize it in a staging table, import tabular data into a Confluence database, and use that database as the index for richer pages created separately via API. That gives you searchable structure without forcing every record into a flat spreadsheet model.

Permission mapping

SharePoint and Confluence handle permissions in fundamentally different ways.

SharePoint uses an inheritance-based model: permissions cascade from site collection → site → library → item. Breaking inheritance at any level creates unique permissions for that object. Groups follow the Owners/Members/Visitors pattern with granular permission levels.

Confluence uses an additive model: There are three levels of permissions in Confluence: global permissions, space permissions, and content restrictions. Confluence permissions are additive. This means that if someone is in two groups, and one group has permission to view a content item while the other does not, that person will still be able to view the content item because at least one of the groups they're in has permission to view it. Confluence's permissions model is set up so that content can only be further restricted from whatever the container is set at. A content item cannot have greater access than its container.

Mismapping permissions can expose sensitive HR or financial data to the entire company. Confluence also exposes that a restricted page exists — users see the link but hit an access-denied screen. That means truly sensitive content often migrates better into separate spaces than into one large space with page-level exceptions. (support.microsoft.com)

For a deep dive into SharePoint's permission model and how to audit it before migration, see The Definitive Guide to SharePoint Permissions & Security (2026 Edition).

Web Part to Macro mapping

Most SharePoint Web Parts have no direct Confluence macro equivalent. Here are the realistic mappings:

Think in classes, not in one-to-one widgets: text web parts become native page body, list web parts become databases or tables, Office file embeds map to attachments plus Smart Links, and custom SharePoint web parts almost always need manual rebuild.

Handling Attachments, Images, and Broken Links

These are the three failure modes that turn a technically complete migration into a practically broken one.

Attachments

SharePoint stores files in document libraries with versioning, metadata columns, and co-authoring state. Confluence stores files as page-level attachments with version history but no custom metadata.

The default is 100 megabytes, expressed as 104857600 bytes. — this is Confluence Cloud's default maximum per-attachment size. Files larger than this limit must be split or stored externally.

The critical decision for each document library is attach vs. convert:

• Attach as-is: PDFs, large spreadsheets, and files people download — attach them to a Confluence page
• Convert to native pages: Word documents that people read inline — convert .docx → XHTML and create native Confluence pages for full searchability

Convert Word docs to Confluence pages where it helps search; keep large files as versioned attachments.

Legacy tools like UWC and integration connector apps both fail here in the same way. UWC explicitly creates links back to SharePoint rather than physically moving files. Connector apps keep files in SharePoint by design because they are integration products, not migration engines. If your goal is to leave SharePoint, every attachment needs to be physically uploaded into Confluence and re-referenced from the new page body.

Images

Images embedded in SharePoint pages (stored in SiteAssets or inline in page content) must be:

1. Downloaded from SharePoint
2. Uploaded as attachments to the target Confluence page
3. Referenced in the page body using Confluence's <ac:image> storage format:

<ac:image ac:alt="Diagram">
  <ri:attachment ri:filename="architecture-diagram.png" />
</ac:image>

Images embedded in .docx files can be extracted during the Mammoth conversion step — Mammoth outputs them as base64-encoded <img> tags by default, which you then decode, upload as attachments, and rewrite to <ac:image> references.

Word import via the Confluence UI supports a defined set of image types and replaces unsupported images with placeholder text. HTML import ignores unsupported media. In API migrations, treat inline images as first-class objects: download them, upload as attachments, then rewrite the reference in a second pass after the target page ID exists. (support.atlassian.com)

Internal link rewriting

This is the hardest part. Every internal link in your SharePoint content points to a SharePoint URL like:

https://contoso.sharepoint.com/sites/Engineering/SitePages/API-Guidelines.aspx

After migration, the equivalent Confluence URL will be something like:

https://contoso.atlassian.net/wiki/spaces/ENG/pages/12345678/API+Guidelines

You need a URL mapping table — a lookup that maps every old SharePoint URL to its new Confluence page ID. Build this table during the migration as each page is created, then run a post-migration script that scans every Confluence page body for old SharePoint URLs and replaces them.

Links to files within document libraries that are now attachments need a different rewrite pattern pointing to the Confluence attachment URL. SharePoint page APIs expose webUrl; Confluence page responses expose web UI links. Once that map exists, you can scan the imported body for old SharePoint links and replace them deterministically.

For teams looking at bidirectional syncing or moving data the other way, see Confluence to SharePoint Migration: Methods, Limits & Macro Mapping.

Method 4: Enterprise Bridge (CaseAgile)

Enterprise Bridge is the most commonly referenced third-party tool for SharePoint → Confluence migrations. Enterprise Bridge supports Confluence on premise servers and Confluence online, SharePoint 2010, 2013, 2016, 2019 and SharePoint Online. It transfers text, images, tables, wiki pages, documents, files, videos etc.

It offers automated conversion with metadata preservation and supports two-factor authentication. Links to other SharePoint pages and documents (Related Articles) remain intact when migrated to Confluence.

The trade-off: Enterprise Bridge is an on-premise enterprise tool designed for large, compliance-heavy environments. It requires infrastructure to run and is priced for enterprise budgets. For smaller or cloud-first teams, it can be overkill.

Method 5: Managed Migration with ClonePartner

For teams that need the migration done right without building and maintaining custom scripts, ClonePartner handles SharePoint → Confluence migrations end-to-end.

What this looks like in practice:

• API-to-API migration — content is physically moved into Confluence storage, not linked back to SharePoint
• Automated .docx → XHTML conversion — Word documents become native, searchable Confluence pages
• True attachment migration — every file is downloaded from SharePoint and uploaded to the correct Confluence page via API
• Internal link rewriting — SharePoint URLs are programmatically replaced with Confluence page links
• Permission mapping — SharePoint site permissions are translated to Confluence space and page restrictions
• Zero downtime — your team keeps working in SharePoint during the migration; the cutover is coordinated

Establish secure API connections between your SharePoint and Confluence accounts. All communication is encrypted and credentials are stored using AES-256 encryption.

We separate the process into discovery, mapping approval, pilot migration, full load, delta sync, and QA — so the final cutover is boring on purpose. We've seen the edge cases that break DIY scripts: nested permission inheritance, orphaned pages, .docx files with embedded OLE objects, SharePoint pages with 20+ Web Parts. These are the failure modes we've already solved.

Post-Migration QA and Validation Checklist

A migration is only successful if the content is usable after the move. Run these checks before declaring the migration complete.

Content integrity

• Page count audit — Compare the number of migrated pages against your source inventory. Every page should be accounted for (migrated, archived, or intentionally excluded).
• Attachment count audit — Verify attachment counts per page match the source. Missing attachments are the most common silent failure.
• Sample rendering check — Open 10–15% of migrated pages in the Confluence editor. Look for broken formatting, missing images, and garbled tables.
• Search verification — Search for known terms that exist in migrated content. If Confluence search doesn't return expected results, page body content may not have been stored correctly.

Link integrity

• Internal link scan — Run a script or use a link checker to find any remaining sharepoint.com URLs in Confluence page bodies.
• Attachment link check — Verify that links to attached files resolve correctly.
• Cross-space link check — If you split one SharePoint site into multiple Confluence spaces, verify that cross-space links work.

Permissions

• Space permission audit — Verify that each Confluence space has the correct groups and permission levels assigned.
• Page restriction spot-check — For pages that had restricted access in SharePoint, confirm the restrictions carried over.
• Anonymous access check — Ensure no pages are accidentally exposed to anonymous users if your Confluence instance allows public access.

Metadata and hierarchy

• Page tree validation — Confirm the parent-child hierarchy in each Confluence space matches your intended structure.
• Label verification — Check that SharePoint metadata (tags, categories) migrated as Confluence labels.
• Author attribution — If author preservation matters for compliance, verify the createdBy fields.

Idempotency and delta checks

• Rerun the pilot set — Prove that rerunning the migration script doesn't create duplicates, cause label drift, or break restrictions.
• Delta rehearsal — Run a delta sync using only changed items. If it creates duplicates or drops restrictions, fix the pipeline before go-live.
• Confirm navigation and search with business owners — not just admins.

Performance Considerations for Large-Scale Migrations

For organizations with thousands of pages and hundreds of gigabytes of attachments, a few constraints become critical:

• Confluence Cloud API rate limits are points-based and shared across your tenant. Rate limiting controls how many API requests your app can make to Confluence Cloud within a given time period. This ensures platform stability, fair resource allocation, and a reliable experience for all users. Plan for migration windows that spread API calls across hours, not minutes. Note that Atlassian's new points-based rate limits started enforcement on March 2, 2026 for Forge, Connect, and OAuth apps, while API-token traffic remains on existing burst limits.
• SharePoint throttling applies to large-scale reads. Microsoft Graph will return 429 Too Many Requests if you hit the tenant-level throttle. Implement retry logic with exponential backoff and honor the Retry-After header.
• Attachment upload time dominates large migrations. A library with 50GB of files will take significantly longer to upload than the page content itself. Parallelize attachment uploads where the API allows.
• Confluence Data Center has configurable rate limits per node. When automated integrations or scripts send requests to Confluence in huge bursts, it can affect Confluence's stability, leading to drops in performance or even downtime. With rate limiting, you can control how many external REST API requests that automations and users can make.

Choosing the Right Method for Your Migration

The honest answer for most teams: if you have more than 100 pages with attachments, custom scripts become a maintenance burden and manual migration is too slow. That's the window where a managed migration service pays for itself in time saved and errors avoided.