The Complete Guide to Migrating a Salesforce Knowledge Base

knowl·edge ˈnä-lij. a(1) : the fact or condition of knowing something with familiarity gained through experience or association.
Gray clouds in front of a sunset sky.

Salesforce Knowledge is a solution designed to create a better customer experience for a company’s customers and internal employees by making answers to commonly asked questions easily accessible. It takes significant time and effort to implement Salesforce Knowledge, not because the solutions are particularly tricky, but because it takes time to aggregate and compile good information to meet customer needs and provide solutions to queries. These articles can contain many types of data, from plaintext that provides basic instructions to elaborate guidance with multiple images, embedded videos, tables, and more!


Knowledge Article on How to Make Pancakes.

Unlike traditional Salesforce records, you create a new version of the record each time you edit a Knowledge Article. Creating a new version of the record can be helpful if you need to roll back to an earlier version of an article since this type of immediate change reversal is near impossible for other Salesforce records.

With the investment in creating and maintaining a Knowledge base, it is not surprising that Salesforce customers want to keep these data sets intact when companies merge or split. As a result, Knowledge Articles must move from one Salesforce organization to another, a daunting task many avoid due to the perceived difficulties in performing this task. 

Version 2 of How to Make Pancakes, where the ingredient list is now a table instead of just a line of text.

Why Exactly Is Knowledge Migration So Hard?!

There are two common challenges in migrating Salesforce Knowledge articles:

1. Knowledge Versioning & Import 

The data model supporting Salesforce Knowledge Articles includes automatic article versioning each time a record is modified. Instead of a standard record edit, changing the text within a knowledge article requires a user to create a new version of the article. Thus, the revised article becomes the primary version, with the old version moving into draft status. When creating an article version, a version number is assigned, which can not be changed. These Knowledge Articles are edited frequently to keep in step with the company’s products or technologies. This creates a challenge for article migration as Salesforce has strict requirements around article import and a separate Knowledge API. 

4 versions of How to Make Pancakes!

Understanding the Knowledge API

To understand why loading Salesforce knowledge is so tricky, you must first understand that Salesforce Knowledge uses a different API than the standard data APIs. This API supports specific functions necessary to migrate Knowledge Articles with corresponding restrictions:

  1. Publish or Create a Draft Article
    One version of an article can be in draft status at a time. Therefore, the request to Salesforce will fail if one version is in draft status and another request is made to create a new draft. Similarly, articles can have only one published version.
  2. Archive a Published Article
    Only one published Knowledge Article version is supported, and all older versions must be archived. If an article is published, and you attempt to use the Knowledge API to push a new published version of this article, the request will fail. The original article must be moved into an archived status first. 

Knowledge Versions 

The first step to migrating a Knowledge Article is to upload the oldest version of the article using this Knowledge API. The article will then be automatically assigned a permanent version number that cannot change. Next, all versions of the Knowledge Article are uploaded in reverse chronological order, starting with the second oldest version. 

2. Images

Salesforce stores images in a separate location that is not readily accessible via a standard query over the API. For example, when inserting an image into a Knowledge Article, the image will appear visually on the article records, but what is actually in the article is a hyperlink. Salesforce stores the actual image in a separate system. Hence, a proper backup of Salesforce Knowledge requires the article and a different extract to this file subsystem to fetch any images. This Salesforce content storage method also means importing images requires restoring the raw data. After an import, Salesforce will automatically migrate the raw content to the subsystem and generate a new hyperlink. 


How Can I Migrate My Knowledge Base To a New Salesforce Instance? 

The overall approach to migrating Salesforce Knowledge follows the same pattern as any other Salesforce migration project. Data must first be extracted, transformed if needed, then loaded into the new Salesforce organization. 

Standard extract, transform, load (ETL) methodology is the simplest way to describe these migration projects. However, it is critical to leverage solutions that understand the complexities of Salesforce’s custom data models and API intricacies. For example, CapStorm’s solutions support Salesforce’s Knowledge Article data model, including image export/import and article versioning constraints. 

You can find additional Salesforce migration resources in this post, including a sample framework for end-to-end project management.

How Do I Ensure a Successful Knowledge Base Migration in Salesforce?

Let’s dive a bit deeper into how to efficiently perform Salesforce migrations including migration of Salesforce Knowledge Articles, following the ETL process. 


This step requires pulling data, including Knowledge, from the source system, typically Salesforce, into a staging environment. It is vital that the solution used for this extract retrieve both the text of the knowledge article body and any embedded images or videos. The image must include the raw content, not just hyperlinks, as you can not restore them. 

