Microsoft Dynamics CRM 2016 (both Online and on-premises) has introduced a new knowledge management system that offers many new features compared to the knowledge management capabilities offered in previous versions. Powered by the also newly introduced interactive service hub, the new knowledge management system allows the creation of much richer knowledge articles with support for embedding external multimedia contents, such as images and videos, as links. Additionally, the new knowledge management feature provides support for article versioning and translation, which makes it a truly enterprise ready feature.
As Microsoft rolls out these new features, it becomes a natural decision for Microsoft to announced the deprecation of old knowledge management entities, which include KbArticle, KbArticleComment, and KbArticleTemplate. Further details about the deprecation can be found in one of Microsoft recent announcements.
If it happens to be the case that you have used the old knowledge articles in past or current CRM projects, you likely need to migrate data from the old knowledge management feature to the new one.
In this blog post, we will demonstrate how to use our software to migrate old KbArticle data to the new knowledgebase without having to write a single line of code. When discussing the migration project, would like to also discuss the techniques that can be used to work with article versioning.
Some background information about the new Knowledge Articles
The access to the new knowledgebase functionality is available in a yellow bar above the Articles grid:
By clicking the “Access it here” link, you will be directed to the new knowledge articles page:
Each article has a major version number, a minor version number and it also comes with a language attribute. When you create a new knowledge article record, the major version is automatically set to 1 and minor version to 0. If no other language is specified, the article would be generated in the default language of the CRM installation.
When you create a knowledge article record through the UI, the Article Publish Number is automatically generated based on the format specified in the CRM settings, it stores the unique ID as reference to look up knowledge articles and remains the same across versions and translations.
The new knowledge management solution provides a rich text editor in HTML format as compared to associating with an Article template to define the formatting and sections in the old Article entities.
How To Migrate To CRM KnowledgeArticle Entity
The core of the new knowledge management solution is the KnowledgeArticle entity which stores and manages knowledge locally in CRM. Every knowledge article record has a root article record internally created by CRM, the root article acts like a container for all article versions and translations. The root record would be automatically deleted if all article versions and translations are deleted. It is easy to identify the root record since it has a “True” value in isrootarticle field and NULL values for all the contents and formatting fields.
Since all versions and translations and the root record have the same Article Publish Number, we would face two challenges if we try to migrate the KbArticle data to KnowledgeArticle entity:
- How do we manage the versioning if any KnowledgeArticle records are updated with new versions during the migration process (let's say your migration spans a few weeks while you have the old CRM system and new CRM system running in parallel)?
- How do we manage and work around with the root record, as it cannot be updated or deleted by external methods (CRM has a mechanism to delete it internally)?
You may find it difficult to overcome these obstacles, but there is always a solution when using our software. You can create the new knowledge records and update the latest version of the existing article records with our CRM integration toolkit.
It is quite easy to identify the latest version of existing article records and non-existing records by using a Left Join to the target knowledgebase and join on the Article Public Number, you will also need to include two fields from the target KnowledgeArticle entity: islatestversion and knowledgearticleid.
The islatestversion field can be used as an identifier to find the latest version of existing records and new records:
- Islatestversion=NULL: non-existing records;
- Islatestversion=True: latest version of existing records.
The left join can be performed by using FetchXML queries if your migration is within one CRM system, otherwise you need to use the SSIS Merge Join component to achieve this goal.
Let’s start from the FetchXML query option, you would be using a FetchXML query such as the following to combine the data in KBArticle and KnowledgeArticle:
<fetch mapping='logical'>
<entity name='kbarticle'>
<all-attributes />
<link-entity name="knowledgearticle" from="articlepublicnumber" to="number" alias="ka" link-type="outer">
<attribute name="islatestversion" />
<attribute name="knowledgearticleid" />
</link-entity>
</entity>
</fetch>
If you are migrating articles from two different systems, you would need to use an SSIS Merge Join component to join the data that you read from the source system and the CRM destination system.
Further, the state of Knowledge Article has expanded by four more states than the old KBArticle as shown below:
|
State |
KBArticle |
Knowledge Article |
|
0 |
Draft |
Draft |
|
1 |
Unapproved |
Approved |
|
2 |
Published |
Scheduled |
|
3 |
|
Published |
|
4 |
|
Expired |
|
5 |
|
Archived |
|
6 |
|
Discarded |
This issue can be easily taken care of by using our CRM OptionSet Mapping component to manage the mappings of the statecode values (click here for the detail use of this component):
Then we use an SSIS Conditional Split to divide the input data based on the value of islatestversion field to locate new records and the latest version of the existing records.
The last step is to direct the input data into the target CRM servers using two CRM destination components. You just need to supply necessary fields in the destination component to create the new records, and update the latest version of the existing records by using “Primary Key” (knowledgearticleid) as the matching criteria.
Please note that you need to make sure that you have turned on “Ignore Null-Valued Fields” option in the CRM destination component. Otherwise you may receive “An unexpected error occurred” error message because CRM does not like having NULL value sent to keywords and description fields.
The data flow of Articles migration within one system would be:
The migration dataflow between two systems might be:
Sample SSIS Package
A sample SSIS package that includes both FetchXML task and SSIS Merge Join task can be download here.
The sample package was prepared in a SQL Server 2008 R2 format, and it should automatically upgrade if you are using any newer version of SSIS.
Closing Note
Our data flow task looks pretty complicated, the main reason is, we tried to show you a robust way to migrate from a legacy knowledgebase system to the new CRM one while keeping the two systems running at the same time, in which case there is a chance that a new version has been created in the new CRM system. If it is a one-off migration, the data flow can be much simpler, since we don't need to worry about the versioning in the new CRM KnowledgeArticle entity, and it would be a straight entity field-to-field mapping.
The sample package we provide in this blog post can also be used as the reference for the case that you need to integrate a third-party knowledgebase system with the new CRM KnowledgeArticle entity on an ongoing basis.
Hope you find this blog post useful.