Import Articles
Import Articles is the Salesforce Knowledge feature that bulk-loads knowledge content from external systems into the Salesforce Knowledge base.
Definition
Import Articles is the Salesforce Knowledge feature that bulk-loads knowledge content from external systems into the Salesforce Knowledge base. The Setup utility takes a CSV file plus a ZIP archive of attachments and creates Lightning Knowledge articles with their titles, bodies, data category assignments, file attachments, and translation metadata in a single load operation.
The feature is the standard migration path for orgs moving from a legacy knowledge management tool (Zendesk Help Center, ServiceNow Knowledge, Confluence, SharePoint, or a homegrown CMS) into Salesforce Knowledge. It supports the import of new articles, updates to existing articles, and translated versions of the same article in multiple languages. Successful imports require careful preparation of the source data, a valid configuration file describing the import, and pre-existing matching data categories, record types, and validation rules in the target org.
Anatomy of an article import
The CSV, the properties file, and the ZIP
An article import consists of three pieces packaged together. The CSV file holds one row per article with columns for the title, summary, URL name, body fields (rich text), data category groups, and any custom fields the org has added to the Knowledge object. The properties file (a small CSV named .properties) declares the configuration: source character encoding, default language, RecordType to assign, and the article type if the org still uses the legacy multi-article-type model. The ZIP archive contains the CSV, the properties file, any HTML file fragments referenced by the rich text fields, and any image or attachment files. The whole bundle is uploaded through the Article Importer in Setup.
Required preparation in the target org
Before launching an import, the target org needs to mirror the structure that the CSV references. Data category groups and the specific categories named in the import file must exist in the target org. Record types must exist if the import specifies one. Custom fields on the Knowledge object must exist with the API names the CSV references. The articles' language metadata must match a language already enabled on the org's Knowledge settings. Skipping any of these prep steps results in the import running but each row failing with a validation error, and the import logs become a long list of nearly identical errors that point at the missing dependency.
Rich text body fields and HTML preservation
The article body is usually a rich-text field that supports HTML. The importer preserves most standard HTML tags, including headings, lists, tables, images, and inline links. Style attributes and inline CSS are stripped to enforce the org's Knowledge formatting policy. Image references inside the HTML must point at relative paths to files included in the ZIP, which the importer uploads as ContentDocument records and rewrites the references to. Anything that depends on absolute URLs from the source system (cookies, session-bound media, embedded widgets) does not transfer. The cleanup of source HTML for Salesforce Knowledge compatibility is often the most time-consuming preparation step.
Multi-language translation imports
The importer supports translations through a multi-pass workflow. First, import the master-language articles. Each article gets a unique URL name and a Knowledge Article Version ID. Then, for each target language, import a separate CSV that references the master article by URL name and provides the translated title, body, and metadata. The translations are linked to the master article through the Knowledge data model, and the standard Article Translation workflows pick them up. Re-running an import with the same URL name updates the existing article rather than creating a new version, which is the right behavior for ongoing content sync from a source system.
Data category assignment
Data categories control article visibility and findability. The CSV file assigns one or more data categories to each article via specific column conventions: column name is the data category group, cell value is the comma-separated list of category API names. The importer validates that every category referenced exists in the target org and aborts the row with an error if a category is missing. For large knowledge bases moving in, the simplest pattern is to build a temporary mapping spreadsheet that maps source taxonomy values to target data categories before generating the CSV, then validate the mapping with a content owner before the import runs.
Article status, publication, and review state
Imported articles enter the system in Draft state by default. They are not visible to customers, agents, or the public Knowledge base until someone publishes them. This is intentional safety: it lets the import succeed and lets a content reviewer step through the imported articles, verify formatting, fix any HTML quirks, and publish only the articles that meet the org's quality bar. For very large imports where review is impractical, the post-import path is to use a bulk-update Apex job or Data Loader against the KnowledgeArticleVersion object to publish the articles en masse. Going from import directly to publication without a review pass usually surfaces formatting problems in customer-facing content, which is the worst place to discover them.
Logs, errors, and re-runs
Every import generates a log file with one row per source CSV row, reporting success or the specific error that prevented import. Common errors include missing data categories, invalid record type, HTML that exceeds the rich-text field size limit (around 130 KB per field), and unicode characters not in the declared encoding. Salesforce sends an email to the import initiator when the job completes. Failed rows can be corrected in the source CSV and re-imported using the same URL name, which performs an upsert. Iterative imports of the same CSV through the Article Importer are the right way to incrementally clean up a large migration over several days.
Run a Salesforce Knowledge article import
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.
Trust & references
Cross-checked against the following references.
- Import Articles into Salesforce KnowledgeSalesforce Help
- Data Categories for KnowledgeSalesforce Help
Straight from the source - Salesforce's reference material on Import Articles.
- Article ImporterSalesforce Help
- Knowledge SettingsSalesforce Help
- About Lightning KnowledgeSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. Which Salesforce Cloud includes Import Articles as a key feature?
Q2. What customer experience metric would Import Articles help improve?
Q3. How does Import Articles help support agents be more productive?
Discussion
Loading discussion…