Akretion and Anevia present the "asterisk_click2dial" module: unleash your Asterisk phones in OpenERP!

Module Asterisk_click2dial for OpenERP

Author : Alexis de Lattre <alexis _at_ via.ecp.fr>

General description                                   

This module adds a dial button in the partner address view so that 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.

Installation of the module

You should install the asterisk_click2dial modules on OpenERP just like any regular OpenERP module. What you need to know :

1. the source code of the module is available from Launchpad, in the extra-addons repository :

1. for OpenERP v5 (stable branch, as of September 2010) : https://code.launchpad.net/~openerp-commiter/openobject-addons/stable_5.0-extra-addons
2. for OpenERP v6 (development branch, as of September 2010) : https://code.launchpad.net/~openerp-commiter/openobject-addons/trunk-extra-addons

1. the asterisk_click2dial module doesn't require any additional python library.

Note : the module named asterisk in the extra-addons repository is useless and doesn't have any working functionality. The asterisk_click2dial module doesn't depend on it.

Configuration of Asterisk

OpenERP will communicate with Asterisk through the Asterisk Manager Interface (AMI).

So the first step is to configure AMI :

1. create an AMI account for OpenERP
2. 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 an example of the configuration with my comments inline :

; 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 cut the communications).

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

% telnet <asterisk_server> 5038

It should display :

Connected to <asterisk_server>.

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. Then, for each OpenERP user, you must configure on which Asterisk server he is connected.

Go to 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.

Two parameters require additional explanations :

1. Alert-Info SIP header : more explanations below. You can leave it empty for now, it is not a problem.
2. How the different prefixes are used by the module, see below.

Configure users

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

1. Internal number : the internal phone number of the user
2. Asterisk channel type : the channel type of the phone of the user (if the user has a regular IP phone, select SIP)
3. 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 <0141981242>

1. Asterisk server : select the Asterisk server on which the IP phone of the user is registered. If you have read the previous section, you should already have created it.

That's it, the configuration is finished, you can start playing... or debug !

How phone numbers are reformated

This diagram explains it all.

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

1. Out prefix : 0
2. National prefix : 0
3. International prefix : 00
4. My country prefix : 33

Use the click2dial feature

Go to the menu Partners > 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 are in a foreign country. 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 :

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 it 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 :

1. the exact syntax of the content of the header may differ from one SIP phone manufacturer to another,
2. the name of the ring tones may also differ from one SIP phone manufacturer to another.

I have tested this feature with 2 different phone manufacturers : 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 edit this document and share your knowledge.

Thomson 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 transform the ring tone Bellcore-dr5 into a fully silent ring tone.

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

info=<Bellcore-dr5>

Note : if you have a mix of Aastra and Thomson phones and you don't want to configure 2 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 Thomson IP phone to Bellcore-dr5 !

Troubleshooting

If you have some issues with the module :

1. start openerp-server with the command line option --log-level=debug : you will get usefull messages about the phone number reformating process
2. also check logs on the Asterisk side : on your Asterisk server, run :

% asterisk -rvvvvvvvvvvvv

1. if the Openerp server and Asterisk don't communicate, use tools like tcpdump or wireshark to check the network traffic between the 2 machines.