Docs / Running the server
Importing from FreePBX and 3CX
When a customer moves to Onyx Voice from FreePBX or 3CX, you do not have to type their phone system in again. Onyx Voice reads the old system's export, shows you everything it would create, lets you leave items out or give them other numbers, and then creates extensions, conference rooms, ring groups, queues, auto attendants (IVRs), time conditions and phone numbers (DIDs) in one go. This chapter covers getting the files, the Import (FreePBX, 3CX) page, how the old system's items map to Onyx Voice, what is not imported, and the command line.
Before you start
- Create the tenant first. An import always goes into one tenant. See Tenants (companies).
- Set up the trunk and outbound routes yourself; they are not imported. Phone numbers can be imported before the trunk exists. See Trunks (carriers) and Phone numbers and routes.
- Importing never changes or removes anything already in the tenant, so you can import into a tenant that already has some extensions, and you can run the same import again.
- Phones keep working on the old system until you move them: the import gives every device a new SIP password.
The import has been checked against sample exports in FreePBX's own table layout, not yet against many real customer systems. The first time you import from a given system, read every note in the preview before you press Import.
Getting the files
| From | Files | What they give |
|---|---|---|
| FreePBX 13 to 17 (everything) | The database dump and the voicemail file (see below) | Extensions (name, outbound caller ID, ring time, voicemail on or off, voicemail PIN and e-mail), conference rooms, ring groups, queues (static agents, strategy, maximum wait, overflow), IVRs, time conditions (from time groups) and DIDs |
| FreePBX Bulk Handler | The Extensions CSV and the DIDs CSV | Extensions; DIDs with their destinations |
| 3CX | The user export (Users, Export) as CSV | Extensions (name, e-mail, outbound caller ID, voicemail PIN, and the desk phone's MAC address and model when the export has them) |
| Any other system | A CSV with the columns number, name, email, and optionally mac and model | Extensions, with desk phones when MAC and model are given |
| Any other system | A CSV with the columns did, destination, name | DIDs |
For FreePBX, sign in to the FreePBX server as root and run:
mysqldump asterisk > /root/freepbx.sqlCopy /root/freepbx.sql and /etc/asterisk/voicemail.conf to your computer and upload both together. The voicemail file adds the voicemail PINs and e-mail addresses; without it, every extension gets a new PIN and e-mail addresses come only from FreePBX's User Management.
Things to know about the files:
- Dump only the
asteriskdatabase. The call records are in a separate database (asteriskcdrdb) and are not needed. All files of one upload together may be at most 100 MB. - The FreePBX dump is read, never run. Onyx Voice takes only the tables it needs, and finds the columns by name, so the FreePBX version does not matter.
- CSV files may be separated by commas or semicolons, and saved as UTF-8 or as Windows (Excel) text.
- You can upload several files at once: a dump with its voicemail file, or an extensions CSV with a DIDs CSV. They become one preview.
- One import can hold at most 5000 items.
Importing in the console
- If you are a system administrator, pick the tenant to import into first. Tenant administrators import into their own tenant.
- Open Import (FreePBX, 3CX).
- Under The export, click Files and choose the files from the old system.
- Press Read the files. Nothing is created yet.
- Read the preview (see below). Untick anything you do not want to bring over.
- If you want an IVR or time condition on another number, type the new number in its field (2 to 8 digits). Everything that pointed at the old number points at the new one.
- Press Import.
The preview
The top card says what was read (for example "Read from FreePBX database") and how many items will be created, with warnings for the whole import, such as a missing voicemail file. Below it is one table for each kind of item: Extensions, Conference rooms, Ring groups, Queues, IVRs (auto attendants), Time conditions and Phone numbers (DIDs).
Each row has a tick box, the number, the name, What it does (for example "all at once: 101, 102, 103 ยท then voicemail 101") and Notes.
- A number that is already in use in the tenant is unticked and cannot be ticked. Its note says "already in use: left alone".
- Some items arrive unticked because they cannot be imported as they are: a number that is not 2 to 8 digits, a ring group with no members, a time condition with no opening hours Onyx Voice could read, a DID whose destination could not be followed, a DID that applied only to calls from one caller. The note says why. If you tick one of these anyway it may fail, or need finishing by hand; a DID without a destination is never created.
- A note on a ticked item tells you what to finish after the import, for example "Its greeting (Main greeting) is not imported" or "It went to an announcement, which is not imported: choose its destination after the import".
- IVRs and time conditions show their number in an editable field. FreePBX does not give them numbers, so Onyx Voice picks free ones (see Numbers for IVRs and time conditions).
The result
When the import finishes, the page shows Import finished with how many items were created, how many need a look and how many failed, and a table of every item with its result:
| Result | Meaning |
|---|---|
| Created | Created as it was in the old system. |
| Created: check it | Created, but something needs finishing. The note says what: a destination to choose, a greeting to upload, settings that were not all taken. |
| Failed | Not created. The note gives the reason. The other items were still created. |
| Already in use | The number (or DID) was already there; it was left as it is. |
| Not imported | You unticked it. |
Press Extensions & numbers to go to the new extensions.
After the import
- Provision the desk phones again, or enter the new SIP credentials on them: their SIP passwords are new. Extensions with a MAC address and a known model in the export already have their desk phone assigned. See Desk phones.
- Upload IVR greetings, announcements and hold music under Prompts & hold music, and choose each greeting on its IVR. The notes name the recordings the old system used. See Auto attendants, opening hours and prompts.
- Go through every Created: check it item. Anything without a destination hangs up until you choose one.
- Check the opening hours and add holidays to the time conditions; FreePBX holidays and calendars are not imported.
- Set up the trunk and outbound routes if you have not, and point the carrier's numbers at the new server.
How FreePBX items map
| FreePBX | Onyx Voice |
|---|---|
| Extension (user) | A user extension with voicemail and a SIP device: name, outbound caller ID (digits only), ring time (5 to 300 seconds), voicemail on or off, PIN and e-mail from the voicemail file, e-mail from User Management when the voicemail file has none |
| Conference | A conference room: number, description, user PIN, admin PIN as the moderator PIN, maximum users |
| Ring group | A ring group: members, strategy, ring time, caller ID name prefix, destination if no answer |
| Queue | A queue: static members with their penalty, strategy, maximum wait (default 600 seconds), caller ID name prefix, fail-over destination as the overflow |
| IVR | An auto attendant on a new number: single-key options (0-9, *, #), direct dial on or off, timeout (1 to 60 seconds), attempts (invalid retries plus one), timeout and invalid destinations |
| Time condition | A time condition on a new number: opening hours from its time group, destinations when open and when closed |
| Inbound route | A DID with its destination and caller ID name prefix |
Destinations:
| FreePBX destination | Onyx Voice |
|---|---|
from-did-direct,101,1, ext-local,101,1 | 101 |
ext-local,vmb101,1 (also vmu, vms, vmi) | vm:101 |
ext-group,600,1, ext-queues,400,1, ext-meetme,800,1 | the number |
ext-findmefollow,FMGL-101#,1 | 101 |
ivr-3,s,1 | the number the IVR gets |
timeconditions,2,1 | the number the time condition gets |
app-blackhole,hangup,1 (terminate call) | hangup |
| Announcements, misc destinations, call flow control (day/night), languages, set caller ID, callback, DISA, the dial-by-name directory | Not imported. The item's note says "choose its destination after the import"; until you do, it hangs up. |
Strategies and hours:
| FreePBX | Onyx Voice |
|---|---|
| Ring group strategy ringall, ringall-prim | ringall (everyone at once) |
| Ring group strategy hunt, hunt-prim | hunt (one after another); each member rings for the FreePBX ring time |
| Other ring group strategies (memoryhunt, firstavailable, random...) | hunt, with a note |
| Queue strategy rrordered | linear, with a note |
| Other queue strategies Onyx Voice does not have | rrmemory, with a note |
Time group entry 08:00-17:00|mon-fri|*|* | opening hours mon-fri 08:00-17:00 |
| Time group entries that name month days or months, or run past midnight | Not imported; the note lists them to add by hand |
| DID route with a caller ID number | Not imported (unticked): Onyx Voice routes a DID the same way for every caller |
| "Any DID" route | Not imported: a catch-all route in Onyx Voice belongs to a trunk; add it after the trunk |
Numbers for IVRs and time conditions
FreePBX reaches IVRs and time conditions by an internal id, not a number you can dial. Onyx Voice gives each one the first free number from 700 (IVRs) and from 750 (time conditions), skipping every number already in the tenant or in the import and the call parking numbers 700 to 720, so the first IVR usually gets 721. When most extensions have four digits, the ranges start at 7000 and 7500 instead. You can change the numbers in the preview.
If you import the same dump again, IVRs and time conditions that the first import created (found by their name) keep their numbers, so nothing is created twice.
How the import works
- Previewing writes nothing.
- On import, numbers already in use in the tenant and DIDs already routed are left alone.
- One item failing does not stop the others.
- Ring groups, queues, IVRs and time conditions may point at each other in any order. They are first created pointing at hang up, then pointed at their real destinations once every number exists.
- Running the same import twice creates nothing the second time.
What is not imported
- SIP passwords. Every device gets a new random password, so desk phones must be provisioned again.
- Recordings: IVR greetings, announcements and hold music are files on the old server, not in the database. Upload them under Prompts & hold music. Each IVR or ring group that used one says which.
- Trunks and outbound routes. Set them up from the carrier templates; they are short and carrier-specific.
- Voicemail PINs that are too simple (fewer than 4 digits, all the same digit like 1111, or a run like 1234 or 4321). The extension gets a new PIN, shown on the extension, and a note says so.
- Mobile numbers in a 3CX export are read but not stored anywhere.
- Follow-me lists, call forwarding, blacklists, paging groups, parking settings, feature codes, holidays and calendars, queue settings other than the ones listed above, and people's portal sign-ins. Create portal accounts afterwards under Sign-in accounts.
Column names Onyx Voice recognises
CSV columns are found by name; case, spaces and punctuation in the heading do not matter. If a file is refused with "no column with the extension number", rename the heading to one of these:
| What | Column names |
|---|---|
| Extension number | extension, number, ext, extension number |
| Name | name, display name, full name, or first name plus last name |
email, email address, voicemail email, mail | |
| Voicemail PIN | voicemail_vmpwd, vmpwd, vm password, voicemail password, voicemail pin, vmpin, pin |
| Voicemail on or off | voicemail (novm = off), voicemail enable, enable voicemail, voicemail enabled (no, 0, false, off or disabled = off) |
| Outbound caller ID | outboundcid, outbound caller id, callerid |
| Ring time | ringtimer, ring seconds, ring time |
| Desk phone MAC address | mac, mac address, provmacaddress, phone mac (12 hex digits) |
| Desk phone model | model, phone model (must be a model Onyx Voice provisions) |
| DID | did, did number, phone number, extension, number |
| DID destination | destination, dest, route to: a number, vm:101, hangup or a FreePBX destination |
| DID name | description, name, label |
A file with a destination column is read as a list of DIDs; any other file as a list of extensions.
From the command line
The same import runs from a shell on the server:
sudo onyx import plan acme freepbx.sql voicemail.conf
sudo onyx import apply acme freepbx.sql voicemail.confplan prints the preview as a table (kind, number, name, whether it would be imported, note) and writes nothing. apply imports everything the plan marks for import, prints the result of each item and exits with 1 if any failed. The command line cannot untick or renumber items; use the console for that. See Command line (onyx).