Default functionality

FusionPBX comes preconfigured with powerful features.  There are some things you might want to disable or change though.

For instance.  If you have SIP phones (as opposed to using ATAs with traditional phones) they might do unexpected things.  One example of this is that *8 followed by an extension is the freeswitch preconfigured intercom function that is defined in the advanced dialplan.  Unfortunately on Yealink phones if this is enabled a person can call your phone with it and without you needing to accept the conversation the phone automatically answers the call and turns on your microphone - so they can hear everything that is being said in the presence of your phone without you having authorised it.  So you might want to disable this.  Actually, FusionPBX ships with intercom.lua in the freeswitch/scripts directory and if you set up this intercom it mutes the line of the person receiving the intercom call until they accept the call - a much safer option.

You might also want to disable the "eavesdrop" functionality provided in the advanced dialplan too.

Additionally, you might want to change the pin on the DISA dialplan entry (not in the advanced dialplan) - theoretically if you enable direct dialing from IVR and you left this as the default pin and someone knew you had a fusionpbx phone system they might be able to dial it from an IVR and make long distance phone calls at your expense because it was still using the default pin.  I'm not really sure if that is possible but is it worth the risk?

While I'm at it, if you do edit your advanced dialplan and make a mess of it you'll want to restore it.  For some reason my restore default button on the bottom of that screen didn't restore the default but instead left me with an empty file.  I had to copy the default from /var/www/fusionpbx/includes/install/dialplan/default.xml
However, I made a big error.  Before doing this I backed up my current default.xml file and left the old copy in the same directory with the extension .xml.  Unfortunately freeswitch still processed the backup because it had the extension .xml and therefore my error didn't go away!  So if you are going to make a backup in the same directory give it a different extension eg. .old

Note that if you to create a mess of your advanced dialplan you may generate errors when you apply settings.  eg. '+OK [[error near line 4968]: unclosed'.  To locate this use an editor such as nano to look at freeswitch/log/freeswitchxml.fsxml - this file is generated by freeswitch when it is processing your dialplan files.  In nano CTRL-_ will allow you to enter the line number from the error message.  When you have seen the line in that file you can then go back and look for the corresponding line in the advanced dialplan and fix the problem.  Note that the error might not be on that line - in my case it said it was near that line but it did enable me to locate the problem.

Understanding dial plans in more depth

Since writing my earlier posts about dial plans, I've discussed them with people and learnt a bit more about them so I'm sharing that with you to make your life easier as well!

The default dialplan that ships with freeswitch gives you 1000-1019 and 2000-2999 for use for extensions and uses lots of other numbers for other purposes.  When FusionPBX was created it was decided to move all these pre-defined things that were in the freeswitch default configuration out of the way so that people were unrestricted in what extension numbers they could use.

Accordingly all the default freeswitch dialplan configurations have been moved to start with *.  You can see these in dialplan/default.xml.  The easiest way to look at this is to go to the Dialplan Manager screen and press the Advanced button.  This will open up an editor that shows you this particular file and allows you to change it.

