Migrating from Desk to Service Cloud via Data Loader

Last Updated -

How to use this guide:

The purpose of this guide is to provide best-practices for importing standard Desk CSV export data into Salesforce. We have altered the format of the Desk exports in order to make it more compatible for the Salesforce Data Loader tool, which is used to perform the Salesforce import. Please keep in mind that there are multiple approaches to importing the data in this fashion and that your use case may be different.

This guide assumes that you have an understanding of the Data Loader and Setup section of Salesforce. This guide should be performed by or in collaboration with your Salesforce Admin.

Sample Data

If you would like to use sample data to test this process, use the file below.
2017-09-22_zzz-demo-49_site_export.zip
 

Making decisions

Data Structure

Desk and Salesforce have fundamental differences in data structure that must be addressed in order to be successful. For example, Salesforce only allows one email address per Contact, whereas Desk allows up to 10. In this situation, there is no perfect way to make the data fit. Our recommendations are for the easiest method that we found. Where there are options, we do our best to give relevant information to make a decision.

Here's a simplified overview of the data structure in Desk:

Data Relationships

The Data Loader uses the Salesforce ID field to map child records to the parent. The export from Desk will not have the ID of the Salesforce records beforehand, which makes it difficult to create these relationships. However, the Data Loader can relate objects upon import using an external ID field. Where possible, we will set the external ID field with the Desk ID. Then when the child objects are imported, the external ID can be used to relate it to the proper parent. Please review this article before proceeding: https://help.salesforce.com/articleView?id=000002783&type=1

Field Mapping

The Salesforce Data loader requires fields to be mapped manually, but mapping templates can be saved. The suggested mappings can be found here. Please review each mapping as your requirements or field names may be different. You will need to edit the mappings to add custom fields as necessary.

Testing

Please use a sandbox or use partial data sets while testing out the process. There are many steps and it's unlikely that everything will be perfect on the first run.

Setting Object Timestamps

Some objects allow setting various timestamps to the original date rather than the import date. To do this, you will need to enable Audit Fields on your Admin profile. Here are the instructions on how to enable this: https://help.salesforce.com/articleView?id=Enable-Create-Audit-Fields&type=1

Case Assignment

Desk cases have an assigned agent, which is equivalent to the Case Owner field in Salesforce. Desk's assigned group is roughly equivalent to Salesforce's “Queues” feature. However a case in Salesforce can be assigned to either a User or Queue but not both. To accommodate this, we recommend adding a case custom field (text or picklist) to hold the group. If there is no assigned user in Desk, then the group will be both the Case Owner and held in the custom field.

Additionally, limitations with the Data Loader prevent the Case Owner from being mapped to an external ID field. This makes it more difficult to import cases. Here are the main options:

  1. Import the Users and then export them, including the Salesforce ID. In the tickets spreadsheet, replace the assigned_user_id with the corresponding Salesforce ID in each row.
    1. This can be done using find and replace or with an Excel macro or local code script.
  2. Store the user and group in a custom field instead of the default Case Owner field. All cases would then be assigned to the importing user.
  3. Store the user in a custom field and then use Case Assignment rules to assign them properly once imported.
  4. Ignore the user and group altogether. All cases would then be assigned to the importing user.

 

Resolving Errors

Due to the complex nature of Salesforce, there will likely be errors during this process. Here are some common errors and how to resolve them (variable parts of the error are marked in italics):

  • Required fields are missing: [Field Name]
    • This error means that a field required to create a record is missing. Redo the import step and make sure the field is mapped properly.
  • Closed Date: invalid date: Tue Oct 15 23:43:00 GMT 15
    • This error means that the date field is improperly formatted. The format of all fields must be YYYY-MM-DDThh:mm:ss+hh:mm .
    • Open the file of the offending date and reformat.
  • Foreign key external ID: ####### not found for field Desk_ID__c in entity User/Account/Contact/etc.
    • Generally caused when a record fails to be created and then in a later step, a child record attempts to reference it.
    • This error is caused by attempting to upsert a record using an external id field to establish an object relationship, but that external id value is not found. To troubleshoot, check the spreadsheet for the object referenced in the error message. Find the record by the external ID value and then attempt to find that record in Salesforce. Either the record was not created or the Desk_ID field was not populated. Correct the issue and then rerun the upsert.
  • Unable to create/update fields: LastModifiedDate, CreatedDate. Please check the security settings of this field and verify that it is read/write for your profile or permission set.
    • See Setting Object Timestamps section above
    • If you are getting this error on an update to an existing record, remove the LastModifiedDate and CreatedDate fields from the field map and try again.

 

