The first import is the easy case: selected source data enters an empty or prepared destination. The second import is where trust is earned. By then, users may have corrected a company name, cleared a stale phone number, reassigned a deal, merged duplicate contacts, deleted an unwanted record, or added information from another connector. A blind overwrite would erase useful work; a blanket “never update” rule would leave imported data stale.
Repeatable imports can solve this tension with two related pieces of state. A durable provider identity link remembers that a particular source record corresponds to a particular destination record. An imported-value baseline remembers what this connector last wrote for each managed field. On the next run, the importer compares the current destination value, the previous imported value, and the new source value. That is a three-way merge: local now, source then, and source now.
The current Intelligent CRM HubSpot and Pipedrive importers implement this pattern for supported records and fields. A later import can refresh a field when the local value still matches the previous imported value; an initial or no-baseline import can populate an appropriate blank field; and a value or intentional local clear that diverges from an existing baseline is preserved. They also avoid recreating a destination record deleted after an earlier import. These safeguards reduce destructive surprises, but they do not guarantee zero conflicts, zero duplicates, or complete semantic equivalence between systems.
Understand the field-level merge decision
The exact implementation varies, but these cases express the central ownership rule used by a cautious repeatable importer.
| Current destination | Previous imported baseline | New source value | Cautious outcome |
|---|---|---|---|
| Matches the baseline | Known prior source value | Changed nonblank value | Apply the source change and record the new baseline |
| Differs from the baseline | Known prior source value | Changed value | Preserve the local edit and report or record a conflict |
| Blank after previously imported value | Known prior source value | Nonblank value | Preserve the intentional local clear |
| Blank or absent | No prior baseline | Nonblank value | Populate when field policy permits |
| Matches the baseline | Known prior source value | Source is explicitly blank | Clear only when blank represents an authoritative source clear |
| Locally changed | Known prior source value | Source is blank | Preserve the local value or clear rather than infer ownership |
| Already equals new source | Old or absent baseline | Same value | Record the source value as baseline without needless visible change |
Link records by provider identity before merging fields
The importer first needs to know which destination record represents the source entity. Store a workspace-scoped link containing provider account identity, entity type, source record ID, local record type, and local record ID. Do not include mutable fields such as owner, display name, stage, or email in the durable key. A source record can change those values without becoming a new entity. The link makes retries and later imports resolve the same local record directly.
A stable link also supports explicit local merges. If two contacts are merged in the destination, provider identities can be repointed to the chosen survivor under controlled logic. That is different from allowing two new source identities to auto-adopt the same destination record during a race. The current HubSpot and Pipedrive models keep a separate adoption claim so one automatic adoption does not let concurrent imports collapse unrelated source records. Identity is a governed relationship, not a fuzzy search repeated on every run.
Adopt existing records cautiously on the first run
A destination may already contain customers before the connector is enabled. Exact normalized contact email or account domain evidence can identify a single plausible record to adopt. The supported HubSpot and Pipedrive implementations can use exact email evidence for contacts and domain or website evidence for accounts. Company name alone is too ambiguous for automatic account adoption. Multiple matching candidates should not be resolved by an arbitrary first result.
Adoption reduces avoidable duplication but cannot promise a duplicate-free workspace. The source itself may contain duplicates, an email may be shared, a company can own several domains, or a destination record may lack the matching identifier. Record every automatic adoption and keep ambiguous cases visible. If another source identity already claimed the local record automatically, create or review a separate record rather than silently attaching two unrelated provider identities. Human merge remains available after evidence is inspected.
Store a baseline for fields the connector actually supplied
After creating or updating a record, retain the accepted source values as the connector’s baseline. This is not a full snapshot of the destination and should not claim values written by users, formulas, enrichment, or other integrations. A source-specific baseline answers one narrow question later: does the current local field still equal what this connector last imported? If yes, the connector can usually refresh it. If not, another actor has expressed local intent.
Baseline semantics need type-aware normalization. Trim or normalize identifiers where the product model requires it, preserve false and zero as real values, compare dates and structured values consistently, and distinguish missing from explicitly blank. For multi-value fields, decide whether the connector owns the entire list or only its source contribution. The current Pipedrive implementation, for example, can keep a source-only email baseline while the contact holds a union that may include an email from another source. That prevents one connector from claiming the combined list as its own.
Use three-way merge to identify local intent
Suppose the previous import wrote “Acme Software” and the current destination still says “Acme Software.” If the source now says “Acme Systems,” the connector can update the destination because its earlier value remains untouched. If a user changed the destination to “Acme Systems India,” the current value no longer equals the baseline. The importer should preserve that correction, record the new source observation separately if needed, and surface a conflict rather than deciding that recency alone gives the source authority.
A destination field that was blank before the connector ever supplied it can usually accept a supported nonblank source value. A destination value that already equals the new source can be recorded as a baseline without a meaningless write. These small distinctions matter for audit history, workflow triggers, and notifications. An importer should avoid generating a visible change merely to prove that it ran. The outcome report can distinguish created, updated, unchanged, locally preserved, skipped, and failed work.
Treat an intentional local clear as an edit
Blank is not always missing. If the importer previously wrote a phone number and a user deliberately removes it because it is invalid, the destination is now blank while the baseline still contains the old number. Repopulating the same or a newer source number would override local intent. A cautious merge therefore treats the clear as divergence and preserves it until a person or explicit policy decides otherwise.
Source blanks also need care. In the current HubSpot importer, a supported provider-side clear can remove a destination value only when that value still matches the importer baseline. The current Pipedrive importer ignores non-present remote values rather than interpreting them as a command to erase destination data. Neither behavior permits a rerun to repopulate an intentionally cleared local value. More generally, omitted fields, inaccessible properties, and serialization differences must not masquerade as deletion.
Preserve intentional local record and field deletion
Record deletion carries stronger intent than a field edit. When a durable link shows that the record was imported previously but the linked destination record no longer exists, the current importers do not recreate it automatically. They count or warn that a locally deleted record was preserved. This prevents an administrator from deleting an unwanted imported contact only to have it reappear on the next rehearsal. Recovery should be an explicit action, not an automatic side effect.
Custom field definitions can also be deleted or changed locally. A connector should not silently recreate a deleted destination field or force values into a field whose type changed. The current implementations warn when deleted or type-changed CRM fields are not repopulated. Keep this distinct from source-side deletion: a record absent from a provider response may be archived, filtered, unauthorized, or outside the page window. Without reliable tombstone semantics and an approved policy, absence should not trigger destination deletion.
Protect the merge from concurrent local changes
The three values cannot be read once and then written unconditionally. A user might edit the record after the importer reads it but before the update reaches the database. Use a compare-and-set condition that applies the change only if the field still has the value observed during merge evaluation. If the condition fails, reload and reevaluate or record a conflict. This closes the gap in which a technically correct three-way decision erases a newer edit.
Concurrency also affects identity reservation, relationship creation, and side effects. Two jobs should not adopt the same local record, create duplicate activities, or send duplicate “contact created” effects because a retry observed partial state. Use workspace-scoped operation locks, idempotent keys, link-level uniqueness, and bounded retries. A repeatable import is safe only when both business merge semantics and delivery mechanics tolerate retries; one without the other leaves a different path to corruption.
Merge relationships and ownership independently from fields
Companies, people, deals, owners, pipelines, stages, activities, and notes form a graph. Updating a company name safely does not prove that a deal association should be replaced. Define identity and merge rules for relationships: whether the source may add a missing link, whether local links can coexist, how an explicit local removal is preserved, and what happens when a parent record was skipped or deleted. Process dependencies before dependents so decisions use real local IDs.
Owner mapping is another independent layer. Durable record identity should not include the destination owner, so remapping an owner does not create a duplicate entity. Yet an owner field is still subject to authority. A source reassignment may refresh an unchanged imported owner, while a manager’s destination-side reassignment may deserve preservation. Validate this behavior in the actual connector; not every relationship or system field necessarily uses the same merge implementation as ordinary properties.
Make preserved edits and conflicts operable
Preservation without visibility can create silent drift. The final report should show records and fields kept because of local edits, intentional deletions, ambiguous adoption, unsupported values, and relationship failures. Give operations enough context to decide whether the destination remains authoritative, the source should be corrected, or a local value should be reset to allow a later import. Do not expose sensitive field contents unnecessarily in logs; record identifiers and reason codes can lead an authorized reviewer to the record.
Measure conflict rate across rehearsals. A falling rate can show that mappings and cutover discipline are improving. A rising rate may mean users are actively editing both systems and need a shorter migration window or a clearer authority rule. Preserve source snapshots and job identifiers long enough to reproduce a decision. The goal is not to eliminate every difference. It is to make each material difference intentional, reviewable, and safe to carry into go-live.
Refresh source changes without erasing destination corrections
A team imports an account, two contacts, and an open deal. The first run writes the account name “Northstar Mobility,” a contact phone number, a deal close date, and the source owner. During review, an operator changes the account name to its verified legal form, clears the invalid phone number, adjusts the close date after a customer meeting, reassigns the deal locally, merges one contact into an existing survivor, and deletes the other imported contact as irrelevant. Meanwhile, the source changes its account description and pipeline stage. The second import resolves durable identities, follows the merged contact link, and compares each current value with its previous imported baseline.
The source-owned description and unchanged imported stage can refresh. The verified account name, cleared phone, locally confirmed close date, and manager-approved owner remain because they diverged from the baseline. The explicit contact merge keeps the provider identity on the survivor, while the deleted contact is not recreated and appears as a preserved-deletion warning. The report lets operations review each preserved difference. The outcome is not identical systems; it is a controlled destination whose local decisions survive a useful source refresh.Repeatable-import merge checklist
- Create a workspace-scoped link for every supported provider entity
- Keep mutable names, owners, stages, and emails out of durable record identity
- Adopt existing records only from strong, unambiguous matching evidence
- Store baselines only for values actually supplied by this connector
- Normalize values by type without collapsing false, zero, missing, and blank
- Apply a source update only when the local value remains connector-owned
- Treat intentional local field clears as edits worth preserving
- Require explicit semantics before propagating source blanks or deletions
- Do not recreate locally deleted records during an ordinary rerun
- Protect database updates with compare-and-set or equivalent concurrency checks
- Make retries idempotent for records, relationships, activities, and side effects
- Define separate merge rules for relationships, ownership, and custom fields
- Report local preservation, ambiguity, skips, conflicts, and failures visibly
- Test a second and third run with source changes and destination corrections
- Use cutover authority and conflict trends to limit long-lived dual editing
Repeatability depends on remembering what the connector did
A rerunnable importer cannot protect local work if it remembers only the latest source payload. Durable provider identity connects the same records across runs, while imported-value baselines reveal whether a field still contains the connector’s prior contribution. Three-way merge, intentional-clear handling, deletion preservation, and concurrency checks turn that memory into cautious update behavior.
These controls reduce destructive overwrites without pretending migration is automatic truth reconciliation. Ambiguous identities, incompatible models, unsupported values, and genuine conflicts still require people. Test those cases openly, report preserved decisions, and define when the destination becomes authoritative. A repeatable import is trustworthy when its rerun behavior is explainable before anyone presses the button.