REQUIREMENTS
------------

Minimum software versions:

PHP version 5.1 or higher
MYSQL version 5.0 or higher

INSTALLING
----------

To download and install the software just run this 5 commands:

#> cd /usr/src
#> wget download.asternic.net/asternic-stats-pro-2.2.5.tgz
#> tar zxvf asternic-stast-pro-2.2.5.tgz
#> cd asternic-stats-pro-2.2.5
#> make


RECOMMENDED AND OPTIONAL MODULE
-------------------------------

On big systems, you might want to install the php-apc cache module:

yum install php-pecl-apcu


ACTIVATING THE PRO LICENSE
--------------------------

After the installation, you need to activate the software. The license
is tied to the MAC address of your server network interface. You will 
also need internet access from the server in order to activate the copy.

If you do not have internet connection, contact us to do an offline
activation.

Once you load the web page for the first time, it will prompt you for
the activation code (You have received that code via email), and a Licensee
Name. The Licensee Name can be anything you want, it will be displayed on 
the footer of every report.

Once you enter both fields, you can press the "Generate Request" button.
When you do that it will contact our registration servers, validate your
code, send the license request and retrieve the final license. If all goes
well, you will be prompted with a login box. The default admin user is "admin"
with password "admin".

If you get an error, you will have to contact us. If your server crashes or if
you need to move licenses around, you will also have to contact us. 

The license is stored in the asterniclic.php file on the same directory as 
the reports themselves. Be sure to back the directory up just in case.

PARSING LOGS
------------

Requirements: perl, perl-Time-HiRes

In /parselog there is a script: ./asterniclog

It accepts several parameters:

       -u <name>     - Connect to mysql as username <name> [root]
       -p <pw>       - Connect to mysql with password <pw>
       -h <host>     - Connect to mysql host <host> [localhost]
       -d <dbname>   - Connect to mysql database <dbname> [qstats]
       -l <queuelog> - Path and name for queue_log [/var/log/asterisk/queue_log]
       -c            - Convert Local/xxx@from-queue/n to agent name in FreePBX
       -r            - Reparse the full log with no date check
       -s            - Skip events with SIP/IAX in queue member
       --daemon      - Daemonize process and detach from console
       -w            - Write configuration to disk
       --purge       - Purge all data from tables


You can run it manually as a background job, it will read events in 
realtime from the queue_log file and feed it into mysql. There is no 
need for cron jobs. You can start it from rc.local. Eg:

/usr/local/parselog/asterniclog -u qstatsUser -p password -d qstats -l /var/log/asterisk/queue_log -c --daemon

There is an init script provided that you can use to start/stop asterniclog as
a service inside the init directory.  The simple way to install the init script is to 
run:

make initscripts

Then you will be able to configure options in /etc/sysconfig/asterniclog file or /etc/default/asterniclog
and manage the service with commands like:

service asterniclog start|stop|restart



RECORDINGS
----------

In parselog there is a script to convert and organize queues recordings.
You have to configure the DB access details and recording directory at the top
of the file. It uses some tools that might not be installed in your
linux distro (sox, lame), so you might need to tweak it a little bit. You 
also need to add some tidbits in the dialplan before launching the Queue 
command, like:

extensions.conf

exten => s,1,Answer
exten => s,n,Set(__MONITOR_FILENAME=/var/spool/asterisk/monitor/q${EXTEN}-${STRFTIME(${EPOCH},,%Y%m%d-%H%M%S)}-${UNIQUEID})
exten => s,n,Set(__MONITOR_EXEC=/usr/local/parselog/update_mix_mixmonitor.pl ^{UNIQUEID} ^{MIXMONITOR_FILENAME})
exten => s,n,Queue(myqueue)

This will instruct asterisk to call the script with some parameters
after a call is recorded. The script task is to update the mysql tables
to relate filenames with call ids, and optionally convert them to mp3. 
(for mp3 convertion to work, recording format must be set to wav and
lame must be installed)

You queue configuration should be set to record calls and use mixmonitor for it:

queues.conf

[myqueue]
eventmemberstatus=no
eventwhencalled=yes
monitor-type=mixmonitor
monitor-format=wav
..


You will have to modify the following script:

/usr/local/parselog/update_mix_mixmonitor.pl

Be sure to update the script and tweak it to your needs. Basically, be sure
to set the correct MySQL credentials:

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

and change the following parameters if needed:

$config{'asterisk_spool'} = "/var/spool/asterisk/monitor";
$config{'destination_dir'} = "/var/spool/asterisk/asternic";

The later is the directory where you want to store recordings. The script
will archive recordings in subdirectories using the YYYYMMDD scheme, inside it.

