Description

Asternic Call Center Stats is a queue reporting solution for the open source Asterisk© PBX. In order to use the software you must have a working Asterisk PBX, and you should be using queues with it.

Asterisk is a powerful and complex software. You won't find here instructions on setting up Asterisk itself here. If you are new to Asterisk and VoIP and want to get started, an easy and quick way is to install one Asterisk based Linux distribution like Elastix, PBXinaFlash, AsteriskNow, etc. Any of these distributions will install a complete Linux system with Asterisk and a web fronted for configuring it.

Once you have Asterisk working you can install Asternic Call Center Stats to get the best of breed queue reports and metrics available for it. Don't take our word for it. Download it and see it for yourself.


System Requirements

Asternic Call Center Stats PRO is a PHP application, encoded with Ioncube. There are certain requirements to be met in order to successfully run the software

Server Requirements

On the server side you need:

  • A web server (Apache/Nginx)
  • 32 or 64 bits Linux Operating System
  • PHP 5.1 or above
  • MySQL Server 5 or above
  • Ioncube Loader

It also has a log processing daemon that is written in Perl, and requires the Perl-Time-HiRes module to be installed. The log processing daemon should run on the background at all times, and it will feed any data that is written into the Asterisk queue log files in its own database.

Client Requirements

You access rerpots using your web browser. For a full experience you have to use a modern one:

  • Modern Web Browser (IE8 or above, Google Chrome, Safari, Firefox)
  • Javascript enabled

Getting the software

You can see available downloads in http://www.asternic.net/download.php. Asternic Call Center Stats PRO requires an activation code, you can purchase a license to get a perpetual activation code, or you can request a 30 days trial code for testing it out before buying.

You also have the choice of installing the open source Lite version of our software. It is important to note that it is not the same software as the PRO version. Database schemas differ and installation instructions are also different. There is another installation guide for the Lite version that you can find here.

So, log into your server and run this from your server command line:

cd /usr/src
wget http://download.asternic.net/asternic-stats-pro-2.0.8.tgz 

Installation

Once the download finishes, extract the package:

tar zxvf asternic-stats-pro-2.0.8.tgz

Then change to the newly extracted directory that contains all files:

cd asternic-stats-pro-2.0.8

Note

You must know beforehand the MySQL root password in order for the installation to succeed. The database and tables need to be created, and you must enter that password when prompted. Otherwise, installation will be partial and non working.

And finally start the installation script:

make install

Note

If you use the FreePBX© or other trimmed down distributions, the make command might not be installed by default. In the case that the above command throws a command not found error, you will need to install the make utility and try again. (This is not needed if you do not receive any command not found errors). To install make run:

yum -y install make

The installation script will do several things:

  • Check if the software is already installed, if so it will abort and exit
  • Check if the database qstats exists, if so, it will abort and exit.
  • It will install the ionCube loader for your platform and PHP version
  • It will install an init script for the asterniclog parser daemon
  • It will install the perl-Time-HiRes module
  • It will create a MySQL database and tables named 'qstats'
  • It will install both the parselog tool in /usr/local/parselog and the web application in /var/www/html/stats

Configuration

Manager Credentials

For the realtime page to work, you must supply valid Asterisk Manager Interface (AMI) credentials to Asternic config.php file. So, look at your /etc/asterisk/manager.conf file and search for a valid user and secret, it will look something similar to this:

[admin]
secret=amp111
deny=0.0.0.0/0.0.0.0
permit=127.0.0.1/255.255.255.0
read=all
write=all

In the above case, the user is 'admin' and the secret is 'amp111'. Use those values into Asternic's /var/www/html/stats/config.php file:

// Manager details (for realtime tab)
$MANAGER_HOST   = "127.0.0.1";
$MANAGER_USER   = "admin";
$MANAGER_SECRET = "amp111";

Without those credentials being set, the realtime view won't display any agents or queue activity. But reports will run normally.

NOTE

It is also very important that the manager user has the originate (or all) permission in the write line if you want to use the realtime actions for spy, coach and steal calls. Without it, those actions will misserably fail without notice.


Managing the asterniclog service

Once Asternic CCStats PRO is installed under a Debian/Ubuntu or RedHat/Centos based systems, a set of init scripts will be also copied and installed. Those scripts can be used to start, stop or restart the service that reads the Asterisk queue_log file and inserts data into the MySQL table for the reports to run.

Apart for the script themselves, there is also an OPTIONS file you should edit to pass extra command line parameters to the service at startup. For example, if you want to reparse old entries, or convert Local members to their FreePBX name, you should edit that file and add the parameters there.

The file is named /etc/sysconfig/asterniclog and the default content for a FreePBX based distro is:

OPTIONS="-u qstatsUser -p qstatsPassw0rd -d qstats -h localhost -l /var/log/asterisk/queue_log -c --daemon"

If you do not use FreePBX, then the parameters are a little bit shorter:

OPTIONS="-u qstatsUser -p qstatsPassw0rd -d qstats -h localhost -l /var/log/asterisk/queue_log --daemon"

Normally, you do not need to change anything in there, unless you decide to use a different mysql user or password.


Starting the service

In Centos/RedHat based systems you can do it with the command:

service asterniclog start

In Debian or Ubuntu the correct command is:

/etc/init.d/asterniclog start

Stopping the service

