Written by James BrittTechnically reviewed by Jim Freeze · Reviewed
Salesforce imports seem simple until automation breaks
Importing data into Salesforce can look straightforward. Choose a file, map the columns, test the records and move them into production. The administrative steps are familiar.
The difficulties often appear later, when an automation acts on data that differs from what its developers expected. A changed identifier, an unexpected duplicate or an incomplete customer history can create operational, financial and data integrity problems.
Salesforce tracks customer relationships and sales pipelines. For Ruby and Rails teams, errors in that data can reach well beyond the CRM, affecting services that depend on it.
Ruby applications rely on Salesforce data consistency
Rails applications integrated with Salesforce may write back through API calls, subscribe to events and use local copies of CRM data for reporting. Record states can also determine which workflows run.
Background jobs processed through Sidekiq depend on assumptions made in the application code. A job might expect an Account to have a designated primary contact, for example, or expect an Opportunity to move through particular stages. Those are application-specific expectations, rather than guarantees supplied by Sidekiq.
An import that violates these expectations may not produce an immediate alert. The failure can remain hidden until a background job tries to use the affected record.
Duplicate contacts are one example. If the application cannot identify a canonical customer record, it may trigger the same action repeatedly or miss the intended action altogether.
Teams then have to reconcile the duplicates and repair affected downstream records. A single customer represented by several Salesforce records can leave connected systems with conflicting versions of the same relationship.
The real issue is usually synchronization integrity, not import speed
The Bulk API supports large data operations, but processing capacity alone cannot establish whether imported data is useful to every connected application. Salesforce provides separate results for successful, failed and unprocessed records, which teams need to inspect. Salesforce’s Bulk API guide explains these checks.
Synchronization integrity means keeping record relationships consistent within Salesforce and across the systems that depend on it.
Consider an import that associates child records with parents through external IDs. A missing parent, mismatched identifier or inconsistent format can prevent the intended association from being created. Duplicate records introduce a further problem: the import may target a different record from the one the application expects.
A rejected row and an accepted but misleading record are different failures. Even where a record passes Salesforce’s configured checks, a missing optional relationship or an incorrect business association can still make it unsuitable for downstream processing.
Why Rails and Sidekiq environments amplify small Salesforce import mistakes
Concurrent processing and automatic retries can spread a small data problem across many jobs. The risk depends on the application’s design and how it handles partial failures.
If a job writes to Salesforce and then fails before recording that success locally, a retry may repeat the write. Jobs therefore need to be safe to run more than once. Sidekiq’s own guidance explicitly warns that it does not guarantee exactly-once execution.
An incorrect Salesforce ID or missing validation can also produce duplicate or incomplete data. Meanwhile, concurrent updates involving the same parent records may encounter locking conflicts. Salesforce’s record-locking guidance describes how relationships and roll-up summaries affect locking.
Dependencies between jobs add another complication. A child-record job that runs before its parent is available may fail even when both source records are correct.
Most teams underestimate historical data complexity during imports
Historical imports bring problems that a small sample of current records may not reveal. Old hierarchies, missing relationships, obsolete picklist values and hidden dependencies can surface long after the upload.
Field structures change over time. A value that was accepted when a record was created may conflict with today’s Salesforce configuration.
Validation rules also need attention. Historical records are still subject to the rules applicable to the import operation. Teams need to decide how to handle legitimate old data that no longer fits current requirements, then test that approach before production.
Ownership and access deserve the same care. Imported records need appropriate owners, and teams should check how profiles, permissions, sharing rules and role hierarchies affect access. Incorrect ownership can leave users or backend integrations unable to reach records they need.
Opportunity records imported without related Activities or Tasks may be technically valid but lack essential context. Scoring and personalization systems can then produce misleading results from an incomplete customer history. The upload screen is unlikely to reveal that business-level problem.
Salesforce import workflows need engineering-level governance
The practices that make data pipelines reliable also help with imports. Validate the input before execution, test in a staging environment, prepare a recovery plan before cutover and verify the results after completion.
Teams should use a structured reference on importing data reliably into Salesforce to address validation, staging, and verification. These steps give the team a repeatable process to review and improve.
Each import should leave an audit record showing what was imported, when it happened, who ran it, which checks were applied and the previous state of any changed data.
Without that record, investigating a synchronization failure 3 days later means reconstructing the operation from incomplete evidence. Keep the source file, mappings and result files together so the team can trace an affected record back to the import.
Ruby engineering teams already understand data discipline
Experienced Ruby developers know the architecture of a proper Rails application should be based on ActiveRecord transactions, database rollback logic, idempotent job design, structured logging, and reproducible test environments. The same disciplines are useful when planning Salesforce imports.
There is an important boundary, though. An ActiveRecord transaction protects work on its database connection; it does not roll back a completed Salesforce API request. Recovery across both systems needs an explicit plan. The Rails transaction documentation explains the scope of that protection.
The ownership gap is often organizational. CRM teams may run imports while engineering teams maintain the services consuming the results. Both need to agree on identifiers, relationships, expected states and recovery procedures.
Extending those checks to CRM operations gives engineers a chance to identify problems before the data reaches their services.
Post-import visibility matters more than initial migration success
An import completed without reported errors still needs verification. Check the records themselves and the behavior of the systems using them.
Look for missing values, unexpected duplicates and incorrect relationships. Confirm that duplicate detection has neither missed repeated customers nor merged records that should remain separate.
Jobs that finish successfully but produce incorrect results can be particularly difficult to spot. An inaccurate customer score or revenue report may never raise an exception.
Before importing, record baseline customer counts, revenue totals and pipeline metrics for the affected data. Compare those figures after the import, allowing for the changes the team actually intended to make.
Continue checking as background jobs and reports run. Immediate record checks and later business results answer different questions, and both matter when judging whether the import worked.
Treating Salesforce imports as infrastructure operations instead of admin tasks
Salesforce imports require shared ownership. CRM teams understand the configuration and business rules; engineering teams understand the connected applications and their dependencies.
Bring those perspectives together during import planning. Include an engineering review, apply the change-management discipline used for database migrations and API changes, and decide who will investigate unexpected results.
The import should remain observable after the upload has finished. Teams need enough information to trace a changed record through Salesforce, background jobs and downstream reports.
For Ruby and Rails teams, reliable CRM data starts with that shared responsibility. When both teams agree on what a successful import must deliver, they can test those expectations before customers or reporting systems expose the mistakes.