Beginner’s Guide to Salesforce Data Migrations Part II
Beginner’s Guide to Salesforce Data Migrations Part II

Beginner’s Guide to Salesforce Data Migrations Part II

01/23/2024 by Annemarie Forgie
Embarking on our data migration journey, we’ll guide you through the process of building a data mapping document which will serve as a blueprint for a successful migration.

Welcome back to the second part of our Salesforce data migration series. In part one we established why data migration is important and key considerations before embarking on our data migration journey. Our focus today will be on building a data mapping document.

Data Mapping - Your Path to Migration Success!

Data mapping is the process of reviewing your existing data, determining which data you want to keep, and identifying where each piece of data will fit into the new system. This foundational step helps identify and resolve data quality issues early on, preventing problems during migration. Moreover, the mapping process can be used as a tool to facilitate discussions with stakeholders to ensure alignment with business processes before the migration takes place.

Data mapping can become complex, especially when dealing with large datasets or migrating data from multiple systems. The good news is whether you currently manage your data in spreadsheets or are transitioning to Salesforce from one or more external systems, the core process remains about the same.

Before we proceed, let's clarify a few terms that will frequently pop up. The legacy or source system is where your data currently resides, such as spreadsheets or an external system. The target system, on the other hand, is the new home for your data, such as your shiny new Salesforce instance.

Let’s also review the typical Data Migration Stages:

  1. Data Mapping: This stage involves mapping data fields and objects from the source system to Salesforce, serving as a blueprint for the migration process.
  2. Data Transformation: This stage involves the process of cleaning and transforming data to meet the requirements of the new system.
  3. Initial Test Migration: This stage involves a small-scale migration of a subset of data, ideally in a sandbox or test environment, to validate the migration approach and identify any potential issues.
  4. Full Data Migration: This stage involves migrating all data from the source system to the target Salesforce production environment. After this stage is complete, users should be using the new system going forward.
  5. Delta Migration: This stage involves migrating any changes or updates made to the source system data since the last data pull. If you can avoid a delta migration, I would highly recommend it, as it can save quite a bit of time and effort. However, be aware that it may result in a few days of downtime for your team while the migration is in progress.

Creating Your Data Mapping Document

Develop a data mapping document to guide you through the entire migration process. 

Field Map Tab(s)

Create a separate tab for each table or spreadsheet in your existing data. These tabs will serve as a dedicated space for capturing key information about each field that is migrating, its current status, and any relevant notes.

  • Source Field Name: The name of the field in the source system.
  • Source API Name: The API name associated with the source field.
  • Source Field Type: The data type of the source field.
  • Field Usage %: Percentage of records in the source system that contain data.
  • Target Object: The object in the target system where data will be mapped.
  • Target Field Label: The label or name of the field in the target system.
  • Target API Name: The API name associated with the target field.
  • Target Field Type: The data type of the target field.
  • Status: Indicates the current status of the mapping for each field (e.g., To Be Reviewed, Needs More Discussion, Signed-Off).
  • Cleaned: Indicates whether the data has been cleaned or transformed.
  • Notes: Specific instructions or notes related to the mapping process for that field.

You may want to add additional columns to track if a field is required, field length, picklist values, formulas, field descriptions, or help text. 

When setting up your field map tab, if migrating from another Salesforce org, you can use tools like Schema Lister or Field Dumper to export the list of fields (also known as metadata), including field type, picklist values, and other valuable information. If migrating from another system, you may need to take a bit more of a manual approach. A great tip is to export the data to a spreadsheet and use a formula trick to copy the column headers, paste using "transpose", and voilà! you’ve started your mapping document.

Calculating field usage percentage can be somewhat tricky. For Salesforce to Salesforce migrations, tools like Field Spy or Field Trip can provide that information. If working from spreadsheets, consider using a COUNTA() formula under the last row of data to determine field usage count. To calculate usage percentage, you’ll need a bit more complex formula: =COUNTA(A2:A100) / (COUNTBLANK(A2:A100) + COUNTA(A2:A100)). Give this formula a try!

Once you start mapping, it is best practice to map your existing data to standard objects and fields whenever possible. Create custom objects and fields only when absolutely necessary. This approach minimizes technical debt and ensures the longevity of your Salesforce instance across multiple releases with new features. For data that will not be moving to the new system, it is recommended to mark those rows as "Not Mapping" instead of deleting them completely from the mapping document. This way, when you pull the final data, you won’t be surprised by columns missing from the mapping document and you won’t need to fear that they were missed.

Data Migration Screenshot showing spreadsheet tracking values

Summary Tab

Use this tab as an overview of the entire migration process. Here you can track the overall status for each field map tab from Draft Mapping to Migration Complete. Additional statuses may include Mapping Signed Off, Data Transformed, Test Migration Complete, Initial Migration Complete, and Delta Migration Complete. If you want to get extra fancy, you can use hyperlinks to link each source file Name to its corresponding Field Map Tab to help easily navigate the data mapping document.

Data Migration Screenshot showing spreadsheet tracking values

Order of Operations Tab

Use this tab to outline the sequence of imports to avoid errors during migration. You’ll want to consider dependencies and field relationships to determine the import order. For example, importing Campaign Members depends on the existence of Campaigns. You’ll also want to account for self-lookups (e.g., Parent Account or Parent Campaign) and lookup fields for objects not yet imported. In these instances you’ll likely need to perform an initial import with the field left blank, followed by a separate update operation to fill in the missing information.

When data mapping, ensure you identify a unique ID in each table of your existing data to serve as a legacy ID field. This data should be stored in a custom external ID field in Salesforce which is unique and potentially case-sensitive based on your needs. If your current data doesn’t have one, create one by concatenating several values together (FirstName-LastName-Birthdate) or build your own unique identifier (C-01, C-02, etc.). This becomes a crucial reference point throughout the data migration process to ensure you can link data together correctly. 


A well-structured data mapping document is the cornerstone of a successful Salesforce migration. By following these guidelines and customizing your document to suit the unique needs of your organization, you'll ensure a smoother and more efficient transition. Remember, the key is not just moving data but ensuring it thrives in its new home. Happy mapping!

Continue following this guide for future posts, where we will cover practical advice for cleansing and transforming your data. We will also explore a variety of data migration tools, providing insights into their strengths, use cases, and considerations.

Have you embarked on a Salesforce data migration project before? Want to share your experiences or opinions? Tell me about them on the Salesforce Trailblazer Community, or reach out to me on LinkedIn.