Also, you must configure the recordings_path via Setup/Preferences in 
the Asternic GUI. You should set its value to the same directory that 
is set as destination_dir in the update_mix_mixmonitor.pl script, by 
default is set to /var/spool/asterisk/asternic

Finally, be sure that the above directory and all its contents are 
readable by the same user that your web server runs as. Otherwise, you
won't be able to retrieve or listen to the files from your web browser.


RECORDINGS AND FreePBX
----------------------

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

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

For version 2.9:

cd /var/www/html/admin/modules/queues
patch < /path/to/FreePBX/fpbxmonitor29.diff

For version 2.10:

cd /var/www/html/admin/modules/core
patch < /path/to/FreePBX/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 see that option, you will need to enable the options to
allow modification of read only settings at the top of Advanced Settings.

After the patch is applied or the configuration is made, you will have 
to make a change on FreePBX web UI and apply changes so the dialplan 
is regenerated. The above patch will call the following script:

/usr/local/parselog/update_mix_mixmonitor.pl

Be sure to update the script and tweak it to your needs. Basically, be sure
to set the correct MySQL credentials:

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

and change the following parameters if needed:

$config{'asterisk_spool'} = "/var/spool/asterisk/monitor";
$config{'destination_dir'} = "/var/spool/asterisk/asternic";

The later is the directory where you want to store mp3 recordings. The script
will archive recordings in subdirectories using the YYYYMMDD scheme, inside it.
You will have to create that directory if it does not exists, and you must be
sure the owner of the directory is the "asterisk" user. (If you do not run
your web server as the 'asterisk' user, set ownwership to whatever user your
web server runs as).

You can also convert scripts to mp3 within the script, in that case be sure you
have:

$config{'convertmp3'} = true;

mp3 convertion requires the utility "lame" to be installed in /usr/bin. If you do
not have the utility or if its installed in some other directory, modify the
script accordingly. Also, be sure the recording format in FreePBX queue config
is set to "wav" (not wav49 or gsm or any other format).

You can also set convertmp3 to false and the original recording format as set in
FreePBX queue config will be preserved. Asternic 2.0 supports audio streaming for
.wav and .gsm files.


OUTBOUND CALL TRACKING AND FreePBX
----------------------------------

The other file in the FreePBX directory is a dialplan to use with asterisk
to track outbound calls. The included one will only track calls if you set
the account code to something before performing the dial (it could be added
to the extension configuration for example). The filename is:

extensions_custom_asternic_outbound_freepbx.conf

You have to include that file from your dialplan, you can do so by adding
"#include extensions_custom_asternic_outbound_freepbx.conf" at the end
of /etc/asterisk/extensions_custom.conf


OUTBOUND CALL TRACKING (no FreePBX)
-----------------------------------

In the docs directory you have the README.outbound with a sample dialplan.
You will need to tweak it heavily in order to suit your needs. The example
uses a 3 digit prefix and fixed trunk.

MAINTENANCE
-----------

If you want to clear/purge the tables run tailqueuelog with
the purge parameter:

./tailqueuelog -u root --purge

Attention! It will remove all queue activity from the logs so you
can start afresh.


ACCESING STATS
--------------

Point your browser to the new url. There are two default users:

admin, password admin
user, password user

You should login as admin first and set user permissions.

IMPORTANT!!!! ******************************************************
 You should go to USER ACCESS tab and at least select ALL QUEUES 
 and ALL AGENTS for the admin user. After you have some data in the
 tables you can refine the user access as you wish. But the default
 install DOES NOT permit viewing ANY queues or agents, so you will
 be stuck in the HOME page until you set them up.
********************************************************************

Agent and Queue data are not displayed until you start populating mysql
with the parselog scripts.  


UPDATING THE queue_stats TABLE FROM ASTERNIC 1.6 OR PREVIOUS 
------------------------------------------------------------

Transfers now are logged with a forth parameter in queue_log, you have to
alter the queue_stats table and then update records in order to store
information correctly:

ALTER TABLE queue_stats ADD info4 varchar(40) default '';

UPDATE queue_stats SET info4=substring_index(info3,'|',-1),info3=substring_index(info3,'|',1) WHERE info3 like '%|%';


UPDATING THE users TABLE FOR ASTERNIC 1.9 AND ENCRYPTED PASSWORDS
-----------------------------------------------------------------

ALTER TABLE users CHANGE password password varchar(100);

UPDATE users SET password=sha1(password);


UPDATING THE queue_stats TABLE FROM ASTERNIC TO VERSION 1.9.2
-------------------------------------------------------------

ALTER TABLE queue_stats ADD info5 varchar(40) default '';

