Asterisell

asterisell-testing-0.9.8 release

Sun, 29 Jun 2008 00:00:00 +00:00

Fixed a bug about rates displaying.

If you update remember to execute ”./symfony cc” inside Asterisell root directory.

Unsupported Project

Sun, 15 Jun 2008 00:00:00 +00:00

Sorry, I have no more time to support this project.

If there is someone interested to become the new maintainer I can help him.

asterisell-testing-0.9.7 release

Mon, 11 Feb 2008 00:00:00 +00:00

fixed a bug about user viewable CDRs;
account code is now 30 chars for both CDR table and AR_ASTERISK_ACCOUNT table;

“user_viewable_cdr” was removed from “apps/asterisell/config/app.yml”. Now Asterisell displays all (only) the “billable_cdr” calls.

If you update remember to execute ”./symfony cc” inside Asterisell root directory.

asterisell-testing-0.9.6 release

Wed, 06 Feb 2008 00:00:00 +00:00

configuration files are not overwritten during upgrade;
added a “rate per minute” method;

asterisell-testing-0.9.5 release

Wed, 12 Dec 2007 00:00:00 +00:00

fixed another bug about invoice generation with total less than 1.00;

asterisell-testing-0.9.3 release

Thu, 28 Jun 2007 00:00:00 +00:00

Fixed:

upgraded from “symfony 1.0.4” to “symfony 1.0.5” framework;
many improvements to the online help;
invoices are now generated using customers locale;

Asterisell forum

Tue, 26 Jun 2007 00:00:00 +00:00

Now there is a forum about Asterisell configuration and usage.

asterisell-0.9.2-testing release

Wed, 20 Jun 2007 00:00:00 +00:00

Fixed:

upgrade to “symfony 1.0.4” framework;
null telephone operators prefixes;
online help;
home page improvements;

asterisell-0.9.1-testing release

Sat, 09 Jun 2007 00:00:00 +00:00

Fixed:

rating of calls on different Asterisk destination channels;
download of CSV and Excel files using Internet Explorer;
upgrade to “symfony 1.0.3” framework;

Development

Fri, 01 Jun 2007 00:00:00 +00:00

Symfony Framework

Asterisell uses the Symfony PHP framework wich is a well documented and designed framework.

Installation

Asterisell distribution contanins a “snapshot” of the Symfony framework.

If you want to use the most recent version of Symfony framework you can install it through the PEAR PHP Extension and Application Repository

pear channel-discover pear.symfony-project.com
pear install symfony/symfony

In order to upgrade to new versions of symfony:

pear upgrade symfony/symfony

Do not forget to clear the Asterisell cache executing in the Asterisell directory:

symfony cc

Patch Application

Up to date a patched version of Symfony 1.0.5 is used, so you must apply the patch inside the directory “symfony-patch”.

Consult the README file for details on how to apply the patch.

Asterisell Development Version Usage

If you run Asterisell in production mode every time you change some code you must rexecute the command

symfony cc

because the page generation result is cached for performance reasons.

If you run Asterisell in development mode all the pages are regenerated every time.

In order to enable the development mode execute

symfony enable asterisell dev

If Asterisell project is in the ”/var/www/asterisell” directory and your local apache server is listening on port 3000, then you must open the web page:

http://localhost:3000/asterisell/web/asterisell_dev.php/login

Asterisell Localization

If you want to support a new language / culture you must:

add to “apps/asterisell/config/app.yml” the new currency and culture;
copy “apps/asterisell/i18n/messages.it.xml” to “apps/asterisell/i18n/messages.your_culture_code.xml”;
replace all Italian translations with your locale translations;
update “apps/asterisell/lib/standardMailWithInvoiceGenerator.class.php” with the new culture support;
execute ”./symfony cc” in order to clear the cache and view the new messages;
make a login in Asterisell web interface using a web account with the new culture in order to inspect the result;

Installation and Configuration

Thu, 01 Feb 2007 00:00:00 +00:00

Software Infrastructure

VoIP calls are managed from Asterisk Server:

