OpenERP – Asterisk connector

Introduction

Asterisk 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 connector

The OpenERP-Asterisk connector has two main features. First, it adds a dial button in the partner address 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.

Akretion service offering

Deploying 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 module 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 module,

• 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 700 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 module or other Asterisk-side scripts than those used by the OpenERP-Asterisk connector.

Installation of the module

You should install the asterisk_click2dial module on OpenERP just like any OpenERP module. The source code of the module is available from Launchpad, in the extra-addons repository :

• for OpenERP v5 : https://code.launchpad.net/~openerp-commiter/openobject-addons/stable_5.0-extra-addons
• for OpenERP v6 : https://code.launchpad.net/~openerp-commiter/openobject-addons/trunk-extra-addons

The asterisk_click2dial module doesn’t require any additional Python library.

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 feature
enabled=yes
; TCP Port on which AMI will listen
port = 5038
; I suppose Asterisk and OpenERP are on two different machines,
; so you must bind AMI on 0.0.0.0
bindaddr = 0.0.0.0
; We don’t need to activate the HTTP AMI interface : the module uses the native interface
webenabled = no

; Then, we create an AMI account for OpenERP
[click2dial]  ; This is the AMI login
secret = mypassword ; This is the AMI password
; We deny AMI access for everybody
deny = 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
read = call
write = call
; For Asterisk 1.6.x, you need the “originate” rights :
;read = originate
;write = originate

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.0

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 section Quiet click2dial 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 User tab :

• Internal number : the internal phone number of the user

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

• 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>
  

• Asterisk server : select the Asterisk server on which the IP phone of the user is registered.

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.

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.

Thechnicolor 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 Thechnicolor phones and you don’t want to configure two Asterisk servers in OpenERP that point to the same server with just a different Alert-info SIP header parameter, here is a trick : rename the Silent ring tone of the Thechnicolor IP phone to Bellcore-dr5.

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.

Setup on the OpenERP side

Make sure that you have a recent version of the asterisk_click2dial module with the function get_name_from_phone_number 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 or lower, you have to install the timeout package,

• under Debian Squeeze or higher and Ubuntu Maverick 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.

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 :

• 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.

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/agi_cid_timeout.sh
Full AGI environnement :
agi_callerid = 141981242
VERBOSE "CallerID number = 141981242"
phone number sent to OpenERP = 141981242
VERBOSE "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, 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 !

Troubleshooting

If 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.

• 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.

• 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 debug
  

  To disable it :

  asterisk*CLI> agi debug off