
Knowledge Base Migration: Planning, Validation, and Cutover Guide
Knowledge base migration is a controlled move of content, structure, access rules, assets, URLs, and operational dependencies—not merely copying article text into a new editor. A successful migration defines what must move, what may be transformed or retired, how the result will be tested, when traffic will switch, and what conditions require rollback.
The safest approach is to inventory the source, map it to the destination model, run a representative pilot, reconcile every source object, preserve important links, and keep the old system recoverable until the new platform has passed both technical and user validation.
This guide is platform-neutral. Product importers, APIs, and export formats have different coverage, so verify the current documentation for the exact source, destination, plan, and migration direction before committing to a method.
Define what the migration must preserve
Begin with the business outcome. A public help center migration may prioritize URLs, translations, indexing, and anonymous access. An internal wiki migration may prioritize employee identities, group permissions, ownership, attachments, and integrations. An AI knowledge migration also needs source metadata, vector indexes, authorization rules, and stale-cache handling.
The migration scope may include far more than published articles:
- Categories, sections, folders, spaces, collections, ordering, and navigation.
- Titles, slugs, source IDs, publication status, drafts, archived pages, and scheduled content.
- Authors, accountable owners, reviewers, approvers, subscribers, and user mappings.
- Reader groups, user segments, tenant boundaries, restricted collections, and direct grants.
- Tags, labels, custom fields, search keywords, SEO metadata, canonicals, and review dates.
- Languages, locale relationships, untranslated fallbacks, and translation status.
- Inline images, attachments, videos, embeds, tables, callouts, code blocks, macros, and reusable content.
- Internal links, external links, old URLs, custom domains, redirects, sitemaps, and bookmarks.
- Comments, votes, feedback, revision history, approvals, analytics, and audit records.
- Themes, custom code, widgets, APIs, webhooks, notification templates, and support integrations.
- AI sources, embeddings, vector chunks, permission metadata, citations, caches, and generated-answer histories.
Do not assume every object should be transferred. For each item, choose an approved outcome: migrate unchanged, transform, merge, archive separately, retain read-only, retire, or exclude. A missing record and an intentionally retired record are not the same result.
Keep adjacent systems outside the promise unless they are explicitly in scope. Moving knowledge articles does not automatically move support tickets, customer profiles, inbox rules, macros, CRM records, or analytics history.
Set measurable success criteria before exporting anything
A migration cannot be evaluated without an agreed definition of success. “The articles are there” is too weak because the pages may have missing files, incorrect ownership, exposed restricted content, broken links, or unusable navigation.
| Success area | Question to answer | Possible evidence |
|---|---|---|
| Completeness | Does every source object have an approved destination outcome? | Migration manifest and reconciliation report. |
| Content fidelity | Did meaning, formatting, files, and important relationships survive? | Representative source-to-destination comparisons. |
| Access | Can intended readers open the content while denied readers remain blocked? | Allowed and denied identity tests with access events. |
| Findability | Can users locate critical answers through navigation and search? | User acceptance tests and search-query checks. |
| Public URLs | Do important old links reach the correct new destination? | Status-code and destination checks against the URL map. |
| Operations | Do widgets, APIs, notifications, integrations, and support workflows still work? | Integration smoke tests and defect records. |
| Recoverability | Can the team roll back or restore required information if launch fails? | Rollback plan, protected export, source availability, and restoration checks. |
Set launch-blocking conditions before the cutover. Exposure of restricted content, unexplained missing articles, widespread asset failures, loss of a critical locale, or an unusable rollback path may be more important than a high average import percentage.
Create a source inventory and migration manifest
The migration manifest is the project’s control record. Give every source object a stable ID so it can be mapped, imported, retried, validated, and reconciled without relying only on a title or URL that may change.
Useful manifest fields include:
| Field group | Examples | Why it matters |
|---|---|---|
| Identity | Source ID, URL, title, slug, content type. | Prevents ambiguous matching and duplicate creation. |
| Structure | Parent collection, section, folder, space, order. | Supports hierarchy and navigation mapping. |
| Lifecycle | Published, draft, archived, scheduled, review status. | Prevents every imported page from becoming publicly visible. |
| People | Author, owner, reviewer, approver. | Preserves accountability separately from historical authorship. |
| Access | Reader group, user segment, tenant, direct grant. | Supports positive and negative permission testing. |
| Language | Locale, translation family, source language, fallback. | Prevents translated pages from becoming disconnected duplicates. |
| Content | Body, tags, metadata, SEO fields, custom properties. | Defines which fields require transformation. |
| Assets | Inline images, files, embeds, external URLs. | Identifies dependencies that article counts will not reveal. |
| Links | Internal links, inbound importance, redirect target. | Supports link replacement and public URL preservation. |
| Outcome | Keep, merge, update, archive, retire, exclude. | Turns omissions into explicit decisions. |
| Destination | Destination ID, URL, import result, validation status. | Enables reconciliation and reruns. |
Use the correct export identity
The identity performing the export can affect what appears in the package. Notion states that pages the exporter cannot access are not included in a workspace export. Confluence likewise notes that export coverage can depend on visibility and administrator status. Confirm the intended scope and authorize the export identity rather than assuming an absent page never existed.
Notion’s export documentation supports HTML and Markdown/CSV exports with files, but it also states that an exported workspace cannot be instantly recreated by uploading the package again. That distinction is central to migration planning: a readable export is not necessarily a restorable application state.