it routes the calls to the proper dial peer;
it associates to every customer a unique “accountcode”;
it writes Call Detail Records (CDRs) on a specific MySQL database table shared with Asterisell.

Asterisell is a PHP5 web application that:

reads calls information from the CDR table shared with Asterisk Server;
associate to every call a cost (what the service provider pays to other vendors for routing the customer’s call);
associate to every call an income (what the customer pays to the service provider);
displays calls info;

Asterisk Configuration

Account Code

An “accountcode” is the code of the user requesting the call. It is assigned from Asterisk server after the user validation.

There must be a unique “accountcode” for each different customer.

Note: the Asterisk standard documentation pretends that this code is specified on a per-channel basis, but this is not the case in Asterisell configuration. So each accountcode has the same associated customer for every channel. This is also useful/practical in case of the same customer using different channels.

Amaflags

amaflags stands for “Automated Message Accounting flags”.

You must configure Asterisk to use certain “amaflags” in order to classify a call as documentation or to bill or to ignore etc..

As in the case of “accountcode” in theory every different channel can have its set of “amaflags”, but Asterisell supports only a unique set of flags that are assumed valid and with the same meaning for all channels.

Web Server

Installation

The typical installation requires:

Apache2 HTTP server
mod_php5
mod_ssl
MySQL database server

Asterisell use some PHP5 libraries. On Fedora for example you must install

yum install php
yum install php-bcmath
yum install php-xml

and then execute

/etc/init.d/httpd restart

Directory Configuration

Create the file “asterisell.conf” inside the directory:

”/etc/httpd/conf.d/” or
”/etc/apache2/conf.d/”

The content is something like:

Alias /your-asterisell-web-name /your-asterisell-installation-directory/web/

<Location /your-asterisell-web-name>
  Order allow,deny
  Allow from all 

  # If you have mod_ssl installed 
  # then with these lines you can force the usage of https connections
  # for all Asterisell access.
  # If you omit them the passwords are sent in plain text and
  # they can be intercepted from hackers...
  #
  AllowOverride All
  <IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
  </IfModule>

</Location>

Restart the apache2 httpd server in order to render active the configurations using a command like:

/etc/init.d/httpd restart

/etc/init.d/apache2 restart

If it is all correct then “http://your-host/your-asterisell-web-name” will display the login form.

Asterisell Configuration

Rename

  apps/asterisell/config/_app.yml

  apps/asterisell/config/app.yml

and then inspect / change its content.

Important

After any change of configuration files or PHP code execute

  ./symfony cc

in order to clear the Asterisell execution cache.

IMPORTANT: in YAML files use only spaces and not tabs because they are not allowed!

Customizations

“web/css/asterisell.css” contains the Cascading Style Sheets;
“apps/asterisell/templates/asterisell_layout.php” contains the html page template;
“web/images/” contains the available images;
“config/properties.ini” contains the project/web-site name;

Source Code

It is normally not needed but you can customize low level Asterisell behavior modifying its source code or Symfony PHP Framework related configuration files.

Database Installation

Up to date Asterisell is tested only with MySQL DBMS, but the Symfony framework support many other popular open source DBMS.

Database Creation

  mysqladmin -u your-root-user-name -p create your-asterisell-db-name

Access

Rename

config/_databases.yml

config/databases.yml

and adapt it to yours needs:

 all:
 propel:
   class:        sfPropelDatabase
   param:
     phptype:    mysql
     host:       your-mysql-server-host--typically-localhost
     database:   your-asterisell-db-name
     username:   your-root-user-name
     password:   your-root-password
     encoding:   utf8

with the correct

root-user-name and
asterisell-db-name

Rename

config/_propel.ini

config/propel.ini

and adapt it to something like:

propel.project             = asterisell
propel.database            = mysql
propel.database.createUrl  = mysql://localhost/
propel.database.url        = mysql://localhost/asterisell
propel.mysql.tableType = InnoDB

; directories
propel.output.dir              = /your-asterisell-install-dir

Schema Creation

From YAML to SQL

