1. Overview

Migrating from Atlassian Confluence to Microsoft SharePoint Online represents a significant transition for team collaboration and document management. While moving content between these platforms is often a complex process, the Confluence-to-Sharepoint migration tool simplifies and automates this journey.

Designed to process Confluence spaces independently, this solution converts Confluence pages, blog posts, attachments, comments, and nested page hierarchies into SharePoint modern Site Pages. It handles the extraction, HTML transformation, file uploads, link rewriting, and navigation setup automatically, ensuring your team has a seamless transition with minimal downtime.

2. Key Features

• Hierarchy Preservation: Recreates the multi-level page tree structure of Confluence in SharePoint using left sidebar navigation, breadcrumbs, child page lists, and a site map.
• Fidelity Transformation: Converts Confluence formatting, tables, inline images, code blocks, and custom status badges into clean, modern SharePoint-compatible HTML.
• User Identity Resolution: Maps Confluence accounts to Microsoft 365 users to attribute page authorship and convert @mentions into clickable profile links.
• Link Rewriting: Automatically updates internal links and cross-space links to point to their new SharePoint locations post-migration.
• Resumable Operations: Tracks migration checkpoints so the tool can resume from where it left off in case of network interruptions.

3. Working Procedure

The tool operates in four main stages to migrate a Confluence space to SharePoint Online:

1. Extraction: Connects to Confluence Cloud using an API token and extracts pages, attachments, comments, metadata, and space hierarchy data.
2. Transformation: Parses page content, translates Confluence-specific macros, downloads images and attachments locally, and converts text to SharePoint-compliant HTML.
3. Upload: Generates modern SharePoint Site Pages via Microsoft Graph API and saves attachments to dedicated per-page folders in the SiteAssets library.
4. Post-Migration Processing: Re-scans pages to repair links, creates navigation elements (QuickLaunch sidebar links and breadcrumbs), populates custom metadata columns, and performs validation.

4. Prerequisites and Permissions

To successfully execute the migration, specific accounts, permissions, and environments must be prepared in advance.

4.1 Confluence Side Requirements

An API token must be generated for a Confluence account with read access to the spaces being migrated.

• API Token Generation: Log in to Confluence, navigate to Account Settings > Security > API tokens, click Create API token, and copy the token.
• Access Scope: The migrating account must have full permissions to view all spaces, pages, comments, and attachments within the migration scope. Read-only permissions are sufficient.

4.2 SharePoint and Microsoft 365 Side Requirements

The tool authenticates with SharePoint using a Microsoft Entra ID (Azure AD) App Registration.

• App Registration Setup:

  1. Navigate to the Azure Portal > Microsoft Entra ID > App registrations and register a new application.
  2. Save the Application (client) ID and Directory (tenant) ID.
  3. Generate a client secret under Certificates & secrets and save the value.

• API Permissions (Application Type):

  | Permission Name | Type | Purpose | | :--- | :--- | :--- | | Sites.Manage.All | Application | Create pages, lists, and columns on the SharePoint site | | Files.ReadWrite.All | Application | Upload attachments to the SiteAssets library | | User.Read.All | Application | Resolve author emails to set page attribution | | TermStore.ReadWrite.All (Optional) | Application | Convert Confluence labels to managed metadata terms |

• Sites.Selected Option (Alternative for Sensitive Environments): If tenant-wide access is restricted, grant the Sites.Selected permission instead of Sites.Manage.All. You must then run a PowerShell script using the Microsoft Graph module to grant fullcontrol access to the registered app ID on the specific target SharePoint site:

  Connect-MgGraph -Scopes "Sites.FullControl.All"
  New-MgSitePermission -SiteId $siteId -BodyParameter @{
      roles = @("fullcontrol")
      grantedToIdentities = @(@{
          application = @{ id = $appClientId; displayName = "Migration Tool" }
      })
  }
  

• Delegated Navigation Setup: Building the left-hand sidebar navigation on SharePoint requires signing in as an actual user during the migration. The person completing this step needs Design or Full Control access to the target site.

4.3 User Identity Mapping

Providing a CSV mapping file ensures correct authorship attribution. The mapping file should map Confluence accounts to Microsoft 365 accounts with the following columns:

• confluence_username: Confluence login name
• confluence_account_id: Unique identifier from the Confluence API
• display_name: Full name of the user
• entra_upn: Microsoft 365 email address
• entra_object_id: Azure AD object ID (GUID)

Users not mapped in the CSV file will fall back to their Confluence display name in plain text, but will not have clickable profile links or native page authorship.