Confluence offers different export formats for different uses. Its export guide describes separate purposes and omissions for PDF, CSV, HTML, and XML. Comments, unpublished changes, calendars, and other elements may differ by export type. Select the format based on the destination and required data—not familiarity with the file extension.
Preserve an untouched source snapshot
Before transforming content, retain an authorized source export or API snapshot. Record the export date, platform edition, exporter identity, count summaries, file inventory, and available checksums. Protect the archive because it may contain restricted or personal information.
Do not call the package a complete backup unless it can restore the state you require. An article export may omit roles, workflows, versions, analytics, theme settings, integrations, and administrative configuration.
Triage content before mapping the platforms
A migration is an opportunity to remove clearly obsolete or duplicate material, but combining too many changes increases risk. Platform replacement, domain changes, hierarchy redesign, permission restructuring, ownership reassignment, and full editorial rewrites should not all happen invisibly inside one import.
For each source page, assign one outcome:
- Keep: transfer with only required technical transformations.
- Update: migrate, then apply an approved correction.
- Merge: combine several source pages into one identified destination.
- Archive: preserve separately for historical or records purposes.
- Retire: do not recreate; define the correct URL or user outcome.
- Exclude: keep out of the project with a named reason and approver.
Use content owners to approve these outcomes. The migration team should not decide that a procedure is obsolete merely because it has low traffic or an old modification date.
Map the source model to the destination model
Migration is a data-model transformation. Zendesk’s API migration overview demonstrates why sequence matters: users and authors, categories, optional user segments, sections, articles, attachments, and comments have dependencies, and destination IDs created in earlier stages are needed later.
Create explicit mappings for hierarchy, fields, users, roles, visibility, languages, assets, history, and URLs. A simple field table helps expose unsupported relationships before the pilot.
| Source concept | Destination concept | Transformation decision | Validation |
|---|---|---|---|
| Category → Section → Article | Collection → Folder → Article | Preserve order and map stable source IDs. | Compare representative navigation paths. |
| Draft article | Draft article | Prevent accidental publication during import. | Check as an ordinary reader. |
| User segment | Reader group | Rebuild membership and resolve unsupported rules. | Allowed and denied direct-link tests. |
| Locale family | Translation group | Map every locale and fallback separately. | Switch languages and inspect canonical relationships. |
| Inline image URL | Destination-hosted asset | Download, create asset, and replace the source URL. | HTTP response, rendering, dimensions, and checksum where useful. |
| Article comments | No native equivalent | Archive in a protected, searchable record. | Confirm archive coverage and access. |
| Old public URL | New article URL | Create a permanent one-to-one redirect. | Check status code and final destination. |
When the destination cannot represent a source feature, document the chosen alternative: transform it, archive it, retain the old system read-only, or accept the loss with named approval. Do not describe a missing workflow or comment history as successfully migrated.
Choose the migration method that matches the complexity
| Method | Useful when | Strength | Main risk to evaluate |
|---|---|---|---|
| Manual recreation | The set is small, curated, or requires substantial rewriting. | Human review happens during transfer. | Inconsistent formatting, missed pages, and limited repeatability. |
| Native importer | The destination officially supports the exact source platform. | Low-code path with product-specific mappings. | Unsupported objects, fixed limits, one-way behavior, and weak exception reporting. |
| Export and import | The destination accepts a documented source format. | Uses portable files and can support offline transformation. | Loss of relationships, permissions, history, or rich components. |
| API or custom script | The project needs repeatability, complex mapping, or controlled deltas. | Detailed transformation and reconciliation logic. | Development effort, rate limits, credential handling, and partial failures. |
| Managed migration service | The source is complex and the organization lacks migration capacity. | Specialist transformation and project assistance. | Scope assumptions, data handling, vendor dependency, and unclear acceptance criteria. |
| Repository or docs-as-code move | The content is maintained in version control. | Reviewable source and repeatable builds. | Hosting, search, authentication, and custom-component portability. |
Read importer limitations before selecting the method
Importer coverage can be narrower than the product’s overall capabilities. HubSpot’s current knowledge-base import documentation, for example, lists supported source platforms and CSV fields, while also documenting limitations such as a per-import article cap, unsupported table imports, and language handling after import.
Help Scout’s data export documentation states that Docs articles are obtained through the Docs API rather than a general in-app article export. That may turn an apparently simple platform move into an API extraction project.
Verify the current tool against your manifest: hierarchy, article statuses, files, comments, languages, authors, permissions, redirects, and history. A successful import of article text is not proof that the project scope is supported.
Distinguish one-time import from ongoing synchronization
Intercom currently documents two different Zendesk relationships. A synchronized source continues pulling changes, while an import converts the content into native Intercom articles, severs the source connection, and makes Intercom the new editing location. The one-time conversion is documented as irreversible.

