Salesforce Service Cloud Migration Checklist

Migrating to Salesforce Service Cloud offers significant benefits, but successful migrations depend on meticulous planning, accurate configuration, and ensuring the right data flows into the platform.

This checklist covers what to migrate via API, what requires manual UI configuration, the technical constraints that cause migrations to fail at scale, and how to validate a completed migration against measurable acceptance criteria.

Scope the Migration

Determine the time span of the ticket history you want to migrate. Whether it's one year, five years, or all available history, ensure this aligns with your operational needs.

Decide if you're migrating active agents only or including legacy/archived agents for proper ownership of historical tickets.

Identify which Salesforce objects need migration (e.g., Cases, Contacts, Accounts, Attachments, Custom Fields, and Notes).

Clearly define what data to exclude, like spam, test tickets, deprecated tags, or old user data that doesn't add value.

Thoroughly map old system fields, statuses, and tags to Salesforce's data model to ensure smooth field mapping.

Source System Field Mapping Considerations

Migrations are not generic. The specific problems you will encounter depend on what you are migrating from:

• Zendesk → Salesforce Service Cloud: Zendesk ticket forms use a flat field structure; Salesforce uses Record Types with conditional field visibility. You must map each Zendesk ticket form to a corresponding Salesforce Record Type before import. Zendesk tags are free-text strings; Salesforce picklist fields require predefined values. Tags that don't match an existing picklist value will fail silently or require a default fallback value.
• Freshdesk → Salesforce Service Cloud: Freshdesk stores ticket properties like fr_escalated, spam, and due_by as system fields with no direct Salesforce equivalent. These must either be mapped to custom fields or dropped from scope before migration begins.
• Intercom → Salesforce Service Cloud: Intercom conversations do not have a native "subject" field. Salesforce Cases require a Subject value. You need a transformation rule — typically auto-generated from the first message body — to populate this field, or imports will fail validation.

Timestamp Normalization

This is one of the most common and least-discussed failure modes in migrations to Salesforce. Legacy systems often store timestamps without timezone information (timezone-naive). Salesforce stores all datetime fields in UTC. If you import timezone-naive timestamps directly, case history will appear out of sequence in Salesforce — older cases may sort as newer ones depending on the source system's local timezone offset.

Fix: Before import, normalize all datetime fields to ISO 8601 format with explicit UTC offset (e.g., 2023-04-15T10:30:00+02:00). Apply the source system's configured timezone to all naive timestamps before transformation.

What Can Be Migrated Via API

Salesforce Service Cloud has a robust API that lets you migrate various key elements:

• Contacts & Accounts: Migrate contact and account data using the Salesforce REST API or Bulk API 2.0. Preserve legacy IDs as external ID fields on the object, custom attributes (e.g., customer type, account status), and associated records for seamless customer experience.
• Cases & Case History: Migrate case records, including each interaction within a case. The Case object (Case) in Salesforce can be used to recreate cases, with all case-related messages (stored as CaseComment or EmailMessage records), attachments, and updates.
• Attachments: File attachments should be migrated using the ContentVersion object, not a generic file upload endpoint. Each ContentVersion record creates a file in Salesforce Files; you then link it to the parent Case via a ContentDocumentLink record. Do not use the legacy Attachment object for new implementations — it is deprecated in Lightning Experience.
• Custom Fields & Metadata: Migrate custom fields on Cases, Contacts, and Accounts. The Metadata API handles custom field definitions; the REST or Bulk API handles the data values.
• Notes & Activities: Salesforce allows you to migrate internal notes (as Note or ContentNote records) and activities (Task, Event) tied to Cases or Contacts to maintain workflow continuity.
• Automation Rules: Some automation and case workflows can be recreated programmatically, but rules like auto-response or escalation policies need manual setup.
• Reports & Dashboards: Reports are built on Report Types in Salesforce. These cannot be directly imported from another platform — they must be recreated manually or via the Metadata API using report metadata XML.

Salesforce API Limits and Volume Thresholds

The right API strategy depends on data volume. Using the wrong approach at scale is a common cause of migration failures and extended timelines.

Salesforce API governor limits to be aware of:

• The REST API enforces a per-org 24-hour rolling limit on total API calls (the specific limit depends on your Salesforce edition and the number of licenses).
• Bulk API 2.0 jobs count against the same 24-hour limit but each job processes up to 150 million records without per-record API call overhead.
• SOQL queries used during delta sync are subject to query row limits (50,000 rows per synchronous query; 50,000,000 rows per Bulk API query).
• File uploads via ContentVersion are subject to per-transaction governor limits on heap size and CPU time. Large attachment sets should be batched and uploaded in separate jobs from case record imports.

What Needs to Be Configured in Salesforce UI

Some elements of your Salesforce Service Cloud environment cannot be migrated via the API and must be manually configured in the UI:

• Users, Roles & Profiles: Create users and assign roles and permissions through the Salesforce UI. Ensure each agent has the right permissions set before they can access cases and data.
• Queues & Teams: Set up teams and assign them to specific case queues to ensure efficient workload distribution.
• Case Assignment Rules: Salesforce's Case Assignment Rules and Escalation Rules must be set up manually to ensure cases are routed correctly based on predefined conditions.
• Email & Social Media Channels: Configure your email channels, social media channels (e.g., Facebook, Twitter), and any other communication channels directly within Salesforce.
• Workflows & Process Builders: Recreate your workflows and business processes using Salesforce Process Builder and Flow Builder. While some workflows can be migrated via API, others require manual setup.
• Saved Replies & Knowledge Articles: Recreate Saved Replies for agents and upload Knowledge Base Articles to Salesforce's Knowledge Management system. Knowledge articles must be organized into categories manually.
• Lightning Components: For custom Salesforce setups, you may need to build or reconfigure Lightning Components that interface with your Service Cloud.
• Custom Apps & Tabs: If your organization uses custom applications or tabs within Salesforce, these need to be configured manually via the App Manager in Salesforce.

