Design a duplicate-safe callback migration

Build one normalized identity set

Fast answer: callbacks are usually tied to lead records, while imported files are often keyed by phone number. Normalize country code and punctuation once, then resolve each phone to the intended lead before planning a write.

A phone number that looks identical to a human can still fail to match: a leading country code, a stray extension digit, or punctuation left over from a spreadsheet export all change the literal string VICIdial's own search compares against. Decide and document one normalized shape for every input before the first lookup, and apply it identically to both the migration input and whatever VICIdial's own phone_number field actually stores, rather than normalizing only one side.

Ambiguous numbers belong in a review queue. Never let a last-row-wins rule silently choose between duplicate leads.

See vicidial-terminology-for-complete-beginners for the rest of this glossary.

• Country code, spacing and punctuation are normalized identically on both the input file and the field VICIdial's own search compares against.
• Every ambiguous phone number is quarantined in a review queue, not resolved by a default rule.
• The normalized shape you chose is written down once, so a second engineer applying the same migration months later reproduces it exactly.

SELECT phone_number, COUNT(*) AS lead_rowsFROM vicidial_listWHERE phone_number IN ('<PHONE_A>','<PHONE_B>')GROUP BY phone_numberHAVING COUNT(*) > 1;

Prepare a tiny input before a large migration

Start with three synthetic cases: one unique callback needing a move, one already owned by the target agent and one deliberately ambiguous phone. This small set proves the reject and no-op branches as well as the happy path.

A fourth case is worth adding once the first three pass: the same phone number, but represented differently between your input file and VICIdial's own stored value — an extra leading digit, or punctuation the export tool left in. That case exercises your normalization step specifically, separately from the identity-resolution logic the other three already cover, and it is the case most migrations skip until it causes a real mismatch.

Use opaque fixture labels in the public worksheet. The example values explain the columns; they are not real agent IDs, lead IDs or phone numbers.

input_ref,normalized_phone,lead_match,current_owner,proposed_owner,planfixture-01,PHONE_A,unique,AGENT_OLD,AGENT_NEW,updatefixture-02,PHONE_B,unique,AGENT_NEW,AGENT_NEW,no-opfixture-03,PHONE_C,ambiguous,unknown,AGENT_NEW,reject

Run VICIdial's own dry run before building anything custom

VICIdial already ships the dry run this article used to reconstruct by hand: update_lead's own no_update flag. Setting no_update=Y performs no write at all — it only reports whether a lead matching your search criteria exists, using the same search_method and search_location logic a real update would use. Run every input through this flag first, and build a custom ledger only for whatever it reports as ambiguous, not for the whole migration.

The write itself, once you are ready, moves through the same function's callback_type and callback_user fields: USERONLY assigns the callback to one specific agent named in callback_user, and ANYONE — the function's own documented default — leaves it open to whichever agent reaches it first. A last-row-wins mistake is not hypothetical here: update_lead's own records field documents that when a search matches more than one lead, the call updates only one of them, defaulting to '1', the most recently loaded lead. Treat more than one match from no_update as a hard stop, not as that default quietly choosing for you.

The search itself has two documented dimensions worth setting deliberately rather than leaving at their defaults: search_method can combine LEAD_ID, VENDOR_LEAD_CODE and PHONE_NUMBER matching in one call, and search_location narrows where VICIdial looks for a match — LIST for the one list a lead was loaded under, CAMPAIGN for every list under that list's campaign, or SYSTEM, the default, for the entire installation. A phone-only search with no search_location narrows nothing, which is exactly why an ambiguous-match rate that looks too high is often a search_location left at its widest setting, not a genuinely dirty input file.

function=update_lead  &phone_number=<PHONE_NUMBER>  &search_method=PHONE_NUMBER  &no_update=Y  &callback_type=USERONLY  &callback_user=<AGENT_USER>

Verify with an independent read path

Do not count a 200 response as proof. Re-read the callback records by normalized phone and confirm the owner, date, status and duplicate count.

A clean migration ends with input count, planned count, changed count, no-op count, rejected count and independently verified count reconciling exactly.

Read this back through a separate, read-only credential from whatever wrote the change, not the same writer account a second time — the same separation-of-duties reason a scripted read after a scripted write only proves something if the two paths cannot share a mistake. A verification query that quietly reused the writer's own cached assumption about which lead it just touched would not catch a records-defaulted-to-1 mistake at all.

SHOW COLUMNS FROM vicidial_callbacks; SELECT status, recipient, COUNT(*) AS callbacksFROM vicidial_callbacksWHERE campaign_id = '<CAMPAIGN_ID>'GROUP BY status, recipient;

Stop cleanly and reverse only proved changes

Stop the worker on authentication errors, ambiguous responses, count mismatch or a duplicate discovered after a write. Do not continue from the next row until an independent read has classified the prior operation.

Rollback from the immutable ledger in reverse operation order using the same supported, idempotent path. Re-read each callback after reversal and retain only sanitized reconciliation totals in the incident record.

Rollback is itself a write, so run the same no_update=Y dry run against every row you intend to reverse before you reverse it. A row already touched by someone else since the original migration — a fresh disposition, a new callback scheduled by an agent — is exactly the case a blind reversal would clobber, and it is the same class of mistake this whole article exists to prevent in the forward direction.

• Changed plus no-op plus rejected must equal the input count.
• Every reversed item must match its recorded original owner and schedule state.
• Unknown outcomes block dependent work until independently resolved.