This distinction changes the operating plan. Decide which system is authoritative, when authors must stop editing the old platform, how a final delta will be captured, and how duplicate or stale content will be prevented.
Make API migrations rerunnable
For scripted migrations, store the immutable source ID in the destination or mapping database. Use it as the reconciliation and upsert key. A repeated run should update, skip, or flag an existing object rather than silently create another copy.
Record every attempt with source ID, destination ID, action, status, and error reason. Follow official API rules for pagination, rate limits, idempotency, and retry behavior. Use least-privilege credentials stored outside code and public logs.
Run a representative pilot before the full migration
Use a non-public staging, sandbox, preview, or test destination when the platforms support it. The pilot must represent the difficult content—not only a few short text pages.
Include examples with:
- Short and long articles.
- Deep hierarchy and cross-links.
- Tables, lists, callouts, code blocks, and special characters.
- Inline images and downloadable attachments.
- Supported video or embedded content.
- Comments, revision history, or approvals.
- Draft, archived, scheduled, and review-state content.
- Translated pages and locale relationships.
- Restricted or tenant-specific content.
- Custom metadata, tags, owners, and search keywords.
- Important old URLs and inbound links.
- Pages used by widgets, support replies, chatbots, or AI systems.
Atlassian strongly recommends a test migration before a production move. Its testing guidance includes validating data, links, attachments, apps, and integrations. Its separate UAT guidance recommends involving major user types and having them repeat everyday tasks.
Use authors, administrators, ordinary readers, restricted readers, support agents, and less-frequent users where relevant. Ask them to complete realistic tasks instead of approving screenshots:
- Find a specific answer using ordinary wording.
- Open the article and every required file.
- Edit and publish a test page through the intended workflow.
- Confirm that a restricted reader is denied through navigation, search, and direct URL.
- Use the article through a connected support or chat experience.
Log each defect, severity, owner, fix, and retest result. Do not scale to the full import while high-risk content types remain unexplained.
Preserve URLs and search visibility for public migrations
This section applies to public or externally indexed knowledge bases. A private employee wiki may not require search-engine migration steps, but it may still need to preserve email links, bookmarks, widgets, chat references, and integrations.
Google’s site-move guidance recommends creating an old-to-new URL map, preparing destination pages, using server-side permanent redirects such as 301 or 308, updating internal links, and monitoring the move.

