Known Issues and limitations
Limitations
Size-Related
Pages with more than 2 MB of page text content cannot be created in SharePoint Online. This is a known limitation of SharePoint Online. Note that this does NOT mean page attachments, but actual page content. Pages hitting this limit would be massively long.
Overly long page titles break page creation in SharePoint. This is tracked in issue #3.
Selector-Related
When the same content is selected by multiple selectors in one migration run, it is migrated only once, for the selector that picks it up first. This also applies to space-level features like team calendar synchronization: when the same source space is mapped to multiple target SharePoint sites in one run, only the first calendar synchronization for that space runs.
Restrictions/Permissions-Related
Page restriction migration is optional and is not a 1:1 copy of the Confluence permission model. Review the resulting permissions before making migrated content available to users.
Restriction collection limit: 200 entries. WikiTraccs does not page beyond the Confluence API limit for page restrictions. It can process up to 200 entries in each of the view-user, view-group, edit-user, and edit-group collections. A page with more than 200 entries in any one collection cannot be migrated completely, permission-wise.
Complex group hierarchies are not supported. Direct restrictions and some simple restriction hierarchies can be mapped. Hierarchies that combine or change group restrictions cannot always be represented on flat SharePoint pages. Those pages are reported as failed permission transactions.
Only page restrictions are applied. Space and global permissions are not migrated. The SharePoint lists created for Confluence calendars and databases also inherit their target site’s permissions. Configure site and list access separately.
Target principals must already exist. WikiTraccs maps Confluence users to existing Entra ID users and Confluence groups to existing SharePoint groups. It does not create accounts or groups. A mapped SharePoint group must exist in both the WikiTraccs site and every applicable target site.
The target access control list is not an exact source copy. Confluence view and edit restrictions map to SharePoint Read and Contribute, and these permission levels are not configurable. The identity running the migration is retained with Full Control.
Missing mappings fail closed. When a required mapping is missing or empty, WikiTraccs still breaks permission inheritance and grants access only to principals it could resolve, plus the identity running the migration. This avoids unintended broad access, but it can leave a page inaccessible to intended readers. Review failed entries in Page Transactions (WikiTraccs).
Edit-only restrictions use a tenant-wide internal audience. When a page has edit restrictions but no view restriction, WikiTraccs grants Read to SharePoint’s Everyone except external users claim. This includes all internal tenant users and excludes guests, which may differ from the target site’s normal audience.
Restricted pages consume unique SharePoint permission scopes. Every restricted page breaks inheritance and creates a unique scope in the Site Pages library. Microsoft supports up to 50,000 unique scopes per library and recommends staying below 5,000 for best performance. Plan multiple target sites when migrating many uniquely restricted pages.
Permission updates use stored snapshots. The permission update mode normally applies the restriction snapshot captured when the page content was migrated. Later restriction changes in Confluence are not picked up unless the snapshot is refreshed.
Source access and selectors can omit restricted pages or restrictions. The Confluence account must be able to retrieve every selected page and its restriction data. In addition, CQL selectors can omit restricted pages even when an administrative account is used.
Multilingual page permissions are incomplete. Page restrictions are applied only to the SharePoint page in the site’s default language, not to translated pages. See Multilingual pages in SharePoint.
For setup instructions and examples, see Mapping principals and migrating permissions. For the required SharePoint roles and application scopes, see Required permissions for SharePoint Online.
Authentication-Dependent Features
Some Confluence content is available only through a signed-in browser session or through internal endpoints that require its session cookies. In the table below, Interactive Login includes both normal cookie-based authentication and Interactive Login with Proxy Confluence API calls through browser enabled. Proxy mode is an option of Interactive Login. It does not make Personal Token or Anonymous access equivalent to an interactive session.
| Feature | Interactive Login | Personal Token / API key | Anonymous | Details |
|---|---|---|---|---|
| Confluence Cloud database migration | Supported | Not supported | Not supported | Database values are read from an internal Confluence Cloud endpoint that requires session cookies. This is a Gray Feature and migration is best effort. |
| Whiteboards as PNG images | Supported | Not supported | Not supported | WikiTraccs opens the Confluence Cloud whiteboard in a logged-in, controlled browser and uses the export controls in the user interface. |
| Whiteboard raw data and draw.io conversion | Supported | Not supported | Not supported | Raw data, referenced media, and the best-effort draw.io conversion use internal Confluence Cloud endpoints that require session cookies. See Inside Confluence Whiteboards for technical background. |
| Jira issue-list data cards in Confluence Cloud | Supported | Not supported | Not supported | This applies to Jira issue-list data cards that WikiTraccs resolves into a static issue table. Ordinary links are not affected. |
| Team Calendars | Supported | Supported | Not supported | Calendar discovery and iCalendar export use regular authenticated calendar endpoints, so Interactive Login is not required. Cloud API tokens and Data Center Personal Access Tokens are supported, subject to the source account’s calendar permissions and endpoint availability. |
Personal Token includes Confluence Cloud API tokens or API keys and Confluence Data Center Personal Access Tokens. See the Confluence authentication overview for the authentication options and the Interactive Confluence Authentication documentation for proxy mode.
Anonymous migrations can retrieve only content that Confluence exposes anonymously.
Calendar and Database Migration
Calendar and database migration is documented in the Confluence Content Types section, including the supported and unsupported features and the behavior on repeated runs and manual changes:
- Team Calendars: what is migrated, updates and manual changes
- Confluence Databases: what is migrated, updates and manual changes
The SharePoint lists created for calendars and databases inherit their target site’s permissions; see the Restrictions/Permissions-Related section above.
Attachment-Related
The principal/metadata update mode does not support pages with more than 5,000 attachments.
Modern SharePoint Online team sites have the “no-script” security setting enabled by default, which blocks uploading files with certain extensions. WikiTraccs cannot bypass this and will skip such attachments during migration; a warning of the form [Files] Skipping upload of file '<name>' to '<folder>' is written to the log for each one.
The blocked extensions are: .asmx, .ascx, .aspx, .htc, .jar, .master, .swf, .xap, .xsf.
Delta Mode-Related
Changes to a Confluence page’s attachments or comments are not counted as “page change”. The page is detected as unchanged, even if e.g. attachments are added.
Changes to a Confluence pages’s title will duplicate the page in SharePoint, as the file name of the SharePoint page changes. Those kinds of title changes in Confluence might also lead to stale or broken links in SharePoint. If already migrated pages (in SharePoint) link to the newly migrated page (that now has a new name in SharePoint), those links will point to the old page; or be broken if the old page is deleted manually.
Content-Related
Rich image captions are not supported by SharePoint Online, the text content of the image caption will be used instead.
Macro/Web Part-Related
Macros transformation for macros which include content from other pages, like Excerpt Include and Multiexcerpt include are resolved one level deep. Nesting is not supported.
Draw.io embeddings from OneDrive etc. are not migrated as image, as they have no preview image.
Confluence Cloud
Link transformation for sharing links that have been pasted to pages (those contain ‘/l/cp/’ ) is not yet possible. Note that those are not tiny links, which are properly transformed. Discussions about this link format: 1, 2.
At the time of this writing, retrieving inline comments might fail in Confluence Cloud. Note that inline comments are currently not surfaced anywhere on migrated pages, but only stored in the WikiTraccs site with the page storage format XML blob. This inline comment retrieval currently seems to be broken with the Confluence Cloud REST API v2.
Hard links of type create page are left as is, pointing to Confluence. WikiTraccs doesn’t know what to do about them as there is no equivalent in SharePoint. Sample link: https://contoso.atlassian.net/wiki/pages/createpage.action?spaceKey=SPC&title=Page.