4.4 Machine and Network Requirements

• Operating System: Windows machine with Python 3.10 or newer.
• Dependencies: Installed via pip install -r requirements.txt.
• Network Allowances: The machine must be allowed to connect to:
  • [your-confluence-domain].atlassian.net (Port 443)
  • graph.microsoft.com (Port 443)
  • login.microsoftonline.com (Port 443)
  • [your-tenant].sharepoint.com (Port 443)
• Disk Space: Local storage equal to at least the size of all attachments, with 2x the size recommended for logs and staging files.

5. Scope and Fidelity Coverage

This section details how different Confluence features translate into SharePoint Online.

5.1 Content Migrated with Full Fidelity

These elements transfer with a layout and function equivalent to Confluence:

• Text Formatting: Headings, basic styles (bold, italic, underline, strikethrough), paragraphs, and external links are preserved.
• Blog Posts: Converted into SharePoint News posts, appearing in news feeds and web parts.
• Tables: Standard HTML tables including borders, spans, and alignment transfer directly.
• Attachments and Images: Downloaded and stored in per-page folder paths under SharePoint SiteAssets to prevent filename conflicts.
• Code Blocks: Code syntax formatting is maintained with line numbering options.
• Status Badges: Converted into styled, colored inline badges resembling original states.
• Emoticons: Mapped to their native Unicode emoji equivalents.
• Version History: Previous revisions and page versions from the Confluence edit history are migrated and preserved.

5.2 Content Migrated with Workarounds

These items have no direct SharePoint equivalent and are mapped to reasonable approximations:

• Info Panels: Rendered as blockquote-styled divs with colored borders and light backgrounds matching the panel type.
• Expand Sections: The contents are fully expanded and displayed inline. The collapsible interaction is lost, but the text remains visible.
• Page Layouts: Layouts of 1 to 3 columns map to native SharePoint columns. Layouts with 4 or more columns are flattened into an HTML table structure.
• Tabs: Flattened and displayed sequentially down the page, separated by horizontal dividers.
• Table of Contents (TOC): Generated as static anchor links at migration time. They do not update automatically when headings are edited later.
• Children and Page Trees: Converted into static bullet lists of page links at the time of migration.
• Diagrams (Draw.io/Gliffy): Displayed as static PNG or SVG images on the page. The raw editable diagram file is attached to the page for download.
• Jira References: Converted to styled external links pointing to the Jira issue URL. Live status indicators are not supported.
• Comments: Rendered as a styled, read-only HTML archive at the bottom of the page. They cannot be replied to or edited natively.
• Video Embeds: Converted to a styled play card linking directly to the video file stored in SiteAssets.
• Task Lists: Rendered as checked or unchecked checkbox emojis. They cannot be checked or unchecked interactively.

5.3 Content Not Migrated

These items are skipped during the migration:

• Databases and Whiteboards: Confluence databases and whiteboard content types are not migrated.
• Embedded iFrame Links: iFrame embedded links are not migrated due to security policy restrictions.
• Page Watchers: Notifications and subscriber lists are not transferred.
• Dynamic Macros: Live content lists like Recently Updated, Popular Labels, and Live Search are replaced by static placeholder cards.
• Page Permissions: Space and page-level restrictions are not enforced on the target site. Restriction metadata is flagged for manual post-migration configuration.
• Third-party App Data: Features and data stored outside the page body cannot be extracted.

6. Technical Limitations and Details

• HTML Sanitization: SharePoint's modern engine strips out custom JavaScript, fonts, and heavy CSS formatting. Segment styling is replaced with default typography.
• API Rate Limits: The tool runs under rate-limiting controls to prevent API throttling by either cloud environment. Migration speed depends on volume size.
• Large Pages: Extremely large pages (over 10 MB in HTML content) might fail due to Microsoft Graph upload limits. These should be split manually before migrating.
• Nested Tables: Nested tables are flattened and placed sequentially below the parent table.

7. Post-Migration Activities

Following the completion of the automated run, the following steps are recommended:

1. Enforce Permissions: Use the provided restrictions report to manually configure security groups and break permission inheritance in SharePoint where necessary.
2. Verify Navigation: Inspect the QuickLaunch left navigation and breadcrumbs to ensure correct site structure.
3. Perform Spot Checks: Review pages containing complex formatting, code blocks, or large tables.
4. Confirm Search Indexing: Allow 24 to 48 hours for SharePoint to crawl and index the new pages before testing global search.

For technical assistance and inquiries regarding migration packages, you can reach out directly to the Support Team.