You are here:
Plan and Sandbox Test Your Migration
If you helped build your Classic knowledge base, you know that planning is critical. In fact, planning is the most important part of migrating to Lightning Knowledge.
Required Editions
| Available in Salesforce Classic and Lightning Experience. View supported editions. |
Sandbox Testing
Before performing a production migration, perform the migration in a sandbox. We strongly recommend testing in a full-copy sandbox. There is a high likelihood of data corruption when a partial-copy sandbox is used. The steps to perform a sandbox migration are the same as a production migration. After planning the migration and reviewing the Pre-Migration Checklist, perform either the Single Article Type migration or Multiple Article Type migration.
Pre-Migration Checklist
Whether you have one or multiple article types in Knowledge, read through the entire checklist before performing the sandbox test.
Article Types
When migrating from Classic to Lightning Knowledge, article types are mapped to new record types with the same name as the article types. They map to the API name, not the label name. Perform the following checks before proceeding to migration, and be mindful of these limitations.
- Deploy undeployed article types that you want to migrate.
- Identify and hard-delete article types that you don’t need.
- Change metadata settings in Knowledge article types in Setup. For example, add an article type, remove an article type, change settings on an article type, or change profile access to article types.
- Change the Default Article Type setting to None.
Remove the following dependencies. When the migration tool deactivates old article types, these objects aren’t always deleted, causing the migration to fail.
- Entities summarized by other entities
- Report jobs referencing a custom entity definition
- Article types referenced by the Agent Contribution setting
- Article types referenced by the Answers Promotion setting
- Custom objects used by matching rules
- Article types used by a duplicate rule
- Managed deletions that point to the article type
- Article types with non-deletable child custom fields from other managed packages
- Article types referred to by other features, such as Apex classes or data flows
Lightning Knowledge enablement is blocked if any packages created in the current org contain an article type. To enable Lightning Knowledge, remove article types from packages created in the current org.
Page Layouts
To give your users a great layout experience and access to the appropriate fields, adjust the page layouts. You can assign different page layouts per record type and user profile after the migration. Ensure that they are properly configured during the migration. Before starting the migration, remove page layouts that you don’t need.
Field Considerations
When mapping fields from multiple article types into one record type, keep these considerations in mind.
- Formula fields don’t migrate. After migration, create formula fields in the Knowledge object, and revise the formulas to reference the new object.
- Field dependencies don’t migrate. The migration tool migrates the fields. However, it doesn’t migrate their field dependency settings.
- Picklists and multi-select picklists only map if they have the same picklist values, the
same deactivated values, or the same global picklist. You can’t migrate dependent picklists.
The picklist options migrate, but the mapping between them doesn’t. You reset these after
migration. Also, default values for picklists and checkboxes don’t migrate to Lightning
Knowledge.Tip An org can have two picklist fields, A and B. A is the controlling picklist and B is the dependent picklist. The migration tool migrates both A and B, but they become standalone picklists, and you must redefine their field dependency settings.
- When mapping fields to other fields, choose the target field from a picklist that establishes which one is the primary field.
- If field size is reduced before migration but the articles have more characters than before field size reduction, all the text shows in Classic. However, after migration, the field size is truncated in the new object, which means that the additional characters don’t display. For example, if a field with 500 characters is increased to 1,000 in Classic, there can be 1,000 characters in the field, but only 500 of them display in Lightning.
- Required field flags don’t migrate. Therefore, required fields must be rethought after migration by each org because they all reside in the same table. It is better to manage required fields through page layouts or validation rules, unless they are truly required for all records across all record types.
- Migrated fields are named “Article Type_Field Name.” This convention removes field name conflicts.
- Deleted fields (soft-deleted fields that are retained for 30 days) don’t migrate.
Customizations and Managed (or Unmanaged) Packages
Inspect custom elements before and after the migration to ensure that they moved to the new Knowledge object. Sometimes they break, so prepare to assess this aspect of the org when performing the sandbox migration (before migrating in production). After migration, adjust custom elements that reference an Article Type to point to the new Knowledge object.
Uninstall all packages that include an article type. If you don’t uninstall those packages, you can’t enable Lightning Knowledge or start the Lightning Knowledge Migration Tool.
The Lightning Knowledge Migration Tool doesn't work for the Developer Edition if you define a namespace for packaging.
Here are a few examples of customizations to consider in your post-migration assessments.
- SOQL that queries the concrete entity name
- Visualforce pages that refer to old article types
- Code that uses field sets
- Apex code that refers to old article types
- Custom code using API calls that references article types
- Customer application logic such as current API code
- AppExchange packages
- Validation Rules
- CRUD (per Article Type)
- Applications that use metadata APIs on field sets or compact layouts
File and Attachment Considerations
Files from custom file fields in Classic Knowledge articles are moved to the standard Files object. After migration, users can view and attach files in the Files related list. When the Lightning Knowledge Migration Tool runs, you choose the basic visibility setting to apply to the migrated articles. You can choose to make files visible to all users with access to the article, including guest and Experience Cloud users, or only your internal users. If your internal users require access to files that you don't share with external users, you can adjust permissions for individual files after migration. To minimize the effort of setting file access, choose the visibility option that applies to most of your files.
Pre-Migration Best Practices and Post-Migration Considerations
Mapping—Assemble complex mapping ideas using a spreadsheet or organizational tool. Using a spreadsheet or organizational tool gives you a sense of how to map your knowledge base in Lightning.
Prepare for Validation—Save or print a few articles in advance so you can compare them afterward and verify a successful migration.
Records Owned by Inactive Users—Knowledge article versions (kav) linked to inactive users can cause problems during migration. To successfully migrate articles with inactive owners, the org preference Update Records with Inactive Owners must be enabled. If this setting is disabled in your org, the Migration Tool temporarily enables it during migration. Find the preference in Setup | User Interface.
Case and answer settings:
- In Case Settings, under Allow user to create an article from a case, set the default article type to None.
- In Answer Settings, under Allow users to create an article from a reply set the default article type to None.
Maintenance Notice: Stop Knowledge Base Activity During Production Migration
To prevent data loss, ensure that your users don’t edit the knowledge base for the duration of the migration. This action is most important for orgs with multiple article types, because migration takes longer and the data model changes significantly. After you begin the migration, it’s important to finish the process as soon as you can. Plan carefully to ensure minimal downtime for knowledge base users.
Before performing your production migration, communicate a company-wide bulletin to ensure that all changes to the knowledge base, its structure, and articles stop during migration. However, your users and customers can still read articles during migration. For orgs with multiple article types, the switch to articles in Lightning occurs at the start of the Activation stage.
Here’s a few examples of activities that must stop during migration.
- Editing articles
- Creating articles
- Changing the publishing status of articles
- Changing Knowledge setup, including changes to Data Categories
- API calls that change your Knowledge setup or articles
- Apex triggers that change or create Knowledge articles
- Votes on an article
- Linking to a case
- Linking to a work order or work order item
- Adding feed posts, changing feed posts, or following an article
- Edits to files attached to articles
- Adding topic mappings to articles in Experience Cloud sites
Get Ready to Use the Lightning Knowledge Migration Tool
After planning and successfully sandbox testing, contact Salesforce support and tell us you’re ready to perform the migration in your production org. We ask you about the results of your sandbox migration before we enable the tool in production. Do you have a single article type org or a multiple article type org? Use the appropriate guide and move your knowledge base from Classic into Lightning.
