Desk to Service Cloud Case Migration Tool - Implementation Guide

Last Updated -

The Case Migration Tool is a free Lightning application that migrates your Desk users, groups, companies, customers, cases, interactions, notes, case attachments from Desk to Service Cloud.

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 Case 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 Case Migration Tool pre-installed.

  1. Visit https://appexchange.salesforce.com/listingDetail?listingId=a0N3A00000EFmqaUAD and install the tool.
  2. Use the App Launcher to load Desk Case Migration Tool.

Video Guide

Installation and Setup

  1. Prerequisites:
    1. Lightning
      1. The app runs in Lightning only. If you don’t have Lightning, you must Preview from the Lightning installation guide in order to run the app.
    2. My Domain
      1. The app won’t work without a custom domain for your org.
      2. See this guide for instructions on deploying a custom domain: https://help.salesforce.com/articleView?id=domain_name_guidelines.htm&type=0
      3. Make sure you deploy your custom domain to all users. If deploy your domain after installing the tool, you will need to re-install it.
  2. Installation:
    1. Log into your Salesforce instance and navigate to AppExchange.
    2. Enter “Desk to Service Cloud” to search for the migration tool.
    3. Install the App directly from the AppExchange.
      1. If you're installing into a production org the link should start with "login.salesforce.com"
      2. If this is a sandbox change the URL to "test.salesforce.com"
      3. Don’t forget to grant access to admins.
 

User Permissions and Settings:

We recommend creating a migration user in Salesforce and logging in as that user when using the tool.

Migration users should have the proper system permissions for the data in your migration. Some permission examples include but are not limited to:

  1. System Administrator profile
  2. Assign migration user the SCMT Audit Permission Set (see below)
  3. Full access to all the fields and objects in the migrated data
  4. Live Agent should be available for moving LiveAgent Chats. See the instructions here

Click here for a video demo of the full setup.

  1. Login to Salesforce as the user you wish to use to perform the migration.
  2. In Setup → User Interface → User Interface, enable "Set Audit Fields upon Record Creation" and "Update Records with Inactive Owners".
  3. In Setup → Custom Code → Custom Metadata Types
    1. Click “Manage Records” next to Desk Config
    2. Edit “SCMT Configuration”
      1. Check the “Active” box if it is not already.
      2. Update the fields with your Desk.com url and tokens. Endpoint should be in the format “https://yoursite.desk.com” without the quotes. Your consumer key/secret and token key/secret can be found in Desk under your client application's details in Admin → Settings → API → My Applications. Check out this article for more detailed instructions.
      3. Save.
  4. Setup → (Manage) Users → Permission Sets
    1. Clone the SCMT Audit permission set and set a unique description so you can tell it apart from the original. Do not change any of the other fields. The following steps are done in this permission set.
    2. Enable System Permissions → “Set Audit Fields upon Record Creation”
    3. Enable System Permissions → “Update Records with Inactive Owners”
    4. Enable the Desk.com Migrated record type for Accounts, Contacts and Cases.
      1. In the permission set under “Object settings”, select Accounts. Edit the settings and find the “Record Type Assignments” section. Click the checkbox for Desk.com Migrated Companies.
      2. In the permission set under “Object settings”, select Contacts. Edit the settings and find the “Record Type Assignments” section. Click the checkbox for Desk.com Migrated Contacts.
      3. In the permission set under “Object settings”, select Cases. Edit the settings and find the “Record Type Assignments” section. Click the checkbox for Desk.com Migrated Cases.
    5. Now assign the permission set to the user who will run the migrations. Manage Assignments → Add Assignments → Select a user.
  5. Setup → Custom Label
    1. Verify a custom label exists called "BypassProcessBuilder". If one doesn't exist, click "New Custom Label" to create one with Short Description / Name BypassProcessBuilder and Value of 0.
 

Migration Steps

To use the tool, select Desk Case Migration from the apps menu. Select the Migration Wizard tab.

Here’s a quick video showing the Wizard in action: https://screencast.com/t/ROcSKvZvPZ

Step 1: Pre Flight Check
  1. If you have all the License Permissions and Feature Enablement items checked, proceed to next step by clicking Continue at the bottom-right.
  2. Otherwise, see the “User Permissions and Settings” step above.


Step 2: Connect to Desk
  1. If you entered your credentials in the Custom Metadata Record from the setup stage, you should see your credentials here already.
  2. If not, please enter them. Endpoint should be in the format “https://yoursite.desk.com” without the quotes. Your consumer key/secret and token key/secret can be found in Desk under your client application's details in Admin → Settings → API Applications.
  3. Proceed to the next step.

Step 3: Review Your Metadata
  1. This step is primarily to show you which fields and queues will be created in Salesforce. Initially, the fields will be blank. Clicking Next will initiate this migration.
  2. If you click Back from step 4, you’ll see that the fields and queues are now created.