Steps

These steps must be taken in order. If there are errors they must be resolved before moving to the next object.

  1. Export data from Desk and unzip the files.
    1. Request a data loader export by emailing support@desk.com. It may take several days or more to provide the export depending on the volume of data.
    2. Download the file to your computer and move the file to a folder with a file path that is easy to work with. You will need the file path later.
    3. Decrypt the files and unzip.
  2. Download the Data Loader from Salesforce: Setup > Administration Setup > Data Management > Data Loader
  3. Create a custom field “Desk ID” for each possible parent object (Accounts, Contacts, Cases, Users, Email Message ). This field should be Text, 255 characters, and have the External ID checkbox selected on creation. The Field Label is Desk ID and the Field Name is Desk_ID. After creation, view the field to ensure the API name for these fields are Desk_ID__c, as the pre-made field mapping files rely on this. Here's an example of the proper setup: https://screencast.com/t/9SdNTSkt2f
  4. Recreate any Case, Customer, and Company custom fields in Salesforce.
  5. (Optional) Create a Case custom field to house the Desk assigned group.
  6. Create a Case custom long text field to house the labels.
  7. Open the data loader and connect it to the salesforce instance.
    1. Note: If you add a new field in Salesforce, it will not show up in the Data Loader unless you close the application and reconnect.
    2. If you are connecting to a sandbox instance, please login with https://test.salesforce.com
  8. Import Users
    1. Before using the data loader, the spreadsheet must be modified.
      1. Salesforce requires certain fields when importing users. These are fields not found in Desk. Every field in the export must be filled out except “Deleted At”. We have provided blank columns for you to use.
    2. Open the agents_dataload_1.csv spreadsheet.
    3. Fill out the Username, Alias, TIMEZONESIDKEY, LOCALESIDKEY, EMAILENCODINGKEY, PROFILEID, LANGUAGELOCALEKEY, ISACTIVE fields for all users. It may be easiest to export your current users to use as an example for these fields as they have a specific format.
      1. The profile ID can be found in the url of the profile in Setup (Classic Salesforce).
      2. Values for ISACTIVE are TRUE and FALSE. You should use TRUE if you plan on assigning cases to these users later. If you set the value to TRUE, you must have enough licenses to house all the new users.
    4. Save the spreadsheet.
    5. In the Data Loader, select Insert. Select Users as the object and browse for the agents_dataload_1.csv spreadsheet.
    6. Click Next.
    7. On the mapping page select Choose Existing Mapping and open the suggested mapping file agents.sdl. Click Next and then Finish.
    8. If you are going to import cases with the Case Owner linked to the Users you just imported, you will want to export them now and update the tickets file.
    9. If you are using case assignment rules to set the Case Owner, this is a good time to set those up.
  9. Create Groups as Queues (optional).
    1. In Salesforce go to Setup and search for Queues. Add all groups as queues and assign the proper agents to them.
  10. Create Companies as Accounts.
    1. To store the Desk.com Company “domains” field, you can create a custom text Account field.
    2. Insert.
    3. Select Account as the object and use the file companies_1.csv.
    4. Click Next.
    5. Use the provided mapping accounts.sdl (adding the domains field mapping if necessary).
    6. Click Next and then Finish.
  11. Create Customers as Contacts.
    1. Browse your customers_dataload_1.csv file and determine the maximum number of phone numbers, email addresses, and addresses your customers have. If this number exceeds the number of standard Salesforce fields, create custom fields as necessary. Contacts only have one default email address, so any additional can be stored in custom fields. For Phone numbers, there are multiple standard fields (such as “Other Phone”) that you can choose to use. Do not save the file with a spreadsheet editor.
    2. Upsert.
    3. Select Contact as the object and use the file customers_dataload_1.csv.
    4. Use “Desk_ID__c” as the matching field on the contact.
    5. Use “Desk_ID__c” as the Account matching field. Leave the others unselected.
    6. Use the contacts.sdl mapping and add any custom fields you may have.
    7. Click Next and then Finish.
  12. Create Cases/Tickets as Cases.
    1. Before using the data loader, the spreadsheet must be modified.
      1. In the tickets_dataload_1.csv file, replace the assigned user id with the salesforce id using the export.
    2. Upsert.
    3. Select Case as the object and use the file tickets_dataload_1.csv.
    4. Use “Desk_ID__c” as the matching field on the case.
    5. Use “Desk_ID__c” as the Contact matching field. Leave the others unselected.
    6. Use the tickets.sdl mapping and add any custom fields you may have. At this point you should map the case owner or assigned_agent/group custom fields depending on which route you chose.
    7. Click Next and then Finish.
    8. Repeat this step if there are errors, making adjustments as necessary.
  13. Add Email interactions to your Cases
    1. Upsert
    2. Check the box for “Show All Salesforce Objects” and select Email Message.
    3. Choose “email_interactions_dataload_1.csv” as your file
    4. Use “Desk_ID__c” as the matching field on the Email Message
    5. Use “Desk_ID__c” as the Parent matching field. Leave the other unselected.
    6. Use the interactions.sdl mapping and finish the import
  14. Adding Phone Interactions:
    1. Before using the data loader, the spreadsheet must be modified.
      1. In the ticket_id column, replace the Desk Id with the id of the salesforce object the interaction is being related to. The easiest way to do this is to export all the cases id and external id (Desk ID) and then find and replace in your spreadsheet.
    2. Insert
    3. Select Tasks as the object.
    4. Choose “phone_interactions_1.csv” as your file
    5. Click through until you get to mapping
    6. Use the phones.sdl mapping. Finish the import.
  15. Add Notes
    1. Edit the “ticket_notes_1.csv” spreadsheet and replace the user_id field with the corresponding Salesforce ID for the user
    2. Upsert
    3. Check the box for “Show All Salesforce Objects” and select Case Comment
    4. Choose “ticket_notes_1.csv” as your file
    5. Next
    6. Use “Desk_ID__c” as the matching field on the Parent and CreatedBy fields.
    7. Use notes.sdl mapping and Finish the import
  16. Add Ticket Attachments
    1. Before using the data loader, the spreadsheets must be modified. Open ticket_attachments_dataload_1.csv and interaction_attachments_dataload_1.csv.
      1. In the attachment_path column, replace the values with the location of the files on your computer. A handy excel formula is below:
        1. CONCATENATE("your file path",A2,”/”,F2) where you replace 'your file path' with the location of the ticket_attachments folder in the export folder.
      2. In the ticket_attachments_dataload_1.csv ticket_id column, add the id of the salesforce object the attachment is being related to. The easiest way to do this is to export all the cases id and external id (Desk ID) and then find and replace in your spreadsheet editor.
      3. In the interaction_attachments_dataload_1.csv interaction_id column, replace this value with the salesforce ID based on the interaction id. The easiest way to do this is to export all the activities' id and external id (Desk ID) and then find and replace in your spreadsheet editor.
    2. Upsert
    3. Check the box for “Show All Salesforce Objects” and select Attachments.
    4. Choose “ticket_attachments_dataload_1.csv” as your file
    5. Use “ID” as the matching field on the Attachments
    6. Use the ticket_attachments.sdl mapping and add the Parent ID field to the mapping. Finish the import.
    7. Repeat b-f with the interaction_attachments_dataload_1.csv and interaction_attachments.sdl files.
  17. Add Articles and Article Translations
    1. We recommend using the Knowledge import tool to migrate your articles and translations. Here is the help article.

 

Survey

Questions? Comments? Please take our short survey on this guide: https://www.surveymonkey.com/r/LW8MYDP