Desk to Salesforce Article Migration Tool - Implementation Guide

Last Updated -

Note: This tool is in beta. Always test in sandbox prior to production.

The Article Migration Tool is a free Lightning application that migrates your Desk topics, articles, embedded images, article attachments (up to 8mb) from Desk to Service Cloud Lightning Knowledge. (Note: Article translations are not currently migrated.)

Have you created your Desk to Service Cloud Trial Org yet?

If you are a Desk customer evaluating Service Cloud, we highly recommend creating a Desk to Service Cloud Trial Org. This 90-day trial includes the best of Service Cloud plus Communities. It's also pre-configured to give a great Desk-like experience. If you wish to use the Desk Article Migration Tool in your existing org, click into the 'Other' tab below.

Setup Guide

Your Desk to Service Cloud Trial Org comes with the Desk Article Migration Tool pre-installed. Before kicking off a migration, simply complete these steps:

  1. (Optional) If you have Private Portal or IP Whitelist enabled on your Desk site, articles with embedded images will fail to migrate over. You may wish to temporarily disable these features for the duration of your article migration. How?
  2. At the top-right, click the Gear icon to enter Setup.
  3. On the left, use Quick Find to find Apex Settings, click the checkbox for 'Deploy Metadata from Non-Certified Package Versions via Apex', and click Save.
  4. Use the App Launcher to load Desk Article Migration Tool.
Pre-requisites
  1. (Optional) If you have Private Portal or IP Whitelist enabled on your Desk site, articles with embedded images will fail to migrate over. You may wish to temporarily disable these features for the duration of your article migration. How?
  2. If you don't have an org yet, create a dev org https://developer.salesforce.com/signup
  3. Your org must have a custom domain. This is required to use custom lightning components.
    1. If this is a production org, please review this change with your stakeholders and agree on a plan. Most production orgs shouldn't have issues with a custom domain but you should make sure everyone is aware.
    2. Setup → Company Settings → My Domain
    3. Type in a name and submit
    4. On My Domain page, once you see “Your domain name is ready”, click Log in
    5. On My Domain page, click Deploy to Users
  4. The user running the tool must have the System Admin profile and is provisioned as a Knowledge User. To enable this, go to Setup > Users > Users and edit the user. Check the box for Knowledge User and then save.
  5. The Knowledge product must be enabled in your Salesforce org. Salesforce Classic → Customize → Knowledge → Knowledge Settings.
  6. Lightning Knowledge must be enabled. If you are already using Classic Knowledge, please be aware that upgrading to Lightning Knowledge is irreversible. Please review with your team to ensure you are ready to upgrade. Check out this Trailhead module to help guide you through this process.
  7. Go to Setup > Apex Settings, check the checkbox for 'Deploy Metadata from Non-Certified Package Versions via Apex'. Save.
  8. Your org must have enough space to hold all of the articles and images/attachments you are migrating.
    1. Images and attachments are stored as Files. If you need an estimate of your attachment storage, please contact support@desk.com.
    2. There is a limit on the number of articles you can store. Unfortunately this is not listed in the Storage Usage section of Setup. You will need to reach out to Salesforce support or your Account Executive to confirm.
  9. (Optional) To migrate topics, your org must have less than three active data category groups and less than five data category groups total.
 
Setup
  1. Check that your org and user meet all of the pre-requisites above.
  2. Download the latest managed package: https://appexchange.salesforce.com/listingDetail?listingId=a0N3A00000FABALUA5
  3. Install the package for Admins Only.
  4. Assign the Desk Article Migration permission set to your user under Setup > Permission Sets. To assign the permission set, click on Manage Assignments near the top and then add your user.

Running the Tool

Select the Desk Article Migration app from the app selector.
  • Click the Migration Wizard tab at the top.
  • Review the Pre-flight check and make sure that you meet the requirements (see above).
  • Continue to the next step.
  • On the Connect to Desk.com step, enter the url for your Desk.com site. The format should be "https://yoursite.desk.com" or "https://customdomain.domain.com" without the quotes.
  • Click “Authorize Desk” to check your credentials. You will be redirected to the Desk login screen if you are not logged in. Once you're logged in, it will ask you to authorize the "Desk Article Migration Tool" app.
  • Click Yes, Grant Access and you will be returned to the wizard.
  • On the “Configure your Knowledge Migration” step, you have a couple choices to make:
    • Select if you want to migrate Topics. Topics are migrated into Data Categories.
    • Select a page layout if you want to automatically add your fields to the page layout. This is recommended if you are creating fields because they won't be visible unless you add them to a layout. 
    • Map the Desk fields to Salesforce fields.
      • A red star indicates a required field.
        • We have pre-mapped “Subject” to “Title”. This can't be edited.
        • Body field must be mapped, either to a new custom field, or to an existing rich text area field. It defaults to a new custom field.
        • It is important to map `In Support Center` to `Public Knowledge Base`. Otherwise, all articles will import as hidden and will need to be manually set to visible one at a time within Article Management.
      • All other fields are optional. The fields you map will depend on your support processes. We recommend mapping more fields rather than less, so that you have the data later if you need.
  • Click “Start Migration” to begin the article import. Once you start the migration, you will not be able to update the Desk credentials and field map until you complete the migration and start a new run.
  • On the “Migration Status” step, you can monitor the migration status, articles migrated/failed and the migration logs.
    • Once the migration finishes, we will set the status to “Done”. You can still interact with the migration at this point and if you restart the wizard, you will be returned to the “Migration Status” page.
    • If any articles failed during the migration, we will show a “Retry” button so that you can attempt to retry these failed records. It may be useful to click on the number of failed articles, which will take you to a list of these records.
    • Once you are done with the migration, click “Complete” at the bottom right to finish the migration. You will not be able to retry any failed records once you complete the migration.
  • Post migration steps
    • Check the logs for any notable errors. We will alert you if we ran into any trouble with the attachments or image links. You will need to manually migrate attachments over 8MB in size.
    • Check your article drafts. If we had any issues with the internal link replacement, we will leave the article in Draft status. Please review these manually and then publish. 

