Migrate KB Articles with all attachments from Dynamics 365/CRM

KB Articles Migration Guide

Yesterday, someone from a WhatsApp group asked me to help with "How to migrate KB Articles with all attachments from CRM to another system".

Migrating Knowledge Base (KB) Articles along with their attachments from Microsoft Dynamics 365 CRM to another system requires careful planning. Below is a detailed step-by-step approach to achieve this:

---

1. Analyze the Target System

Before starting the migration, ensure the target system supports the following:

• KB Articles: The system should have an equivalent data structure for KB Articles.
• Attachments: Ensure the target system can handle attachments and metadata such as filenames and file types.

2. Export KB Articles and Attachments from CRM

In Dynamics 365 CRM, KB Articles are stored as records in the KnowledgeArticle entity. Attachments are stored in the Annotation entity.

Option A: Use Power Automate or Power Platform Dataflows

1. Export KB Articles:
   • Use Dataverse (Common Data Service) connector in Power Automate to extract KB Articles from the KnowledgeArticle table.
   • Export key fields such as:
     • Title
     • Content
     • Author
     • Keywords
     • State (Published/Draft)
     • Created On / Modified On
2. Export Attachments:
   • Extract the corresponding records from the Annotation table where the objectid field links to the KnowledgeArticleId.
   • For each attachment:
     • Save the notetext (description), filename, and the encoded file (documentbody).
3. Store Data:
   • Save the exported data (articles and attachments) in a structured format like CSV, JSON, or Azure Blob Storage.

Option B: Use a Third-Party Tool

• Tools like KingswaySoft, Scribe, or XrmToolBox plugins (e.g., "Attachment Manager") can help you export KB Articles and attachments in bulk.

---

3. Transform Data for the Target System

• Clean and prepare the exported data to match the schema of the target system.
• Convert the CRM-specific fields (e.g., documentbody for attachments, which is base64 encoded) into formats required by the target system.

---

4. Import KB Articles and Attachments into the Target System

Option A: Use Target System's API

1. KB Articles:
   • Use the target system’s API to create articles.
   • Map fields from the exported data (e.g., title, content, metadata) to the corresponding fields in the target system.
2. Attachments:
   • Upload attachments using the target system’s API by:
     • Decoding the documentbody (base64).
     • Attaching the file to the corresponding article.

Option B: Use a File-Based Import

If the target system supports file-based imports:

1. Prepare files (e.g., CSV, JSON, or XML) for articles and attachments.
2. Use the target system’s import functionality to upload the data.

---

5. Validate the Migration

• Check that all KB Articles have been imported correctly.
• Ensure that attachments are linked to the correct articles and are accessible.
• Test article searchability and formatting in the target system.

---

Sample Power Automate Flow

A high-level view of how to use Power Automate for this migration:

1. Trigger: Run manually or on schedule.
2. Action (Dataverse): Fetch records from KnowledgeArticle table.
3. Action (Dataverse): Fetch related Annotation records for attachments.
4. Action (Apply to Each):
   • Save articles and attachments to a target storage location or directly post to the target system API.

Custom Migration Tool for Dynamics 365

However, I suggested using a custom console application built with C# to create your own migration tool.

The code leverages the Dataverse Web API along with the Microsoft.Xrm.Sdk and Microsoft.Crm.Sdk namespaces.

Below is the sample implementation:

Prerequisites

1. Add the following NuGet packages:
   • Microsoft.PowerPlatform.Dataverse.Client
   • Microsoft.CrmSdk.CoreAssemblies
   • Newtonsoft.Json (if needed for API calls to the target system)
2. Set up an Azure App Registration for authentication to Dynamics 365 CRM.
3. Provide necessary permissions to the app (Dataverse scope for KnowledgeArticle and Annotation).

Code

using Microsoft.PowerPlatform.Dataverse.Client;
using Microsoft.Xrm.Sdk.Query;
using Microsoft.Xrm.Sdk;
using System;
using System.IO;
using System.Text;
using System.Collections.Generic;

namespace KBMigration
{
    /// <summary>
    /// A console application designed to migrate Knowledge Base (KB) Articles
    /// along with their related attachments from Dynamics 365 CRM to a local directory.
    /// </summary>
    class Program
    {
        static void Main(string[] args)
        {
            // Step 1: Initialize the connection to the Dataverse (Dynamics 365) CRM
            string connectionString = "AuthType=OAuth;Url=https://yourorg.crm.dynamics.com;Username=yourusername;Password=yourpassword;AppId=your-app-id;RedirectUri=your-redirect-uri;";

            try
            {
                // Establish a service client to interact with CRM
                var serviceClient = new ServiceClient(connectionString);

                // Check if the connection is successful
                if (!serviceClient.IsReady)
                {
                    throw new InvalidOperationException("Failed to connect to CRM. Please check your credentials and network connection.");
                }

                Console.WriteLine("Connected to CRM successfully!");

                // Step 2: Retrieve and process KB Articles
                var articles = RetrieveKBArticles(serviceClient);

                if (articles.Entities.Count == 0)
                {
                    Console.WriteLine("No KB Articles found in CRM.");
                }
                else
                {
                    foreach (var article in articles.Entities)
                    {
                        Guid articleId = article.Id;
                        string title = article.GetAttributeValue<string>("title");
                        string content = article.GetAttributeValue<string>("content");

                        Console.WriteLine($"Processing Article: {title} (ID: {articleId})");

                        var attachments = RetrieveAttachments(serviceClient, articleId);
                        SaveArticleAndAttachments(articleId, title, content, attachments);
                    }
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"An error occurred: {ex.Message}");
            }
        }

        static EntityCollection RetrieveKBArticles(ServiceClient serviceClient)
        {
            // Implementation for retrieving KB Articles
        }

        static EntityCollection RetrieveAttachments(ServiceClient serviceClient, Guid articleId)
        {
            // Implementation for retrieving attachments
        }

        static void SaveArticleAndAttachments(Guid articleId, string title, string content, EntityCollection attachments)
        {
            // Implementation for saving articles and attachments
        }
    }
}
        

---

Potential Enhancements

• Retry Logic: Add logic for retrying failed operations (useful for network-related errors).
• Pagination Handling: If there are too many KB Articles or attachments, implement pagination to handle large datasets efficiently.
• Parallel Processing: Consider parallel processing to speed up the migration (using Task.WhenAll or Parallel.ForEach).

Key Considerations

1. Authentication

   Use Azure Active Directory authentication for security (replace Username/Password with ClientSecret for production).

2. Scalability

   For large datasets, consider using pagination with RetrieveMultiple.

3. Custom Fields

   If you have custom fields in KB Articles, include them in the ColumnSet.

4. Migration to Target System

   Replace the SaveArticleAndAttachments method with an API call or logic to import the data into your target system.