Asterisk-JTAPI Setup

Here we describe setup and interaction with the asterisk dialplan.

Classpath

You need at least the these jars in your classpath:

  • asterisk-jtapi-<version>.jar
  • gjtapi-<version>.jar
  • asterisk-java-<version>.jar
  • jtapi-1.3.1.jar
The Asterisk-JTAPI jar-file must be before the GJTAPI jar in the classpath.

Client Setup / Provider Parameters

You retrieve the Asterisk JTAPI provider by issueing JtapiPeer.getProvider("Asterisk; parameters"); where parameters are in the form name=value; name=value; .... Supported parameters are:

  • Server IP address or hostname of your Asterisk box
  • Port Port number of the Manager Interface
  • Login manager login user
  • Password Secret for the asterisk manager login
  • IncomingContext Context of incoming calls, see Dialplan section below
  • TerminalContext Context of terminal, see Dialplan section below
  • OutgoingContext Context of outgoing calls, see Dialplan section below

Asterisk PBX Setup

To setup the manager interface in your Asterisk PBX check the configuration file /etc/asterisk/manager.conf

Dialplan Setup

The JTAPI standard allows an application to retrieve information about the addresses and terminals under control and their actual state. To avoid doubled configuration work we construct this information by analysing the Asterisk dialplan.

Before we go into detail some definitions from the JTAPI and Asterisk "worlds":

  • address Defined by JTAPI, this is a number that is dialed, which is the routing information in a telecommunications network.
  • terminal Defined by JTAPI, this is a communications endpoint, e.g. a telephone or a fax machine. A terminal may be reachable through several addresses (we call this alias) and an address may have several terminals assigned e.g. for a group call.
  • context Defined by Asterisk; Call routing starts in different contexts to seperate different issues, e.g. incoming/outgoing calls, calls from different trunk lines.
  • extension Defined by Asterisk; A target in the dialplan. An extension has a name, number or a number wildcard match and executes commands if its number/name is dialed. The idea of an extension is more generic then a terminal. An extension a phone, voicemail box, meetme room, an alias for another extension, etc.
  • extension id The dialed extension name or number.
For a starting point about the Asterisk dialplan options and commands take a look at Asterisk howto dial plan

From Extensions to Terminals

There are many different ways to construct an Asterisk dialplan. Let's start with an example: We have a trunk line with two digits direct dial in numbers. A straight-forward dialplan looks like this: 

[dialin]
; telephone from jens routed to internal ISDN 
exten => 30,1,Dial(Zap/g2/30)
; telephone from birgit routed to her SIP phone
exten => 31,1,Dial(SIP/birgit,30,r)
; hotline calls go to birgit
exten => 24,1,Goto(31,1)

As we can see the extension ids 30 and 31 are routed to some endpoints and number 24 is just an alias of 31.

Asterisk JTAPI transfers such a dialplan automatically to meaningfull JTAPI objects: We get two terminals named 30 and 31. Terminal 31 has the address 31 and 24 and terminal 30 has just the address 30. To use this kind of dialplan set incomingContext and terminalContext to the same value (in the above example this is "dialin").

It is best practise to seperate terminals from the routing either by using a special number space or a different context for the terminals: 

[terminals]
; telephone from jens routed to internal ISDN 
exten => jens,1,Dial(Zap/g2/30)
; telephone from birgit routed to her SIP phone
exten => birgit,1,Dial(SIP/birgit,30,r)

[dialin]
exten => 30,1,Goto(terminals,jens,1)
exten => 31,1,Goto(terminals,birgit,1)
; hotline calls go to birgit
exten => 24,1,Goto(terminals,birgit,1)

Defined this way JTAPI application get two terminals named "jens" and "birgit". Terminal "jens" has the assigned address 30 and terminal "birgit" has the assigned address 31 and 24. In the Asterisk JTAPI configuration inscomingContext needs to be set to dialin and terminalContext needs to be set to terminals.

Dialplan Analysing

Now that we saw two example dialplans, lets define how the translation from dialplan to JTAPI object model is done. The dialplan is parsed and the JTAPI object model is constructed according to the following rules:

  • Each extension in the terminal context becomes a JTAPI terminal. The terminal name is the extension id
  • If the terminal context is also the incoming context the extension id of a terminal is also an address of that terminal
  • If incoming and terminal context is identical and an extension is a recognized routing command it is excluded from the terminal list
Routing commands that we recognize so far:
  • Goto A Goto at priority 1 in the incoming context to a terminal target: The extension id is added to the terminal address (alias definition)
  • Dial A Dial at priority 1 in the incoming context to multiple local targets: If the target is a terminal the extension id is added to the terminal address (alias or group call)