Skip to main content

Migrating from the Legacy Pages

What happens to Organization Documents and the Help Center when the Documents hub is switched on, and how to bring their content across.

Overview​

The Documents hub replaces two older areas:

  • Organization Documents β€” a flat list of document names and links
  • Help Center and the Knowledge Base β€” categorized articles

Nothing about them is removed. Their data stays where it is, their APIs keep responding, and no content is deleted at any point in this process. What changes is where people are sent in the interface, and that is controlled by a switch you own.

Both Keep Working​

Until an administrator enables the Documents feature for an organization, absolutely nothing changes:

  • Organization Documents and Help Center appear in the sidebar as before
  • Their pages behave exactly as they always have
  • The Documents hub does not appear at all

This is the default state. Enabling Documents is a deliberate act, and it can be reversed.

The Feature Flag​

The hub is governed by the Documents feature, toggled per organization in Settings β†’ Features.

Feature stateSidebar showsLegacy pages
OffOrganization Documents, Help CenterWork normally
OnDocumentsRedirect to the Documents hub
Off againOrganization Documents, Help CenterWork normally again β€” nothing was lost

Because it is per organization, a multi-organization deployment can pilot the hub with one team before rolling it out everywhere.

Redirect Behavior​

Once Documents is enabled, opening a legacy Organization Documents or Help Center URL takes you to the Documents hub instead. Old links in emails, tasks, and bookmarks keep working rather than landing on a dead page β€” you simply arrive at the new home.

The legacy route that used to open the "add document" dialog opens the Documents upload dialog instead, so that habit survives too.

note

Redirects change navigation only. The legacy data is untouched, and turning the feature off restores the original pages immediately.

Importing Legacy Content​

Redirects move people. Importing moves content. It is a separate step, and one you should always rehearse first.

The import is run by an administrator holding DOCS_MANAGE:

# Dry run β€” reads, maps, validates, writes NOTHING (this is the default)
POST /api/plugins/docs/migrations/import-legacy
{ "dryRun": true }

# Real run β€” requires dryRun to be set explicitly to false
POST /api/plugins/docs/migrations/import-legacy
{ "dryRun": false }

# Optionally limit the sources
POST /api/plugins/docs/migrations/import-legacy
{ "dryRun": false, "sources": ["organization-document"] }

# Undo a run
POST /api/plugins/docs/migrations/import-legacy/rollback
tip

Dry run is the default. Calling the import without asking for a real run gives you the complete report β€” everything that would be created, skipped, or flagged β€” with no changes made. Read that report before running it for real.

Both runs return the same report: how many items were scanned, created, skipped, and failed, plus any warnings.

What Maps to What​

Legacy itemBecomesNotes
The organization documents listA folder named Organization DocumentsCreated once, as the home for the imported list
An organization documentA fileThe existing stored file is reused β€” nothing is copied or re-uploaded
A document with no fileA file marked Failed, flagged for reviewWarned about in the report
A document that was only a linkA file flagged for reviewWarned about, so somebody can attach the real file
A help center base or categoryA folderIcon, color, description, and ordering are carried over
A help center articleA pageContent is converted for the new editor
A draft articleA page marked Needs reviewDrafts are not silently published
A private article or categoryA Private documentWarned about β€” see below
An orphaned article or categoryParked in a Help Center (recovered) folderNothing is dropped because its parent was missing
Article revisionsVersion history entriesCounted separately in the report

Everything imports as not in AI knowledge. The import never puts anything into AI answers on your behalf.

Duplicate names are given a numbered suffix rather than overwriting each other.

warning

Privacy is now enforced. In the Help Center, marking an article private mostly affected how it was displayed. In the Documents hub, Private genuinely restricts who can open a document. Anything that was private comes across as Private and is flagged in the report β€” review those items so nobody loses access to something they need.

Running It Twice Is Safe​

The import is idempotent. Re-running it only brings across legacy items that do not already have an imported copy. Archived and deleted copies count as existing, so a second run will not resurrect something you deliberately removed. If a run is already in progress for an organization, a second request is refused rather than allowed to overlap.

Rolling Back​

The rollback removes the documents a migration created. It is deliberately conservative:

  • Imported documents that have been edited since the import are left alone
  • Imported folders that now contain non-imported documents are left alone
  • Nothing physical is deleted β€” file storage is untouched, and the legacy tables are never modified

A forced rollback overrides the first two rails. Even then it does not delete anything that was not created by the migration; documents that ended up inside a removed folder are moved up to the top of the tree instead.

note

The import and rollback are run against the API today. A screen for this in Settings β†’ Documents is planned for a later release.

Suggested Rollout​

  1. Enable Documents for one organization
  2. Run the import as a dry run and read the report
  3. Fix anything obviously wrong in the legacy data, then dry run again
  4. Run it for real
  5. Review everything flagged Needs review, especially items that became Private
  6. Decide, document by document, what belongs in AI knowledge
  7. Repeat for the remaining organizations