Pre-Migration Setup in Salesforce

Before importing data into Salesforce, ensure the environment is ready for a smooth transition:

1. Create a Sandbox Instance First: Run the full migration against a sandbox before touching production. This is not optional at any meaningful data volume. A sandbox lets you validate field mapping, test transformation rules, and confirm record counts without risk to live data.
2. Configure Users and Teams: Invite all agents, assign roles, set permissions, and map legacy agent IDs as external IDs for smooth ownership migration.
3. Set Up Channels & Routing Rules: Configure email and social media channels, ensuring proper routing of incoming cases to the correct teams.
4. Custom Fields & Record Types: Ensure all necessary custom fields, record types, and layouts are created ahead of time in Salesforce. The API cannot create records that reference fields or record types that don't yet exist — missing fields cause silent data loss, not import errors.
5. Test Data Import: Run a small pilot migration to test how records (cases, contacts, etc.) are imported, ensuring data integrity (timestamps, attachments, custom fields).

Migration Execution

1. Migrate Contacts and Companies First Start by importing your contact and company records. These are essential for linking cases and conversations in Salesforce, ensuring customer data is properly associated with case records.
2. Import Cases and Case History Migrate your case records along with their associated messages (CaseComment, EmailMessage), updates, and attachments. Each legacy case should be converted into a Salesforce Case record, preserving the full history. Confirm that the ContactId and AccountId lookups resolve correctly — unresolved lookups will create cases with no customer association.
3. Import Custom Fields and Metadata Migrate any custom fields and metadata associated with contacts, cases, and companies. This ensures all relevant data from your old system is retained in Salesforce.
4. Import Tags and Statuses Import legacy tags and case statuses, ensuring they are correctly mapped to Salesforce's tagging and status model. Free-text tags from source systems must be mapped to predefined picklist values before import.
5. Migrate Assignments and Ownership Assign case ownership to the correct agents and teams within Salesforce, ensuring proper continuity of case management after migration.
6. Run Delta Import and Finalize Routing Perform a delta import to capture any new records generated during the migration process. Update communication routing rules and forward channels to Salesforce to ensure new cases are handled correctly.

Rollback and Recovery Planning

Migrations fail. Plan for it before you start.

• Maintain your source system in read-only mode — not decommissioned — until post-migration validation is complete and signed off. This is your rollback state.
• Export a full data snapshot from the source system immediately before cutover. Store it in a format you can re-import if needed (CSV with all fields, not a platform-specific backup format).
• In Salesforce, sandbox environments serve as your validation environment. Do not promote to production until you have validated record counts, spot-checked attachments, and confirmed timestamp ordering in at least a sample of cases.
• If a production migration fails mid-run, the safest recovery is to delete the partially imported records (using the same external IDs used during import) and restart from the last validated checkpoint, not from the beginning. Maintain an import log that records which record batches completed successfully.

Post-Migration Checklist

Once your data is in Salesforce, perform thorough checks to ensure everything is correct. Define your acceptance criteria before go-live, not after.

Quantitative acceptance criteria:

• Case count in Salesforce must match source system case count within 0.1% (or an exact match for sub-100K record migrations).
• Attachment count and total byte size must reconcile against source system export totals.
• CaseComment and EmailMessage record counts must match expected values per case (spot-check a minimum sample of 50–100 cases across different date ranges and statuses).
• Timestamp ordering on case history must be verified on a sample set — confirm that the earliest message on a case has the earliest CreatedDate in Salesforce.

Functional checks:

• Channel Testing: Test each communication channel (email, chat, social media) to ensure that new cases are routed properly.
• Automation & Workflow Testing: Ensure that workflows, case assignment rules, and escalation rules are functioning as expected.
• Agent Training: Ensure that agents are trained on the new system, particularly on workflows, case management, and custom features in Salesforce.
• Go-Live Transition: Set your old system to read-only mode, ensuring agents do not enter new data in the old system.

Common Mistakes and Pro Tips

• Missing Custom Fields: Salesforce API can only populate custom fields that already exist. Create all fields in Salesforce before migration. Fields that don't exist at import time are silently dropped — there is no error.
• Using the wrong file object: Migrating attachments to the legacy Attachment object instead of ContentVersion will work technically but creates files that are not accessible in the Lightning Experience Files tab. Use ContentVersion + ContentDocumentLink.
• Timezone-naive timestamps: As described above, importing timestamps without explicit timezone information will corrupt case history ordering. Always normalize before import.
• Unresolved lookups: If a Case record references a ContactId that doesn't exist yet in Salesforce, the lookup will fail silently or the record will import with a null contact. Always import parent objects (Contacts, Accounts) before child objects (Cases).
• Not Testing Enough: Always run a sample import with varying data to spot-check for issues before importing everything.
• Skipping Agent Training: Even the best migration can fail if agents aren't properly trained on the new system.