An article import is straightforward in mechanics but unforgiving in preparation. The sequence below walks through a typical migration from a legacy knowledge base into Salesforce Knowledge, scoped to one language and one product line. Multi-language and multi-region migrations follow the same pattern repeated per language.
- Map the source knowledge base to Salesforce Knowledge
Inventory the articles in the source system: total count, languages, categories, custom fields. Map every source category to a target data category, every source field to a target Knowledge field, and identify which source fields will not have a home (and where they go instead). Build a spreadsheet documenting the mapping and review it with the content owner. This step takes longer than every other step combined and skipping it is the most common reason imports fail.
- Prepare the target org
In a sandbox, create the data category groups and individual categories the import will reference. Create any custom Knowledge fields the source CSV uses. Enable the languages the import needs under Knowledge Settings. Confirm the article record type (if the org uses one) is configured. Run a small five-row sandbox import to validate the configuration. Iterate until the five-row test imports cleanly. Only then begin the real import preparation.
- Generate the CSV and ZIP, then upload through the Article Importer
Export the source articles into the CSV format the Article Importer expects, including the data category columns and the properties file. Bundle the CSV, properties file, HTML attachments, and image files into a single ZIP. From Setup, navigate to Article Importer (under Knowledge), upload the ZIP, configure language and record type, and start the import. Monitor the import job from the Article Imports queue. Most imports finish in minutes to hours depending on volume; very large imports run overnight.
- Review imported articles and publish in waves
When the import completes, open the Knowledge tab and filter to Draft articles. Walk through each one, spot-checking formatting, data category assignment, and field population. Fix HTML or category issues directly on the article in the UI, or in the source CSV and re-import for systematic fixes. Once a batch passes review, publish those articles. Repeat per content area until the entire migration is reviewed and published. Notify customer-facing teams when each batch goes live so they can update agent enablement.
- The rich-text body field has a 130 KB limit. Long source articles must be split or trimmed; the importer aborts the row when the body exceeds the limit.
- Imported articles enter Draft state and are not visible publicly until someone publishes them. This is deliberate, but stakeholders often expect immediate visibility.
- Source HTML with inline styles or absolute image URLs imports broken. Pre-process the HTML to use relative image paths and strip inline CSS before generating the CSV.
- Re-running the import with the same URL name updates existing articles rather than creating duplicates. This is the right behavior for ongoing sync but surprising on the first run.
- Translations require a separate import per language after the master language has been imported. Trying to import all languages in one CSV does not work.