Freeze the artifact and first failed boundary
Stop further imports and preserve the exact uploaded file, its hash, encoding, delimiter, quoting, headers and row count; installed FreePBX and Bulk Handler versions; handler or object type; start and end times; validation output; replace-or-update setting; progress or error rows; Apply Config result; and a before export or backup. Do not publish credentials or personal data in the evidence.
Classify the first failure: upload or decoding, header or schema parsing, row validation, identifier collision and update scope, row write, partial batch, Apply Config, owning-module state or runtime consumer. An error shown after several green rows is not evidence that earlier writes were rolled back.
Compare CSV bytes with parsed and previewed values
Open a sanitized copy in a text editor and compare the literal bytes for one failed and one accepted row with the validation preview. Check leading zeros and plus signs, scientific notation, date conversion, delimiters, quotes, embedded line breaks, byte-order marks and Unicode. Spreadsheet appearance is not the uploaded value.
Compare the headers with a fresh export from the same installed handler. Current release metadata includes trunk import, while the Sangoma guide's object list does not; that difference is a warning to use installed schema evidence rather than borrowing a template from another object, module version or PBX.
Inspect every mutation in the row detail
Sangoma notes that the preview table shows only some headers and provides a detail view for all values. Inspect the full proposed row, its identifier and whether it will create or update. Preserve absent columns, blank cells and explicit values separately. For documented extension fields, blanks can disable call waiting, Follow Me or voicemail, and REGEN in the secret field can rotate the credential.
If the wrong record would be changed, identify the matching key and collision before continuing. If the wrong fields would change, remove or correct only the demonstrated columns; do not assume a blank means 'keep existing.' For a DID, verify the full context,extension,priority destination rather than only the visible label.
Reconcile a partial import before any retry
Record accepted, rejected, skipped and unknown rows from the progress output, then inspect those identifiers in their owning modules and export the handler again. Compare counts and intended fields with the before snapshot. A green row, a Finished message and a successful Apply Config remain separate observations, and none proves the file was processed as one transaction.
Build a retry file containing only unresolved approved rows after determining why they failed. Do not replay the original batch to make the progress display look complete. If unexpected credentials, routes, permissions or existing records changed, isolate access and restore the smallest safe scope using the before evidence or supported recovery plan.
Trace Apply Config and the runtime owner
If rows were written but behavior did not change, preserve the Apply Config result, then inspect the object in the module that owns it. Follow generated and loaded state only where applicable and keep the runtime consumer separate: extension contact and call path, DID route, User Manager login and effective group permissions, contact visibility in the intended consumer, or the installed trunk's registration or peer behavior.
Correct the first failed owner. Repeated CSV edits cannot repair an endpoint with the wrong provisioned secret, a call using another DID route, a user whose effective permissions come from another group, a directory consumer that has not refreshed, or a provider-side trunk fault.
Replay a bounded acceptance and close securely
After one supported correction, import one representative row and repeat the evidence chain: validation, full preview, row result, Finished state, Apply Config, post-export and the owning module's runtime behavior. Add a neighboring unchanged record and the relevant rollback check. Expand only when the pilot matches the written change list.
Document final accepted and rejected rows, unexpected changes, recovery actions and remaining uncertainty. Revoke or rotate any exposed credentials, restrict or destroy unnecessary working files and remove temporary diagnostic access. This procedure is documentation-derived and has not been reproduced on a customer or laboratory PBX.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Sangoma Bulk Handler user guide ↗
- FreePBX Bulk Handler release/17.0 metadata ↗
- Sangoma deprecated Bulk Extensions notice ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.