Faxing

FusionPBX faxing has a lot of promise.  From all accounts it appears that when the function works it works much more reliably than Asterisk based faxing.

Something I learnt is that if you select ADVANCED, XML Editor a new window will open.  Choose autoload_configs from the list, then choose fax.conf.xml

In fax.conf.xml there is an option that by default sets a variable called verbose = false.  If you change this to true you get more logging details as the fax is actually received, such as the quality of the connection etc.  You can see these details when you run the freeswitch command line ie. /usr/local/freeswitch/bin/fs_cli

Well there are lots of things that can go wrong.  So others can learn from them here goes:
- careful that the extension you use for your fax is not valid for something else!  In my case I used 8001.  This turned out to be valid for the feature code that changes group membership or something (see dial plan, advanced).  For information on how to diagnose a fault like this see my blog entry on dial plans.
- I changed the fax extension from 8001 to 7701 and this got me closer.  Now I appeared to have a permission problem.  But in reality, because I had changed the number rather than creating a new fax extension from scratch, it created the folder for 7701 but failed to create the "inbox" and "sent" folders underneath that, and so when the fax server tried to write to the inbox folder it had an error.  If I'd created the fax extension from scratch I wouldn't have had this problem.
- in the process of doing all this, I have made an enhancement to the fax processing script that has now been incorporated into the official release of FusionPBX (for more details see below).  My enhancement tells you any error message from the fax receipt process (if you fail to successfully receive a fax you receive an email but the email contains no attachment - this addition allows you to know why you didn't get an attachment), the fax senders' identification information, and the number of pages in the fax (not necessarily the number of pages received).

Limitations of the fax server functionality: With the fax server in its current form it is not possible to send a fax to the fax server from an extension on the same phone system.  I was doing my testing using a fax machine connected to an ATA on an extension of the phone system and the system fails to send the fax as an email because when the fax machine hangs up, the call terminates and the fax_to_email script is never executed.  The only way to make this work is to modify the dialplan created by the fax server function so that prior to starting rxfax it sets the variable api_hangup_hook=system /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=youremailaddress@yourdomain extension=yourfaxextension name=${last_fax}
(where the bit following the keyword of system is the exact same data that is automatically put into the dialplan of the fax configuration on the action system line that follows the line containing rxfax).  This limitation does not apply to externally sent faxes and therefore this line is not necessary.  Accordingly unless you have a really good reason to change it so you can receive internal faxes I think you should stick with the standard fax server configuration.

My Enhancement of the fax server functionality (this is now included in FusionPBX)
The enhancements I have implemented are:

- add fax status information into the email that is sent - the driving force for this requirement was that I discovered that a failed fax transmission (eg. a telephone calling the fax number rather than a fax) would result in an email that is sent without any fax attachment and without any explanation.  Therefore I modified the script so that we could include messages as well.  Additionally the action system line in the dialplan needs to change to support this as well: /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=youremailaddress@yourdomain extension=yourfaxextension name=${last_fax} messages='result: ${fax_result_text} sender:${fax_remote_station_id} pages:${fax_document_total_pages}'
(note that you can test faxing from your server by running this line interactively, but you can simplify it a bit as the variables mean nothing if you run it from the shell prompt eg. /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=youremailaddress@yourdomain extension=yourfaxextension name=the_name_of_the_fax_tif_file_without_a_file_extension messages='you don't need to put anything here')

 - create a log of sent faxes - because I was frustrated in the debugging process of the fax to email script that although I could tell that freeswitch had received the fax I was unable to tell if the fax had ever been attempted to be emailed because FusionPBX doesn't use an MTA (message transfer agent eg. sendmail) to send the messages and therefore there is no message queue to check.  The log is  /usr/local/freeswitch/storage/fax/emailed_faxes.log
- add sending retries on failed email - I discovered that if the email server is misconfigured, or uncontactable at the time the fax is received, then the fax_to_email process fails and the user never receives the fax - it is just stored on the server.  So I added a section to the script that enables it to queue messages it cannot send when the email server is not contactable.  It will continue to retry sending these messages once every 3 minutes.  The messages will queue on the server until sending is successful.  These messages are queued in /usr/local/freeswitch/storage/fax/failed_fax_emails.log - the lines in that file are actually executed by the re-sending process, so the structure of the lines is important.
- added checking to see if there is an attachment on the server to send.  If there isn't one it will send an appropriate message in the fax email.  This is helpful when we have a failed fax, it is also helpful if someone manually deletes queued faxes before we successfully email them.

I hope this makes faxing simpler for you.