Howto:XCAPI: Difference between revisions
| Line 133: | Line 133: | ||
==== Routing to and from the XCAPI gateway ==== | ==== Routing to and from the XCAPI gateway ==== | ||
Create routes from GW3 (XCAPI) to all desired destinations (PSTN, PBX, the XCAPI itself if needed). In this example, we use 0 as prefix for PSTN access, 1 for PBX access, and 93 to route calls back to the XCAPI itself (normally, this is only required for testing purposes). | Create routes from GW3 (XCAPI) to all desired destinations (PSTN, PBX, the XCAPI itself if needed). In this example, we use 0 as prefix for PSTN access, 1 for PBX access, and 93 to route calls back to the XCAPI itself (normally, this is only required for testing purposes). | ||
[[Image:6-from-gw3-routes.PNG]] | |||
Here is an overview of the routes to the XCAPI. Calls from the PSTN, the XCAPI and the PBX can access the XCAPI via prefix 93. [[Image:8-to-gw3-routes.PNG]] | PBX users can access the XCAPI via the XCAPI gateway object in the PBX configuration, but their calls will be routed to GW4 (XCAPI-SIP-GW-PBX). For XCAPI access, we have to add a route from GW4 to GW3 (XCAPI). In this example, we route calls beginning with 93 to the XCAPI gateway. | ||
[[Image:7-from-gw4-route.PNG]] | |||
Here is an overview of the routes to the XCAPI. Calls from the PSTN, the XCAPI and the PBX can access the XCAPI via prefix 93. | |||
[[Image:8-to-gw3-routes.PNG]] | |||
=== XCAPI Configuration === | === XCAPI Configuration === | ||
Revision as of 16:30, 28 June 2010
 |
