Desk to Salesforce Migration Wizard - Implementation Guide

Last Updated -

The Desk Migration Wizard is a free Lightning application that migrates your Desk case data (companies, customers, cases, interactions, notes, attachments) and article data (topics, articles, article translations, embedded images, article attachments up to 8mb) from Desk to Service Cloud.

Installation & Setup

If you're using a Desk to Service Cloud Trial Org, no setup is required. Your org comes with Desk Case Migration Wizard pre-installed and configured.

Pre-requisites
  1. Important: Review our Existing Org Migration Best Practices guide.
  2. 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
  3. The user running the tool must have the System Admin profile and is provisioned as a Knowledge User and Service Cloud User. To enable this, go to Setup > Users > Users and edit the user. Check the box for Knowledge User and Service Cloud User and then save.
  4. Before you can enable Knowledge you must switch to Salesforce Classic. 
  5. Navigate to Setup → Knowledge → Knowledge Settings.
  6. Lightning Knowledge must also 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 and check the box for "Deploy Metadata from Non-Certified Package Versions via Apex". Save.
  8. Email to Case must be enabled under Setup > Support Settings > Email-To-Case.
  9. Enhanced email must be enabled under Setup > Email > Enhanced Email.
  10. Enable Audit Fields
    1. Under Setup > User Interface > User Interface, check the box for "Enable "Set Audit Fields upon Record Creation" and "Update Records with Inactive Owners" User Permissions". Save.
    2. Under Setup > Users > Permission Sets, create a new permission set called "Audit Fields". In the permission set, go to System Permissions. Edit the page and enable "Set Audit Fields upon Record Creation" and "Update Records with Inactive Owners". Save.
    3. Click Manage Assignments > Add Assignments and select the user who will run the tool. 
  11. Your org must have enough space to hold all of the Accounts, Contacts, Cases, 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.
  12. (Optional) To migrate topics, your org must have less than three active data category groups and less than five data category groups total.
  13. (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?
 
Setup
  1. Check that your org and user meet all of the pre-requisites above.
  2. Use this link to install the latest version of the Desk Migration Wizard.
  3. Install the package for Admins Only.
  4. Assign the Desk 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.

Usage Video Guide


Usage Steps

  1. Open the App Launcher and click Desk Migration Wizard.
  2. Select whether to import Articles (which includes Topics, Embedded Images, and Article Attachments) or Cases (which includes Users, Groups, Customers, Companies, Interactions, and Notes). 
  3. You may see a checkbox "I have checked the box under Setup > Apex Settings". If so, check the checkbox.
  4. At the bottom-right, click Continue.
Connect to Desk.com
  1. For "Desk.com Endpoint", type in your full Desk site URL. For example, https://mysite.desk.com or https://support.mysite.com (if your Desk site has a custom domain CNAME).
  2. Click the button Authorize Desk.
  3. At the bottom-right, click Continue.
 
Configuration Your Migration
  1. On the left, read the instructions and click into Articles tab.
  2. For Step 1, it's recommended to import your topics. If you uncheck this box, topics will not be imported and you'll need to manually create / manage topics post-import.
  3. For Step 2, it's recommended to select your primary layout (often called "Knowledge Layout") so that fields imported will be visible to your team. If you uncheck this box, you'll need to manually modify your layouts to make fields visible.
  4. For Step 3, choose which article fields to import. The only required fields are Subject and Body. Body will require mapping to an existing custom field or creation of a new field. We recommend leaving the map of 'In Support Center' to 'Visible in Public Knowledge Base'.
  5. When finished with configuration, click Start Migration at the bottom-right.
  6. You may be prompted to confirm you are okay with the risks of auto-matching new, imported data with any existing data. If uncertain, click Cancel and click Need further help? at the top-right of the page to create a support ticket with the Desk team so we can help address any concerns. Otherwise, click Accept and Start Migration to begin the migration.
 
Migration Status
Once this step loads, the migration is underway! You can monitor the status at the top (e.g. "Running") and see a detailed list of objects migrated in the Objects table. If the Records Failed count is higher than 0 for any object, click the number to view more details.

Scroll down to view a full log of the import which will surface any notices or errors. 

Once the Migration Status is updated to Done, a new section will appear beneath the Objects table called "Next Steps". These are optional suggested post-import steps we recommend completing prior to marking the migration complete.

When finished with post-migration steps, click Complete at the bottom-right.
Connect to Desk.com
  1. For "Desk.com Endpoint", type in your full Desk site URL. For example, https://mysite.desk.com or https://support.mysite.com (if your Desk site has a custom domain CNAME).
  2. Click the button Authorize Desk.
  3. At the bottom-right, click Continue.
 
Configuration Your Migration
  1. On the left, read the instructions and click into Users tab.
    • Select a profile to import users as. If unsure, 'Standard User' is most common.
    • You must map all users. Only active users will use up a license.
  2. On the left, read the instructions and click into Group tab.
    • You must map all groups.
  3. On the left, read the instructions and click into Accounts tab.
    • To ensure mapped fields are visible to your users, you can optionally select a Layout.
    • You must map Name field. All other fields are optional.
  4. On the left, read the instructions and click into Contacts tab.
    • To ensure mapped fields are visible to your users, you can optionally select a Layout.
    • You must map Last Name field. All other fields are optional.
  5. On the left, read the instructions and click into Cases tab.
    • For Data Set, you must either migrate all cases, all cases since a specific Created Date, or all cases since a specific Modified Date.
    • To ensure mapped fields are visible to your users, you can optionally select a Layout.
    • You must map Subject field. All other fields are optional.
  6. When done mapping, click Start Migration at the bottom-right.
  7. You may be prompted to confirm you are okay with the risks of auto-matching new, imported data with any existing data. If uncertain, click Cancel and click Need further help? at the top-right of the page to create a support ticket with the Desk team so we can help address any concerns. Otherwise, click Accept and Start Migration to begin the migration.
 
Migration Status
Once this step loads, the migration is underway! You can monitor the status at the top (e.g. "Running") and see a detailed list of objects migrated in the Objects table. If the Records Failed count is higher than 0 for any object, click the number to view more details.

Scroll down to view a full log of the import which will surface any notices or errors. 

Once the Migration Status is updated to Done, a new section will appear beneath the Objects table called "Next Steps". These are optional suggested post-import steps we recommend completing prior to marking the migration complete.

When finished with post-migration steps, click Complete at the bottom-right.

Running the Tool

Select the Desk 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.