config/schema.yml

contains the asterisell database schema description. It is defined using the YAML syntax.

Typically you must not change this file, but in case remember to regenerate the SQL counterpart with:

  ./symfony propel-build-model
  ./symfony propel-build-sql

From SQL to Database

In order to create the Asterisell database:

  mysql -u your-root-user-name -p your-asterisell-db-name < data/sql/lib.model.schema.sql

WARNING: this command will delete all previous data inside the previous Asterisell tables / databases.

Add Asterisell Root User

  cd /your-asterisell-directory/batch
  php create_root your-password

These commands will create:

an admin user with login “root” and
password “your-password”

Insert Demo-Data

FIXME: due to incompatibility with the new version of the Symfony framework the current “demo-data” does not work. So skip this section. However you can use the root-user created in the previous section, but without any demo data…

WARNING: these commands will delete all previous data from the Asterisell database. So do not execute if you have important data on the database.

If you want to populate the database with some demo data then execute:

  cd /your-asterisell-directory/batch
  php insert_demo_data.php

In this case the default admin user is “root” with password “root”.

Asterisk Database-Related Configuration

Asterisell reads info from the your-asterisell-database-name.CDR table (Call Details Records table). So you must configure Asterisk server to write calls info inside this table.

Mail Configuration

Asterisell can send mails to the administrator or to the customers with invoice information. It uses the PHP mail function. In order to enable it you must follow the notes on PHP documentation site .

Cron Job

Calls Rating

Asterisell rates the calls:

“just-in-time” when users navigate in the reports and
“off-line” using a cron-job process.

The cron job process is important because it tests also if there is a Customer who does not respect his cost limits.

In case of errors the process sends an email to the administrator as configured in the “apps/asterisell/config/app.yml” configuration file.

The process must be executed from the same user that is associated to http connection. On Fedora it is “apache”, on Debian “www-data”. In order to retrieve it you can execute

ls -l /your-asterisell-dir/log/

Supposing the http user is “apache” you can associate to it a cron job using the command

crontab -u apache -e

Add to the apache user crontab this line:

5,20,35,45 * * * * sh -c "cd /your-asterisell-dir/batch/ ; php rate_all_and_test.php"

The meaning of the line is to execute at minutes 5, 20, 35 and 45 of every hour the “php rate_all_and_test.php” command inside the Asterisell directory.

NOTE: in order to enter the above line using “vi” editor digit:

:i
5,20,35,45 * * * * sh -c "cd /your-asterisell-dir/batch/ ; php rate_all_and_test.php" 
"press ctrl-c" 
:wq

Log Rotate

In order to reduce log file size put “asterisell-logrotate” with execution privileges in ”/etc/cron.monthly” directory:

#!/bin/sh

cd /your-asterisell-install-dir
./symfony log-rotate asterisell prod

VoIP Accounts

You must define an “Asterisk VoIP Account” using Asterisell Web-Interface for each corresponding Asterisell “accountcode”.

WARNING: If there is an “accountcode” not registered as “Asterisk VoIP Account” then (for current technical limitation) it will not registered on the CDR table.

Other Configurations

Every call is associated to a VoIP account. Every VoIP account is associated to a Customer who is the responsible for the account. The Customer is who pays the calls cost. A Customer can have more than one VoIP account.

Every customer or VoIP account can have a Web Access Account. It is a login and a password. If you connect as VoIP account you can inspect only the calls made from you. If you connect as a Customer you can inspect all the calls of your VoIP accounts. If you connect as Admin you can inspect all the calls.

Customer Categories (normal, discounted, etc..)
Dial Peer Telephone Operators
Telephone Operators Prefixes Numbers
Vendors
Rate Methods
Currency Conversions
Customers
VoIP accounts
Web Access Accounts

A rate can be applied to a customer category. In this case it specifies an income from a specific class of Customer. Otherwise it can be applied from a “Vendor”. In this case it specifies a cost due to a specific vendor.

Troubleshooting

Directory Permissions

Often there are problems related files and directories permissions. In this case run

  ./symfony fix-perms