UPDATE queue_stats SET info5=substring_index(info4,'|',-1),info4=substring_index(info4,'|',1) WHERE info4 like '%|%';


UPDATING THE queue_stats TABLE FROM ASTERNIC TO VERSION 1.9.3
-------------------------------------------------------------

ALTER TABLE setup CHANGE value value varchar(255);





UPGRADE TO 2.0
--------------

CREATE TABLE IF NOT EXISTS `userqname` (
  `users_id` int(6) default NULL,
  `qname_queue_id` int(6) default NULL
) DEFAULT CHARSET=utf8;

CREATE TABLE IF NOT EXISTS `userqagent` (
  `users_id` int(6) default NULL,
  `qagent_agent_id` int(6) default NULL
) DEFAULT CHARSET=utf8;

CREATE TABLE IF NOT EXISTS `sqlrealtime` (
  `id` int(6) NOT NULL,
  `lastupdate` timestamp NOT NULL default CURRENT_TIMESTAMP on update CURRENT_TIMESTAMP,
  `data` longtext,
  PRIMARY KEY  (`id`)
) DEFAULT CHARSET=utf8;

CREATE TABLE IF NOT EXISTS `designer` (
  `id` int(11) NOT NULL auto_increment,
  `keyword` varchar(50) default NULL,
  `parameter` varchar(50) default NULL,
  `value` varchar(255) default NULL,
  PRIMARY KEY  (`id`),
  UNIQUE KEY `keypar` (`keyword`,`parameter`)
) AUTO_INCREMENT=1 DEFAULT CHARSET=utf8;

CREATE TABLE IF NOT EXISTS `language` (
  `id` int(6) NOT NULL auto_increment,
  `iso_code` varchar(5) NOT NULL default 'en',
  `string` text,
  `translation` text character set utf8 collate utf8_bin,
  `pending` tinyint(1) default '1',
  PRIMARY KEY  (`id`),
  KEY `stindex` (`string`(200)),
  KEY `idx` (`iso_code`,`string`(200))
) AUTO_INCREMENT=1 DEFAULT CHARSET=utf8;

CREATE TABLE IF NOT EXISTS `sched` (
  `schid` int(6) NOT NULL auto_increment,
  `destinos` text,
  `reportes` text,
  `ultimos` tinyint(4) default NULL,
  `campo` varchar(40) default '',
  `valor` varchar(40) default '',
  `crondiames` varchar(40) default '*',
  `crondiasem` varchar(40) default '*',
  `cronhora` varchar(20) default '*',
  `cronminu` varchar(20) default '*',
  `lastrun` datetime default '0000-00-00 00:00:00',
  `activo` tinyint(4) default '1',
  PRIMARY KEY  (`schid`)
) AUTO_INCREMENT=1 DEFAULT CHARSET=utf8;

REPLACE INTO qagent VALUES (-1,'ALL');

REPLACE INTO qname  VALUES (-1,'ALL');

INSERT INTO userqagent SELECT users.id,agent_id FROM user_filter INNER JOIN users ON user_filter.user=users.login INNER JOIN qagent ON qagent.agent=value WHERE param='agent';

INSERT INTO userqname SELECT users.id,queue_id FROM user_filter INNER JOIN users ON user_filter.user=users.login INNER JOIN qname ON qname.queue=value WHERE param='queue';

ALTER TABLE qname CHANGE qname_id queue_id int(6);

ALTER TABLE user_filter DROP id;

UPDATE setup SET keyword='avg_time_format' WHERE keyword='avg_duration_format';
UPDATE setup SET keyword='realtime_custom_pauses' WHERE keyword='custom_pauses';
UPDATE setup SET keyword='realtime_group_queues' WHERE keyword='group_queues';
UPDATE setup SET keyword='realtime_spy_device' WHERE keyword='spychannel';
UPDATE setup SET keyword='short_abandon_threshold' WHERE keyword='minimum_abandon_duration';
UPDATE setup SET keyword=concat('realtime_',keyword) WHERE keyword like 'alarm_%';

// Find out if queue_stats unico index has the uniqueid set or not
SHOW INDEX FROM queue_stats WHERE Key_name='unico' AND Column_name='uniqueid';
ALTER TABLE queue_stats DROP INDEX unico;
ALTER TABLE queue_stats ADD unique unico (`queue_stats_id`,`uniqueid`,`qagent`,`qevent`,`qname`);

Import data from sql/lang.sql


UPGRADE TO 2.0.6

ALTER TABLE sched add queues varchar(200) default NULL;


How to Import queue Names for FreePBX in one query:
---------------------------------------------------

insert into setup (keyword,parameter,value) select 'dict_queue',extension,descr from asterisk.queues_config;
