Skip to main content

Move from another PBX

The migration autopilot brings a company over from its old phone system in one sitting: users, extensions, ring groups, queues, menus (IVRs), office hours, inbound numbers, trunks, voicemail greetings and contacts. You see a mapping report first, then run a dry run, then apply. Nothing changes before you apply, and passwords and PINs are never imported.

Open System, Move from another PBX (/admin/migration). You need settings:read to preview and settings:write to apply. Importing the contacts also needs contacts:write.

What it reads​

Choose your old system, then add the files it exports. Several files can be added at once (at most 60 files and 7 MB together).

Old systemFiles to add
3CXThe JSON configuration export. Contact CSV files can be added too.
FreePBXThe CSV files of the Bulk Handler export (extensions.csv, dids.csv, contacts.csv) and the configuration files of a backup (pjsip.*.conf, voicemail.conf, queues_additional.conf, extensions_additional.conf). Unpack the backup first.
AsteriskThe configuration files: pjsip.conf or sip.conf, voicemail.conf, queues.conf, extensions.conf. Files named in #include lines are listed in the report: add them too if they hold configuration.
CSV filesA users file (one row per extension) and, if you have one, a contacts file.

How the files are used:

  • Users and extensions: from the users file, the SIP endpoints and the voicemail boxes (name and e-mail). An extension without an e-mail address is imported as an extension without a user, and the report says so. Add the e-mail column, or assign a user in the console later.
  • Ring groups and queues: from the queue files and the dial plan (a number that dials several phones becomes a ring group; a number that runs a queue gives the queue its number). Strategies are mapped to the nearest MonoPbx strategy; one without an exact match is reported.
  • Menus: a menu that plays a prompt and sends keys to plain destinations becomes a call flow draft. Upload its prompt, then publish it in the flow editor. A menu with time rules or nested logic is reported to rebuild.
  • Office hours: weekly time conditions become schedules. Conditions on days of the month or months are reported.
  • Inbound numbers: numbers routed to an extension, voicemail, ring group, queue or menu become inbound routes. A number behind a time condition, a script or custom logic is reported.
  • Trunks: IP trunks are imported. A trunk that registers to the carrier needs its password, which an export never carries, so it is listed under Trunks to create in the console with its host, user name and numbers.
  • Contacts: from a contacts file (name, company, phone, mobile, e-mail). They go to the company phonebook with Import contacts.
  • Audio: prompts and voicemail greetings are listed with their file name in the old system and where they belong here. Copy them in Call handling, Music on hold and prompts and on the voicemail boxes.

Users files and column mapping​

Columns are found by their names: extension (or ext, number), first_name, last_name, name (a full name is split at the last space), email, department. The delimiter can be a comma, a semicolon or a tab. If your columns are named differently, open Column mapping and type the column name for each field. Columns that hold passwords or PINs are counted and never read.

Steps​

  1. Preview the move. The mapping report shows how each file was read, what was mapped, how many passwords and PINs were found and left out, the list To finish by hand (every gap, one line each), the trunks to create, the audio to copy and the changes this company would get.
  2. Dry run. Everything is written in a transaction and rolled back, so you see that the import applies without changing anything. Apply is available after a successful dry run.
  3. Apply the import. One confirmation, then everything is written in one step. If anything fails, nothing changes. Nothing that already exists in the company is deleted. The apply is recorded in the audit log.
  4. Import contacts into the company phonebook.
  5. Work through To finish by hand, create the registering trunks with their passwords and copy the audio.

The Cutover checklist at the end of the page lists these steps and the ones below in order, with a link to the page where each is done.

Side by side (cutover in batches)​

You do not have to move everything at once. Tick Add a trunk to the old PBX and enter its address. The import then adds an IP trunk named "Old PBX (side by side)", so both systems can reach each other while phones move over in batches:

  1. On the old PBX, add a SIP trunk to this PBX and route the extensions that have moved through it.
  2. Here, add an outbound rule (Call handling, Inbound and outbound rules, Outbound rules) that sends the extension numbers still on the old PBX to the trunk "Old PBX (side by side)".
  3. Move the phones in batches: provision them on this PBX (Desk phone provisioning) and sign in the apps. Test calls both ways after each batch.
  4. Move the numbers: port them (Number porting) or point the carrier trunk at this PBX.
  5. When the last phone and number have moved, remove the trunk and the outbound rule and switch the old PBX off.

If the address is an IP address, only that address may send calls over the trunk. With a host name, the addresses it resolves to are accepted. In an install with several companies, the address list waits for a system administrator's approval, as for any trunk.

Good to know​

  • The importer reads the documented formats of these systems. Systems are configured in many ways: always read the report and test calls before you move phones.
  • Custom dial plan logic (patterns, scripts, macros) is never guessed. The report counts it per context so you can rebuild what you need as call flows or outbound rules.
  • Report lines name things as they were called in the old system and are shown in English.
  • Over the API this is POST /api/v1/config-as-code/migrate. It returns the document, the report, the plan, the contacts as a phonebook CSV and the checklist. Apply the document with POST /api/v1/config-as-code/apply?dry_run=true, then without dry_run.

3CX, FreePBX and Asterisk are trademarks of their respective owners. MonoPbx is not affiliated with, endorsed or sponsored by them. The names are used only to say which exports the importer reads.