Home / admin / knowledge-classic-to-lightning

knowledge-classic-to-lightning

Migrating Classic Knowledge (KnowledgeArticleVersion / Article Types) to Lightning Knowledge (Knowledge__kav with record types): article-type-to-record-type mapping, multi-language translation preservation, data category re-architecture, file attachment porting, version and publication-state retention, channel visibility translation, and downstream Case Feed / Community / Bot rewiring. NOT for new Lightning Knowledge setup or editorial publishing workflow design (use admin/knowledge-base-administration).

• v1.0.0
• Salesforce Spring '25+
• Updated 2026-04-29
• User Experience
• Operational Excellence
• Reliability

• knowledge
• lightning-knowledge
• article-types
• record-types
• data-categories
• migration
• multilingual

Open the skill folder on GitHub

Knowledge Classic to Lightning Migration

This skill activates when a practitioner needs to migrate from Classic Knowledge (multiple Article Types as separate sObjects) to Lightning Knowledge (a single Knowledge__kav sObject with record types), preserving versions, translations, data categories, and downstream consumer integrations.

Before Starting

Gather this context before working on anything in this domain:

• Confirm Classic Knowledge is enabled and inventory Article Types: SELECT Id, MasterLabel, DeveloperName FROM KnowledgeArticleType. Each Classic Article Type is a separate sObject (FAQ__kav, HowTo__kav, etc.); Lightning collapses them into one Knowledge__kav with record types.
• Inventory translations. SELECT Language, COUNT(Id) FROM KnowledgeArticleVersion WHERE PublishStatus='Online' GROUP BY Language. Lightning Knowledge supports the same multi-language structure but the migration must port each language version individually.
• Inventory data categories. SELECT Id, MasterLabel, ParentId FROM CategoryGroup and SELECT Id, MasterLabel, GroupId FROM Category. Categories carry over but visibility settings must be re-validated against the new record-type structure.
• Identify downstream consumers: Case Feed Knowledge Component (Lightning Service Console), Knowledge Sidebar (Classic only — being deprecated), Community Knowledge pages, Einstein Bot Knowledge action, Salesforce Service Cloud "suggested articles" on Cases, and any Apex code querying article sObjects directly.
• Confirm whether the Salesforce-provided Lightning Knowledge Migration Tool is in scope. The Migration Tool handles 80–90% of cases; custom code is needed only for unusual data category structures, custom field mappings, or article-type consolidation decisions.

Core Concepts

1. Object Model: From Many to One

Classic Knowledge created one sObject per Article Type — FAQ__kav, HowTo__kav, Procedure__kav, etc. Each had its own fields, layouts, and validation rules.

Lightning Knowledge has ONE sObject: Knowledge__kav. Differentiation between former Article Types is via record types on Knowledge__kav.

2. Migration Tool vs Custom Migration

The Salesforce Migration Tool is invoked from Setup → Knowledge → Lightning Knowledge Migration Tool. It runs in the background, produces a detailed log, and supports re-run for failed articles. Default to using it.

3. Versions and Publication States

Classic Knowledge tracks versions: each article has a "master" version, may have an "online" published version, and may have draft versions. Translations are per-version per-language.

Lightning Knowledge preserves the same state machine. Migration must port the publication state per-language per-version. The Migration Tool handles this; custom migrations must explicitly preserve PublishStatus, IsLatestVersion, and IsVisibleIn* flags.

4. Translations

Each translated article in Classic is a KnowledgeArticleVersion row with the same KnowledgeArticleId (the master article) and a different Language value. Lightning Knowledge structure is identical: each translation is a Knowledge__kav row sharing a KnowledgeArticleId with a different Language.

Migration MUST preserve the KnowledgeArticleId linkage so master and translations stay grouped. Inserting translations as standalone articles (with new KnowledgeArticleId per language) breaks the language-switcher UX in the published surface.

5. Data Categories: Preserved but Re-validated

Data Category Groups, Categories, and the category visibility settings (per role / permission set) port directly. The migration tool preserves the assignments. The risk is that record-type-based visibility (new in Lightning) may unintentionally restrict article visibility for users who previously saw articles by category alone.

Verify: pre-migration, run "as user X, list visible articles." Post-migration, run the same query. Visible-article counts should match (or differences should be intentional and documented).

6. Downstream Consumer Migration Surface

Common Patterns

Pattern 1: Standard Migration via Lightning Knowledge Migration Tool

When to use: Org has standard Article Types, modest custom field counts, and uses the standard Knowledge object model.