| this is 3rd party content not provided by innovaphone, see history for authors. |
Applies To
This information applies to
- IP302, IP305, IP400, IP800, IP3000, IP6000
Configuring the XCAPI with the innovaphone Gateways
Introduction
This document is intended to support you with the integration of the XCAPI (version 3.3.161) into an existing environment of current innovaphone gateways (Version 6 and following). In the following sections we describe the essential steps of configuration to allow for optimal cooperation of both the XCAPI and the innovaphone PBX/gateway. At this point, we suppose that the innovaphone PBX, the hardware the XCAPI is running on and both the XCAPI and your CAPI applications are already installed properly. For some extended information on installation procedures please refer to the respective manuals. A short installation manual for the XCAPI is available at the XCAPI Homepage (http://www.te-systems.de/community/index.php?L=0).
H.323
Configuring the innovaphone PBX
In order to establish communications between the XCAPI and the innovaphone PBX using the H.323 protocol, you need to create a new controller inside the XCAPI and set up a connection to the XCAPI inside the innovaphone PBX. First, we start to configure the innovaphone PBX. Please open the web based innovaphone PBX configuration interface. The XCAPI can be configured as a PBX object for assigning single MSNs or it can be configured as an external gateway, allowing the mapping of a route pattern with multiple extensions. In most cases, the second method should be preferred.
Configuring a VoIP Gateway
To add the XCAPI as a new gateway, you have to choose the Gateway dialog out of the Administration menu. If you haven’t logged in as administrator yet, you need to do now for accessing this configuration dialog. Now you can configure a new gateway in the VoIP dialog. Click on an arbitrary GW Interface entry that is not configured yet. If you haven’t configured any gateway, please use GW1. A new window will open where you can configure the gateway settings. TechNote In this example we configure the new gateway as described:
- The Name field should be set to a meaningful name. Here we enter the name XCAPI Gateway.
- Please make sure that the Disable option is not active.
- In the Protocol field we select the value H.323 as protocol for the communication between the XCAPI and the innovaphone PBX.
- The Gatekeeper Address (primary) field has to be filled with the IP address of the computer the XCAPI is running on.
- We recommend selecting a codec like G.711 a-Law or G.711 μ-Law for the internal communication between the XCAPI and the innovaphone PBX. Set both the General Coder Preference and the Local Network Coder to the appropriate codec that fits your VoIP environment. Set the Framesize ms of both codecs to the value of 20 ms. This is the default value for the XCAPI.
- Activate the Enable T.38 option for fax functionality.
- For best results, we recommend to activate the No Faststart and No H.245 tunneling options.
All other options that were not mentioned should be left by the default settings. Depending on your environment some further settings could be necessary. Please refer the innovaphone PBX manual for detailed descriptions. Finally, please click the APPLY button to add the new gateway to your innovaphone PBX configuration. The IP address will be automatically assigned to the new added XCAPI Gateway after configuring the XCAPI.
Route Patterns
Please select the Routes dialog from the Administration - Gateway menu for configuring a route pattern. Here you have to create one route for each direction, from ISDN to VoIP and the other way round. We start with the route from the ISDN interface to the XCAPI. Please click the small icon with the arrow pointing to the right. A new dialog will appear where you can set the route pattern and its direction. In the Description field, you may enter a meaningful description for this route. In this example, we enter the value ISDN –> XCAPI Gateway. From the list of checkboxes to the left, select the incoming interface, i.e. the interface from where the calls for this route originate. We use the first PRI interface for the ISDN connection, so please activate the option PRI1. The two text areas that are connected with an arrow are used for the route pattern. The left text area describes the incoming number, whereas the right text area describes the outgoing number that is delivered to the XCAPI. If, for example, the ISDN interface can be reached using the trunk number 123 and you want to configure a pattern of numbers beginning with 123100 and ending with 123199, simply enter 1231 in both fields. If you would like to truncate the trunk number from the route pattern, enter 1231 in the left field and 1 in the right field. This means that the route pattern can be reached when dialling any number beginning with 1231, but only the part of the extension beginning with the second 1 will be delivered to the XCAPI. From the list to the right, please select the Gateway we have configured earlier (GW1 XCAPI Gateway).
Finally, confirm the settings with the APPLY button and close the window.
XCAPI Configuration
Please start up the XCAPI configuration to create a new controller assigned to the innovaphone PBX. If you’ve just installed the XCAPI and start the configuration tool for the first time, the XCAPI Controller Wizard will pop up automatically. This will also happen if there’s no controller configured at all. To start up the XCAPI Controller Wizard on your own, just click the link labeled Click here to add a controller on the overview page of the XCAPI configuration tool. On the first page of the Controller Wizard please select the Add Voice-over-IP controller (VoIP) option and continue by clicking on the NEXT button.
Hint: You can best use the ControllerWizard by making the necessary adjustments in the dialogs presented to you, using the NEXT and BACK buttons to navigate. When showing the relevant dialogs of the ControllerWizard we won’t mention clicking NEXT to advance every time. Just assume you have to click NEXT after completing a dialog.
Network Interface
On this page of the XCAPI Controller Wizard you can select the network adapter you want to bind to the XCAPI controller. Should you have any doubts here, please refer to the XCAPI Quick Start Guide for further details.
Voice-over-IP Environment
The next dialog of the configuration tool shows a list of some common Voice-over-IP environments. Selecting one of those will configure the XCAPI with a selection of near-optimal presets for the kind of environment you have, sparing you quite a lot of manual configuration. Please select the innovaphone option here.
IP address and gatekeeper ID
In this dialog you can provide the address of your innovaphone Gateway and enter a gatekeeper ID. Although it is recommended to let the system discover the IP address of the innovaphone device automatically you can provide the IP address of the innovaphone device and disable the automatic recovery. The gatekeeper ID may be left blank if you have provided the IP address of the innovaphone device or it is the only PBX (gatekeeper) in the network. In this example we disable the automatic recovery and provide the IP address of our innovaphone PBX device with the value 192.168.1.205. The left the innovaphone gatekeeper ID blank, as we use only one PBX (Gatekeeper) in our environment.
Local telephone number and alias name
In this dialog you have to provide the telephone numberand the alias name that are configured at the innovaphone gateway. If no alias name is configured this field may be left blank. If an alias name is configured at the innovaphone PBX the alias name is required. In this example we enter the value 123 in the Telephone number field that describes a six-digit long number so the XCAPI and the connected CAPI applications can be reached with the range of numbers between 123000 and 123999.
Description and Channels
That’s about all information that has to be configured with the XCAPI. The next-to-final dialog of the ControllerWizard allows configuring a meaningful description for the controller you’re going to create. This isn’t really used anywhere, so you can enter a text of your choice here. This dialog, however, also allows configuring the number of channels that the new controller will be able to provide. Please enter how many simultaneous connections the XCAPI should handle when communicating with the PBX.
Confirmation
The final dialog of the Controller Wizard performs some checks on the configuration parameters you’ve made. If any errors are detected here, you can go back to the respective dialogs and correct the necessary input. If everything is correct please use the FINISH button in order to finally create the new controller. The controller you’ve just created now will appear on the overview page of the XCAPI configuration tool. As we’re now finished with all XCAPI-related configuration tasks, please save the changes you’ve made and exit the configuration tool.
SIP
Configuring the innovaphone gateway
In this example, we are going to use one PBX gateway object (XCAPI-SIP-GW) and two gateways (XCAPI-SIP-GW and XCAPI-SIP-GW-PBX). Only one gateway will communicate with the XCAPI via SIP, the other gateway and the gateway object in the PBX are simply for routing purposes between the innovaphone gateway and the PBX.
Creating a Gateway Object in the PBX
Log in to the PBX administration and create a new gateway object. The name of the object is "XCAPI-SIP-GW", and the number is 93 in this case. 
GW4, which we will create later in the gateway configuration, will register itself with this object and enables PBX objects to connect to the gateway with prefix 93. 
Creating the gateways towards the XCAPI and PBX
In the gateway administration, we will create two gateways: GW3, which will connect to the XCAPI via SIP, and GW4, which will be used for the outbound routing from the PBX towards the XCAPI.
Edit the settings of GW3 to use SIP, Gateway without Registration mode, and enter the IP address of the XCAPI server as Domain. As codecs, we select ITU.T G.711 a-Law with a framesize of 20 ms, and enable T.38 as fax codec. All other settings can use the default values.
Add another gateway (GW4), but this time, register it with the local PBX. You can do so by selecting H.323 as protocol and Register as Gateway as mode. Enter 127.0.0.1 as Address and the name XCAPI-SIP-GW and 93 as number in the Alias List. This causes this gateway to register with the previously created gateway object in the PBX. This gateway should use the same codec settings as the XCAPI gateway.
Routing to and from the XCAPI gateway
Create routes from GW3 (XCAPI) to all desired destinations (PSTN, PBX, the XCAPI itself if needed). In this example, we use 0 as prefix for PSTN access, 1 for PBX access, and 93 to route calls back to the XCAPI itself (normally, this is only required for testing purposes).
PBX users can access the XCAPI via the XCAPI gateway object in the PBX configuration, but their calls will be routed to GW4 (XCAPI-SIP-GW-PBX). For XCAPI access, we have to add a route from GW4 to GW3 (XCAPI). In this example, we route calls beginning with 93 to the XCAPI gateway.
Here is an overview of the routes to the XCAPI. Calls from the PSTN, the XCAPI and the PBX can access the XCAPI via prefix 93.
XCAPI Configuration
When the XCAPI configuration is started for the first time, there are no configured controllers. Use the link "Click here to add a controller" in the overview page to start the controller wizard. 
Add new VoIP controller
On the welcome page of the controller wizard, select to add a new VoIP controller. 
Network Interface
In the next dialog, select the network interface that you want to use for the SIP connection between the XCAPI and the innovaphone gateway. 
Select VoIP environment template
From the list of predefined VoIP environments, select a generic SIP template. 
Provide SIP user information
The XCAPI is connected as a SIP trunk (gateway mode), so it is not necessary to enter any user information. 
Default SIP domain
As default SIP domain, please enter the IP address of the innovaphone gateway. Please do not use any configured DNS hostnames because of interoperability reasons. 
Registrar and Proxy
It is not necessary to activate the registrar or proxy function. 
STUN
STUN functionality is also not required. 
Description and channels
Enter a meaningful description and the number of lines that the XCAPI can use to communicate with the innovaphone gateway simultaneously. In this example, we enter the prefix number (81893) of the XCAPI as the description. This way, we always know which number to dial if we want to call the XCAPI. 818 is the trunk number of the PSTN access while 93 is the prefix from the innovaphone gateway routing. 
Confirmation
Check if all necessary information has been entered correctly (green symbols on the left) and confirm all data by clicking Finish. 
The new controller appears in the XCAPI configuration. Save the changes and stop all running CAPI applications before restarting them. 
Known Problems
SIP to H.323 interworking has turned out to be a problem.
XCAPI does neither support Faststart nor Extended Faststart (EFC). XCAPI only supports capability exchange through H.245 procudures.
One trick to get this working is to configure the gateway interface to media-relay and exclusive coder (gateway interface talking to XCAPI).
But the recommended strategy is to configure the XCAPI to use SIP signaling. This eliminates the whole interworking problem.