Step 4: Migrate Objects
  1. Migrate each object in order starting with Users. Wait for each step to complete before moving to the next one.
  2. Be sure to check the Bulk Job after each migration, especially if there are failed records.
  3. See below for notes on each object.
 

Object Level Details

We recommend running the object migrations in order, waiting for each object to finish. Certain objects require parent objects to be present.

Here's a video describing each object and some tips on running the migration: https://screencast.com/t/dAd2qE0sfQF

Users

  • Before migrating the users, make sure there are enough user licenses.
  • The Select a profile drop-down list populates all the profiles with a Salesforce License type. The profile selected from this list will be assigned to all the users that migrated from Desk.
  • All the migrated users will default to inactive in Salesforce.

Group Members

  • Groups are migrated as Queues in Salesforce, per Step 3.
  • This step will assign users to the proper Queues.

Accounts

  • There are two options to select which data you would like to migrate:
    • Migrate All Data: This will migrate all your companies in Desk to Salesforce.
    • Migrate Data Range: This will migrate companies created after the entered timestamps in UTC.
  • For Record Type, select 'Desk.com Migrated Accounts'.

Contacts

  • There are two options to select which data you would like to migrate:
    • Migrate All Data: This will migrate all your customers in Desk to Salesforce.
    • Migrate Data Range: Here you can either select a created date, or a starting Desk customer ID. Timestamps are in UTC.
  • For Record Type, select 'Desk.com Migrated Contacts'.

Cases

  • There are two options to select which data you would like to migrate:
    • Migrate All Data: This will migrate all your cases in Desk to Salesforce.
    • Migrate Data Range: This will migrate cases created after the entered timestamps in UTC.
  • For Record Type, select 'Desk.com Migrated Cases'.

Notes

  • There are two options to select which data you would like to migrate:
    • Migrate All Data: This will migrate all your notes in Desk to Salesforce.
    • Migrate Data Range: Here you can select a starting page from the Desk.com notes endpoint (/api/v2/notes).

Interactions

  • There are two options to select which data you would like to migrate:
    • Migrate All Data: This will migrate all your interactions in Desk to Salesforce.
    • Migrate Data Range: Here you can select a starting interaction ID from the Desk.com interactions endpoint (/api/v2/interactions).

Attachments

  • All Desk case attachments will be migrated as Attachments on the Case object.

Migration Complete!

After migrating all of these records, your migration is complete. You can use the App Launcher to hop out of the migration tool and browse your imported records to review the imported data.

 

What’s Not Available At This Point

  1. Case Data:
    1. Case History
    2. Merge case data
    3. Split case data
    4. Linked case data
    5. Customer Satisfaction (CSAT) score
  2. Admin Settings:
    1. Rules
    2. Macros
    3. Filters/queues
    4. Dependent pick lists
    5. Portal user
    6. Snippets and translations
    7. Email Templates
    8. Support Center Themes
    9. Site Settings
    10. Social Personas
    11. User Roles

Service Cloud & Desk Differences

We have created a Desk.com to Salesforce Service Cloud Migration Considerations document to outline the differences between Desk.com and Salesforce in detail. Click here for more details.
 

Frequently Asked Questions

Q: I can't see the migration wizard. Why is that?
A: The most likely explanation is that you have not deployed a custom domain to your org. If you installed the package before deploying your custom domain, try uninstalling the package and then reinstalling.

Q: What permissions do I need in Salesforce?
A: You should have read/write access to all of the objects, fields and permission sets you are migrating. All of this is included in the SCMT Audit permission set. The migration tool can update a clone of this permission set to allow for all migrated custom fields, so please follow the instructions above.


Q: What permissions do I need in Desk.com?
A: You should be an Admin in Desk.com that has access to generate OAuth tokens. In the Desk.com admin panel, click the gear icon to go to Settings. On the left hand side there is a link for API. Generate a key and secret (callback URLs are not required). These will be your OAuth key and secret. There is a link that reveals your access key and secret. You need both pairs to use the migration app.


Q: Why do my usernames have a string of numbers appended to the end?
A: By default, a random string is appended to your usernames. Usernames cannot be reused in any production or sandbox. It's easier to generate a list or report of users after migration is complete and change the names than it is to partially migrate users and lose the migrated data.


Q: What is installed in my org?
A: The application installs custom apps, tabs, objects and custom fields. After migration is complete the installed metadata can be removed.


Q: Why do migrated custom fields have “SCMT_Desk” as a prefix?
A: Custom fields have this prefix in order to prevent any name collisions,. After migration is complete you can change the field name and label. If you plan on doing this, you should do so before referencing the fields in any Apex, Visualforce, or Workflows.

Q: I'm getting an INVALID_SESSION_ID error on step 3
A: Go to Setup > Security > Session Management and remove all of the sessions. This will force everyone to log in again unfortunately.