CapStorm’s CopyStorm application enables incremental extraction of Salesforce data, metadata, and schema, including Knowledge Articles, images, and images used in other objects –– even rich text fields that contain images. With Salesforce users entering new data and modifying records up to the cutover date, incremental extraction is critical to account for the static nature of the source Salesforce instance. Moreover, an extract that only retrieves new or changed data calls for a migration project that can happen in stages and allows for the migration of the core data set to a new Salesforce Org long before the final cutover date.


 Performing data transformation can happen in various ways, but the simplest is to use a migration staging database to manipulate data. However, using a migration staging database is sometimes only necessary in more straightforward scenarios. You can skip this step when, for example, a knowledge base using Salesforce’s default fields is migrated to a Salesforce organization also using the same field set. 

In more complex scenarios, data transformations require a database migration to get the data set into the format of the target Salesforce organization. CapStorm simplifies this process by creating the target database schema and replicating the object and field setup directly from Salesforce, creating a 1:1 mapping of the Salesforce data structure in a relational database.  


 The most complex part of most Salesforce data migrations is moving the data from a staging area into Salesforce, primarily due to Salesforce data relationships, meaning the connection between individual records results in data requiring a specific load order. Knowledge Articles also contain these restrictions along with some object-specific idiosyncrasies. 

CapStorm’s applications seamlessly migrate Salesforce Knowledge, including awareness of the Knowledge API, versioning requirements, and image movement. 

How to Perform a Salesforce Knowledge Migration Using CapStorm Technology

It’s easy to talk about Knowledge Migration in theory, but it is an entirely different thing to actually perform the task! Watch how to perform an end-to-end Salesforce Knowledge Migration in the video below!

For more detail, here’s a more in-depth explanation of what all was done to achieve an end-to-end Salesforce Knowledge migration with CapStorm:

Preparation: We created two Salesforce Trailhead Orgs and enabled Knowledge in Service Setup. Next, we assigned ourselves the Knowledge User permission from our System Administrator profile. The final preparation step was to create a Knowledge Article with an image, then edit it a few times to create multiple versions. However, before we did this, we cleared out the default Salesforce demo data in both environments so that the only Article in our source Salesforce Sandbox is one that we created. Therefore, the target Salesforce Org should be empty. 

Extract: CapStorm’s CopyStorm application replicated the Knowledge Article, including versions and images, into a Postgres database stored on our computer. We did not have to use a local installation or database – and we typically would not use a local laptop in most cases due to volume. We would instead recommend an AWS EC2 and RDS implementation. However, for one Knowledge Article, this simple setup was the easiest. To extract, we entered our Salesforce login credentials and pointed the software at an empty Postgres schema.

Transform: For reader’s sake, we skipped the transformation step to create a 2-minute demo video rather than a 30-minute presentation. However, it is relatively easy to manipulate data once it’s in a relational database. The two Salesforce organizations had an identical data model, given they were both default Trailhead dev environments. CapStorm’s solutions have built-in migration assistants for data mapping and record matching – which would have been handy for a more complex migration!  

Load: Performing the data import was the most straightforward part of the migration. We connected the CS:Restore application to the database created in the Extract step and clicked a few buttons to instruct the application to move my Knowledge Article and all other relationships, like the image content. The application automatically handled the Knowledge API complexities and restored the data as a mirror match of the original Knowledge Article. Viola! The migration is done – congratulations!

How Do I Integrate My Salesforce Knowledge Base With Other Systems and Tools In My Organization?

Ready for more? Salesforce Knowledge can be leveraged outside of the force platform and integrated with any other internal system. It’s simple, and the architecture follows the exact same process that was outlined for the migration. Salesforce Knowledge is replicated to a database that you own, on a frequency that you set. This mirror of Salesforce Knowledge off-platform is accessible and usable. You are only limited by your imagination.

Ready to dive into all things Salesforce Knowledge? Our experts are here to help you. 

Rebecca Gray

Rebecca Gray

Rebecca is 5 year Salesforce fanatic and certified Salesforce Admin, Service Cloud Consultant, Sales Cloud Consultant, and App Builder. She volunteers in the Salesforce community, leading the Saint Louis, MO Salesforce Admin Group and is a former Lightning Champion. In her day job, Rebecca supports Customer Success, helping CapStorm customers achieve their goals for Salesforce data management.

About CapStorm

CapStorm is the most technologically advanced Salesforce data management platform on the market. Billions of records per day flow through CapStorm software, and our solutions are used in every industry from credit cards, telecom providers, insurance agencies, global banks and energy providers.

Recent Posts

Follow Us

Become a CapStorm Insider

Become a CapStorm Insider

Subscribe to the CapStorm Forecast

This field is for validation purposes and should be left unchanged.