Course12:Advanced - TAPI

Book about the Innovaphone TAPI

Concept

Overview

 Here is an overview about the integration of the TAPI

The PBX supports a TAPI interface. With innovaphone devices, call control via the Computer Telephony TAPI interfaces is possible. This is implemented by innovaphone's TSP, which is a driver that is installed into the Windows TAPI subsystem. The TSP monitors and controls innovaphone PBXs and phones via SOAP. Each user object device is represented as a TAPI line.

The TSP will install on any Windows 32bit and x64 platform down to Windows XP/Server 2003. For more information about TAPI refer to  TAPI Service Provider.

This book describes how to install and use it, as well as how to configure the PBX in order for the TSP to work properly.

What is a Tapi Line?

TAPI provides a model of phone lines, the user object has a phone registered in the PBX and the Tapi interprets this as a registered line. By default the Line Name will be the objects Long Name followed by the name of the Device [Name](if it is different than the Long Name).

Normally the first registration will be used as  TAPI line device

Multiple registrations on user objects together with TAPI and SOAP applications are also possible. User objects with multiple registrations could have several phones registered to it, but only one could be used as TAPI line. We describe the  multiple registrations in the chapter TSP Line Name and Modifier Flags (Map PBX Devices to Lines).

The following scenarios are possible with TAPI and innovaphone PBX

1st Party Configuration

In a  1st party scenario the TSP will only work on a single PBX object. This will typically be a user's phone and thus the user itself will be used as the TAPI user. In such a configuration the TSP is typically installed on the users PC and the CTI software is accessing TAPI directly (such as e.g. Microsoft Outlook does). The TSP configuration dialogue will check the number of lines. If it is only one, then there will appear a  warning message. This is because 3rd party configurations are much more common and this situation often indicates a configuration problem. In a first party configuration, you can safely ignore this message. Important! If you use the User Account (e.g. UserA) in the Tapi configuration, then you have to pay attention on it when the user password is changed in myPBX.

3rd Party Configuration

In a  3rd Party Configuration the TSP will work with multiple PBX objects. Typically, you will share a single TSP instance on a server system for use by several users on their desktop PCs. This is done by virtue of a TAPI Server. There are various TAPI server products available on the market, including but not limited to the Estos ProCall product and the remote TAPI server included in Microsoft Windows server operating systems. In this scenario, it is recommended to create a PBX user object for use as the TAPI User. This user is often called _tapi_. You would create a dedicated group to control the list of PBX objects the TSP creates a line device for. This group is often called tapigroup.

Remote TAPI

The TSP is not tested with Microsoft’s Remote Tapi Server. While some installation have reported this to work fine, others have encountered problems. This scenario is not supported by innovaphone. If you using Microsoft's TAPI Server and remote TSP. See Microsoft Telephony service providers overview and Manage Telephony Servers documents. More informations about Microsoft`s TAPI Server and remote TSP do you find on this web pages:  Telephony service providers overview and  Manage Telephony Servers

Multi Site Configuration

In a system with . multiple PBXs, the TSP needs to connect to each of the individual PBXs

In this case, you would specify your master PBX as PBX Master. There is no need to configure the complete PBX tree to the TSP as it is determined dynamically on runtime by analysing the PBX/Node objects in the master PBX and their registration status. If a registered PBX is found, this PBX is added to the list of active PBXs and a new connection is established. The PBX tree is built and maintained dynamically. A reconfiguration or restart of the TSP is not required on changes thus. For this to work

• the PBX/Node objects must be visible to the TSP.
• the PBX object used as TAPI User must exist in each PBX with same properties (including the password)

In a replicated scenario, you would create a TAPI user as recommended above and leave the  PBX and Node properties empty. You can disable slave detection by checking  Do not monitor Slave PBXs property in the TSP configuration dialogue. In this case, you have an replicated Master/Slave szenario and when you press the verify button you see this  pop up window.

Tapi and Dyn-PBXs

Having a master PBX and one ore more dynamical PBXs (dyn-PBXs) at one innovaphone gateway installed, the TAPI will work for the master and dynPBX.
To have TAPI talk to a dynamic PBX, you would specify the IP address of the Master PBX, and not the internal IP: 127.0.0.1!
The TAPI driver will then talk to the dynamic PBX on that IP address.

Tapi Line Names

Tapi Line Names

The innovaphone tapi handle several Tapi Line Names. Innovaphone Tapi has three different default values: Name, Number and Nickname.

 Name

 Number

 Nickname

As you can see in the three images, the characters changes. The default pattern is %C (%x).

You can specify a different pattern by changing the TAPI Line Namesproperty of the TSP configuration dialogue.

These  replacement characters are available.

The Tapi line name is relevant for each CTI application, because the client announced this characters as line name!

