Confluence Databases

• 1: Confluence Databases: What Is Migrated, What Is Not
• 2: Confluence Databases: Updates and Manual Changes

"Features": {
    "MigrateDatabases": true
}

1 - Confluence Databases: What Is Migrated, What Is Not

Database migration is a best effort Gray Feature: database values are read from internal Confluence Cloud endpoints that are not documented as supported by Atlassian. A change on Atlassian’s side can make this feature stop working at any time. See the Confluence Databases overview for how the migration works.

What is migrated

• Fields become list columns. The columns are generated from the database’s field definitions. Every database has its own schema, so every generated list does too.
• All rows of the database, matched by their stable Confluence entry identifier.
• Person fields become two columns. The source data contains only Confluence account IDs, no names. A raw-text companion column always keeps those account IDs. In addition, account IDs that have an entry in the WikiTraccs user mapping list are written to a real SharePoint person column; for account IDs without a mapping the person cell stays empty. There is no name lookup against Confluence.
• Unknown or unsupported field types keep their raw values as text in a fallback column.
• Jira references and links are kept as text.
• A permissions note: the source page’s view and edit restrictions are not applied, but a human-readable note about them is added to the list description.

What is not migrated

• Permissions. The generated list inherits the permissions of its target site. Source restrictions are only noted in the list description; configure list access yourself.
• Database views, filters, and layout settings. The result is a plain SharePoint list. You can build your own SharePoint list views on it.
• Migration is best effort. Databases are read via internal Confluence Cloud endpoints. Content those endpoints do not deliver, or field types WikiTraccs does not know, end up as raw text rather than typed columns.

SharePoint field limits

Database values are stored in SharePoint list columns and are subject to SharePoint field length limits:

• Short values use single-line text or choice fields, which can store at most 255 characters.
• Longer content, including database text, raw user values, Jira references, and fallback data for unknown field types, is stored in multi-line text fields. SharePoint limits those to 63,999 characters.

Content beyond these limits cannot be stored completely in a list field.

2 - Confluence Databases: Updates and Manual Changes

Synchronization is one-way

Changes flow from Confluence to SharePoint only. Nothing is written back to Confluence.

What happens on a repeated migration run

• WikiTraccs recognizes its database lists by a marker in the list description (wt-database-id:...). Renaming the list is safe; WikiTraccs finds it again. Do not remove the marker from the list description, otherwise WikiTraccs creates a new list on the next run.
• The list is reconciled with the source database: rows are matched by their Confluence entry identifier. Changed rows are updated, new rows are added.
• Rows that were deleted in Confluence are deleted from the list. Only WikiTraccs-managed items are deleted; see below. As a safety measure, deletions are skipped when the source data could not be read completely.
• New database fields add new list columns.
• Changes to the user mapping list are not picked up on their own. The person columns are written only when the database itself is migrated again. An update run skips a database that is unchanged in Confluence, so changing the WikiTraccs user mapping list alone does not refresh the person columns. The next migration that includes the database applies the then-current mapping to all rows.

Manual changes in SharePoint

• Do not edit WikiTraccs-managed rows while further migration runs are planned. A managed row (it carries a source entry identifier) is overwritten with the source values on the next migration of that database. While migration runs are still happening, treat the generated list as a read-only mirror. Once the migration is finished, the list is a normal SharePoint list and all rows can be edited freely.
• Rows you add yourself are safe. Items without a source entry identifier are never modified or deleted by WikiTraccs.
• Safety guard: WikiTraccs only writes to lists that carry both its description marker and at least one WikiTraccs column (internal name starting with WT_). Copying the marker into an unrelated list does not make WikiTraccs write to it.