- Inventory old URLs. Use the platform export, sitemap, logs, analytics, Search Console, and inbound-link reports where available. Include important image and file URLs.
- Map each retained or merged page. Redirect it to the most relevant final destination, not automatically to the home page.
- Publish destinations first. A redirect should not point to an unpublished or missing article.
- Use direct permanent redirects. Avoid loops and unnecessary chains.
- Update the destination. Replace old internal links and update self-referencing canonicals, hreflang annotations, navigation, and the new sitemap where relevant.
- Test the actual response. Verify the HTTP status and final destination from a representative sample and important inbound URLs.
- Monitor both properties. Watch crawl errors, indexing, traffic, and unmapped requests.
Google currently recommends retaining redirects for as long as possible and generally for at least one year. From a user perspective, important redirects may need to remain longer. Update your own links so normal navigation does not depend indefinitely on redirect hops.
Preserving the custom domain does not eliminate URL work. Article paths, locale segments, collection routes, slugs, numeric IDs, and asset hosts may still change.
Verify the destination platform’s redirect model
Some importers generate redirects only under specific domain conditions. Intercom’s redirect documentation distinguishes same-domain path redirects from cross-domain moves and explains that redirects are tied to the workspace that owns the domain. A platform feature cannot serve redirects after the old domain has moved elsewhere unless the new routing setup supports them.
Confirm who will control the old hostname after the source subscription is changed or canceled. Losing the ability to serve the old URL can invalidate an otherwise complete redirect map.
Handle languages and translated content explicitly
Map each locale separately. Record the source language, translation family, destination locale, translation status, old URL, new URL, and fallback behavior. Do not treat translated pages as ordinary duplicates.
A destination may import translated records without enabling the corresponding language for visitors. Intercom’s import documentation, for example, notes that supported translations can be imported but require the relevant Help Center languages to be enabled before they become visible.
Check language codes carefully. Platforms may support different locale variants or create separate pages when two source locales cannot be represented by one destination relationship. Validate the language switcher, hreflang annotations, canonicals, search behavior, and redirects for each locale.
Define the content freeze, final delta, and cutover
Assign a migration lead, content owner, technical owner, security reviewer, SEO owner where applicable, communications owner, and rollback authority. Name the person who may accept a known omission and the person who can stop the launch.
Choose between a freeze and a final delta
If the importer is one-time, changes made after extraction will not appear automatically. Use one of these controlled approaches:
- Content freeze: stop new pages, edits, status changes, permission updates, translations, comments, and asset changes during the final migration window.
- Final delta: record changes after the initial extraction and apply them in a final controlled pass before cutover.
- Temporary synchronization: keep the source authoritative until an approved switch, if the platform supports a verified ongoing sync.
Salesforce’s Knowledge migration planning guidance provides a product-specific example of why a freeze matters: it recommends sandbox testing and warns that content, publishing, setup, API, attachment, and other changes during production migration can be lost or damaged.
Do not copy Salesforce’s exact freeze procedure into an unrelated platform. Use the principle to identify which writes your selected migration method can safely tolerate.
Use a sequenced cutover plan
- Announce the freeze or final-delta window.
- Capture the final authorized source export or changes.
- Run the last import and reconcile the destination.
- Publish approved destination content and confirm access.
- Validate the custom domain, DNS or CNAME, and TLS where applicable.
- Activate redirects.
- Update navigation, internal links, widgets, templates, email links, and integrations.
- Submit the new sitemap and update search annotations for public moves.
- Run smoke tests with ordinary author and reader identities.
- Communicate the new source of truth and correction process.
Estimate the freeze and cutover from the measured pilot, source volume, attachment size, API rate limits, and platform behavior. Do not use a universal downtime estimate.
Define rollback before the point of no return
A rollback promise is useful only while the old environment, routing control, export, and mappings remain available. Define the last reversible step and any product action that makes the move irreversible.
Possible rollback triggers include:
- Restricted content becomes publicly accessible.
- Critical collections or locales are missing without explanation.
- Important assets fail across multiple content types.
- Redirects send users to incorrect or missing pages.
- The destination cannot support the required authentication or permissions.
- The service is unstable or critical integrations fail.
These are examples, not universal thresholds. The project’s risk owners should approve the criteria before cutover.
Keep the source available or read-only, retain the protected source package and mappings, and preserve old routing control until validation and stabilization are complete. Do not accept an irreversible migration stage while unresolved blocking defects remain.
Validate with reconciliation and user testing
Use both automated checks and human review. Counts can reveal omissions, but they cannot prove that meaning, formatting, ownership, visibility, or permissions survived correctly.