In Centos/RedHat based systems you can do it with the command:

service asterniclog stop

In Debian or Ubuntu the correct command is:

/etc/init.d/asterniclog stop

Activating the License

In order to run reports, you need a valid activation code to get your license, either a trial or purchased one. Once you have your code at hand, use your browser and go to:

http://your.web.server/stats

You should be prompted for both the activation code, and a registration name. The registration name can be chosen by you and it could be your company name, customer name, etc. A legend will appear in the reports footer saying "Licensed to XXXXX" where XXXXX is the registation name you used at time of activation. That name cannot be changed in the future, so please chose wisely.

Afer entering both the activation code and registration name, click the button to acquire a license file. That's it! After a short while, you will be presented with the login form. The default user/pass to access the system is: admin/admin . You can change the password once logged by selecting the Setup/Users menu inside Asternic GUI.

Continue reading the Administrator Guide in order to configure or set preferences for your reports.


Recordings and FreePBX

If you use FreePBX, you will find a freepbx patch and a custom dialplan in the FreePBX directory.

There are different patches depending on your FreePBX version:

  • For version 2.8 or older: fpbxmonitor.diff
  • For version 2.9: fpbxmonitor29.diff
  • For version 2.10: fpbxmonitor210.diff
  • For version 2.11: no need to patch. You need to configure FreePBX manually

You will need to apply that patch to FreePBX in order to have the queue recordings integrated in the reports. You can do so with the following commands (change the path to the directory where you extracted the tarball):

For version 2.8:

cd /var/www/html/admin/modules/queues
patch < /usr/src/asternic-stats-pro-2.0.8/FreePBX/fpbxmonitor.diff

For version 2.9:

cd /var/www/html/admin/modules/queues
patch < /usr/src/asternic-stats-pro-2.0.8/FreePBX/fpbxmonitor29.diff

For version 2.10:

cd /var/www/html/admin/modules/core
patch < /usr/src/asternic-stats-pro-2.0.8/fpbxmonitor210.diff

For version 2.11:

You will need to open SETTINGS - Advanced Settings and under the option DEVELOPER AND CUSTOMIZATION you need to set the field POST CALL RECORDING SCRIPT to:

/usr/local/parselog/update_mix_mixmonitor.pl ^{UNIQUEID} ^{MIXMONITOR_FILENAME}

If you do not find that option, you will have to enable showing and allow modificaitons of read only settings at the top of the Advanced Settings page inside FreePBX, by turning on the following options at the top of the advanced settings page:

  • Display Readonly Settings
  • Override Readonly Settings

With those options enabled, you shoul see the Post Call Recording Script option in the Developer and Customizations section.


Outbound Call Tracking and FreePBX

Asternic CCStats will report queue based activity. That means that only inbound calls that go into queues will be reported. However, there is a method to track outbound calls by using a custom dialplan to track outbound trunk calls under FreePBX.

The included dialplan will only track calls for extensions that have an account code set inside FreePBX preferences

NOTE

If you use the pinset module, or any other module that uses account codes, it will conflict with the included outbound track dialplan. However, it is possible to customize the dialplan a little bit to not use account codes but track all calls and using a unique name for the outbound queue like 'Outbound'

The dialplan file is located in /usr/src/asternic-stats-pro-2.0.8/FreePBX/extensions_custom_asternic_outbound_freepbx.conf

You have to copy it over to your /etc/asterisk directory with the command:

cp /usr/src/asternic-stats-pro-2.0.8/FreePBX/extensions_custom_asternic_outbound_freepbx.conf /etc/asterisk

Then you have to include that dialplan into Asterisk. For doing so, you will have to use your favorite text editor to modify the /etc/asterisk/extensions_custom.conf file and add at the end of it:

#include extensions_custom_asternic_outbound_freepbx.conf

Finally restart your asterisk dialplan:

asterisk -rx "dialplan reload"

Once that is done, the only thing left to do is edit an extension inside FreePBX, and set an account code for it. The account code you use will be used as a fake queue name in queue_log. You should use the same account code on the extensions you want to track outbound calling so their calls will be grouped under the same queue. We recommend to use a name like "Outbound" or similar.

NOTE

Do not use the same name for outbound calls than you have for inbound queues, as any outbound call that fails will be logged as an ABANDON, and will impact the inbound metrics in a bad way

Also, this context has the limitation of not following failover trunks. If your configuration depends on failover trunks, do not use this macro for tracking outbound calls, but use instead this one: extensions_custom_asternic_outbound_freepbx_failover.conf

To test, perform outbound calls with any of the extensions with an account code set, after a short while, you will see a new Queue appear as available in the Asternic Reports, that will include those calls. Refer to the Administrator Guide in order to see how to separate Distribution reports based in call flow/direction to separate reports for inbound and outbound calls further.


Uninstalling the Software

In case you want to remove all related files and services, asuming you installed via the make install command, follow these steps:

Stop the service script:

service asterniclog stop

Remove /var/www/html/stats and /usr/local/parselog:

rm -rf /var/www/html/stats
rm -rf /usr/local/parselog

Remove the service script:

chkconfig --del asterniclog
rm /etc/rc.d/init.d/asterniclog
rm /etc/sysconfig/asterniclog

Remove the database:

mysqladmin -u root -p drop qstats

And that's it.