Discover the installed handler and schema
Choose one object type and one change boundary before exporting. Sangoma documents extensions, DIDs, User Manager users and groups, and contacts, while current release/17.0 metadata says trunk import was added in 17.0.7. The installed module and its available handlers are therefore controlling evidence; an older screen guide or another PBX's template is not a compatibility matrix.
Export that object type from the target PBX and preserve an untouched before copy. Use the installed import screen's required and recommended headers. The separate Bulk Extensions module is deprecated, so do not translate its historical columns into Bulk Handler merely because the labels look familiar.
Preserve literal CSV values and secrets
Keep the source export, working file and exact import artifact distinct. Record a hash, byte encoding, delimiter, quoting and row count for the artifact actually uploaded. Treat extension numbers, DIDs, caller IDs and other identifiers as text: spreadsheet display, a cell's stored type, literal CSV bytes, parsed values and the validation preview are separate states. Check for removed leading zeros or plus signs, scientific notation, changed dates, embedded delimiters, quotes, line breaks and Unicode conversion before upload.
Protect the files as configuration and personal data. Documented fields can include SIP secrets, plaintext User Manager passwords, voicemail PINs, DIDs and contacts. Store them in a restricted location, redact support evidence and never attach a populated production CSV to a public ticket.
Treat blank cells and control tokens as changes
A blank cell is not a universal 'leave unchanged' instruction. In Sangoma's documented extension schema, blank callwaiting_enable, findmefollow_enabled or voicemail_enable values disable those features. The secret field accepts the REGEN token to generate a new secret. Preserve absent columns, empty values, explicit disable values and control tokens as different inputs, and confirm the installed handler's semantics before touching an existing record.
For DIDs, preserve the documented destination tuple of context, extension and priority as one routed target. For User Manager and Contact objects, keep identity, group, type and internal-user references bound to their owning module. A syntactically valid row can still redirect a DID, rotate a credential, disable a feature or change directory visibility.
Make validation and update scope explicit
Sangoma states that Submit opens a validation page; it does not complete the import. Preserve the uploaded filename and hash, handler, header mapping, validation errors, preview counts and the Yes/No control that determines whether existing data may be replaced or updated. The preview table shows only some headers, so open the row detail and compare every affected field with the written change list.
Start with one approved representative row and stop if its identifier, action or full field set is wrong. A replace-or-update setting is a high-impact scope boundary, not a convenience toggle. Do not enable it to overcome a duplicate error until the exact matching key and intended mutations are understood.
Separate row progress, finish and Apply Config
During import, preserve start and end times, progress state, row colors or messages, accepted and rejected identifiers and the first error. Sangoma describes rows turning green as each item imports and a separate Finished state, followed by Apply Config. Those observations show stages in the workflow; they do not prove that the entire file was atomic or that the running PBX accepted the resulting configuration.
After Apply Config, inspect the changed objects in their owning modules and export the same handler again. Compare intended fields and counts with the before export and identify every accepted, rejected, skipped or unexpectedly changed record. If the batch partially succeeded, do not blindly replay the original file: a second run can update already changed rows or repeat credential and routing side effects.
Accept runtime behavior and preserve rollback
Test only the functions implicated by the approved change: for example registration and authorized calls for an extension, route selection for a DID, login and effective permissions for a User Manager record, consumer visibility for a contact, or provider-facing behavior for a trunk. CSV acceptance, a green row and Apply Config are not proof that a phone registered, a DID reached the intended destination or a trunk worked.
Retain the before export, exact import artifact, validation evidence, result export, affected-object list and supported backup long enough to complete rollback. Correct the smallest demonstrated field through supported controls or restore from the approved recovery point when a narrow correction is unsafe. This workflow is documentation-derived and was not 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.