OpenERP - Asterisk connector

IntroductionAsterisk is an OpenSource software for telephony. This software is often used to run IP PBX systems inside companies, combined with an IP phone for each employee and SIP trunks on xDSL or fiber links or traditionnal ISDN lines to access the public telephone network. Asterisk is available under the GNU General Public Licence and is edited by the American company Digium. If you want to know more about Asterisk, please read its Wikipedia page.

Description of the connectorThe OpenERP-Asterisk connector has three main features. First, it adds a dial button in the Partner view so that your users can directly dial a phone number through Asterisk. This feature is usually known as click2dial. Here is how it works :

1. In OpenERP, the user clicks on the dial button next to a phone number field in the Partner address view.

2. Asterisk makes the user's phone ring.

3. The user answers his own phone (if he doesn't, the process stops here).

4. Asterisk dials the phone number found in OpenERP in place of the user.

5. If the remote party answers, the user can talk to his correspondent.

The second main feature is : it adds the ability to show the name of the calling party on incoming phone calls if the presented phone number is present in the Partner addresses of OpenERP. Here is how it works :

1. On incoming phone calls, the Asterisk dialplan executes a script.

2. This script will make an XML-RPC request on the OpenERP server to try to find the name of the person corresponding to the phone number presented by the calling party.

3. If it finds the name, it is add as CallerID name to the call, so as to be presented on the IP phone of the user.

The third main feature is : the ability to get the partner corresponding to the calling party in one click. This feature is only available in the 6.1 branch. Here is how it works :

1. Someone calls you. Before or after taking the call, you click on the button 'Open calling partner' in OpenERP : OpenERP sends a query to the Asterisk Manager Interface to get a list of the current phone calls (ringing or on conversation).

2. If it finds a phone call involving the user's phone, it gets the phone number of the calling party

3. It searches the phone number of the calling party in the Partner addresses of OpenERP. If a record matches, it shows the name of the related Partner and proposes to open it, or open its related sale orders or invoices. If no record matches, it proposes to create a new contact with the presented phone number as 'Phone' or 'Mobile' number or update an existing contact.

The OpenERP-Asterisk connector also has additionnal CRM-specific feature packaged in a dedicated module.

Akretion service offeringDeploying the Asterisk-OpenERP connector require to have expertise on both OpenERP and Asterisk. As the ERP and IP PBX systems are two critical components for your company, you may prefer to delegate the installation and configuration of the connector to an experienced consultant.

Being the author of the Asterisk click2dial module, Akretion is the best option to find this expertise. Akretion proposes a service package for the Asterisk-OpenERP connector which includes :

if necessary, an update of the code of the asterisk_click2dial and asteriskclick2dialcrm modules to make it work on the version of OpenERP that you are using,

if necessary, an update of the code of the Asterisk-side scripts to make them work on the version of Asterisk that you are using,

the installation and configuration of the asterisk_click2dial and asteriskclick2dialcrm modules,

the update of the configuration of your existing Asterisk IPBX to make it work with the OpenERP-Asterisk connector,

the update of the configuration of your IP phones if you want to have a quiet click2dial (this functionnality may not be possible on all IP phones, but we know that it works fine at least on Aastra and Technicolor/Thomson IP phones),

a brieffing on the use of the module,

technical support via email and a bug-fix warranty during a period of 2 months starting from the date of installation of the module. This warranty is a bug-fix warranty on bugs that alter the behavior of the Asterisk-OpenERP connector as described in this document. This warranty requires a remote access to the OpenERP and Asterisk servers, or the customer should make available to Akretion a mean to reproduce the issue at Akretion's office.

This service package is proposed at a price of 500 EUR without taxes.

This service package doesn't include :

enhancement requests,

additionnal Asterisk setup and configuration that is not necessary to make the OpenERP-Asterisk connector work,

technical support and bug-fix warranty after the period of 2 months starting from the date of installation of the module,

technical support and bug-fix warranty on other OpenERP modules than the asterisk_click2dial and asteriskclick2dialcrm modules or other Asterisk-side scripts than those used by the OpenERP-Asterisk connector.

Installation of the modulesThe OpenERP-Asterisk connector is made of 2 modules :

asterisk_click2dial : this is the main module, that everybody should install. This module has been fully developped by Akretion.

asteriskclick2dialcrm : an additionnal module that you should install only if you are interested in the additionnal CRM-specific features. This module has initially been developped by the Spanish company Zikzakmedia and later enhanced by Akretion.

These modules should be installed on OpenERP just like any OpenERP module. The source code of the module is available on the dedicated project OpenERP-Asterisk connector on Launchpad :

for OpenERP v5/v6 (same code for these 2 versions of OpenERP) : https://code.launchpad.net/~openerp-asterisk-team/openerp-asterisk-connector/6.0

for OpenERP v6.1 : https://code.launchpad.net/~openerp-asterisk-team/openerp-asterisk-connector/6.1

The version of OpenERP 6.1 is currently the main focus of development ; some features are only available in this version.

These modules require two additional Python libraries : phonenumbers and py-Asterisk. To install the library phonenumbers, run :

% sudo pip install phonenumbers

The pip command is the successor of easy_install and is the official tool to install Python libraries. If you don't have this tool on your system, install the corresponding package (package python-pip on Debian/Ubuntu systems).

To install the library py-Asterisk, you can't use the pip install command because you need a very recent version which is not yet in Pypi. In fact, you need to have this commit which is dated November 20th, 2012. So you should get the source from the project py-asterisk on Google code :

% hg clone https://code.google.com/p/py-asterisk/ % cd py-asterisk % sudo python ./setup.py install

The hg command is part of the Mercurial version control system. If you don't have this tool on your system, install the corresponding package (package mercurial on Debian/Ubuntu systems).

Note : the module named asterisk in the extra-addons repository is not related to this connector. The asterisk_click2dial module doesn’t depend on it.

Setup the click2dial feature

Configuration of Asterisk

For the click2dial feature, OpenERP will communicate with Asterisk through the Asterisk Manager Interface (AMI).

So the first step is to configure AMI :

create a new AMI account for OpenERP

configure AMI to accept requests from OpenERP for click2dial.

The configuration file of AMI is /etc/asterisk/manager.conf (depending on your Linux distribution, the directory may be different). Here is a sample configuration file with my comments inline :

; manager.conf file for the Asterisk Manager Interface (AMI); It starts with the “general” section first[general]; You must enable the AMI featureenabled=yes; TCP Port on which AMI will listenport = 5038; I suppose Asterisk and OpenERP are on two different machines,; so you must bind AMI on 0.0.0.0bindaddr = 0.0.0.0; We don’t need to activate the HTTP AMI interface : the module uses the native interfacewebenabled = no

; Then, we create an AMI account for OpenERP[click2dial] ; This is the AMI loginsecret = mypassword ; This is the AMI password; We deny AMI access for everybodydeny = 0.0.0.0/0.0.0.0; We accept AMI access for OpenERP server (192.168.0.42)permit = 192.168.0.42/255.255.255.255; We give the minimum access rights required for the click2dial feature; For Asterisk 1.4.x, you need the “call” rights (for both click2dial and the 'open calling party' feature);read =;write = call; For Asterisk 1.6.x and 1.8.x, you need the “originate” rights (for click2dial); and the 'reporting' rights (for the 'open calling party' feature)read =write = originate,reporting

Warning : simply reloading Asterisk is not enough to activate the AMI ; you need to restart Asterisk (check that nobody is on the phone, because a restart of Asterisk will stop all ongoing phone calls).

Now check that you can access the AMI from the OpenERP server :

% telnet <asterisk_server_IP_address> 5038

It should display :

Connected to <asterisk_server_IP_address>.Escape character is '^]'.Asterisk Call Manager/1.1

Configure OpenERP

Log on as administrator on OpenERP.

Configure Asterisk server(s)

First, you must create one or several Asterisk servers. The click2dial module supports several Asterisk servers (for each OpenERP user, you will configure on which Asterisk server he is connected).

Go to the menu Administration > Companies > Companies (under OpenERP v5, the menu is Administration > Users > Company’s structure > Companies). Select the company in the list. Then, go to the IPBX tab. Create one or several Asterisk servers. All the fields have a detailed contextual help, so you should be able to understand how to set each parameter by reading the help.

Some parameters require additional explanations :

Alert-Info SIP header : you will find more explanations about it in the sections Quiet click2dial and Auto-answer on click2dial with Aastra IP phones below. You can leave it empty for now, it is not a problem.

the different prefixes : you will find more explanations about it in the section How phone numbers are reformated below.

Configure users

Go to the menu Administration > Users > Users. For each user that require the click2dial feature, you need to set some parameters that the asterisk_click2dial module has added in the Telephony tab :

Asterisk channel type : the channel type of the phone of the user (if the user has a regular IP phone, select SIP)

Resource name : this is the resource name for the channel type that you selected. If you channel type is SIP, the resource name is the name of the entity that you defined in /etc/asterisk/sip.conf. For example, if you have an entity defined with [alexis] in sip.conf, then the resource name is alexis (it also means that you use Dial(SIP/alexis) to call this user in your Asterisk dialplan). For SIP phones, the internal phone number is often used as resource name.

Internal number : the internal phone number of the user

Caller ID : this field is important. If you don’t know what a Caller ID is, you should read more documentation about Asterisk. In short, it has to do with the name and phone number presented to the remote party. When you call someone via click2dial, the callerid parameter for your IP phone defined in /etc/asterisk/sip.conf (if you have a SIP phone) will NOT be used ; the Caller ID field defined in OpenERP will be used instead. You should use the same syntax for the Caller ID field in OpenERP than for the callerid field in Asterisk, for example :

Alexis de Lattre <141981242>

Alert-Info SIP header : this is the same parameter as for the Asterisk server, but user-specific. You can leave it empty for now.

Variable : this parameter is for advanced Asterisk users only. Leave it empty for now.

Propose to create a call in the CRM after a click2dial : this option is available only if you have installed the asteriskclick2dialcrm module ; it is activated by default. It can also be modified via the user's preferences (this means that users can modify this option by themselves).

Asterisk server : select the Asterisk server on which the IP phone of the user is registered. If your company only has one Asterisk server, you can leave this field empty : OpenERP will use the only Asterisk server created in OpenERP .

That’s it, the configuration is finished, you can start playing with click2dial !

How phone numbers are reformated

This diagram explains how phone numbers are managed by the asterisk_click2dial module.

In the diagram, the two examples (ex1, ex2 and ex3) are based on the following configuration :

Out prefix : 0

National prefix : 0

International prefix : 00

My country prefix : 33

Use the click2dial feature

In OpenERP, go to any menu that give you access to Partners and open a partner that you want to call. In the General tab, select the Partner contact that you want to call. Next to the Phone and Mobile fields, you should see a Dial button.

Important : the phone number in OpenERP should be in international format, for example : +33 1 41 98 12 42

This is the same format that you must use in your mobile phone’s directory when you want to be able to call a number saved in your phone’s directory when you travel abroad. For example, check this Nokia user manual page 19, section Make calls, look at the tip.

If the phone number is not in the international format, you will get an error message when you click on the Dial button, unless you activated the option Allow national formats ? for this the Asterisk server.

Here is the complete usage scenario pf the click2dial feature :

1. Click on the Dial button next to the phone number you want to dial.

2. OpenERP reformats the phone number using the different prefixes defined for this Asterisk server. Then OpenERP connects to the Asterisk Manager Interface and sends a request.

3. Asterisk makes the user's phone ring.

4. The user answers his own phone. If he doesn't answer his phone, the process stops here, the next steps are not executed.

5. Asterisk dials the phone number that has been reformated and, immediately after dialing, connects the user’s phone to the call (the user hears the call waiting tones, just like if he had dialed the number himself).

6. The user is in full control of the call.

7. If you have installed the asteriskclick2dialcrm module and you haven't disabled the option Propose to create a call in the CRM after a click2dial on the user form or via the user's preferences, you will get a pop-up that proposes to create a phone call in the CRM :

Quiet click2dial

Imagine you share the same workroom with other colleagues. When one of your colleagues makes a phone call, the workroom stays quiet until the conversation starts. Now, if the colleague uses the click2dial feature of OpenERP, his phone will ring and bother everyone before the conversation even starts ! I think it’s an important drawback.

Hopefully, there is a solution to his : when Asterisk “calls” the user (before calling the remote party), he should tell the phone not to ring. In fact, when I say “tell the phone not to ring”, I mean “tell the phone to use a silent ring tone”. This is usually possible with SIP phones. In the SIP protocol, you can use the Alert-Info header to tell the phone to choose a particular ring tone. This feature is often called “distinctive ringing” or “priority alerting”. Most SIP phones support the Alert-Info header, but :

the exact syntax of the content of the header may differ from one SIP phone manufacturer to another,

the name of the ring tones may also differ from one SIP phone manufacturer to another.

I have tested this feature with two different phone manufacturers : Technicolor i.e. the new name of Thomson (ST2030 model, it probably works the same way with other models) and Aastra (6731i model, I am sure the other models work the same way). I give the details below ; if you have some experience with other phones, don’t hesitate to send me an email (alexis.delattre at akretion.com) and share your knowledge.

Technicolor ST2030 IP phones

I suppose you use TFTP to configure the phone. If you edit the default configuration file for system melodies which is called Tone-RG.txt, you will see a ring tone Silent defined like this :

Silent:d=32,o=5,b=160:8P,2D

With this configuration, it is a “quiet” ring tone, but not a fully silent one. To make it a fully silent, change the definition of this ring tone to :

Silent:d=32,o=5,b=160:P

Note : for the changes to take effect, don’t forget to change the name of the ring tone file and update the filename in the parameter system_melodies of the <MAC_address>.inf file.

Then, in OpenERP, in the configuration of the Asterisk server, you should give the following value to the the Alert-info SIP header :

info=<Silent>

Aastra IP phones

According to the Aastra documentation, a Silent ring tone exists, but it can’t be used for distinctive ringing. I found a workaround for this : choose a ring tone that is not used but default, for example Bellcore-dr5 (which is a “quiet” ring tone, but not a fully silent one), and redefine it in the configuration file (aastra.cfg to change it for all Aastra phones, or <MAC_address>.cfg to change it only for one phone) :

bellcore cadence dr5: 0,-1

This will convert the ring tone Bellcore-dr5 to a fully silent ring tone.

Then, in the configuration of the Asterisk server in OpenERP, you should give the following value to the Alert-info SIP header :

info=<Bellcore-dr5>

Note : if you have a mix of Aastra and Technicolor phones, you can either use the user-specific Alert-info SIP header which is available on the User's form, or use the server-wide Alert-info SIP header parameter and rename the Silent ring tone of the Thechnicolor IP phone to Bellcore-dr5.

Auto-answer on click2dial with Aastra IP phones

If you want your Aastra IP phones (other IP phones also support this feature) to answer automatically on a click2dial, here is how to proceed.

First, you need to configure the *Incoming intercom calls" on your Aastra IP Phone. Here are the parameters that you should use in your Aastra configuration file :

sip allow auto answer: 1 # Allow auto-answer on incoming intercom callssip intercom warning tone: 1 # Activate warning tone on incoming intercom callssip intercom mute mic: 0 # Enable microphone on incoming intercom calls

Then, in the Alert-info SIP header, enter :

info=alert-autoanswer

If the Alert-info SIP header already has a value, note that you can put several values in this field if you separate them with ';', for example :

info=<Bellcore-dr5>;info=alert-autoanswer

If you want the auto-answer to be user-specific, use the Alert-info SIP header of the user's form ; if you want it to be for all the users of an Asterisk server, use the Alert-info SIP header of the Asterisk server form. When the Alert-info SIP header of the user's form is set, the equivalent field on the server form is ignored.

Now, when you do a click2dial, your Aastra IP Phone will auto-answer the call and use the speaker by default.

Get the name of the calling party on incoming phone calls

Technical introduction

Here is a scenario which explains how the feature works :

1. On incoming phone calls, the Asterisk dialplan executes an AGI get_cid_name_timeout.sh.

2. The get_cid_name_timeout.sh script calls the get_cid_name.py script with a short timeout.

3. The get_cid_name.py script will make an XML-RPC request (or XML-RPC over SSL) on the OpenERP server to try to find the name of the person corresponding to the phone number presented by the calling party.

4. If it finds the name in OpenERP, the name is used as CallerID name for the call, so that users can see the name on the screen of their IP phone. If it doesn't find any match in OpenERP, it can geolocalize the phone number and display the country and city name as CallerID (if you active a specific option).

Setup on the OpenERP side

Make sure that you have a recent version of the asterisk_click2dial module with the function getnamefromphonenumber in the file asterisk_click2dial.py.

I recommend to create a new user on OpenERP ; for example, we will call it asterisk. This asterisk user will be dedicated to this feature and will only have the minimum access rights required to use the feature. For that, add this asterisk user to the Asterisk CallerID group (this group only has the minimum access rights required to use the feature).

Setup on the Asterisk side

First, make sure that you can reach the XML-RPC port of OpenERP from the Asterisk server ; if it doesn’t work, check your network settings and firewalling rules.

Second, check that the shell command timeout is available on your Asterisk server :

under Debian Lenny or lower and Ubuntu Lucid 10.04 or lower, you have to install the timeout package,

under Debian Squeeze or higher and Ubuntu Maverick 10.10 or higher, this shell command is provided by the package coreutils which is installed by default.

Then, copy the two files get_cid_name.py and get_cid_name_timeout.sh in the directory /usr/local/bin/ of your Asterisk server. Make sure that the two scripts have execution rights. You will find below some details about the two scripts.

Eventually, if you are interested by the geolocalisation feature, install the Python library phonenumbers on your Asterisk server :

% sudo pip install phonenumbers

This library contains a database of phone prefixes and their corresponding region/city names for about 55 000 phone prefixes of the world (cf the file phonenumbers/geodata/__init__.py of the library).

First, the script get_cid_name.py is written in Python and it’s the one which “makes the job” :

it receives on its standard input the parameters given by Asterisk, in particular the phone number,

it sends an XML-RPC request to OpenERP to ask if it can find the phone number in the Partner addresses,

it writes on its standard output some instructions for Asterisk, in particular to change the CallerID name.

This script has some options, in particular the information to connect to OpenERP and the optional geolocalisation feature:

the DNS or IP address of the OpenERP server,

the port on which the XML-RPC interface listens (port 8069 by default),

an option to use XML-RPC over SSL instead of XML-RPC,

the name of the OpenERP database to use,

the ID of the OpenERP user (in our example, write the ID of the user asterisk that we created in the previous section),

it’s password,

if you enable the geolocalisation option, you should provide your country (required to parse presented phone numbers correctly) and the language in which you want the country and city name to be displayed.

Run get_cid_name.py -h to have the syntax of these options.

Then, there is the script get_cid_name_timeout.sh which is a one-line shell script. This is the script that is called from the Asterisk dialplan and that calls the script get_cid_name.py with the appropriate options. Why do we need this intermediate script ? In fact, this intermediate script calls the script get_cid_name.py with a short timeout of 1 second by default ; if the script get_cid_name.py has not finish it’s job after 1 second, it will be killed. It is important to set such a timeout because the script will be called by Asterisk upon each incoming phone call ; it the script get stucks, the phone call will also get stucks and you will

miss the call !

Edit the script get_cid_name_timeout.sh and put the right options.

Test the script with a phone number that is present in the Partner addresses of OpenERP :

# echo "agi_callerid:141981242"| /usr/local/bin/get_cid_name_timeout.shFull AGI environnement :agi_callerid = 141981242VERBOSE "CallerID number = 141981242"phone number sent to OpenERP = 141981242VERBOSE "Starting XML-RPC request on OpenERP localhost:8069"VERBOSE "End of XML-RPC request on OpenERP"VERBOSE "CallerID Name = Alexis de Lattre"SET CALLERID "Alexis de Lattre" <141981242>

The script outputs some debug information on stderr and some instructions to OpenERP on stdout. In this example, the instructions to OpenERP are the lines which start with VERBOSE or SET CALLERID. The important line is the last line which has the SET CALLERID instruction : it will tell Asterisk to replace the CallerID of the incoming call by the one given after the instruction.

If the phone number is not found in the Partner addresses of OpenERP and you have enabled the geolocalisation option, the output would be :

# echo "agi_callerid:0141931242"| get_cid_name_timeout.shfull AGI environnement :agi_callerid = 0141931242stdout encoding = UTF-8VERBOSE "CallerID number = 0141931242"phone number sent to OpenERP = 141931242VERBOSE "Starting clear XML-RPC request on OpenERP 192.168.0.10:8069"VERBOSE "End of XML-RPC request on OpenERP"VERBOSE "Phone number not found in OpenERP"VERBOSE "Trying to geolocate with country FR and lang fr"VERBOSE "CallerID Name = France Vincennes"SET CALLERID "France Vincennes"<0141931242>

If you haven't enabled the geolocalisation option, the last line will be :

SET CALLERID "Not in OpenERP" <141981242>

You can personnalize the string “Not in OpenERP” by editing the script get_cid_name.py.

If the test of the script is successfull, you can move on to the last step : modify the Asterisk dialplan to call the script upon the reception of an external phone call. If you have written the Asterisk dialplan yourself, edit the dialplan (usually /etc/asterisk/extensions.conf) and, in the context dedicated to the reception of external phone calls, insert an extension that will execute the AGI function with the location of the script (/usr/local/bin/get_cid_name_timeout.sh) as parameter. Of course, this extension must be placed before the Dial() function which rings the IP phone of the user. For example :

[from-extern]exten => _141981242,1,AGI(/usr/local/bin/get_cid_name_timeout.sh)exten => _141981242,n,Dial(SIP/10, 30)

exten => _141981242,n,Answer()exten => _141981242,n,Voicemail(10@default,u)exten => _141981242,n,Hangup()

Then, reload the Asterisk diaplan :

asterisk*CLI> extensions reload

If you haven’t written the Asterisk dialplan yourself, which is the case of users which use FreePBX or Xivo or any other administration interface for Asterisk, you need to figure out how to insert the extension with the AGI script in the dialplan functions which manage the reception of external calls. If you need help for this, please consider Akretion's service offering.

You are now ready to receive your first phone call with CallerID name lookup in OpenERP !

Setup the 'open calling party' feature

Setup

This feature requires the same configuration as the click2dial feature, which is explained above.

Warning : if you have already deployed the click2dial feature and you upgraded the module to get the new open calling party feature, you should update your /etc/asterisk/manager.conf file to add some write priviledges to the AMI user, cf the click2dial section above.

Use the 'open calling party' feature

The 'open calling party' feature is currently only available for OpenERP 6.1 (backporting it to older versions of OpenERP should be easy).

Here is a typical scenario :

1. Your phone rings.

2. Before or after picking up the phone, go to the menu Sales > Address Book and you double-click on Open calling partner.

3. OpenERP sends a Status request to the Asterisk Manager Interface (AMI) to get the list of all the current phone calls. It will get the first call that involves your phone number and it retrieves the presented phone number.

4. OpenERP searches the presented phone number in the Phone and Mobile fields of the Partner addresses of OpenERP (for this, it uses the same code as the Get the name of the calling party on incoming phone calls feature). If it finds a match, it opens a pop-up that shows the presented phone number, the name of the corresponding Partner address and the name of the corresponding Partner :

You now have several options corresponding to the buttons in the pop-up :

open the form view of the Partner,open the list view of the sale orders related to the Partner,open the list view of the invoices related to the Partner,if you have the asteriskclick2dialcrm module, it also proposes to create a phone call in the CRM.

If it doesn't find a match, it opens a pop-up that shows the presented phone number, and it proposes to create a new partner contact or update an existing partner contact :

TroubleshootingIf you have some issues with the module :

start openerp-server with the command line option --log-level=debug : you will get usefull messages about the phone number reformating process and the connection to the Asterisk Manager Interface.

also check logs on the Asterisk side : on your Asterisk server, run :

% asterisk -rvvvvvvvvvvvv

if the OpenERP server and Asterisk don’t communicate, use tools such as tcpdump or wireshark to check the network traffic between the two machines. Run for example :

% tcpdump -n -i eth0 -A -s 0 port 5038

for the feature “CallerID name lookup in OpenERP on incoming phone calls”, you can get more logs about the execution of the AGI script by running this command in the Asterisk console :

asterisk*CLI> agi set debug on

To disable it :

asterisk*CLI> agi set debug off