| Validation area | Automated or structured check | Human check |
|---|---|---|
| Manifest | Every source ID has an approved outcome and import status. | Owner reviews exclusions, merges, and accepted losses. |
| Hierarchy | Compare parent IDs, order, and destination paths. | Reader follows important navigation journeys. |
| Content | Compare required fields, lengths, hashes, or parsed elements where practical. | Reviewer checks meaning, formatting, warnings, and prerequisites. |
| Assets | Check URLs, status codes, MIME types, sizes, and checksums where useful. | Open representative images, downloads, and embeds. |
| People | Reconcile users, authors, owners, and groups. | Confirm accountability and departed-user handling. |
| Permissions | Run allowed and denied access cases. | Ordinary users test navigation, search, direct URLs, and files. |
| Languages | Compare locale counts and translation relationships. | Switch locales and review visible fallbacks. |
| URLs | Test status codes, destinations, chains, canonicals, and hreflang. | Open bookmarked and high-value external links. |
| Search | Run a defined query set and record missing results. | Users find answers using ordinary language. |
| Integrations | Test widgets, APIs, webhooks, notifications, and support links. | Agents complete common workflows. |
Use an allowed identity and a denied identity for every restricted content class. An administrator preview does not establish that access boundaries survived the migration.
Treat history that cannot move as an explicit outcome. If comments, revisions, approvals, feedback, or audit records are required but unsupported, preserve them in an authorized archive and document how they can be retrieved.
Record each defect with severity, owner, remediation, retest result, and launch decision. Do not allow a high overall completion rate to hide a critical disclosure or missing operational procedure.
Migrate AI knowledge sources as a separate workstream
Moving articles does not automatically update an AI or RAG system. Inventory the source connectors, document IDs, chunking rules, embeddings, vector indexes, audience metadata, caches, citations, and generated-answer histories.
- Preserve stable source identity and destination provenance where possible.
- Rebuild or refresh indexes using the approved destination content.
- Carry tenant, classification, and authorization metadata into derived chunks.
- Remove or disable old sources to prevent duplicate or contradictory retrieval.
- Test restricted, cross-tenant, revoked-user, and deleted-source cases.
- Verify citations open the correct destination article for the authorized reader.
- Check stale caches and previously generated answers after source deletion.
Keep the old AI source active only when the transition design explicitly requires it. Connecting both old and new libraries without deduplication can create inconsistent answers that are difficult to diagnose.
Worked example: Atlas Help moves to Northstar Support
The following migration is fictional. The platforms, URLs, counts, results, and decisions illustrate a planning method; they are not outcomes from an executed project.
Atlas Help is a public customer help center moving to Northstar Support. The organization keeps the custom domain help.example.com, but destination article paths will change. The source contains public pages, drafts, Spanish translations, partner-restricted articles, inline images, and downloadable PDF files.
| Source item | Approved outcome | Destination treatment | Validation |
|---|---|---|---|
| A-101: Reset a password | Keep | Import as published; map the old URL one-to-one. | Signed-out page, image, search, and redirect tests. |
| A-102: Legacy login troubleshooting | Merge into A-101 | Add its approved content to the destination article. | Both old URLs redirect to the merged destination. |
| A-103: Retired desktop client | Retire | Do not recreate; return the approved removal outcome. | Owner approval and expected HTTP response. |
| A-104: Partner API limits | Keep restricted | Map the partner group before importing the article. | Partner allowed; customer and anonymous users denied. |
| A-105-ES: Restablecer contraseña | Keep translation | Link it to the Spanish destination locale. | Language switch, URL, canonical, and redirect checks. |
| A-106: Billing export draft | Keep draft | Import without publication and assign a new owner. | Author sees it; public reader does not. |
Fictional pilot and cutover decisions
The team selects a pilot containing all six patterns plus additional table, attachment, embed, and feedback examples. The importer is one-time, so Atlas Help remains the source of truth during the pilot. Before production cutover, the team announces a short freeze and applies an approved final delta.
The custom domain is connected to Northstar Support only after destination pages, permissions, translations, and redirects have passed review. The old system remains read-only during stabilization.
The fictional rollback trigger is any unexplained public access to A-104, failure of a group of high-value redirects, or loss of the Spanish translation family. This is a project-specific example, not a universal threshold.
Monitor the destination before decommissioning the source
After launch, monitor both technical and user signals:
- 404s, redirect loops, chains, and requests to unmapped URLs.
- Missing images, files, embeds, and old CDN references.
- Search queries with no useful result.
- Permission incidents and restricted-content exposure.
- Import, synchronization, API, and integration errors.
- Availability and performance on the real domain.
- Search Console indexing and crawl errors for public content.
- User reports, broken article links, and support-agent feedback.
- AI answers citing stale, missing, duplicate, or unauthorized sources.
Compare analytics cautiously because platforms may define views, reads, searches, feedback, and resolutions differently. A metric change does not prove that the migration caused an improvement or failure.
Keep the source read-only for the approved stabilization and retention period when feasible. Confirm records requirements, legal holds, contract terms, rollback needs, and export availability before canceling or deleting it.
Use a controlled decommissioning checklist
- Preserve the required final export, mapping, defect log, acceptance record, and archive.
- Confirm redirects are served independently of the retiring subscription where necessary.
- Revoke API tokens, service accounts, connectors, webhooks, and unnecessary administrator access.
- Remove or update widgets, email templates, bookmarks, integrations, and internal references.
- Document which history was migrated, archived, destroyed, or accepted as loss.
- Transfer ongoing platform and content ownership to the destination teams.
A knowledge base migration is complete only when the new system is authoritative, users can complete their tasks, access boundaries work, important links resolve correctly, defects are controlled, and the old platform can be retired without removing evidence or recovery options the organization still needs.
Official migration, export, import, redirect, and testing documentation checked on November 2, 2026. The Atlas Help example is fictional; no live migration, API import, DNS change, or SEO test was performed.