Publishing your articles to your Community portal

Follow these steps to get your imported articles live on your Community portal.

Features

Article Attachments (up to 8MB) are migrated over automatically.

Inlined Images are migrated and rehosted in Salesforce. We will move these over to Salesforce so that they don't break if your Desk site is disabled. This applies only to images that are hosted by Desk. Other images hosted on external sites will remain unchanged.

Links between articles are preserved. Often Desk articles will reference other articles within the knowledge base. To preserve these links after migrating, we will replace the links to the new Salesforce link. Note that these links will take you to the Classic version of the article if clicked within Salesforce. 

Known Limitations

The package cannot be installed in Professional Edition. Professional Edition doesn't allow custom Apex classes unless the managed package has gone through security review. The package is currently in security review and we hope to remove this limitation in the next month or so.

Attachments over 8MB are not migrated. You will need to manually move these over from Desk. We will alert you in the logs when this occurs.

Script tags and CSS are not allowed in the article body in Salesforce. The body of the article is stored in a rich text area field in Salesforce. Rich text areas will by default strip out javascript tags, style tags, and other more advanced tags. Desk does not have this limitation and if your Desk articles have these tags, the migrated articles may look a bit broken. You will need to manually fix these.

Translations of articles are not brought over. One reason for this is that the Lightning version of Salesforce Knowledge is still limited in its translation capabilities. We hope to add this functionality in a later update, once the Knowledge product has caught up.
 

Articles behind the Private Portal cause the migration to fail. We use the publicly available url to retrieve any inlined images. If these images are behind the login wall of the Private Portal, then we cannot access them. To bypass this, you will need to disable the Private Portal temporarily. To disable Private Portal, go to the Desk Admin and navigate to Channels > Support Center > Private Access. Change the Require Authentication setting to either For Nothing or For Interactions Only. Don't forget to click Update at the bottom and to revert the setting once you are done migrating. 

 

FAQ / Issues

Q: When I check the migrated articles, the body field and custom fields are not visible. How do I see them?
A: You must give yourself permission to newly created fields and add them to the Knowledge object page layout. See the post-migration instructions above.

Q: Some of the articles are in Draft mode while others are Published. Why is that?
A: If we had trouble processing the articles (replacing internal links or rehosting inlined images), then we will leave them in Draft mode. You should review these articles for broken links or images before publishing.

Q. I'm trying to connect to Desk and the page is spinning but nothing is happening. What do I do?
A: Confirm you followed the step to enable the option under Setup > Apex Settings. If you have already done that, reload the page and start over. The migration may show up as "Failed" when you reload. Click Continue and then Complete to start over.

Q. Can I run the migration multiple times?
A. Yes, running the migration multiple times will not duplicate the articles. It will update any existing articles and only add new articles. It will only update the fields that you mapped during the subsequent runs.

Q. Can I migrate from multiple Desk sites?
A. Yes, you can migrate from a different Desk site on subsequent runs. On the Connect To Desk step, simply add a new Desk url and proceed as normal. Note that if you migrated topics for the first site, migrating topics for a second site will break these topics. 

Q. How do I migrate article translations?
A. Article translations are not migrated by the Migration Tool at this time. 

Common Errors

AttachmentFetchAndInsert - execute : Script-thrown exception, (System Code)

This is usually caused by your Desk.com portal having Private Portal enabled. You can temporary disable Private Portal in Desk by going to Admin → Channels → Support Center → Private Access and changing Require Authentication to For nothing. Warning: This will make your articles on Desk public. When you're done with the import, you can revert this back to what it was.

{"message": "The record couldn’t be saved because it failed to trigger a flow. A flow trigger failed to execute the flow with version ID 3016A000000RBRr. Flow error messages: An unhandled fault has occurred in this flow
An unhandled fault has occurred while processing the flow. Please contact your system administrator for more information. Contact your administrator for help.","fields": [],"statusCode": "CANNOT_EXECUTE_FLOW_TRIGGER","extendedErrorDetails": null}

A flow, process, or workflow rule is preventing the record from being created. To get around this, you will need to disable the flow. One approach to doing this is leveraging a Custom Label the tool is designed to look for called “BypassProcessBuilder”. When the tool runs, it sets the value of this rule to “1” for the duration of the import. You can manually build a condition to check for this Custom Label value into your flows.