How it works:

1. Take a sandbox copy. NEVER run the migration tool directly in production without sandbox validation.
2. In sandbox, enable Lightning Knowledge from Setup → Knowledge Settings.
3. Run the Lightning Knowledge Migration Tool from Setup → Knowledge → Lightning Knowledge Migration Tool.
4. Map each Article Type to a record type. Map each Classic field to its Lightning counterpart.
5. Submit; the tool runs asynchronously. Monitor via the Migration Tool log page.
6. After completion, validate: counts match, translations present, data categories preserved, publication states correct.
7. Test downstream consumers in sandbox.
8. Repeat in production once sandbox is signed off. The Migration Tool runs in production exactly the same way.

Why not the alternative: The Migration Tool handles version history, translation linkage, publication state, and data categories better than custom code in 90% of cases. Build custom only when the Tool cannot handle a specific concern.

Pattern 2: Custom Field-Mapping Decisions Requiring Pre-Processing

When to use: Some Classic fields need to be renamed, merged, or transformed before migration. Example: two Article Types both have a "Summary" field, but one is Description__c and the other is Summary__c — they should map to the same Lightning field.

How it works:

1. In the Classic source, normalize field names BEFORE running the Migration Tool. Add a unified Article_Summary__c field to every relevant Article Type, populate it via Apex script from the legacy fields.
2. Run the Migration Tool with the unified field mapping to a single Lightning field.
3. Drop the legacy fields after verification.

Why not the alternative: The Migration Tool maps fields 1:1 — it cannot merge two source fields into one target. Pre-processing in Classic is the right place for the transform.

Pattern 3: Article Type Consolidation Decisions

When to use: The org has too many Article Types (8+). Some are legacy / barely used. Lightning Knowledge benefits from fewer record types — easier list views, simpler approval workflows, simpler reporting.

How it works:

1. Pre-migration, audit Article Types by published-article count and last-update date.
2. Decide which Article Types collapse: e.g., merge "FAQ" and "Q_and_A" into one Lightning record type called "FAQ".
3. Use the Migration Tool's record-type mapping to point both Article Types at the single Lightning record type.
4. Document field-mapping conflicts (where the merged Article Types had different fields with similar purposes).

Why not the alternative: Migrating 1:1 preserves the current proliferation indefinitely. Migration is the moment to rationalize the taxonomy — afterward, consolidating record types requires more downstream rewiring (record-type-aware code, layouts, validation rules).

Pattern 4: Phased Channel Cutover

When to use: The org publishes articles to multiple channels (Internal, Communities, Public) and cannot risk a simultaneous cutover everywhere.

How it works:

1. Migrate to Lightning Knowledge in sandbox + production with all channels disabled in Lightning.
2. Cut over Internal users first: enable Internal channel for Lightning, disable Internal channel for Classic. Service agents use Lightning Knowledge.
3. After 2 weeks of stable Internal use, cut over Communities. Update Community Builder pages, retest.
4. Public Knowledge Base last. The public-facing surface is the highest-risk; cut last after all internal validation.

Why not the alternative: A single big-bang channel cutover risks customer-facing issues with no rollback time. Channel-by-channel preserves rollback at each step.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Sandbox-first inventory and decision matrix. Spin up a Full Copy or Partial sandbox (production enablement is irreversible without article deletion). Enumerate Article Types, custom fields, data categories, languages, channels, downstream consumers. For each Article Type, decide: keep as own record type, consolidate with another, or drop.
2. Pre-process if consolidating fields or types. Run Apex scripts in Classic to normalize fields BEFORE invoking the Migration Tool. Add unified fields, populate, and validate.
3. Run the Migration Tool in sandbox. Configure mappings carefully — this is the high-cognitive-load step. Submit, monitor via the Migration Tool log.
4. Validate exhaustively. Counts per Article Type → record type. Counts per language. Publication state distribution. Data category visibility (impersonate users via System.runAs). Sample articles open and render correctly.
5. Update downstream consumers in sandbox. Service Console pages, Communities, Einstein Bots, Apex code. Test end-to-end (Case Feed shows articles; Community search returns expected results).
6. Sign off; replicate in production with phased channel cutover. Run the Migration Tool with identical configuration in production. Cut over channels Internal → Communities → Public Knowledge Base with stability windows between each — never simultaneously.
7. Post-cutover audit and decommission. After a 30-day soak, run a last-known-good comparison (article count per category, per language, per channel matches the pre-migration baseline). Then decide retain (read-only audit) or drop the Classic Article Types — dropping is irreversible, so be deliberate.