All the dial plan entries you create in FusionPBX are stored in the database and the database is used to automatically generate the dialplan files located in default/*.xml.  So if you have a look through the default dialplan you will see this line halfway down the file:
X-PRE-PROCESS cmd="include" data="default/*.xml"

Everything in the default dialplan BEFORE this line is processed before your dialplan entries and therefore will override anything in your default dialplan.  Anything in the default dialplan AFTER this line is processed after your dialplan entries and therefore will be overridden by anything in your default dialplan.

Additionally, you can, if you want, modify this default dialplan directly in the editor.  Anything you see in the default dialplan is only defined there, it isn't stored in the fusionPBX database.

I hope that removes some of the pain of understanding dialplans!

Dial plans - an easy mistake

One of the mistakes I keep making in the dial plans is that I enter a number that I want people to dial in order to reach a special function on the phone system, instead of entering a regular expression defining that number.  So for instance if I want them to dial 1 to reach a function I have been setting my condition as destination_number=1 but this is wrong.  The correct condition is destination_number=^1$

Don't get caught in the same way!

Dial plans - CLI is your friend

Dial plans are complicated to understand.  How can we see why things are failing to work the way we think they should?

CLI, the command line interface, is one of the most useful tools when it comes to understanding what is going on in your system.  Here you can look in real time at what is happening when you try to make or receive a call and you can diagnose faults.  I have to say that this has been the most useful piece of information when it comes to diagnosing issues with the dial plan (apart from learning to write regular expressions).  To run the cli you type /usr/local/freeswitch/bin/fs_cli at the linux prompt.  If you don't want to look real time you can also look at the logs in /usr/local/freeswitch/log/freeswitch.log.  Note that if you are using the console of your server then you really need to be looking at the log as that way you'll be able to scroll back and forward using your text file viewer and see what you need to see.  But if you use PUTTY you can use the cli as you'll be able to scroll back and forward using the scroll bar on the side of the putty window.  Note that the putty line buffer is set to 200 lines by default - I tend to increase this to 2000 so that I have enough history to scroll back through.

When you are using the CLI you can exit the CLI back to the linux prompt by typing ... (yes, three fullstops in a row, or for Americans, 3 periods in a row).  To diagnose dial plan faults, start the CLI and then dial the number you want to test using your phone.  You will see a bunch of stuff flying past.  You'll then hear your call failure (if you didn't have a call failure you wouldn't be diagnosing it would you...) and at that point press CTRL-S to freeze the CLI output until you are finished looking at it.

So you're looking at the log.  Look for a line like this one:
2010-08-12 09:20:21.736881 [INFO] mod_dialplan_xml.c:331 Processing [THE NAME OF YOUR PHONE EXTENSION YOU DIALED FROM]->[THE NUMBER YOU DIALED] in context default

It could be quite a way back up the log so don't give up looking.  What happens after this is that you'll see a number of lines with the words "Regex (FAIL)" in them.  This is not bad.  What is happening is that your number is being compared to each regular expression in the dial plan in turn, and when it gets through the parts of the dial plan you have configured it then goes through the default dial plan (in dial plan, advanced) and compares each expression with your number.  When it finds a match you will get a "Regex (PASS)".  This pass is the key to diagnosing your problem.  The thing about FusionPBX (maybe also Freeswitch for that matter) is that there are a LOT of functions already defined for you and they don't seem to have any sort of consistent pattern or number range that they are in (unlike Trixbox where you can see all of these in "Feature Codes" and most of them are * followed by a 2 digit number) therefore it is quite possible that what you are trying to set as your dial sequence is already matching one of the pre-defined functions and therefore it isn't working for you.  It would also appear that some of these functions are defined in the dial plan BEFORE the things that you define in the dial plan, as putting your dial plan entry with an order of 0 still doesn't override them.  So look at the PASS line and see which regular expression it matches, and the bits on the lines following that will give you clues as well.  If it isn't the regular expression that you configured then it is likely you are in conflict with one of the already defined functions and you are just going to have to change yours.  

The other possibility is that your regular expression is wrong - but you can test your regular expression with a number of automatic testing pages on the internet to see if that is the problem - the one I like is http://erik.eae.net/playground/regexp/regexp.html because you can cut and paste your regular expression into the first box, and then type your dial sequence into the second box, and then in real time, the third box gives you the interpreted result and even breaks it up into the different number groupings caused by your use of () in the regular expression.

Hopefully this will help make your dial plans easier to test and troubleshoot.

A word on numbering schemes

This post is a later addition that I am submitting in the order that you would need it rather than when I wrote it.  Before setting up your phone system you need to decide on a numbering scheme.

When I was using asterisk I used 3 digit extensions and I used *xxx for special functions such as toggling day/night switches and I used *xx for trunk overrides so that I could force a call through a particular gateway.  However this doesn't work with FusionPBX as using *anything is fraught with difficulties caused by the default dial plan and pre-defined functions - so just don't try to use * for anything of your own and you'll be far better off.

Pre-defined in the dial plan is the ability to work with 3, 4 or 5 digit extensions.  Therefore if you have a small implementation you might want to consider 3 digit extensions and allocate the last 100 (ie. 900-999) to be special functions such as toggling day/night switches, short dial sequences, etc.  If you have a larger implementation you might want to have 4 or 5 digit extensions and to use the entire 3 digit range for special functions.

Whatever you decide, document the ranges you are going to use and be consistent.  It will make your job a lot easier and might save you some of the pain I had to go through in moving from Trixbox to FusionPBX.