Log File Permission

Often there are problems related to the Asterisell log files inside log directory.

If this file was created from root then the “apache” user is not able to add info to it and the entire Asterisell application is blocked. In this case change the permissions of file with something like:

  cd log
  chmod a+rw asterisell_prod.log
  chmod a+rw asterisell_dev.log

or better change the owner in something like

  cd log
  chown apache asterisell_prod.log
  chown apache asterisell_dev.log

Try also to restart the web server.

Additional Run-Time Debug Info

In case of problems you can enable the development/debug version of Asterisell that shows useful informations about its execution and related problems.

Execute:

  ./symfony enable asterisell dev

and open the url

http://your-web-url/asterisell_dev.php/login

When finished remember to execute

  ./symfony disable asterisell dev

NOTE: on the contrary of Asterisell production version, in the development version if you change Asterisell source code or a configuration file you must not execute ”./symfony cc”, because the development version recreate all files every time in order to speed up development at the expense of run-time executions.

Potential Loss of Data

You must define an “Asterisk VoIP Account” using Asterisell Web-Interface for each corresponding Asterisell “accountcode”.

If there is an “accountcode” not registered as “Asterisk VoIP Account” then (for current technical limitation) it will not registered on the CDR table.

Reasons

CDR table has the field “accountcode” that is defined as foreign key of the Asterisell.ar_asterisk_account table.

Symfony generates the schema and it imposes through a database constraint the presence of a corresponding accountcode for each cdr record added.

If there is no accountcode then the MySQL database signals a referential integrity error and it does not permit the insertion of the Call.

So the “nasty effects” is that the CDR table does not contain a potentially billable record.

This type of errors are showed only in the Asterisk server log error messages.

Run Time Configuration Problems

Every problem encountered from Asterisell during the call rating process is clearly reported to the administrator with hints of how to resolve it.

The presence of problems is signaled also via email to the administrator.

In case of dubious configurations Asterisell advise the administrator and suspend the rate of affected calls.

The rate process is rather robust and error-free regarding ill defined configurations because:

re-rating of calls is always possible;
problems are always signaled;

Security

The end user interacts only with the “Call Report” form. The content of user input fields is checked by a very conservative function that removes every non proper character.

No particular care is put on other forms because they are accessible only from the administrator.

User session handling is managed directly from Symfony and PHP engine.

Upgrade

All files except “apps/asterisell/config/app.yml”, “config/databases.yml”, “config/propel.ini” will be overwritten with the new version. So create a backup of them before upgrade Asterisell.

Discard the Symfony cache executing

./symfony cc

inside Asterisell root directory.

License

Thu, 01 Feb 2007 00:00:00 +00:00

Asterisell

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (see gpl.txt); if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Asterisell uses the symfony framework that uses different projects with different licenses (compatible with GPL) listed in the directory licenses.

Requirements

Thu, 01 Feb 2007 00:00:00 +00:00

HTTP WEB Server
PHP 5.0 or greater (PHP 4.0 is not supported)
MySQL DBMS
Asterisk VoIP server

Screenshots

Thu, 01 Feb 2007 00:00:00 +00:00

Customer Calls Report

Administrator Calls Report

Rates

Customer Invoice

Bulk Invoice Creation

Problem Notification

Current Status

Tue, 02 Jan 2007 00:00:00 +00:00

Up to date Asterisell is in beta phase. It is under test in a production environment.

Known Bugs:

multicurrencies support is incomplete / buggy;
English localization must be improved because I am not a native English speaker;
insert-demo-data is not compatible with the new version of Symfony framework;

Overview

Mon, 01 Jan 2007 00:00:00 +00:00

Usage Scenario

you are a vendor of Voice over IP Telephony services (VoIP)
your customers call other users who can reside on different telephone networks
your customers pay you for this service
in order to route the calls on particular networks you have to use the services of other vendors
you are a customer of others vendors
you pays others vendors for this service

So each call has a cost and an income because Asterisell views you (the VoIP service provider) as a reseller of others vendors services.