Review Checklist

Run through these before marking work in this area complete:

• [ ] Migration Tool ran successfully in sandbox; log shows zero unrecoverable errors
• [ ] Article counts per former Article Type → record type match exactly (allow only documented exclusions)
• [ ] Translation counts per language match pre-migration baseline
• [ ] Data category assignments match: same articles in same categories
• [ ] Publication state distribution matches: Online / Draft / Archived counts agree
• [ ] User-perspective visibility tested for at least one user per relevant role / permission set
• [ ] Service Console Knowledge Component is added to Case page layout and surfaces articles
• [ ] Community Builder pages reference Knowledge__kav (not legacy article type sObject)
• [ ] Einstein Bot Knowledge actions updated and tested in conversation
• [ ] Apex code referencing FAQ__kav, HowTo__kav, etc. updated to Knowledge__kav with record-type filter; tests pass
• [ ] Phased cutover schedule agreed; channel-by-channel rollback plan documented
• [ ] Migration audit log persisted (Classic article ID → Lightning Knowledge__kav ID, per language, per version)

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Enabling Lightning Knowledge is irreversible without deleting articles. Once you enable Lightning Knowledge in Setup, you cannot revert to Classic Knowledge without disabling Knowledge entirely — which deletes ALL articles. This is why sandbox-first is mandatory. Test the full migration in sandbox before touching production.
2. Knowledge__kav is one sObject, but article-type record types still drive layouts and validation. The "we have one object now" mental model leads admins to assume layouts are global. They aren't — page layouts are still assigned per record type, validation rules use RecordType.DeveloperName predicates, and approval processes have record-type entry criteria. Migration must recreate per-record-type layouts and rules.
3. Translations preserve KnowledgeArticleId — break this and the language switcher disappears. The Migration Tool does this correctly. Custom migrations that insert translations as fresh records (each with its own KnowledgeArticleId) lose the master-translation linkage. The published article surface has a "view in another language" switcher that depends on this linkage; without it, users see translations as completely separate articles.
4. Data category visibility is per-role and per-permission-set; consolidation may unintentionally restrict. A Classic article visible to a role via category visibility may, post-migration, also be subject to record-type access controls. Users who lacked the new record type's read access lose visibility even though categories are unchanged. Audit visibility per user role post-migration.
5. The Service Console Knowledge Component requires Lightning Service Console — not Lightning Experience alone. Some orgs run on Lightning Experience for sales but Service Console for support. The Knowledge Component renders only inside Service Console. If your support team is using non-console Lightning pages, Knowledge surfacing will be broken until Service Console is adopted.
6. Salesforce Knowledge "channels" (Internal, Customer, Partner, Public) are visibility flags, not separate stores. A single article record can be visible in multiple channels via IsVisibleInPkb, IsVisibleInCsp, IsVisibleInPrm, IsVisibleInApp. Migration must preserve every flag per article. The Migration Tool does this; manual or partial migrations that miss a flag silently hide articles from the channel.
7. PublishStatus is queryable but not directly settable via DML — use KbManagement.PublishingService Apex methods. Custom migration code that tries to INSERT Knowledge__kav (PublishStatus='Online') fails. Lightning Knowledge requires using KbManagement.PublishingService.publishArticle(articleId, isFlagAsNew) to publish, editOnlineArticle(articleId, false) to create a draft from an online version, etc. The Migration Tool handles this; manual scripts must use the Apex publishing service.
8. Quick Actions on Cases referenced article-type sObjects directly in some setups. A "Insert Article" Quick Action that hardcoded FAQ__kav in its URL or relationship breaks after migration. Audit Case Quick Actions for __kav substring references and update to Knowledge__kav.

Output Artifacts

Related Skills

• admin/knowledge-base-administration — Use for new Lightning Knowledge configuration (post-migration)
• admin/approval-processes — Use when designing approval workflows on the migrated articles
• agentforce/rag-patterns-in-salesforce — Use when migrated articles will ground Einstein/Agentforce responses
• lwc/visualforce-to-lwc-migration — Use if Knowledge surfaces also include Visualforce pages being modernized
• data/data-cloud-data-streams — Use when migrated articles must also populate Data Cloud for AI grounding

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/well-architected.md
• templates/knowledge-classic-to-lightning-template.md
• scripts/check_knowledge_classic_to_lightning.py