asternic logo CCStats PRO Installation

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 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.2.2.tgz

Installation

Once the download finishes, extract the package:

tar zxvf asternic-stats-pro-2.2.2.tgz

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

cd asternic-stats-pro-2.2.2

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

Upgrade from a previous 2.x version

Upgrading is similar to a new installation. Once the download finishes, extract the package:

tar zxvf asternic-stats-pro-2.2.2.tgz

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

cd asternic-stats-pro-2.2.2

And finally peform the upgrade:

make upgrade

Note If you want to upgrade from older vdersions (1.x), you cannot perform an upgrade in this way. You will have to generate a queue_log file based on your existing data, and then install as new, using a new and empty database.

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.

Asterisk queue_log file

Asternic reads and parses queue log activity data that is registered in the queue_log file by Asterisk. In most setups and Asterisk distros, that log file is enabled by default.

However, there are some distros, like MiRTA or SNEP, that might have that log to file disabled as they use another way to store data in real time using a database.

In those cases, you will have to edit the Asterisk logger configuration to enable it. Look at the file /etc/asterisk/logger.conf and under the [general] section be sure to have both of these lines:

queue_log=yes
queue_log_to_file=yes

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

In order to have recordings available in Asternic reports, we provide a custom script that will run as soon as a queue recording is finished. The script will udpate the Asternic recordings table and will also move the recording to a new directory with optional convertion to MP3.

The script is located in /usr/local/parselog/update_mix_mixmonitor.pl

FreePBX 2.11 or higher

FreePBX must be instructed to run the post recording script.

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}

NOTE

If you do not find the POST CALL RECORDING SCRIPT 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.

Older FreePBX versions

For older FreePBX versions, you must patch it. 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

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.2.2/FreePBX/fpbxmonitor.diff

For version 2.9:

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

For version 2.10:

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

After the patch is applied, you must go to the FreePBX GUI and Apply Changes. That will modify the appropiate parts of the dialplan so the post call recording script is executed after a queue call recording finishes. To verify if the patch applied correctly, after applying changes in FreePBX you can run this command:

grep update_mix_mixmonitor /etc/asterisk/extensions_additional.conf

It should show some matches. If it returns empty, then the patch was not set correctly.

NOTE

If you update the queue module in FreePBX, the patch will be lost, and recordings will cease to work. Whenever you update FreePBX queue module, you will need to re apply the proper patch.

Configuring the post recording script

If you installed the software using make install then you do not need to modify anything in it. You can skip this step.

If you installed copying files by hand, be sure that the script has execute permissions (mode 755). If in doubt, change it with the command:

chmod 755 /usr/local/parselog/update_mix_mixmonitor.pl

Also you have to be sure that the MySQL credentials inside the script are set correctly and match your configuration. Again, this is done automatically in a default install, only modify in case of a manual install/config. 

# CONFIGURATION
# You have to set the proper database credentials
$config{'dbhost'} = 'localhost';
$config{'dbname'} = 'qstats';
$config{'dbuser'} = 'qstatsUser';
$config{'dbpass'} = 'qstatsPassw0rd';

# Destination directory for recordings
$config{'asterisk_spool'}  = "/var/spool/asterisk/monitor";
$config{'destination_dir'} = "/var/spool/asterisk/asternic";

# If you want "wav" recordings to be converted to .mp3 
# It requires the lame tool to be installed.
$config{'convertmp3'} = false;

As you can see, not only you can set the MySQL credentials, but also you have the option to enable MP3 convertion. By default it is disabled, you can set convertmp3 to true to convert recordings to mp3 format. For that to work be sure that lame is installed. Also be sure that in your queue configuration the recording format is set to wav (not WAV, nor wav49 nor gsm), as the lame convertion tools only handles the wav format correctly.

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 enable outbound call tracking by using a custom dialplan that intercepts outbound trunks calls under FreePBX and updates the queue_log file with their activity.

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.2.2/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.2.2/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.