Sample Use specified template: Toni`s  client appear only Name and Number.

Modifier Flags

Remember, each user object device is represented as a TAPI line, but some users has two phones registered. User objects with multiple registration could have many phones registered to it, but only one could be used as TAPI line. Normally the first registration will be used as TAPI line device for example: User Toni use two devices IP222 and IP110. Both phones registered with its  hardware ID.

Map PBX Devices to Lines

When Toni want to select its lines via CTI Client (IP222 and IP110) then you have to enable the checkmark Map PBX Devices to Lines in the Tapi application.

This now allows to select individual registration devices when multiple devices are registered with the same PBX. Example: User Toni can control both phones  (IP222 and IP110). If you install an tapi with CTI application and the customer use multiple registrations apply this checkmark in your Tapi task.

Use pure Node Extensions

when you use an E.164 concept, and your user run in an numbering node tree, than you can change the algorithm so that only the objects  own Number is used.

Show full E164 Numbers

when set, the TSP will announce the full calling number from the root when indicated by the PBX in the TAPI calling party name attribute. The number will be appended to the calling name with an  @.

Do not monitor Slave PBXs

You can disable slave detection by checking  Do not monitor Slave PBXs property in the TSP configuration dialogue. Sometimes is this feature useful for troubleshooting.

Map Presence Status to TAPI Lines

if set  Map Presence Status to TAPI Lines the TSP will create one extra TAPI line for each PBX device object.

For more information about presence refor to  Enhancements.

Installation and Configuration

Installation

• Install the Windows TAPI Driver from the  Recommended Tools and Firmware for this Course download page on your PC

• select and download the setup32-release.msi install packages on 32bit platforms or the setup64-release.msi install package on 64bit platforms.
• double-click the install package to launch the  installer

•  accept the license agreement
• select the  target folder note: all generated log files are also trasmitted to the installation folder, be sure that you have enough storage for saving log files.
• confirm the  Installation

When the installer has copied all files to the target machine, you need to add the TSP to the machine's TAPI system

• open the Telephone and Modem control panel
• Switch to the rightmost tab (Erweitert/extended)
• Click on the  Add button (Hinzufügen)
• Select the  innovaphone TAPI provider driver and press the Add button (Hinzufügen)
• Fill out the configuration dialogue -> the configuratin will be discussed in the configuration tab

• Install the provider by clicking Verify and OK

In any case we want to refer to the  TAPI Service Provider for further information.

Configuration

For the Tapi applikation to work, you need to setup a  tapi user with an password, group and rights in the PBX. The Tapi User is an active group member, and all other user Objects are passive in this group. The PBX object you use as TAPI User needs to have at least Viewing only PBX User Rights. Its Long Name property is used as TAPI User Username, its Name property as PBX Account and the password as PBX Password. This is why the PBX object used as TAPI User must have a password configured.

The TSP and Tapi User configuration dialogue looks like this:

Master: set the Master PBX IP Address

Standby: if you use an Standby PBX set the Standby PBX IP Address

Account: here you configure the PBX  User Object (Name).

The  Verify button will verify the configuration. Note that the Username drop down list will only be populated after a successful  verify.

when this configuration is correctly, than you can chose your TAPI User

when you press the VERIFY button again than yo see that the configuration to your PBX is  ok

but if you see this  window than is the Trunk Line Object not in the tapi group. Many CTI applications support distinct call forwards for internal and/or external calls. The TSP will translate such requests to a call forward on the PBX which has the Only or Only not property set to the number of the trunk line. For this to work, it needs to know this number. To know the number, the trunk line PBX object must be seen by the TSP (see above). If this is not the case, the TSP configuration dialogue will issue a  warning

In a first party scenario, this is obviously not the case. If you don't care, you can safely ignore this issue. Attempts to set such call forward will be rejected then as operation unavailable.

The OK button will save the configuration.

The CANCEL button will quit the configuration without saving any changes. If it is the initial configuration while you add the TSP via the telephone and modem control panel, the TSP will not be added

TAPI talks to the PBX using SOAP which in turn uses HTTP for communication. Both secure (https) and non-secure (http) communication is supported. In any case, HTTP basic authentication is used. To be able to connect to the PBX, the TSP needs to know proper credentials to use during HTTP authentication. These are referred to as PBX User and User Password. Also, a suitable TAPI User must be selected.

if you configured the tapi and PBX config correctly you see in the  PBX/SOAP tap the SOAP connection.

Standby Configuration

In a system with standby PBX for the master PBX, you need to specify thePBX  Standby IP address. This will be connected if the master is unavailable. No special configuration is needed to configure slave-standby PBXs.

Upgrading to a newer Version

If you want to upgrade the Tapi to a newer version, please read the refer wiki article  Upgrading to a newer Version

Uninstalling the TSP

If you want to uninstall the TSP, please read the refer wiki article  Uninstalling the TSP

Outgoing Dialling Devices

You can choose also a Waiting Queue as line, and it's possible to start a call from one WQ to an other User Object.  Waiting Queue

Potential usecase may be a call-center or hotel-application.

Example for a hotel TAPI application:

• WQ with an announcement for friendly wake-up call.
• the Tapi application calls an hotel guest at 07:00 clock and the guest hears this friendly wake-up call.

Tapi Phone Dialer

Phone Test App

Another way to verify that the TSP is installed and configured properly is to use the TAPI Phone Dialer. TAPI Phone Dialer is an application that helps you to diagnose problems with CTI via TAPI. The Phone Dialer application enables users to place and receive calls from any computer (PC) to any phone. The Phone Dialer has a user friendly interface, easy installation, and many more exciting features.

You will find this Phone Dialer application in your installed  tapi folder. You can also download the Phone Dialer from  this web side.

The program is called  Ephone.exe

How to use the Phone Test App

Assume you're using a 1st party scenario, and  UserA is configured as TAPI User

• Start Ephone.exe
• Select your Device as  UserA (sifi) and press  Start Session button. 
• Now it's possible to start and receive calls via the phone dialer. Enter the phone number that you want to call in the Phone#: field and press  Make Call.
• When the call is established you can  Hold, Transfer, Park, Forward, Hangup the call and much more...

In an 3rd party or Multi Site Scenario it's the same termination like mentioned above. The only difference is that you can chose any device that you want to  control.

Example: UserA call UserB via Phone Dialer. Both subscribers are using the  TAPI Phone Dialer.

TSP Control and Troubleshooting

How to use the TSP Control

With TAPI version 8 it is possible to enable certain trace flags for TSP analyse and troubleshooting. If the TSP still doesn’t work, you need to have the TSP generate trace files. With TAPI V8 you can start the TSP Control application (tsptray.exe). You will find the  TSP Control application in your installed tapi folder. Upon starting tsptray.exe a new icon (innovaphone fish) will appear on the desktop menu:

Hovering over this icon will show a tool tip, indicating the TAPI TSP and Windows TAPI Service status:

Indication of a non-operational TAPI TSP is shown like below:

Indication of a non-operational Windows TAPI service looks as following:

 Image Course Data/TAPI/Troubleshooting/service.png

Right-mouse click on the icon  (innovaphone fish) provides various options:

• Open Config - setup of trace options - see next sub-chapter
• Start Telephony Service - pressing this button starts the Telephony Service
• Stop Telephony Service - pressing this button stops the Telephony Service
• Exit TSP Control - close the tsp control application tool. (note: but not the TSP service!)

Troubleshooting

Upon selection of  Open Config a new window appears with several  Tracelevel flags.

One can set Set Recommended | Set all | Clear all | trace flags. Most often it's enough to set the recommended options but sometimes it could be helpful to set the logging options in TSP Control manually. Don't forget to press afterwards Update Settings and Exit. Now recommended trace flags are active.

The TSP will write trace messages to C:\…\innovaphone\innovaphone® PBX TSP\tsp-''xxxx-xx-xx-xx.log''  Log files on an hourly basis by creating a new file each.

The TSP will keep 24 log files (one day) by default. This value can be changed using the  NumLogFiles value. Older log files will be removed. Also, when the TSP shuts down, the retail version will remove all log files which have been created so far. However, any TSP will only remove log files created by itself. This ensures that if the TSP or the system terminates prematurely, the log files will be kept even if a new instance is started and terminated later on.

 Logging options:

• removes all log files on termination
• keep last n log files (depending on NumLogFiles) on termination
• keep all log files, no log file termination.

In  TAPI TSP Control with Windows7 further special notes can be found. For more informations about  Debugging and  Troubleshooting please refer to the wiki articles.

Monitoring TAPI Lines

The TAPI application also includes an TAPI Line Monitor. Sometimes this is helpful to control the TAPI  LINE_CALLSTATE. The tool can be found in the installation folder as well.

Windows Event Log

Event Viewer is an advanced tool that displays detailed information about significant events on your computer. It can be helpful when troubleshooting problems and errors with TAPI and other programs. The Event Viewer is opened by following selections: Start button > Control Panel > System and Maintenance > Administrative Tools and then double-clicking Event Viewer.? The TSP will write messages of type INFO (informational messages) or WARNING (Warnings/Errors) to the windows event log. Such events are always logged to the application log and event source is the provider name (innovaphone® PBX V8 TAPI Service Provider).

Example on how a TAPI trap may look like:  Windows Event Log

The TSP will write crash dumps to the log directory in case of a trap. Please provide these files to innovaphone support if requested. A crash dump file will be called something like TSP8-build-hour#minute-day.month#seqnr.dmp (TSP8-8140-14#17-17.04#1.dmp)