The income is what your customer pays to you and the cost is what you pays to other vendors in order to route the customer call.

Asterisell

Asterisell is a PHP5 web application that reads calls information generated from Asterisk VoIP server.

It is responsible for the rate process of calls. Up to date it can not manage the routing of calls.

It permits to associate for every call a cost and an income. The cost is what the customer pays to the service provider and the cost is what the service provider pays to other vendors in order to route the call.

Offered Services

From the customer point of view, Asterisell is a web interface where he can inspect calls with associated costs.

From the vendor point of view, Asterisell is a web interface where he can can manage prices lists for customers and rates for other vendors using different currencies and timezones. Then he can inspect calls with associated incomes from customers and expenses due to other vendors.

From a developer point of view, Asterisell is a PHP application that use the symfony framework. It reads Call Detail Records from a CDR table where Asterisk write info for every call.

The use of an object-oriented design permits to extend the software adding new features.

The use of simple YAML based configuration files permits to select at installation time what features to enable or disable, reducing the need for different and hard to maintain branches.

Features

Customer features:

report of calls with aggregate totals
many filter-criteria
different sort-criteria
export to CSV and MS Excel document
many VoIP accounts associated with the same customer

Administrator features:

input fields are secure from intrusion attempts
each customer could have a cost limit for the last 30 days
informal currency conversion table for the test of cost limits
administrator is advised via email if a customer pass its cost limit
different cultures for each VoIP account or Customer
prices and messages are displayed in the specified culture
customers can be grouped into different price list categories
different rate methods applicable to different time periods, customer categories, destination gateway channels, destination telephone network etc..
customizable rate methods adding PHP Class respecting a specific interface
generation of customer invoices
delivery of emails with invoice details to customers
support bulk generation of invoices and emails to all customers with associated incomes
support for multi-currency invoices (not yet tested)
problems during rate process are reported and signaled via email to the administrator

General features:

multi-culture and locales support (it_IT, en_US, ecc..)
multi-currency support (not yet tested)

Limits

See Asterisell development section

Downloads

Mon, 01 Jan 2007 00:00:00 +00:00

Testing Release

asterisell-testing-0.9.8.tar.gz

For more info:

Old Releases

Open Funding

Mon, 01 Jan 2007 00:00:00 +00:00

Open Business Report

Asterisell Total expected net income is EUR 4000 (approximately USD 5130).

Current payments are:

Date	Contributor	Payment Method	Payment Id	Income	Expense
2008-02-04	VoiceNet Consulting Ltd	SWREG	E1325538	EUR 20.00	EUR 30.00 (development-time)
2007-07-09	http://www.tsnet.it/	Direct	Invoice 001	EUR 1020.00
2007-06-26	http://purpleoranges.com/	SWREG	E1202617	EUR 20.00

			Total	EUR 1060.00	EUR 30.00

How to Contribute

You can use the Asterisell SWREG Account:

or you can contact me (Massimo Zaniboni) and ask for information about direct Bank Wire Transfer. For large sum of money this is the preferred method because there are lower transaction fees. If requested in advance I can produce an invoice for the payment.

Philosophy

Asterisell adopts a Open Funding Business Model because:

every income is reported
every expense is reported
there is a fixed expected net income
every contributor can receive an income committing extensions/patches

Financial Contributor

If you have earned (or saved) money using Asterisell then consider to give back something.

Asterisell is released under a open source license so you own entirely the product and you are free to customize and improve it. So contributions are not a license cost but a way to pay for past Asterisell development.

Open Funding of source code Contributors

If you extend Asterisell then you can agree with me (Massimo Zaniboni) an expected net income. This income will be added to Asterisell total expected income and it will be sent to you when raised.

If you commit a patch you can agree with me (Massimo Zaniboni) an income. In this case the net income of the extension affected by the bug will be decreased according the cost of the patch.

Financial Contributions to other Open Source Projects

Incomes higher than the expected Asterisell net income will be redirect to other open source projects related to Asterisell like the Symfony framework, Asterisk VoIP server, PHP language etc..