innovaphone wiki - User contributions [en]

Howto:License Master

2015-10-13T12:02:03Z

Msr: /* Applies To */

{{3rd Party Input}}
==Applies To==
This information applies to

Build V9 and later.

==More Information==
As PBX hosting provider or in large configurations it is of interest to implement a centralized license management.

The advantage of this, new license can be added without to have reset the master PBX.
From one pool of licenses various of master PBXs can be distributed.

A central licensing server instance is needed thus. This can be run on the master Kerberos server or on a seperate hardware without previous PBX function. All licenses purchased by the PBX hosting provider are installed here. The license server runs as Master-PBX. The only task for this PBX is to host the licenses and distribute them to the Frontend and Media PBXs, which are registered as "License only" slaves and will further distribute the licenses to the customer PBXs.

Following screenshot shows the structure and relationships

[[Image:License_Master.jpg]]





[[Category:Howto|{{PAGENAME}}]]

Howto:Firmware Upgrade V9 V10

2015-04-24T09:01:58Z

Msr: /* myPBX */

== Applies To ==
This information applies to:


* All PBX devices
* All DECT devices
* Linux Application Platform

== Configuration Changes ==
=== Registrations with H.323 and there is no matching Device ===
According to [[Reference9:PBX/Objects]], registrations must not be possible if there is no matching ''device'' entry in the object. However, up to V9 it was possible to register if the ''H.323 id'' matched with the user entry. Such registrations will not be possible with V10 any more.
=== LLDP is enabled by default ===
From version 10, LLDP is implemented and enabled by default for all the Ethernet interfaces and can be disabled. If a V9 device is connected to a switch that offers VLAN settings via LLDP, then this was ignored in V9 and will be honoured after an upgrade to V10. Unfortunately, this will change the VLAN the device uses and thus may inhibit IP access to the device after the upgrade.

You should disable LLDP before the upgrade thus. If this is not possible, you may connect to the device using the other ETH interface to disable LLDP. If this is not possible either, you need to connect the device to another switch w/o LLDP prior to the upgrade, disable LLDP after the upgrade and then put back the device to the original switch.

== XCapi ==
For some time now we do recommend to use SIP to register an XCapi client with the PBX. For more details, see [[Howto:XCAPI]]. XCapi installations which used to work with pre-V9 PBXs using H.323 may stop working with V10. Changing the registration to SIP however may fail, if the XCapi used is old. You may need to upgrade to a recent XCapi version (pls. refer to XCapi support for details, we have seen version 3.4 work fine).

== Upgrading Linux Application Platform ==

There is no upgrade hotfix/package available, as we have upgraded to the latest Debian distribution and changed other things, which prevent an easy upgrade. So you have to set up a new Linux Application Platform V10 with Reporting V10. 
To keep your configuration and data, perform the following steps:

* Save your Application Platform configuration files (see [[ Reference10:Concept_Linux_Application_Platform#Save_configuration_files.2Fdata | Concept Linux Application Platform]])
* Save your Reporting configuration and data (see [[ Reference10:Concept_Reporting#Backup_and_Restore | Concept Reporting]])
* Save your files from your Linux Application Platform webdav folder
* Install the current Linux Application Platform V10
* Install V10 Reporting and further applications, if needed
* Restore the saved configurations and data (see [[ Reference10:Concept_Linux_Application_Platform#Restore_configuration_files.2Fdata | Concept Linux Application Platform]])
* Copy your webdav files to the new webdav folder
* Reconfigure relay hosts under Administration->Relay Hosts (formerly known as SMTP Relay)

=== Reporting Replication ===
* Perform the above steps for the standby server too
* disable replication on master and standby afterwards!
* reconfigure replication on master and standby

=== Upgrading from beta/rc? ===
Sorry, you have to perform the steps from above too! And you can't restore faxserver/exchange configuration/data files. You'll have to configure the servers again!

==Known Problems==
=== myPBX ===
Mixed V9 V10 myPBX chat conversations (as may occur when a large multi-slave site is upgraded step by step) are not supported.

myPBX needs a license in v10.

=== phone precence ===
Presence state "Meeting" did not work anymore wehn upgrading from V9 to V10.
With Version 10 we Removed "Meeting" from default set of presence activities to match myPBX.
Set of presence activities can be adjusted with /presence-mask. ( see [[ Howto:How_to_use_Presence_on_the_telephone#Presence_Mask | Presence Mask]])

=== Versions / hotfixes ===
We strongly recommend not to omit a version during a upgrade

I.e. Don't upgrade from v7 directly to V9 or V10

Upgrade only step by step to the next versions highest hotfix.

v7 (latest hotfix) -> v8 (latest hotfix),

v8 (latest hotfix) -> v9 (latest hotfix),

v9 (latest hotfix) -> v10 (latest hotfix)

=== Old Phone Models ===
Some of the older phone models (namely IP110, IP150, IP200A and IP240) are not capable of running the complete V10 firmware due to memory restrictions. There are a few firmware versions with limited feature set available which still run on those models:

{| border="1"
|-
| '''FW-name '''
| '''Display* '''
| '''SIP'''
| '''H.323'''
| '''PPP'''
| '''Video '''
| '''Note '''
|-
| ipxxx
|
| no
| yes
| yes
| yes
| no SIP
|-
| ipxxx-sip
| ps
| yes
| no
| yes
| yes
| no H.323
|-
| ipxxx-no-ppp
| hs
| yes
| yes
| no
| yes
| no PPP
|}

''xxx'' stands for the phone model (110, 150, 200A, 240). 
''*'' Abbreviation displayed in the ''General/Info'' screen next to the version-number

So if you do not need SIP on the phones, you can still use the normal firmware file (e.g. ''ip110.bin''). However, if you need SIP, you need to decide on which feature to drop and use the respective firmware file variation. This may have some effect on your update scripts.

IP110, IP200A, IP230 and IP240 do not support midi-ring tones any more. RTTTL still works.

== Related Articles ==
*[[Howto:Guideline V5 to V6 upgrade]]
*[[Howto:Upgrade Issues V5 to V6]]
*[[Howto:Firmware Upgrade V6 V7]]
*[[Howto:Firmware Upgrade V7 V8]]
*[[Howto:Firmware Upgrade V8 V9]]

[[Category:Howto|{{PAGENAME}}]]

Reference:IP1202/IP1203 DECT System

2014-11-19T15:15:04Z

Msr: /* Admin Menu */

This article describes the new IP1202 DECT system, differences to the IP1200, the migration policy and provides further helpful information.

==Applies To==
This information applies to:

*IP1202
*IP1202e
*IP61
*IP63

It touches:

*IP1200
*IP52
*IP54
*IP55
*IP56
*IP64

==Product Availability==

===IP-DECT base stations===

The '''IP1202''' (50-01202-001) is ready for order since April 2012.

The '''IP1202e''' (50-01202-003) with two external antenna connectors and two included dipole omni directional antennas will be ready for order in Q4/2012.

The '''IP1200''' can be ordered until supplies run out.

The '''defective IP1200''' devices can be repaired via RMA process until 05/2014.

===IP-DECT Repeater and Antennas===

The IP-DECT Repeater '''for IP1200''' and External Antennas can be ordered until 05/2014.

'''IP1202e''' includes two dipole omni directional antennas. Directional antennas have to be ordered separately depending on the use case. Following models will be available for order soon:
* DualDirectionalAntenna (50-01202-004)
* DirectionalSingleAntenna (50-01202-005)
* OmniDirectionalSingleAntenna (50-01202-006)

===DECT Handsets and Accessories===

The DECT handsets '''IP61''' (50-00061-001) and '''IP63''' (50-00063-001) are ready for order since April 2012.

The DECT handsets '''IP52, IP54, IP64, IP55, IP56''' can be ordered until 05/2014 ([http://www.innovaphone.com/en/press/newsletter/news-2014-05.html not available anymore]).

For the new DECT handsets IP61 and IP63 following chargers are available:
* simple charger (50-00060-002)
* programming charger (50-00060-003)(DC4-AAAB/3B) for administration purposes (via WinPDM)
Please be aware of the fact that chargers have to be ordered separately and are not part of the handset!

==Compatibility Statements==

===No Base Station and No Handset Compatibility===
The IP1202-based IP-DECT solution is '''not compatible''' to IP1200 based IP-DECT solution.

The ''old'' DECT handset IP50, IP52, IP54, IP55, IP56 will '''not operate''' on ''new'' IP1202-based IP-DECT system, since not only GAP compliance is required, but also CAP compliance (DECT external handover CAP-N.1).

The DECT handset '''must support GAP and CAP''' for operation on IP1202 based DECT system.

The ''new'' DECT handsets IP61 and IP63 will '''not operate''' on ''old'' IP1200 based IP-DECT system.

The ''new'' DECT base stations IP1202 and IP1202e '''can not be used''' to extend an existing ''old'' IP1200 based IP-DECT system.

=> This means '''NO HANDOVER''' between different systems (move with active call on a specific handset from an IP1200-system to an IP1202-based-system or vice versa)

=> This means '''NO ROAMING''' between different systems (usage of a specific handset in a non-compatible IP-DECT system - see above)

=== Mixed Ascom/innovaphone Environments ===
It is generally not supported to mix Ascom and innovaphone DECT products in a single installation, e.g.

* Combination of IP1202/IP1202e and Ascom IPBS2 base stations is neither allowed nor supported
* Usage of IP61/IP63 with Ascom IPBS2 based networks is not supported
* Usage of non-innovaphone handsets in IP1202 based networks is not supported
* Usage of IP61/IP63 with Ascom Alarm/Messaging Server (ex:UNITE) is not supported

The one and only exception to this is use of the Ascom d81 which may be operated in an IP1202 environment.

===No Multicell License Required===

The Multicell License is obsolete for IP1202-based IP-DECT systems.

For IP1202-based IP-DECT systems a SARI (Secondary Access Right Identity for DECT) certificate is required. The SARI activates an IP-DECT Master based on IP1202. One single SARI certificate is required for a single IP-DECT system, regardless how many base stations are used. Also for IP-DECT systems with one single base station a SARI certificate is required. The SARI certificate is not an innovaphone license and only required to make sure the DECT Radio Fixed Part Identity used in the DECT system is worldwide unique one.

A Multicell License can not be converted to a SARI certificate (and there is also no need to do so).

===Repeater and External Antennas===

There are '''no DECT repeaters available with IP1202''' based IP-DECT solution. Only IP1202-based base stations must be used.

The DECT repeaters for IP1200 are '''not compatible''' to IP1202/IP1202e.

The '''IP1202''' has no possibility to connect external antennas.

In case external antennas are required, the '''IP1202e''' has to be used. The IP1202e has '''no internal''' antennas.

===Certifications and Test Reports===
The innovaphone PBX was tested and certified by Ascom Wireless Solutions with Ascom IPBS based IP-DECT System, on which IP1202 is based (but is not the same product). A [[Media:Innovaphone PBX and Ascom IP-DECT certified by Ascom.pdf|Certificate]] and a [[Media:Innovaphone and ascom DECT Report.pdf|Test Report]] of this certification are available for download.

==Training and Deployment==

===Site Survey Kit===

The Site Survey Kit for IP1200 is not compatible to IP1202, since the battery voltage is to low for IP1202.

The Site Survey Kit for IP1202 contains a battery case for 20 AA/LR06/Mignon standard cells. Any alkaline 1,5 Volt AA batteries can be used and will provide power supply to an IP1202 for 16 hours. As alternative, 20 rechargeable NiMH AA cells with 2000 mAh capacity at least can be used instead and will provide power supply for 10 hours.

The Site Survey Kit will be delivered without IP1202 base station and DECT handsets, instead the base station and handsets from the new DECT Training Kit can be used.

Also a headset for DECT phone with microphone on boom is a part of the Site Survey Kit intended for ongoing monitoring of the voice quality.

The survey kit can be purchased at your Distributor. The recommended retail price is EUR 450,00:

innovaphone article number: 50-00060-022
DECT Deployment Kit
consisting of:
* batterypack for 20x AA batterys (without batterys and charger)
* a case for the IP1202 (without IP1202)
* tripod
* headset

===DECT Training Kit===

To be able to attempt to the optional DECT Training Topic in the Advanced Training a DECT Training Kit must be ordered.

The DECT Training Kit contains:
*IP1202 x 2
*IP61
*IP63
*Charger for IP61/IP62/IP63
*USB-Programming Charger for IP61/IP63

This kit is referred to as ''Trainingspaket 2 (DECT)'' or ''Training Pack 2 (DECT)'' in the price list. Pleas note that this kit needs to present ''in addition'' to the regular training kit.

===Parallel usage of IP1200 and IP1202 IP-DECT systems===

The operation is only possible as two independent systems. No handover or roaming between the systems is possible. An IP1202-based system can and should synchronize the TDM clock with IP1200 based system to avoid interference.

==Migration Policy For New Projects==

The information in this chapter is only a suggestion which devices to use while plan new DECT projects. No mixing of old and new handsets or base stations is possible in the same project.

===Handsets===

{|border="2" cellspacing="4" cellpadding="3" rules="all" style="margin:1em 1em 1em 0; border:solid 1px #AAAAAA; border-collapse:collapse;empty-cells:show;"
|+ DECT Handset Features Matrix
! DECT Handset !! [http://en.wikipedia.org/wiki/IP_Code IP Code]/[http://de.wikipedia.org/wiki/Schutzart Schutzart] !! Headset Connector !! Bluetooth !! Color Display !! Suggested Replacement
|-
| innovaphone IP52 || - || - || - || - || innovaphone IP61, IP63
|-
| innovaphone IP54 || IP54 Dust protected, Splashing water protected || YES || - || - || innovaphone IP63
|-
| innovaphone IP64 || IP64 Dust tight, Splashing water protected || YES || - || - || Ascom d81 Ex
|-
| innovaphone IP55 || - || YES || - || YES || innovaphone IP61, IP63
|-
| innovaphone IP56 || - || - || YES || YES || innovaphone IP63
|-
| innovaphone IP61 || IP40 Object size >1 mm protected || YES || - || - ||
|-
| innovaphone IP63 || IP44 Object size >1 mm protected, Splashing water protected || YES || YES || YES ||
|-
|Ascom d81 (1) || IP65 Dust tight, Water jets protected || YES || YES || YES ||
|-
|Ascom d81 Ex (1) || IP65 Dust tight, Water jets protected || YES || YES || YES ||
|}

Remark (1): When operated within an IP1202 or IP1202e based environment, telephony features of d81 and d81ex are equal to the ones of the IP63. Ascom-special telephony features as mentioned in the Ascom-d81-family-datasheet are not applicable in this use case.

===Base Stations and Repeaters===

The IP1200 Base Stations and all kinds of DECT Repeaters for IP1200 are replaced by IP1202, cause no repeaters are available for the IP1202 based IP-DECT solution.

==DECT System Feature Comparison==
This chapter describes the differences in the feature sets between old and new DECT systems.

{|border="2" cellspacing="4" cellpadding="3" rules="all" style="margin:1em 1em 1em 0; border:solid 1px #AAAAAA; border-collapse:collapse;empty-cells:show;"
|+ DECT Handset Features Matrix
! Feature !! IP1200 based DECT system !! IP1202 based DECT system !! Description
|-
| Registration on 3rd Party IP PBX || YES || NO || IP1202 can only register on innovaphone PBX
|-
| Messaging || [[Howto:Legacy_Method_to_do_DECT_messaging_with_IP1500%2C_IP1200_and_IP600|YES]] || NO ||
|-
| Repeater || YES || NO ||
|-
| External Antennas || YES (on repeater) || YES || with IP1202e
|-
| Non-EU DECT Frequencies || YES || NO || Required for North America, Brazil
|-
| Number of Speech Channels per Radio || 10 || 8 ||
|-
| Max. Number of Radios || 255 || 1000000 || with multiple Mobility Masters for IP1202
|-
| Max. Number of Subscribed Handsets || 1500 || 1000000 || with multiple Mobility Masters for IP1202
|-
| Sync Master Redundancy || NO || YES ||
|-
| Distributed PBX Support with Roaming || NO || YES || In a Master Slave PBX scenario it is possible for DECT Handsets to roam between sites
|-
| Automatic DECT Sync Configuration ||NO || YES || Compared to IP1200 DECT sync, IP1202 is more reliable and stable
|-
| GAP Compatibility || YES || YES || Although both systems are GAP compliant, innovaphone does only support innovaphone handsets used either with IP1200 or IP1202
|-
| CAP Compatibility || NO || YES || IP61/IP63 handsets will always do "external handover" as per CAP (DECT external handover CAP-N.1) between IP1202. GAP-only-compliant handsets will thus not work
|-
| DECT Encryption || NO || YES || DECT Voice Traffic is encrypted between IP1202 and IP61/IP63
|-
| Run innovaphone PBX || YES || NO || On new IP1202 you could not run as innovaphone Master or Slave PBX.
|-
| DECT Security || NO || YES, step B is in preparation || Step B is expected to be published during Q2 2012, see also [http://www.dect.org DECT Forum]
|}

== Usage in non-EU countries ==
The IP1202, IP1202e, IP61 and IP63 can technically be operated in most countries of the world, as the hardware supports all relevant DECT frequencies (software configurable). However, the devices are approved in EU/EFTA states only! Use in other countries will probably be illegal thus.

== Test-SARI ==

DECT Systems are using a worldwide unique system identification (SARI) to be separated from each other.

For test and training purposes, innovaphone offers the following SARI:

31100422072149

This SARI is intended for use in test/training systems only!

'''Usage within productive systems is prohibited and not recommended.'''

If the SARI is changed, all handsets have to be subscribed again.

DECT systems which are near to each other and are using the same test-SARI, may disturb each other.

==DECT Service Codes==

===IP61===
*#34# - Displays the Device Info
*#06# - Displays the IPEI/IPDI

===IP63===
*#34# - Displays the Device Info
*#06# - Displays the IPEI/IPDI
*#77# - Site Survey Tool

===Admin Menu===

The handset has a hidden menu for system administrators. The Admin menu contains:
*Software and hardware information, IPEI/IPDI, and User ID
*DECT link and system information
*Site survey tool
*Fault logging
*Enhanced system menu with ability to alter protection
*Factory reset option

To activate the Admin Menu, enter the Call time screen via "Menu->Call list->Call time" and press <code>> * < < * <</code> .

===Known Problems===
Internal ring tone after external call is blind-transferred to C, which does not save external
number in call list (per IPBS design)

File:Upc SIP Account.png

2014-08-08T11:13:13Z

Msr:

File:SIPProviderUPC austria.PNG

2014-08-08T10:45:14Z

Msr:

File:Upc routes.png

2014-08-01T08:33:37Z

Msr:

File:Upc numbermap.png

2014-08-01T08:31:20Z

Msr:

File:Upc Trunk.png

2014-08-01T08:28:33Z

Msr:

File:Upc SIP.png

2014-08-01T08:19:15Z

Msr:

Reference10:Concept Voice Recording 2014

2014-01-15T11:07:51Z

Msr: /* Recorder */

The innovaphone Voice Recorder application allows recording while the innovaphone Player application a comfortable search and playback of phone calls.

All kinds of calls can be recorded:

*Incoming calls

*Outgoing calls

*Calls from innovaphone IP Phones

*Calls form 3rd party IP-Phones

*Calls from IP-DECT phone sets

*Calls from analogue phone sets

*Calls from with mobile phones (mobility, forking)

*Calls done on a legacy PBX (soft migrations scenarios)

The solution requires an innovaphone PBX, the recording toll and two applications;

*a recording tool described in this document called “Recorder”

*a search and playback tool called “Player”.

The usage of the Player is not part of this description, a separate localized help and user manual is available.

While the recorder (this description) has to be installed by professionals and the maintenance is done by system administrations people (and therefore English wording and this description is good enough) the player is operated by End user and may be not digital native, skilled or knowledge base workers.

Note also that the setup of the player is a typical admin job and not described in the player manual.

== Feature list ==

=== General ===

• Using an innovaphone IP-Phone set immediately after call end the recording can be listened using the phone. One feature key stroke and the conversation is reproduced and repeated endless (auto replay). This call can also be transferred or put in a 3 party conference (immediate sharing)

• Online Help and tooltips for application and setup

• Setup password protected, setup files are encrypted

• Recorder in Demo Mode (20 minutes) , Player for free

• Many recorder in one system and unlimited number of players

=== Recorder ===

• Recording of any type of calls direction

• Recording of calls from any device: IP-Phones (innovaphone and 3rt Party), analogue phones, GSM (mobility), IP-DECT

• Recording of calls from/to legacy PBX (smooth migration)

• Recording can be done in a logical gateway or direct from a innovaphone phone set

• Recording of encrypted calls

• Standard und thread call recording. If thread call recording is on after a settable time period (for example 5 minutes) a call will be automatically deleted. If the user calls inside the time period a code the last call will be saved. This marking to keep the recorded call can be done from any type of phone. If the phone is a innovaphone IP Phone the marking can be done also during conversation

• Storage of all relevant data including the time to answer for each call

• Detail protocol of each call, documentation of the entire call flow, not just the recording period but even previous and following one. Detail report on all call situations, transfer, call forwarding, pick-up, group call, conference etc. Also calls in waiting queues or announcements are reported with second accuracy

• Encrypted protocol data

• Display number of channels in recording with start timestamp

• Error and Event log files

• Email alert in case of master alarm

• Automatic backup (copy to mass storage archive)

• Automatic delete of records older than 2-99 month (not on archives)

• Recordings are saved as wave files, can be reproduced with any player

• Wave data integrity supervision

• File name contains primary data (Timestamp, Caller and called, direction, time to answer, UID)

• Counter of recorded conversations

• Data Link to player, remote control of the recorder from player

• Interface to external applications, via TCP or URL, recorder provides data for later retrieving. Player can be controlled sending commands to the recorder (3rd party)

=== Player ===

• Integrity of the recorded wave files are recognized and displayed

• Agent note, a Player displays automatically agent notes and can add text notes to each call

• Integration with iQM server, display of missed calls, possibility to recall immediately

• Naming of Players

• Month and Day filter

• Filter for internal and external number with wildcards

• Filter for incoming and outgoing calls

• View of oldest or newest call on top

• SOS mode can be switched on/off with just one click. If on all unnecessary key are hide, the newest calls are displayed on top of the call list and filters are switched off

• Selection of calls, one single call, more single selected calls, from to, all

• Online search and display, can be switched off

• Copy, move and delete of calls

• Move and delete operations are logged in centralized manipulation log

• Permissions

• Multiple selected calls can are transferred automatically in a playlist and can be reproduced

• Display record size

• Display number of records in playlist and actual play

• Jump forward and backward in playlist

• Jump to next/previous title in search result list if playlist contains just one record

• Marc record in playlist, select actual record and clear all others

• Play one title after the other in playlist

• Play a beep if record change in playlist (loop playlist)

• Repeat play (loop record), up to 4 positions, stored automatically

• Repeat play of all stored memory positions

• Display internal and external number with name resolution

• Display timestamp, time to answer an call ID

• Display System and Player status

• Display if local remote control interface is on

• Display of play was forced be recorder remote control

• Keys for Stop, Play, Fast Forwarding, Rewind, Pause and Eject

• Display duration record

• Display elapsed time or count down, switchable

• Original time elapsing display

• Progress bar adjustable, direct jump to selected position, drag and drop

• Start and Stop position can be marked an played in loop (selection loop)

• Volume control with audio meter and peek indication

• Delta level Indication (L-R and R-L meter)

• Overflow level audio meter

• Enhanced sensitivity for audio meter

• Attenuation left and right cannel adjustable

• Audio setup can be stored and recalled

• Audio level at maximum

• Levels are stored and set on restart

• Level meter with peek indicator for left and right cannel

• Mute

• Large additional display with call details

• Automatic decryption if files are copied

• Player can be limited to display just calls of one extension

• Communication with recorder, display of link status, last master alarm and cannels in recording

• Reset recorder from player

• Search an play on backup directories

• Operate as Media player, reproduction of audio format wav, mp3, wmp and video format avi, wmv, mp4 and mpg

• 1rst and 3rd party remote control

• Document security, manipulation is detected and displayed

== Scenarios ==

Recording is possible on each logical Gateway and therefore on external lines (ISDN, SIP or H323 Trunks). In theory “external” is just a convention, even internal calls passing through those gateways could be recorded, but this is more a theoretical issue. An innovaphone gateway can also be used as a “recording” bar and introduced between a legacy PBX and the PSTN. Remember anyway that the innovaphone PBX must be activated and the Reporting tool is required.

Being recording defined on a logical Gateway opens different options, for example activate recoding just for a dedicated route. For example just for incoming calls or just for some outgoing calls. Typical examples for such a setup are business and private calls, where just business calls should be recorded. For example if a call is done using “0” as prefix recording is done, using “9” not.

Or normally (“0”) no voice recording is done, but if a user access to a trunk with a particular prefix (“9”), recording is on. This for example is widely used in selling contracts by phone (like mobile phone carrier do); they call the customer and if the customer agrees in the commercial proposal to extend or to “sign” the contract they will call back the customer again using another prefix and record now the conversation.

Recording rules can also be executed automatically because configured in the gateway setup. For example you can exclude certain user from recording or vice versa, doing recording just for some users. For example all calls to the financial operators are recorded, all other calls not. Or all users are recorder but the management not.

All that is a question of setup in then innovaphone gateway (and PBX) and not described in detail in this document, being standard features and described in many other articles (and being part of the advanced technical training).

Please note that recording starts when a connection is established and terminates when the connection is terminated. That means that eventual waiting situations in waiting queues, music on hold sequences calls etc. are recorded too.

Keep in mind that each extension that should be recorded must be active in the reporting, means require a recording license. Even if you operate a soft migration you must go up in the PBX to a dummy user with reporting on and back again down to the relay.

Notes: Recording can be done just in G711A on a logical gateway as endpoint. If you need to record internal calls they must always transit a logical gateway (with the media relay flag on).

The recorded files are in a wave format and can be played with a normal Mediaplayer, the delivered Player allows additional features.

The recorded records are stored in an indicated path and a copy of the records can be done automatically.

Errors and events are stored in a log file and alarms tracked; a mail can be send if an alarm occurs.

It is possible to limit the duration of the storing period; older files will be deleted automatically. This is to avoid disk full errors, keep in mind that this kind of systems usually works unattended all the time.

The number of player and recorder is unlimited.

Recording can be done also directly from the IP-Phone. Doing VR using the IP-Phone has the following advantages or disadvantages; it depends on your point of view and the scenario.

- CPU-Load: No CPU power from the PBX is required, a Phone has enough CPU-Power to do that and more, and therefore it becomes an extremely scalable solution. If you do not use an external WebDAV server but a CF anyway the PBX CPU has some load (playing WebDAV server for the Phone)

- All calls on the phone are recorded (not just those crossing a gateway), so even internal calls (basically everything the phone is doing).

- Al users working on the phone are recorded. This means also that each possible user on the phone must have the reporting license otherwise a call from that user will cause a major alarm.

- Transferred calls to other extensions are after the call transfer no longer recorded. In case of gateway recording it is different, until the call cross the gateway recording is done.

- If you mix both setup in a scenario you should avoid that a Phone is doing recording and cross a gateway doing recording too. If that happen recording is done in two points and you double for nothing disk space and resources (and confuse everybody).

- Only innovaphone IP-Phones IP2x2 series and “A”-types (like IP110A, but not IP110) can performing VR directly.

Switch on the recording has to be done in the phone setup file, there is no menu option. Mode information about that is in the online help of the recorder setup.

== Standard Recording ==

Operating in the “Standard Recording” (STD) mode recorded calls are converted and saved after the call has finished.

A recorder has to operate in one mode (STD or TCR), a mixed scenario is possible using two recorders, setup in this case has to be done very carefully.

== SRTP ==

Recording of encrypt conversation is possible, no particular setup is necessary, the system will decrypt automatically the media stream and store the conversation in unecnryptet wave files for further processing.

== Thread Call Recording ==

Operating in the “Thread Call Recording” (TCR) mode only marked calls are converted and saved, all other calls are deleted automatically.

A call can be marked manually from the user or automatically from his innovaphone IP-Phone. A call can be marked during the call or after call, but within a defined time period (for example until 5 minutes after the call-end). Not marked calls are deleted while marked calls will contain the entire call, so from the beginning on (even if marking is done during or after the call).

Marking calls during the conversation can be done only using innovaphone IP-Phones while all type of phones can mark a call after the conversation. To mark a call after a conversation the user must call a XML object.

In a typical setup the user will hear a confirmation if he is marking a call, something like “the last conversation was recorded and will be saved” or similar.

If marking is done using an innovaphone IP-Phone during the call (pressing the redial key) audio or no audio can be played. For example an automatic advice like “this conversation will be recorded” or similar can be played.

=== Setup TCR ===

This paragraph discusses the different setups and aspects for Thread Call Recording. If you are not interested in those details skip it.

TCR require a XML (TCRec.xml included in the software package of the Last call recording feature, see Related Articles, see Related Articles, go to the article and follow the download [http://download.innovaphone.com/ice/wiki-src#lcr http://download.innovaphone.com/ice/wiki-src#lcr] ), you have to create a directory and copy the xml in, create a VM-Object in the PBX and insert those parameters in the recorder setup (TCR panel). The XML can be called directly or using the recording functions on the innovaphone phones. If called directly the xml will play the audio file Track1.g711a, if called through the recording function of the IP-Phone the file Track2.g711a. If the files are not present the user will hear nothing. A solution for the confirmation could also be to play just a “beep” if calling directly the xml. You could copy the beep.g711a file (for example from the VM) and rename it. A better option is record them using the universal track recording tool, see related articles at the end iof this page.

Some additional information if you use the recoding function of the innovaphone IP-Phone:
Keep in mind that this function will not really recording the voice but just calling the XML (the recoding is done by the Gateway or the phone, but directly and not using this function). As explained the XML will play the file Track2.g711a if present, but to hear the announcement you have to use on your phone at least version 10.0887 or higher and switch on the flag “Two Way Media” in the Recording section of the phone setup. The rest is the usual one, if you setup “Mode=transparent” each call will flagged as “to record”, if Mode=manual you have to press the redial key to flag. No problem if the user presses more than one time the record key, just the actual call will be recorded.

The xml itself will terminate after playing the Tack 1 or 2, delayed for 2 seconds. If the user press the redial key in this way he will see in the display of his IP-Phone appear “Recording” for 2 seconds and has a feedback (even if no tone is played) that the conversation is flagged to record.

== Last Call Recording/Repeat ==

See relative article.

Do not confuse this feature with the Instant Play (rescue mode) feature of the innovaphone Player.

== Overview ==

The recording itself is done by the innovaphone gateway. In each logical gateway a recording path can be configured as a URL; that means that the voice will be recorded in a file, this file can be on a compact flash or on an external WebDAV server. The recorder application copy the recorded file, read out the reporting, combine both, and rename the file. The original file on the compact flash/WebDAV is deleted. The new filename is formed using date and time, caller and called user, direction of the call, the time to answer (ringing time) and the unique ID number. The recorder converts the file from pcap to the wave format and stores the converted file in a directory. If requested a copy of this record can be saved in a second directory (for example a SAN or NAS disk area). A maximum number of storage time expressed in month can be defined, older files will be deleted automatically. In this way no disk space overflow will be in unattended systems. Parallel to the payload (the wave voice file) also a XML file containing the reporting data is created, the name of the file is the same than the one of the voce and just the extension is xml instead of wav. That is basically what the recorder is doing; copy and convert recorded files, retrieve data from the reporting, renaming of the files and copy them to different destinations as well as keeping track of history.

The player allows searching and browsing of records, show the oldest or newest first, can filter the search etc. For example it can be displayed calls in any direction or just incoming or outgoing calls, or calls from a certain number or to a certain number, using even wildcards for quick filter options. See relative description for details. Once the calls a displayed they can be marked using windows usual methods (one, many, all, range, etc.). The marked files can be copy, past, deleted or played in a playlist. A record in the playlist can be marked and the player allows the usual operations of a windows media player. Looping and audio signal before playing the next record in the playlist is included as well as moving inside the playlist from one call to the other. If all that sounds complicated calm down, it is quite simple in using and designed for “users”.

The player can even operate in a mode called “rescue mode” or “direct play mode”. If switched in this mode the latest record is always on top. This is a typical requirement for an emergency center operator, he is interested in replay the last or lasted recordings in a quick and simple mode.

The player shows also the reporting details and generally the most important data of the conversation. If recorded files are copied also the relative reporting information is copied.
Many player can be installed and work in the same moment in a scenario, while the recorder typically is just one. So the recorder is a kind of server and the player a kind of client. More recorders can be installed in a scenario and if necessary a player can be installed on the same PC where a recorder is working. Being the recorder always on usually it will be installed on a dedicated machine doing just that located in the server room.

But remember that the recording job is done as described by the gateway. So even if a recorder application is switched off voice recording is done. The idea anyway is not that the recorder is switched off and just sometimes switched on to retrieve the files. But if you must shut down the application or reboot or enter in setup, no data will lose.

The following diagram shows the logical interfaces between the innovaphone voice recorder, the innovaphone player and the rest of the equipment.

[[Image:Player07.png]]

(*) = Option

The player main data source is the disk where the records are stores. There could be active many player at the same time, and in theory also more than one recorder. One player could monitor just one recorder, but it is possible to start more player on the same PC.

== Requirements ==

=== Recorder ===

The recorder application requires a PC or server with Windows OS Win 7 or higher, also windows server 2008 (Windows 2003 server not tested) or higher is supported.

Disk space: One minute of conversation requires about 1 MB of memory. A lot, but a TB HD today is cheap and for example even a 500 GB Raid 1 external NAS is not real expensive. Typically a recorder should have a Raid system, but remember that the recorder is able to do also a security copy. The copy to an external security drive is possible because in many scenario’s customer has to archive records for many years.
The recorder requires a NTFS file system (no FAT32), usually today a standard on PC.

Some examples: to store 1000 hours a 60GB disk is required, 100.000 hours require a 6 TB Disk, 200.000 hours a 12 TB Disk. On the one hand a Year has 8.600 hours, on the other recording 30 cannel always busy for 10 hours a day for 200 workdays requires 60.000 hour a year. Now if you have this workload (10 hours busy a day on 30 cannels) probably a 16 TB Disk for €1.000 is not a problem.

Remember that on minute require in reality less the 1MB (about 900kB) and it is stereo. Zipping the files reduce about 30%, not really a deal.

No particular memory or CPU speed is requested, standard editions are quite good enough. Invest better in a good quality because in professional environments those machines have to work for many years.

Voice recording requires a Version 10 innovaphone PBX and a Version 10 Reporting tool. No compatibility with older versions is possible. PBX and/or Reporting can run on a gateway as well as on VMware.

The recording of the pcap file is done by the PBX firmware and requires a Compact flash or a WebDAV server. The recorder software will detect those records and copy them on the real storage path. Therefore the storage requirement for the CF/WebDAV not real high (but remember always 1 Minute =1 MB, so if you must record 30 conversations for 30 minutes = 900MB).

Voice recorder and Player could run on the same PC as well one single PC can also be used for the reporting, recording, playing and webdav server (and PBX if you like). So anything on one server is theoretically possible.

The two extreme setups are:

*innovaphone PBX on the GW, reporting on the GW, pcap recording on the CF, recording application on a PC

*innovaphone PBX on the PC, reporting on the PC, pcap recording on the PC, recording application on a PC

Each combination between is possible.

Remember that the CF is a relative slow drive, you will note this if you copy a file from the CF to the local HD of your PC. Exact this file copy is one of the task of the recorder, even a critical one (so not a good idea do anything else in between). The result is that the copy of a huge file (a long conversation) or many files will virtually froze the recorder software. In reality the recorder is just hanging around and waits that the file copy is finally done. So a recording on an external webdav server will solve this, but the CF has the nice flair working even if all PC’s are down. Take your choices and live with them.

=== Player ===

The player application requires a PC with Windows OS Win 7 or higher, the Mediaplayer is necessary. All that on a standard office PC is installed and you have to do nothing in particularly.
Require Framework 3.5.
In theory also a Windows server 2008 could host the player, but in the server versions the media player typically is not installed and there are also different DLL missing. So if you have time or you are well Microsoft server trained face also that if necessary (normally not).

=== Legal Aspects ===

Please take extremely care about the legal issue: in most country voice recording of telephone calls is forbidden and persecuted by law as a crime. In some country it is legal in certain circumstances, for example you have to inform the caller that the call will be recorded. That can be done automatically (using for example a waiting queue) or “manually”, telling the far person that this call will be recorded. Of cause also this announcement should be recorded. In some country recording is legal without any announcement for certain services, for example in case of emergency calls or calls to the police. In most country authority like the secret service do not really care about all that stuff and do what they want, but this is probably not your case.

So inform yourself and the customer about the local legal situation. Using the recording tools is on your own risk and innovaphone will not take any responsibility, even not for eventual malfunctions. See also our general trading terms, valid even for this solution. If you have any doubt about legal questions in using voice recording; don´t do it, don’ use it!

== Installation Sep by Step==

In this and many other wiki articles everything you need to install and operate the product is (hopefully) described. Partners some time have the problem that they could not find a logical flow in the description and the do not realize what is important and what interesting, but not essential.

To help here a simple step by step instruction, all details and comments are in the other paragraph and, of cause, in other articles.

1. Check the Software version of your PBX, it must be 10 or higher otherwise do an upgrade or forget this recording. You PBX must be up and running and to test you need at least 2 Phones.

2. Check that you have a valid license for the recording, if not just a demo-mode is possible, after 20 minutes the recorder stop and you have to restart him again.

3. Your CF should be working fine, create a directory to buffer the pcap files (for example http://123.123.123.123/DRIVE/CF0/IF_REC).

4. Setup the recording gateway, see http://wiki.innovaphone.com/index.php?title=Reference10:Voice_Recorder/Setup#Gateway_Setup . If you want to do a test with internal phones you have to assure that in ca ll from one user to the other this gateway will be involved. Create for example a access code to this GW and flag Media-Relay. If you call this access code followed by the internal number ths should happen. Of cause if you have a real trunk the you will do all that using the relative GW. At the end of the story your call must passing the recording gateway, check it; open you PBX interface, click on gateway and calls: you should see that the call goes through the recording GW. A pcap file will created at the CF directory indicated in the setup of the gateway (the same one you create in pass 3).

5. Start up the reporting (on a xx10 GW or IPVA), it must be up and working, you should be able to see the reports of the call done using the recording gateway.

6. Create SOAP user, a blank empty user object called SOAP (or _TAPI_ or _whatever_)

7. Create a root directory where the recorded files should be stores (for example “c:\mytest\” or “G:\myExternalDrive\”).

8. Now create a directory and put the innovaphone_recorder.exe and the pcap2wav.exe in the same directory (this is done automatically if installation is done with the installer).

9. Start the application and open the setup.

== Installation ==

While the Recorder works “hidden” for the user, the Player has a huge user interface. The Player is typically installed on one or more PC of users. Therefore for the Player more effort to design a foolproof interface was done. The Player description is available, please check the relative section in the innovaphone Wiki.
Recorder and player applications are single executable file. The setup is stored in a xml file located in the same directory where the application is running; no registry entry is done; if you delete the directory where the recorder/player is in, the application is de-installed. If you like install on the same computer the recorder and the player application you have to create two different directories and copy the applications twice. Automatic execution is possible inserting in the auto start directory the recorder application.

Please note that the setup file is in xml format, but his content is encrypted.

The installation tool will copy all reqired files, if you install manually copping file note the following issues:

If you install a recorder application manually you must copy the “pcap2wav.exe” utility in the same directory!

Note: This utility “pcap2wav.exe” can be downloaded in the V7 application folder, access to a directory and download the “tools” Zip file; inside you will find the pcap2wav.exe.
The recorder is not a service because there is a full user interface available. To ensure that the recorder starts up even after a boot put the application in your autostart folder. In the setup an option to start up minimized is available.

Before starting the recorder application check the following items on the recorder PC:

*the directory where the recordings should be stored must be visible and it must be possible to create subdirectories, try using the file explorer

*If backup is requested also a write access to the backup path must be possible (but it is not necessary to be able create subfolders).

*Access to the reporting tool must be possible, use a browser to check

*The access to the CF (or the WebDAV server) must be possible, try to map a drive and access to the directory where the pcap files are

Do the setup the innovaphone PBX, the gateway and the reporting.

See eventually also http://wiki.innovaphone.com/index.php?title=Reference10:Voice_Recorder/Setup#Recorder_Setup for a better understanding of the requirements.

If you do now a call which has to be recorded this call must be logged in the reporting tool and a pcap file must be created in the indicated url path. Go only ahead if that is up and running.

Now start the recording software and open the setup and set the values. An online help will explain the single parameters. Maybe it is also a good idea reading first the rest of this article.

The installation of the Player is similar just simpler. After installing start the application, enter the setup and that its. But it has no sense install or setup a Player without before having a working recorder.

On a single PC multiple Recorder and Player can be installed, simple install and run them on different directories.

=== CPU load ===

The power of the innovaphone CPU on the different gateway models is high enough to ensure the recording of all ISDN cannels (or the same number of SIP/H323 Trunk) on that gateway. If recording is done on a CF the innovaphone PBX CPU will be involved also in the copy operation (if recording is done on an external WebDAV server no CPU load of the PBX for copy is required). After the copy operation no more CPU power of the PBX CPU is required.

The reporting CPU (which is anyway the second core in case of a gateway or a separate CPU in case of VMware) has some small workload because the recorder checks each 5 seconds the reporting.
Using the player will cause no workload for PBX, reporting or recorder CPU, so just the local workstation CPU power is require. Therefore the number of player is practically insignificant for any CPU load.

=== Logging ===

Recorder and the Player applications write an individual error log, this log is a text file and stored in the same directory where the application is. See online help for file names and description of the other files used by this applications.

The recorder can also write a trace file; if tracing option is switched on all operations of the recorder are logged in a file named “iREC_sys_log.txt”. Please not that this files become very large if the option is always on, and this file will not be deleted or resized automatically. The idea is not to keep on tracing all the time but to switch on the trace during the first period or in case of trouble checking.
If enabled in the setup the player stores all special operations in a central log file. All copy, delete and move operations done using the player are in this way stored automatically in a central log file.

A “user operational” log file is in a central point and unique for all players installed. Here all user manipulations done using the player applications are reported, so copy or delete is traced. This file is named “iREC_Player_log.txt” and located in the “\TMP” subdirectory of the root recording directory. In this way all operations of all Player-User are visible at a glance in one single file.

=== Security ===

The setup of the recorder and player is stored in an AES encrypted setup xml file. Therefore the user cannot manipulate or read out setup values. The access to the setup can be protected with a password. If a user deletes the setup file the software assumes that this is a new installation and allows access to the setup without password. If the user enters the correct path for the recording the software read out a centralized password and it is not possible to save the setup without that password. There is no way to read out or decode the password and this means that if you, as administrator, forget the password you have to clear the centralized password and the setup of the recorder and re-configure all. Try to avoid that situation and remember your password.

The centralized password is in the located in the “\TMP” subdirectory of the root recording directory and named “SPlayer.xml”. It is also encrypted of cause.

The Reporting xml data string is even encrypt.

In the first column header of the player a looked/unlooked symbol is displayed showing the encrypt/clear file mode. If (using the player) a encrypt records is copied it will be automatically decrypt, while moving a file (cut and paste) will not change the original file mode. In this way a clear copy of a xml can be done from an authentic encrypted data string.

== Voice Recorder operation ==

The recorder can operate in 3 layouts; minimized in the taskbar, viewing a small window or an extended panel.

[[Image:Recorder01.png]]

Switching between small and large view is done pressing the “>” key, press “_” for minimize.

[[Image:VR010.png]]

=== Start up ===

During start up the basic operational parameter are checked while the master alarm is disabled. The master alarm supervision is just switched on after about 20 seconds. This is necessary because sometimes network operation during start up fails, but becomes up in a second attempt. For example mapping of network drives fails frequently at the first attempt but once up they will remain connected without any problem. The sequence of testing is done by design and the software will not proceed in operation if a parameter fails but continuously try to fix it.

This initial health check during start-up is done in the following order:

*checking setup: try to understand if the setup parameters are reasonable and in particularly if the WebDAV drive or CF can be mapped. If mapping fails the “SETUP” lamp will be red, error message “Setup not o.k.” is viewed.

*checking reporting: pings the reporting, if ping is o.k. try to load a dummy page. If ping or dummy fails the “REPORTING” lamp is red, error message “Reporting Link failure” is viewed.

*checking to access to the recording directory (url): try to read out the indicated path, if fails “PCAP” lamp is red, error message “PCAP directory access fails” is viewed.

*checking if access to the storage path is possible: If reading fails the “DISK” lamp is red, error message “Store path fails” is viewed.

If in the setup no backup path is indicated this last task is skipped and the Backup lamp is grey. Otherwise the access to the path is tested, if access fails the “BACKUP” lamp is red, error message “Backup path fails” is viewed.

If a test is passed the relative lamp becomes green. If after start up 6 lamps are green (or 5 green and one grey) everything is working fine and the message “Normal Operation” is displayed in the System status line.

After 20 second the Master alert supervision is switched to active, an eventual error causes a Master Alarm (see relative section).

=== Normal operation ===

The check counter shows you how many times the recorder reads out the recording directory and checks the reporting. As you see al 5 seconds a reading attempt is done, if data are found further processing operation will start. This counter goes automatically to 0 reaching 9999 and shows you that the software is working and checking but has no further signification.

The counter “Channels in recording” shows you how many recordings are ongoing. The panel shows you the ID of each recording file and the initial recording time. In this way you can see how long a call is jet in recording.

If the call ends it will disappear from the list. If there are more records then default lines a scroll down will automatically appear.

If you click the innovaphone logo the software version is displayed. The version is also displayed in the headline of the setup.

===Extended view ===

If you enlarge the window with the “>” key two additional panels appears.

[[Image:Recorder02.png]]

The left one shows the regular normal operations, the right one the errors and basic messages (like Start-up). The messages displayed of the error panel are stored automatically in an error log file while the messages of the status panel only file if that is enabled in setup. Both windows can be cleared pressing the relative button. This clearage is just an “optical” issue; no file is deleted or similar. Both windows shows up to 100 entries, if entry becomes too large a scrollbar appear automatically. If “full” the oldest message will be cleared. On top the error panel can also display the last 30 Error reading out the error file.

Pressing the “<” key the windows will be resized again.

There is no operational difference between the different layouts. The recording application starts always with the small window stile.

The following picture shows two alarms, Reporting (because there where files without CDR records) and Software (because there was a license overflow).

[[Image:RecXX.png]]

===License===

The license model is based on user, so for each user a license is required. “User” is basically the number (extension) of a user, not the name.

If the recorder is installed between a PBX and a trunk line (soft migration) there will be just numbers. Remember anyway that even the recording must work and therefore for each recording user also a valid reporting licensed is required.

In start-up the recorder will read out the number of recording license in the PBX. If a record is detected and a number associated this number is stored and the license counter decreased. Same numbers will not decrease the counter. If a new number is detected and no more licenses are available the recorder will store this last record normally and stop further operations. Recording in this situation will be buffered on the CF/webdav directory.

The recorder shows the number of license loaded and the number of license used. After startup the “Lic” counter shows the number of license loaded, while the “Used” counter displays initially “0000” and increase if used.

In other word you have to avoid that overflow doing appropriate setup in the routing/PBX.

If an overflow occurs software alarm is triggered, the error log file written, the alarm signaled on the player if enabled, an alarm email is done, a warning triangle near the license counter appears etc.
If you press the “LIC” button the right error table shows the actual status, the number of license, the uses one and the number (user) causing the overflow.

So if you do a correct setup and provide the right number of license a overflow should never happen. If due to an design error a license overflow happen you should proceed as following:

- Stop the recorder (he is anyway halted and doing no operations)

- Add the required right number of license or modify the setup of your PBX that just the right number of extensions will do a recording

- Start the recorder up again.

=== Setup ===

Open a separate window, see relative online help.

http://wiki.innovaphone.com/index.php?title=Reference10:Voice_Recorder/Setup#Recorder_Setup

Note: during setup the recording timers are disabled, this means that no normal operation is done. For normal operation the setup must be terminated (with or without saving).

=== Alarms ===

[[Image:VR011.png]]

About 20 seconds after startup, and always during normal operation, alarms are detected from a particular master alarm routine. Some alarms are self-healing, others not. If an alarm occurs the relative source is switched from green to red, if an alarm disappears from red to green. You can simply test is, just shut down the reporting during operation and you will see that the reporting indicator becomes red. If you start up the reporting again the indication will switch automatically from red to green.

An alarm master routine will control the system and summarize the alarms. On the left side there is an indicator “Master alarm” and two buttons, “RESET” and “OFF”. While the alarms can toggle and appear and disappear, the master alarm once triggered will indicate that there was at least one serious error. The detail can be shown in the error log, but the point is that the master alarm shows you the correct operation in time and store the error event.

With the “OFF” button the master alert can be switched manually off. If the master alarm is switched off the “OFF” button will blink red to indicate this exceptional situation. A manual switch off of the master alarm could be necessary during setup or test, or simply to avoid receive alarm emails being anyway in front of the application or similar.

If the master alarm detect at least one error it will be switch on the Master Alarm status, the relative indicator will blink red, a warning triangle will appear and, if configured in the setup, and a warning email is send to the administrator.

[[Image:VR012.png]]

The icon of the application in the taskbar is changed and a warning triangle appears on the recorder logo; also operating in minimized status the Master Alert situation is visible.

[[Image:VR013.png]]

As explained the master alarm will not recover if an error disappears: to reset the master alarm the “RESET” button has to be clicked. Clicking the Reset Key the Master Alarm becomes again armed and will trigger again if an error is detected.

The single errors are partly described in the startup section while the “SOFTWARE” indicator will go into alarm if there is an unexpected error in the software. While some errors are expected and supported and will not cause such an error (for example “no files” if you browse an empty directory) others are not (for example if the decoding of pcap file fails). So while some errors could be an exception (like the failing of file conversation) others could be persisting (like “disk full”) or are simply bugs.

A particular expected, but not tolerable error is described in the next section.

=== Reporting time out error ===

Each extension recorded must have the reporting license active. If that is not (or of the reporting is switched off for a longer period causing loss of CDR data) the recorder got a pcap file with an ID number, but no CDR data for that file from the reporting. The recorder waits up to 120 minutes to receive valid CDR data, after that time he will give up and save and convert the file with incomplete data. If that happened the “REPORTING” lamp will switch to red and a master alert will trigger. Instead of caller, called number etc. a “U” (like “unknown”) is used in the filename. So if a file name contains “ .. _U.U.U_U_ ..” means that there was a reporting time out. The only usable data are the ID and the creation time of the file, that is the reasonable starting time of the recorded conversation.

The things goes even worst if there is a call up for more than 2 hours, because this situation is similar for the recording application: a record in recording is detected but there is no valid response from the Reporting for that record ID . After 2 hours the recorder try to solve the situation, switch on the reporting error lamp copy and rename the recorded file, but then will happen also a Software error, because the deleting of the pcap file will fail (because the file is jet in use). Remember: while “_U_” should not happen, “_U_” because of busy conversation should never happen. Therefore we recommend limiting the speech time to 120 minutes (the recorder trigger if the value is more than 121 minutes). That can be done in the main window of the innovaphone PBX, field “Max Call duration (h)”, put 2 in. To less 2 hours for conversations? Send us an email we will enlarge that timeout to your requirement.

=== Terminating ===

If you try to stop the application a warning message appears, if you confirm the recorder application stops.

== Files ==

Voice files are stored a subdirectory of the indicated path in the recorder setup.

The files are Wave stereo files where the left channel contains one speaker and the right channel the other one.

There are two working sub directories: the directory “/TMP” contains the central activity log file where the player applications will report their activities (“iRec_Player_Log.txt”). The second is the directory “/REC”, it is a working folder. Both folders are created automatically. The recorder creates a subdirectory for each month, so for June 2013 for example a directory “2013_06” is created and all recorded files in that period will be stored there. Note that in the backup folder no subdirectory folder are created and therefore all files in the backup path are in the same folder.

The recording files are always a couple, one file contains the audio (in wave format, can be reproduced using also standard audio player) and an xml file with the same name containing connection data. Both files are anyway independent and our player handles automatically a single wave file as well as the pair with additional detailed connection data.

One goal of the recorder was to produce a wave file that contains all relevant data.

The format of the name of the Wave file is the following:

"Date and Time of conversation start" + "internal user" + "direction" + "external user" + "time to answer in seconds" + "serial number"

Example:

“2013_06_24_1638_39_o_0800102_7_75c1f48e909d31188fc00903306225f.wav”

Date: 24.06.2013

Time: 16:38

Internal: 39

Direction: o = outgoing

External: 0800107

Time to answer: 7 seconds

Serial: 75c1f48e909d31188fc00903306225f

The file “2013_06_24_1638_39_o_0800102_7_75c1f48e909d31188fc00903306225f.xml” contains the reporting data of this call.

Eventual notes are stored in a file named “2013_06_24_1638_39_o_0800102_7_75c1f48e909d31188fc00903306225f.txt”.

This file is AES encrypt, see relative chapter. If this file is copied with the innovaphone Player it will be automatically decrypt and becomes a standard XML file.

The player retrieves the name of the wave file and displays the data from the xml file if present, otherwise at least the data inside the filename.

If you like you can open the xml file even with an editor and see all the relevant data, much more then displayed using the player.

The player shows also the duration of the call (the recoding) and other details. See relative description.

==Encryption==

The setup files for player and recorder are encrypted, as fix key is used an innovaphone specific secret key. The notes are not encrypted while the reporting and security file (the .xml) is encrypted.

So the reporting and security files are encrypted (those ending with “.xml”) using again as default the innovaphone system key. This default encryption key can be replaced with a customer specific key. In the in the setup of the recorder can be defined a customer key. The only reason to define a customer key is to avoid that other customer can decrypt the files, a remote and strange, but thinkable situation.

If this is done in the Recorder also in all Players must be set this customer decrypt key. Be careful in handling that key, because if you forget the key you will lose all encrypted information. The Player can handle contemporaneously the default key and the specific key. There is no update procedure foreseen if you change the key.

Example:

After 3 month of default operation you decide to insert a customer specific encryption key, for example “MySuperSecret007Key”.

You modify also the Player and insert in the setup this new key. Now you will observe that all data, the one of the first 3 month and the following one, will be decrypt automatically correct; the user will see no difference.

After other 5 Month you decide to return to the default key (leaving blank the key field again in recorder and player). Anything is going well, all records are decrypted correctly.

After other 2 Month you decide to enter a key named “MyBrandNewKey”, doing setup of recorder and player. You will observe now that the data of the month period 0 to 3 , 5 to 7 and after Month 7 will be decrypt while Month 3 to 5 (the one with the old key) will be displayed without CDR data and status “unknown”.

Therefore think well about your key, basically once selected it should remain. If you have the list of all Keys you can of cause change it on the fly in a player and decode the records in the period.

== External Applications ==

The recorder as well the player can be interfaced with external applications like booking or ticketing systems or similar.

The basic idea is that the external application will share common information in his database with the recorder and pilot a player. The user should be able to play a recorder conversation directly from his application interface.

In this chapter the interface is described. If you are not interested is such a feature you can skip this paragraph.

This description is done for the software developer of the external applications. No particular setup for the recorder or player is described, part of other descriptions.

For better understanding the description “hides” all other interfaces.

The “recorder” is a software solution running on a Windows “server” (can also be a simple PC). In the network there will be one or several “players” able to reproducing the recorded conversations.

Under “agent” in this description we understand operators working with the voice recording and using an external application.

It is possible to have a TCP connection between player and recorder but this is not mandatory because the player just access to stored data and read out setup file in the network. The number of player has no limit while the number of player connected to the recorder via TCP is limited to 100. That means that the external application can control up to 100 “agents” trough the recorder. But it is also possible to control a player directly; in this case the remote control has no limit.

Contact us if you have more than 100 agents with voice recording using an external application, we can easily extend this limit.

=== Principle and definition ===

This is the described scenario:

Recorder communicates with Player 1, Player 2 … Player x

The Application server communicates with the Application Client 1, 2, … xx

This description regards the TCP/IP interface in the following picture, the only one to build new from the application point of view.

[[Image:Layout02.png]]

Going on in the description as “Appclient” is intended the User frontend (“Application on terminal x” in the picture).

“AppServer” is called the server of the application (Application Server in the picture), so the server for the ticketing or booking system or whatever.

Keep in mind that just one AppServer can communicate with the Recorder while even each Player can be called even directly from the Appserver or an AppClient. Do not confuse: There are two ways to interface the voice recording system, via TCP and via URL. The smarter and better way is the TCP one. We describe both, read both because in the second section some concepts described in the first one are not repeated.

=== TCP/IP Interfacing ===

This is the preferred and smart way to realize the interface.
All messages and command goes to one single interface as shown in the picture. The Appserver act as a TCP/IP “Master” and will receive from the recorder messages and can send commands to the single Players trough the recorder. So it is a 3rt Party interface, piloting single player using one single IP address. The “play” command for a certain player is send to the recorder (and not to the relative player).

If for example a AppClient wants that the Player starts reproducing a record the command flow will be:

AppClientX press the play key -> AppServer send command to the -> Recorder -> Recorder send a command to -> PlayerX

So the idea is that in the applications is a “Play” and a “Stop” button; if the agent press this button the recording relative to the displayed database record will start to play, pressing stop the play will stop.
Therefore the applications database must contain the record name.

The problem is that the entire information about the record is available just a certain time period after the call end. In most of the cases the application session is terminated or a new one started. Therefore the link is provided in two times.

When voice recording starts, the recorder will send a first record to the AppServer in the following format:

''!FRST!<Extension Number of the Agent>!<UID>!<Agentname>''

<FRST> = indicate that this is the first (of two records)

Extension Number = the Phone number of the Agent

<UID> = a unique ID of the record

<Agentname> = the CN (common name) of the Agent in the PBX

Example:

''!FRST!24!c03a55c2e909d311b6450090331b3e3b!Rossi''

where ''“24”'' is the extension number of the agent, ''“c03a55c2e909d311b6450090331b3e3b”'' is the unique “serial number” of the record and ''“Rossi”'' the name of the agent.

Just the filed ''“!FRST!”'' has a fix length, all the others not; the single field therefore has to be separated searching the “!”.

At this point the applications probably store this information (number, ID and Name) in his database or buffer this info until the Agent has his client ready or similar. Important is that the database record of the application is linked to the record UID.

Basically it is necessary for later data processing that the application server knows the name of the player (in our example “Rossi”). The simplest way to do that is giving the extension in the PBX the right common name (the same name than the application user name). If that is not possible (for example because the application has other items to identify a user) the application has to hold a cross reference table: application user name 1 = recording user name 1 etc. Consider also that not necessarily a record is played only on the player of a certain agent; recording for agent 1 can be required to be played on work station agent 2.

When a call has terminated, the record converted, saved etc. (means, ready to be played) a second record is transmitted from the recording server to the AppServer:

''!LAST!<Extension Number of the Agent>!<UID>!<Track>!<Agentname>''

<Track> = Name of the recorded file, to transmit later to the recorder to play.

Example:

''!LAST!24!93adee5ee909d311b6450090331b3e3b!2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav!Rossi''

You see that the UID is in again and on the same position; even the extension number and name is repeated. In this way the application can easily search the UID in his database (and the name and/or the number) and when found complete the record entry with the record name (in the example ''2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav'').
You see the UID is also part of the record name and in theory the original “stand alone” UID in the application database is no longer required. Therefore a overwriting of the UID field in the application database with the record name is possible.

Note: In the actual version a reverse search is not implemented (that the player told the application to display a record). If implemented in the future the search string will be the entire record name and not just the UID, therefore the stand alone UID has no further sense from the voice recording point of view.

From the timing point of view the first message is critical because the UID has to be written until the Agent has opened his application record and that can be even a short time.

The last string is not very time critical because the retrieving of a record and a update can be done in every moment.

The recorder software has a small send buffer (about 25 recordings) where the messages will be buffered if the AppServer is not reachable or the link is down or. If for example the AppServer is switched off and later on again, the recorder will send to the AppServer the FRST and LAST messages buffered during downtime. The Buffer is a Fifo (first in first out) but not an Overflow-Fifo; if full not the oldest but simply all newer messages are lost. The buffering is done just to buffer short time periods, for example to allow a restart of the AppServer PC without losing information (but not for a “offline” operation).

In the application software design should also be considered the possibility that the AppServer receives a First record, is then stopped, and receives the second one after the restart.

That’s all regarding the recording part, now we discuss the remote control of the player.

Remember that a name can be assigned to a player, for external applications that is mandatory. The name can be defined in the player setup; a good idea to simplify the scenario is to give the player the common name of the phone. So in our example we will name the player of the agent “Rossi” just “Rossi”. Not a must of cause, you can call the player of Rossi even “myFirstAgent” or “1234”; but in doing so the external application must store a table where “Rossi” is mapped to “myFirstAgent”. To avoid such complication we suggest unifying the names and assigning to the phone user, Player name and application user in the same one.

To force a certain player to reproduce a certain recording the AppSever has to transmit to the recorder the following command string:

''TRAC!<PN>!<Track>''

<PN>=player name

Example:

''TRAC!Rossi!2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav''

The Player with the name “Rossi” will start playing the record ''2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav''.

There are not foreseen any error messages, if for example the player will not find the record or is switched off nothing will be transmitted to the AppServer. In case of record not found on the Player a blank result will indicate the fail. If the recorder start reproducing a record a green “RC” label (for Remote Control) near the play symbol shows that a remote control message and not a manual play key press has started the reproduction.

There are available also other commands:

''STOP'' (Stops the actual play)

''EJEC'' (the actual record is unloaded, the player stops)

''PAUS'' (the actual record is paused)

''PLAY'' (the actual record is played again)

Example:

''EJEC!Rossi''

Will force the player Rossi to stop the reproduction of the track and go in an idle mode.

Generally it is not necessary that the AppServer takes care about the actual Player status or observe command flows. If the Player is for example playing a track and the application server send the command to play another track he will Eject the actual track and play the desired one.

Note also that the player can work minimized in the taskbar and play “invisible”, so the user will see just the application. In the setup of the player can also be defined an automatic popup if a remote play is received and automatic hiding if an eject-command is received. If this is enabled in this way the player is minimized in the taskbar and the user works just with the application screen.

The TCP/IP link between recorder and AppServer is based on the fact that the recorder acts as a slave while the AppServer act as a Server. In the Setup of the recorder the IPadress and the port of the AppServer has to be indicated. The recorder expects on the same port where he is transmitting the response from the AppServer.

The recording server performs a keep alive with an interval settable in seconds. The keep alive message send from the recorder to the AppServer each xx seconds is:

''RecKA''

The message has no further meaning and can be thrown away from the AppServer. If any command is received from the Appserver the keep alive will be skipped and repeated after the, in the recorder setup indicated timespan. Unknown messages form the application server will be throw away from the recorder server.

=== URL Interfacing ===

URL interfacing is similar to the TCP one except the player interface. The two methods of interfacing are in alternative, so the application server has to do one of the two (no mix possible).

If this option is enabled in the recorder server setup the first and last messages will be transmitted as an extension of a URL statement. The root URL can be defined in the recorder setup.

If the setup for example contains the URL sting “http://zz.aa.bb.xx/myApp/myapp.php “ (note the blank at the end, any character is possible), the recorder will perform the following command if the recording starts:

“''http://zz.aa.bb.xx/myApp/myapp.php !FRST!24!c03a55c2e909d311b6450090331b3e3b!Rossi “''

The “!LAST” command is transmitted in the same way.

If selected URL interfacing it is not possible send commands from the AppServer to the recorder, so the Appserver just receives URL commands from the recorder.

To force a player to reproduce a track the player has to be interfaced directly. In the player has to be open a remote control port (defined in the player setup); messages coming to this port will be processed.
So addressing a single Player is done sending a command to a specific IP- address and port. Therefore probably in the AppServer a table “Name or Number /IP-AD+Port” has to be stored. So the URL Interfacing is from the player point of view a 1st party interface; so each single player has his own remote control interface.

Note that also the application client (or any other software, for example a browser) can do a player remote control.

The command set for the direct remote access to a single player is similar to the one of the recorder:

''<IPLTRAC><PN>''

There are also available the commands

''IPLPLAY''

''IPLSTOP''

''IPLEJECT''

''IPLPAUS''

Example:

''IPLTRAC2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav''

will force the player to reproduce the indicated record ''2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav''.

Basically the interface of the player is anyway a TCP/IP interface and no mini Webserver is integrated. But a “Get” from an browser will be detected and decoded, but no answer occurs. That means if you try to launch a command with a browser it will work, but the browser will show you “no page”.

Example:

The Player runs on a PC with the address 192.168.0.14 and as the remote control port is indicated port 9090.

If you post in your browser “''http://192.168.0.14:9090/IPLPLAY''“, the player will start to play the marked record.

If a port for direct remote control is switched on a “RC on” label is displayed in the player status line.

=== General Note ===

The first UID will be detected form the recording using the SOAP interface in the PBX. Therefore all Agents has to be in the same group that the SOAP user object.

Example: You have a simple user object called “MYSOAP”, put that object in an active group called “Recording” and now put all you Agents in the same group.

Remember that basically recording is done even without the group stuff. So the group is just required to detect the UID in “advanced”. But there is also an additional benefit; the reporting has less stress because the recorder will query the reporting just at the end of the call (knowing via SOAP when the “end” is) while calls without the group are detected as “finished” because the reporting has a valid CDR record, and so the recorder polls each 4 second the reporting on active calls. That means that it is in any case a good idea put the agents in a group, even if no external application is running.

== Related Articles ==

[[Reference10:Player_Voice_Recording]]

[[Reference10:Voice_Recorder/Setup]]

[[Howto:Last_Call_Recording]]

[[Howto:Universal_Track_Recording_Tool]]

[[Category:Concept|{{PAGENAME}}]]

Reference10:Concept Voice Recording 2014

2014-01-15T11:06:46Z

Msr: /* Recorder */

The innovaphone Voice Recorder application allows recording while the innovaphone Player application a comfortable search and playback of phone calls.

All kinds of calls can be recorded:

*Incoming calls

*Outgoing calls

*Calls from innovaphone IP Phones

*Calls form 3rd party IP-Phones

*Calls from IP-DECT phone sets

*Calls from analogue phone sets

*Calls from with mobile phones (mobility, forking)

*Calls done on a legacy PBX (soft migrations scenarios)

The solution requires an innovaphone PBX, the recording toll and two applications;

*a recording tool described in this document called “Recorder”

*a search and playback tool called “Player”.

The usage of the Player is not part of this description, a separate localized help and user manual is available.

While the recorder (this description) has to be installed by professionals and the maintenance is done by system administrations people (and therefore English wording and this description is good enough) the player is operated by End user and may be not digital native, skilled or knowledge base workers.

Note also that the setup of the player is a typical admin job and not described in the player manual.

== Feature list ==

=== General ===

• Using an innovaphone IP-Phone set immediately after call end the recording can be listened using the phone. One feature key stroke and the conversation is reproduced and repeated endless (auto replay). This call can also be transferred or put in a 3 party conference (immediate sharing)

• Online Help and tooltips for application and setup

• Setup password protected, setup files are encrypted

• Recorder in Demo Mode (20 minutes) , Player for free

• Many recorder in one system and unlimited number of players

=== Recorder ===

• Recording of any type of calls direction

• Recording of calls from any device: IP-Phones (innovaphone and 3rt Party), analogue phones, GSM (mobility), IP-DECT

• Recording of calls from/to legacy PBX (smooth migration)

• Recording can be done in a logical gateway or direct from a innovaphone phone set

• Recording of encrypted calls

• Standard und thread call recording. If thread call recording is on after a settable time period (for example 5 minutes) a call will be automatically deleted. If the user calls inside the time period a code the last call will be saved. This marking to keep the recorded call can be done from any type of phone. If the phone is a innovaphone IP Phone the marking can be done also during conversation

• Storage of all relevant data including the time to answer for each call

• Detail protocol of each call, documentation of the entire call flow, not just the recording period but even previous and following one. Detail report on all call situations, transfer, call forwarding, pick-up, group call, conference etc. Also calls in waiting queues or announcements are reported with second accuracy

• Encrypted protocol data

• Display number of channels in recording with start timestamp

• Error and Event log files

• Email alert in case of master alarm

• Automatic backup (copy to mass storage archive)

• Automatic delete of records older than 2-99 month (not on archives)

• Recordings are saved as wave files, can be reproduced with any player

• Wave data integrity supervision

• File name contains primary data (Timestamp, Caller and called, direction, time to answer, UID)

• Counter of recorded conversations

• Data Link to player, remote control of the recorder from player

• Interface to external applications, via TCP or URL, recorder provides data for later retrieving. Player can be controlled sending commands to the recorder (3rd party)

* test

=== Player ===

• Integrity of the recorded wave files are recognized and displayed

• Agent note, a Player displays automatically agent notes and can add text notes to each call

• Integration with iQM server, display of missed calls, possibility to recall immediately

• Naming of Players

• Month and Day filter

• Filter for internal and external number with wildcards

• Filter for incoming and outgoing calls

• View of oldest or newest call on top

• SOS mode can be switched on/off with just one click. If on all unnecessary key are hide, the newest calls are displayed on top of the call list and filters are switched off

• Selection of calls, one single call, more single selected calls, from to, all

• Online search and display, can be switched off

• Copy, move and delete of calls

• Move and delete operations are logged in centralized manipulation log

• Permissions

• Multiple selected calls can are transferred automatically in a playlist and can be reproduced

• Display record size

• Display number of records in playlist and actual play

• Jump forward and backward in playlist

• Jump to next/previous title in search result list if playlist contains just one record

• Marc record in playlist, select actual record and clear all others

• Play one title after the other in playlist

• Play a beep if record change in playlist (loop playlist)

• Repeat play (loop record), up to 4 positions, stored automatically

• Repeat play of all stored memory positions

• Display internal and external number with name resolution

• Display timestamp, time to answer an call ID

• Display System and Player status

• Display if local remote control interface is on

• Display of play was forced be recorder remote control

• Keys for Stop, Play, Fast Forwarding, Rewind, Pause and Eject

• Display duration record

• Display elapsed time or count down, switchable

• Original time elapsing display

• Progress bar adjustable, direct jump to selected position, drag and drop

• Start and Stop position can be marked an played in loop (selection loop)

• Volume control with audio meter and peek indication

• Delta level Indication (L-R and R-L meter)

• Overflow level audio meter

• Enhanced sensitivity for audio meter

• Attenuation left and right cannel adjustable

• Audio setup can be stored and recalled

• Audio level at maximum

• Levels are stored and set on restart

• Level meter with peek indicator for left and right cannel

• Mute

• Large additional display with call details

• Automatic decryption if files are copied

• Player can be limited to display just calls of one extension

• Communication with recorder, display of link status, last master alarm and cannels in recording

• Reset recorder from player

• Search an play on backup directories

• Operate as Media player, reproduction of audio format wav, mp3, wmp and video format avi, wmv, mp4 and mpg

• 1rst and 3rd party remote control

• Document security, manipulation is detected and displayed

== Scenarios ==

Recording is possible on each logical Gateway and therefore on external lines (ISDN, SIP or H323 Trunks). In theory “external” is just a convention, even internal calls passing through those gateways could be recorded, but this is more a theoretical issue. An innovaphone gateway can also be used as a “recording” bar and introduced between a legacy PBX and the PSTN. Remember anyway that the innovaphone PBX must be activated and the Reporting tool is required.

Being recording defined on a logical Gateway opens different options, for example activate recoding just for a dedicated route. For example just for incoming calls or just for some outgoing calls. Typical examples for such a setup are business and private calls, where just business calls should be recorded. For example if a call is done using “0” as prefix recording is done, using “9” not.

Or normally (“0”) no voice recording is done, but if a user access to a trunk with a particular prefix (“9”), recording is on. This for example is widely used in selling contracts by phone (like mobile phone carrier do); they call the customer and if the customer agrees in the commercial proposal to extend or to “sign” the contract they will call back the customer again using another prefix and record now the conversation.

Recording rules can also be executed automatically because configured in the gateway setup. For example you can exclude certain user from recording or vice versa, doing recording just for some users. For example all calls to the financial operators are recorded, all other calls not. Or all users are recorder but the management not.

All that is a question of setup in then innovaphone gateway (and PBX) and not described in detail in this document, being standard features and described in many other articles (and being part of the advanced technical training).

Please note that recording starts when a connection is established and terminates when the connection is terminated. That means that eventual waiting situations in waiting queues, music on hold sequences calls etc. are recorded too.

Keep in mind that each extension that should be recorded must be active in the reporting, means require a recording license. Even if you operate a soft migration you must go up in the PBX to a dummy user with reporting on and back again down to the relay.

Notes: Recording can be done just in G711A on a logical gateway as endpoint. If you need to record internal calls they must always transit a logical gateway (with the media relay flag on).

The recorded files are in a wave format and can be played with a normal Mediaplayer, the delivered Player allows additional features.

The recorded records are stored in an indicated path and a copy of the records can be done automatically.

Errors and events are stored in a log file and alarms tracked; a mail can be send if an alarm occurs.

It is possible to limit the duration of the storing period; older files will be deleted automatically. This is to avoid disk full errors, keep in mind that this kind of systems usually works unattended all the time.

The number of player and recorder is unlimited.

Recording can be done also directly from the IP-Phone. Doing VR using the IP-Phone has the following advantages or disadvantages; it depends on your point of view and the scenario.

- CPU-Load: No CPU power from the PBX is required, a Phone has enough CPU-Power to do that and more, and therefore it becomes an extremely scalable solution. If you do not use an external WebDAV server but a CF anyway the PBX CPU has some load (playing WebDAV server for the Phone)

- All calls on the phone are recorded (not just those crossing a gateway), so even internal calls (basically everything the phone is doing).

- Al users working on the phone are recorded. This means also that each possible user on the phone must have the reporting license otherwise a call from that user will cause a major alarm.

- Transferred calls to other extensions are after the call transfer no longer recorded. In case of gateway recording it is different, until the call cross the gateway recording is done.

- If you mix both setup in a scenario you should avoid that a Phone is doing recording and cross a gateway doing recording too. If that happen recording is done in two points and you double for nothing disk space and resources (and confuse everybody).

- Only innovaphone IP-Phones IP2x2 series and “A”-types (like IP110A, but not IP110) can performing VR directly.

Switch on the recording has to be done in the phone setup file, there is no menu option. Mode information about that is in the online help of the recorder setup.

== Standard Recording ==

Operating in the “Standard Recording” (STD) mode recorded calls are converted and saved after the call has finished.

A recorder has to operate in one mode (STD or TCR), a mixed scenario is possible using two recorders, setup in this case has to be done very carefully.

== SRTP ==

Recording of encrypt conversation is possible, no particular setup is necessary, the system will decrypt automatically the media stream and store the conversation in unecnryptet wave files for further processing.

== Thread Call Recording ==

Operating in the “Thread Call Recording” (TCR) mode only marked calls are converted and saved, all other calls are deleted automatically.

A call can be marked manually from the user or automatically from his innovaphone IP-Phone. A call can be marked during the call or after call, but within a defined time period (for example until 5 minutes after the call-end). Not marked calls are deleted while marked calls will contain the entire call, so from the beginning on (even if marking is done during or after the call).

Marking calls during the conversation can be done only using innovaphone IP-Phones while all type of phones can mark a call after the conversation. To mark a call after a conversation the user must call a XML object.

In a typical setup the user will hear a confirmation if he is marking a call, something like “the last conversation was recorded and will be saved” or similar.

If marking is done using an innovaphone IP-Phone during the call (pressing the redial key) audio or no audio can be played. For example an automatic advice like “this conversation will be recorded” or similar can be played.

=== Setup TCR ===

This paragraph discusses the different setups and aspects for Thread Call Recording. If you are not interested in those details skip it.

TCR require a XML (TCRec.xml included in the software package of the Last call recording feature, see Related Articles, see Related Articles, go to the article and follow the download [http://download.innovaphone.com/ice/wiki-src#lcr http://download.innovaphone.com/ice/wiki-src#lcr] ), you have to create a directory and copy the xml in, create a VM-Object in the PBX and insert those parameters in the recorder setup (TCR panel). The XML can be called directly or using the recording functions on the innovaphone phones. If called directly the xml will play the audio file Track1.g711a, if called through the recording function of the IP-Phone the file Track2.g711a. If the files are not present the user will hear nothing. A solution for the confirmation could also be to play just a “beep” if calling directly the xml. You could copy the beep.g711a file (for example from the VM) and rename it. A better option is record them using the universal track recording tool, see related articles at the end iof this page.

Some additional information if you use the recoding function of the innovaphone IP-Phone:
Keep in mind that this function will not really recording the voice but just calling the XML (the recoding is done by the Gateway or the phone, but directly and not using this function). As explained the XML will play the file Track2.g711a if present, but to hear the announcement you have to use on your phone at least version 10.0887 or higher and switch on the flag “Two Way Media” in the Recording section of the phone setup. The rest is the usual one, if you setup “Mode=transparent” each call will flagged as “to record”, if Mode=manual you have to press the redial key to flag. No problem if the user presses more than one time the record key, just the actual call will be recorded.

The xml itself will terminate after playing the Tack 1 or 2, delayed for 2 seconds. If the user press the redial key in this way he will see in the display of his IP-Phone appear “Recording” for 2 seconds and has a feedback (even if no tone is played) that the conversation is flagged to record.

== Last Call Recording/Repeat ==

See relative article.

Do not confuse this feature with the Instant Play (rescue mode) feature of the innovaphone Player.

== Overview ==

The recording itself is done by the innovaphone gateway. In each logical gateway a recording path can be configured as a URL; that means that the voice will be recorded in a file, this file can be on a compact flash or on an external WebDAV server. The recorder application copy the recorded file, read out the reporting, combine both, and rename the file. The original file on the compact flash/WebDAV is deleted. The new filename is formed using date and time, caller and called user, direction of the call, the time to answer (ringing time) and the unique ID number. The recorder converts the file from pcap to the wave format and stores the converted file in a directory. If requested a copy of this record can be saved in a second directory (for example a SAN or NAS disk area). A maximum number of storage time expressed in month can be defined, older files will be deleted automatically. In this way no disk space overflow will be in unattended systems. Parallel to the payload (the wave voice file) also a XML file containing the reporting data is created, the name of the file is the same than the one of the voce and just the extension is xml instead of wav. That is basically what the recorder is doing; copy and convert recorded files, retrieve data from the reporting, renaming of the files and copy them to different destinations as well as keeping track of history.

The player allows searching and browsing of records, show the oldest or newest first, can filter the search etc. For example it can be displayed calls in any direction or just incoming or outgoing calls, or calls from a certain number or to a certain number, using even wildcards for quick filter options. See relative description for details. Once the calls a displayed they can be marked using windows usual methods (one, many, all, range, etc.). The marked files can be copy, past, deleted or played in a playlist. A record in the playlist can be marked and the player allows the usual operations of a windows media player. Looping and audio signal before playing the next record in the playlist is included as well as moving inside the playlist from one call to the other. If all that sounds complicated calm down, it is quite simple in using and designed for “users”.

The player can even operate in a mode called “rescue mode” or “direct play mode”. If switched in this mode the latest record is always on top. This is a typical requirement for an emergency center operator, he is interested in replay the last or lasted recordings in a quick and simple mode.

The player shows also the reporting details and generally the most important data of the conversation. If recorded files are copied also the relative reporting information is copied.
Many player can be installed and work in the same moment in a scenario, while the recorder typically is just one. So the recorder is a kind of server and the player a kind of client. More recorders can be installed in a scenario and if necessary a player can be installed on the same PC where a recorder is working. Being the recorder always on usually it will be installed on a dedicated machine doing just that located in the server room.

But remember that the recording job is done as described by the gateway. So even if a recorder application is switched off voice recording is done. The idea anyway is not that the recorder is switched off and just sometimes switched on to retrieve the files. But if you must shut down the application or reboot or enter in setup, no data will lose.

The following diagram shows the logical interfaces between the innovaphone voice recorder, the innovaphone player and the rest of the equipment.

[[Image:Player07.png]]

(*) = Option

The player main data source is the disk where the records are stores. There could be active many player at the same time, and in theory also more than one recorder. One player could monitor just one recorder, but it is possible to start more player on the same PC.

== Requirements ==

=== Recorder ===

The recorder application requires a PC or server with Windows OS Win 7 or higher, also windows server 2008 (Windows 2003 server not tested) or higher is supported.

Disk space: One minute of conversation requires about 1 MB of memory. A lot, but a TB HD today is cheap and for example even a 500 GB Raid 1 external NAS is not real expensive. Typically a recorder should have a Raid system, but remember that the recorder is able to do also a security copy. The copy to an external security drive is possible because in many scenario’s customer has to archive records for many years.
The recorder requires a NTFS file system (no FAT32), usually today a standard on PC.

Some examples: to store 1000 hours a 60GB disk is required, 100.000 hours require a 6 TB Disk, 200.000 hours a 12 TB Disk. On the one hand a Year has 8.600 hours, on the other recording 30 cannel always busy for 10 hours a day for 200 workdays requires 60.000 hour a year. Now if you have this workload (10 hours busy a day on 30 cannels) probably a 16 TB Disk for €1.000 is not a problem.

Remember that on minute require in reality less the 1MB (about 900kB) and it is stereo. Zipping the files reduce about 30%, not really a deal.

No particular memory or CPU speed is requested, standard editions are quite good enough. Invest better in a good quality because in professional environments those machines have to work for many years.

Voice recording requires a Version 10 innovaphone PBX and a Version 10 Reporting tool. No compatibility with older versions is possible. PBX and/or Reporting can run on a gateway as well as on VMware.

The recording of the pcap file is done by the PBX firmware and requires a Compact flash or a WebDAV server. The recorder software will detect those records and copy them on the real storage path. Therefore the storage requirement for the CF/WebDAV not real high (but remember always 1 Minute =1 MB, so if you must record 30 conversations for 30 minutes = 900MB).

Voice recorder and Player could run on the same PC as well one single PC can also be used for the reporting, recording, playing and webdav server (and PBX if you like). So anything on one server is theoretically possible.

The two extreme setups are:

*innovaphone PBX on the GW, reporting on the GW, pcap recording on the CF, recording application on a PC

*innovaphone PBX on the PC, reporting on the PC, pcap recording on the PC, recording application on a PC

Each combination between is possible.

Remember that the CF is a relative slow drive, you will note this if you copy a file from the CF to the local HD of your PC. Exact this file copy is one of the task of the recorder, even a critical one (so not a good idea do anything else in between). The result is that the copy of a huge file (a long conversation) or many files will virtually froze the recorder software. In reality the recorder is just hanging around and waits that the file copy is finally done. So a recording on an external webdav server will solve this, but the CF has the nice flair working even if all PC’s are down. Take your choices and live with them.

=== Player ===

The player application requires a PC with Windows OS Win 7 or higher, the Mediaplayer is necessary. All that on a standard office PC is installed and you have to do nothing in particularly.
Require Framework 3.5.
In theory also a Windows server 2008 could host the player, but in the server versions the media player typically is not installed and there are also different DLL missing. So if you have time or you are well Microsoft server trained face also that if necessary (normally not).

=== Legal Aspects ===

Please take extremely care about the legal issue: in most country voice recording of telephone calls is forbidden and persecuted by law as a crime. In some country it is legal in certain circumstances, for example you have to inform the caller that the call will be recorded. That can be done automatically (using for example a waiting queue) or “manually”, telling the far person that this call will be recorded. Of cause also this announcement should be recorded. In some country recording is legal without any announcement for certain services, for example in case of emergency calls or calls to the police. In most country authority like the secret service do not really care about all that stuff and do what they want, but this is probably not your case.

So inform yourself and the customer about the local legal situation. Using the recording tools is on your own risk and innovaphone will not take any responsibility, even not for eventual malfunctions. See also our general trading terms, valid even for this solution. If you have any doubt about legal questions in using voice recording; don´t do it, don’ use it!

== Installation Sep by Step==

In this and many other wiki articles everything you need to install and operate the product is (hopefully) described. Partners some time have the problem that they could not find a logical flow in the description and the do not realize what is important and what interesting, but not essential.

To help here a simple step by step instruction, all details and comments are in the other paragraph and, of cause, in other articles.

1. Check the Software version of your PBX, it must be 10 or higher otherwise do an upgrade or forget this recording. You PBX must be up and running and to test you need at least 2 Phones.

2. Check that you have a valid license for the recording, if not just a demo-mode is possible, after 20 minutes the recorder stop and you have to restart him again.

3. Your CF should be working fine, create a directory to buffer the pcap files (for example http://123.123.123.123/DRIVE/CF0/IF_REC).

4. Setup the recording gateway, see http://wiki.innovaphone.com/index.php?title=Reference10:Voice_Recorder/Setup#Gateway_Setup . If you want to do a test with internal phones you have to assure that in ca ll from one user to the other this gateway will be involved. Create for example a access code to this GW and flag Media-Relay. If you call this access code followed by the internal number ths should happen. Of cause if you have a real trunk the you will do all that using the relative GW. At the end of the story your call must passing the recording gateway, check it; open you PBX interface, click on gateway and calls: you should see that the call goes through the recording GW. A pcap file will created at the CF directory indicated in the setup of the gateway (the same one you create in pass 3).

5. Start up the reporting (on a xx10 GW or IPVA), it must be up and working, you should be able to see the reports of the call done using the recording gateway.

6. Create SOAP user, a blank empty user object called SOAP (or _TAPI_ or _whatever_)

7. Create a root directory where the recorded files should be stores (for example “c:\mytest\” or “G:\myExternalDrive\”).

8. Now create a directory and put the innovaphone_recorder.exe and the pcap2wav.exe in the same directory (this is done automatically if installation is done with the installer).

9. Start the application and open the setup.

== Installation ==

While the Recorder works “hidden” for the user, the Player has a huge user interface. The Player is typically installed on one or more PC of users. Therefore for the Player more effort to design a foolproof interface was done. The Player description is available, please check the relative section in the innovaphone Wiki.
Recorder and player applications are single executable file. The setup is stored in a xml file located in the same directory where the application is running; no registry entry is done; if you delete the directory where the recorder/player is in, the application is de-installed. If you like install on the same computer the recorder and the player application you have to create two different directories and copy the applications twice. Automatic execution is possible inserting in the auto start directory the recorder application.

Please note that the setup file is in xml format, but his content is encrypted.

The installation tool will copy all reqired files, if you install manually copping file note the following issues:

If you install a recorder application manually you must copy the “pcap2wav.exe” utility in the same directory!

Note: This utility “pcap2wav.exe” can be downloaded in the V7 application folder, access to a directory and download the “tools” Zip file; inside you will find the pcap2wav.exe.
The recorder is not a service because there is a full user interface available. To ensure that the recorder starts up even after a boot put the application in your autostart folder. In the setup an option to start up minimized is available.

Before starting the recorder application check the following items on the recorder PC:

*the directory where the recordings should be stored must be visible and it must be possible to create subdirectories, try using the file explorer

*If backup is requested also a write access to the backup path must be possible (but it is not necessary to be able create subfolders).

*Access to the reporting tool must be possible, use a browser to check

*The access to the CF (or the WebDAV server) must be possible, try to map a drive and access to the directory where the pcap files are

Do the setup the innovaphone PBX, the gateway and the reporting.

See eventually also http://wiki.innovaphone.com/index.php?title=Reference10:Voice_Recorder/Setup#Recorder_Setup for a better understanding of the requirements.

If you do now a call which has to be recorded this call must be logged in the reporting tool and a pcap file must be created in the indicated url path. Go only ahead if that is up and running.

Now start the recording software and open the setup and set the values. An online help will explain the single parameters. Maybe it is also a good idea reading first the rest of this article.

The installation of the Player is similar just simpler. After installing start the application, enter the setup and that its. But it has no sense install or setup a Player without before having a working recorder.

On a single PC multiple Recorder and Player can be installed, simple install and run them on different directories.

=== CPU load ===

The power of the innovaphone CPU on the different gateway models is high enough to ensure the recording of all ISDN cannels (or the same number of SIP/H323 Trunk) on that gateway. If recording is done on a CF the innovaphone PBX CPU will be involved also in the copy operation (if recording is done on an external WebDAV server no CPU load of the PBX for copy is required). After the copy operation no more CPU power of the PBX CPU is required.

The reporting CPU (which is anyway the second core in case of a gateway or a separate CPU in case of VMware) has some small workload because the recorder checks each 5 seconds the reporting.
Using the player will cause no workload for PBX, reporting or recorder CPU, so just the local workstation CPU power is require. Therefore the number of player is practically insignificant for any CPU load.

=== Logging ===

Recorder and the Player applications write an individual error log, this log is a text file and stored in the same directory where the application is. See online help for file names and description of the other files used by this applications.

The recorder can also write a trace file; if tracing option is switched on all operations of the recorder are logged in a file named “iREC_sys_log.txt”. Please not that this files become very large if the option is always on, and this file will not be deleted or resized automatically. The idea is not to keep on tracing all the time but to switch on the trace during the first period or in case of trouble checking.
If enabled in the setup the player stores all special operations in a central log file. All copy, delete and move operations done using the player are in this way stored automatically in a central log file.

A “user operational” log file is in a central point and unique for all players installed. Here all user manipulations done using the player applications are reported, so copy or delete is traced. This file is named “iREC_Player_log.txt” and located in the “\TMP” subdirectory of the root recording directory. In this way all operations of all Player-User are visible at a glance in one single file.

=== Security ===

The setup of the recorder and player is stored in an AES encrypted setup xml file. Therefore the user cannot manipulate or read out setup values. The access to the setup can be protected with a password. If a user deletes the setup file the software assumes that this is a new installation and allows access to the setup without password. If the user enters the correct path for the recording the software read out a centralized password and it is not possible to save the setup without that password. There is no way to read out or decode the password and this means that if you, as administrator, forget the password you have to clear the centralized password and the setup of the recorder and re-configure all. Try to avoid that situation and remember your password.

The centralized password is in the located in the “\TMP” subdirectory of the root recording directory and named “SPlayer.xml”. It is also encrypted of cause.

The Reporting xml data string is even encrypt.

In the first column header of the player a looked/unlooked symbol is displayed showing the encrypt/clear file mode. If (using the player) a encrypt records is copied it will be automatically decrypt, while moving a file (cut and paste) will not change the original file mode. In this way a clear copy of a xml can be done from an authentic encrypted data string.

== Voice Recorder operation ==

The recorder can operate in 3 layouts; minimized in the taskbar, viewing a small window or an extended panel.

[[Image:Recorder01.png]]

Switching between small and large view is done pressing the “>” key, press “_” for minimize.

[[Image:VR010.png]]

=== Start up ===

During start up the basic operational parameter are checked while the master alarm is disabled. The master alarm supervision is just switched on after about 20 seconds. This is necessary because sometimes network operation during start up fails, but becomes up in a second attempt. For example mapping of network drives fails frequently at the first attempt but once up they will remain connected without any problem. The sequence of testing is done by design and the software will not proceed in operation if a parameter fails but continuously try to fix it.

This initial health check during start-up is done in the following order:

*checking setup: try to understand if the setup parameters are reasonable and in particularly if the WebDAV drive or CF can be mapped. If mapping fails the “SETUP” lamp will be red, error message “Setup not o.k.” is viewed.

*checking reporting: pings the reporting, if ping is o.k. try to load a dummy page. If ping or dummy fails the “REPORTING” lamp is red, error message “Reporting Link failure” is viewed.

*checking to access to the recording directory (url): try to read out the indicated path, if fails “PCAP” lamp is red, error message “PCAP directory access fails” is viewed.

*checking if access to the storage path is possible: If reading fails the “DISK” lamp is red, error message “Store path fails” is viewed.

If in the setup no backup path is indicated this last task is skipped and the Backup lamp is grey. Otherwise the access to the path is tested, if access fails the “BACKUP” lamp is red, error message “Backup path fails” is viewed.

If a test is passed the relative lamp becomes green. If after start up 6 lamps are green (or 5 green and one grey) everything is working fine and the message “Normal Operation” is displayed in the System status line.

After 20 second the Master alert supervision is switched to active, an eventual error causes a Master Alarm (see relative section).

=== Normal operation ===

The check counter shows you how many times the recorder reads out the recording directory and checks the reporting. As you see al 5 seconds a reading attempt is done, if data are found further processing operation will start. This counter goes automatically to 0 reaching 9999 and shows you that the software is working and checking but has no further signification.

The counter “Channels in recording” shows you how many recordings are ongoing. The panel shows you the ID of each recording file and the initial recording time. In this way you can see how long a call is jet in recording.

If the call ends it will disappear from the list. If there are more records then default lines a scroll down will automatically appear.

If you click the innovaphone logo the software version is displayed. The version is also displayed in the headline of the setup.

===Extended view ===

If you enlarge the window with the “>” key two additional panels appears.

[[Image:Recorder02.png]]

The left one shows the regular normal operations, the right one the errors and basic messages (like Start-up). The messages displayed of the error panel are stored automatically in an error log file while the messages of the status panel only file if that is enabled in setup. Both windows can be cleared pressing the relative button. This clearage is just an “optical” issue; no file is deleted or similar. Both windows shows up to 100 entries, if entry becomes too large a scrollbar appear automatically. If “full” the oldest message will be cleared. On top the error panel can also display the last 30 Error reading out the error file.

Pressing the “<” key the windows will be resized again.

There is no operational difference between the different layouts. The recording application starts always with the small window stile.

The following picture shows two alarms, Reporting (because there where files without CDR records) and Software (because there was a license overflow).

[[Image:RecXX.png]]

===License===

The license model is based on user, so for each user a license is required. “User” is basically the number (extension) of a user, not the name.

If the recorder is installed between a PBX and a trunk line (soft migration) there will be just numbers. Remember anyway that even the recording must work and therefore for each recording user also a valid reporting licensed is required.

In start-up the recorder will read out the number of recording license in the PBX. If a record is detected and a number associated this number is stored and the license counter decreased. Same numbers will not decrease the counter. If a new number is detected and no more licenses are available the recorder will store this last record normally and stop further operations. Recording in this situation will be buffered on the CF/webdav directory.

The recorder shows the number of license loaded and the number of license used. After startup the “Lic” counter shows the number of license loaded, while the “Used” counter displays initially “0000” and increase if used.

In other word you have to avoid that overflow doing appropriate setup in the routing/PBX.

If an overflow occurs software alarm is triggered, the error log file written, the alarm signaled on the player if enabled, an alarm email is done, a warning triangle near the license counter appears etc.
If you press the “LIC” button the right error table shows the actual status, the number of license, the uses one and the number (user) causing the overflow.

So if you do a correct setup and provide the right number of license a overflow should never happen. If due to an design error a license overflow happen you should proceed as following:

- Stop the recorder (he is anyway halted and doing no operations)

- Add the required right number of license or modify the setup of your PBX that just the right number of extensions will do a recording

- Start the recorder up again.

=== Setup ===

Open a separate window, see relative online help.

http://wiki.innovaphone.com/index.php?title=Reference10:Voice_Recorder/Setup#Recorder_Setup

Note: during setup the recording timers are disabled, this means that no normal operation is done. For normal operation the setup must be terminated (with or without saving).

=== Alarms ===

[[Image:VR011.png]]

About 20 seconds after startup, and always during normal operation, alarms are detected from a particular master alarm routine. Some alarms are self-healing, others not. If an alarm occurs the relative source is switched from green to red, if an alarm disappears from red to green. You can simply test is, just shut down the reporting during operation and you will see that the reporting indicator becomes red. If you start up the reporting again the indication will switch automatically from red to green.

An alarm master routine will control the system and summarize the alarms. On the left side there is an indicator “Master alarm” and two buttons, “RESET” and “OFF”. While the alarms can toggle and appear and disappear, the master alarm once triggered will indicate that there was at least one serious error. The detail can be shown in the error log, but the point is that the master alarm shows you the correct operation in time and store the error event.

With the “OFF” button the master alert can be switched manually off. If the master alarm is switched off the “OFF” button will blink red to indicate this exceptional situation. A manual switch off of the master alarm could be necessary during setup or test, or simply to avoid receive alarm emails being anyway in front of the application or similar.

If the master alarm detect at least one error it will be switch on the Master Alarm status, the relative indicator will blink red, a warning triangle will appear and, if configured in the setup, and a warning email is send to the administrator.

[[Image:VR012.png]]

The icon of the application in the taskbar is changed and a warning triangle appears on the recorder logo; also operating in minimized status the Master Alert situation is visible.

[[Image:VR013.png]]

As explained the master alarm will not recover if an error disappears: to reset the master alarm the “RESET” button has to be clicked. Clicking the Reset Key the Master Alarm becomes again armed and will trigger again if an error is detected.

The single errors are partly described in the startup section while the “SOFTWARE” indicator will go into alarm if there is an unexpected error in the software. While some errors are expected and supported and will not cause such an error (for example “no files” if you browse an empty directory) others are not (for example if the decoding of pcap file fails). So while some errors could be an exception (like the failing of file conversation) others could be persisting (like “disk full”) or are simply bugs.

A particular expected, but not tolerable error is described in the next section.

=== Reporting time out error ===

Each extension recorded must have the reporting license active. If that is not (or of the reporting is switched off for a longer period causing loss of CDR data) the recorder got a pcap file with an ID number, but no CDR data for that file from the reporting. The recorder waits up to 120 minutes to receive valid CDR data, after that time he will give up and save and convert the file with incomplete data. If that happened the “REPORTING” lamp will switch to red and a master alert will trigger. Instead of caller, called number etc. a “U” (like “unknown”) is used in the filename. So if a file name contains “ .. _U.U.U_U_ ..” means that there was a reporting time out. The only usable data are the ID and the creation time of the file, that is the reasonable starting time of the recorded conversation.

The things goes even worst if there is a call up for more than 2 hours, because this situation is similar for the recording application: a record in recording is detected but there is no valid response from the Reporting for that record ID . After 2 hours the recorder try to solve the situation, switch on the reporting error lamp copy and rename the recorded file, but then will happen also a Software error, because the deleting of the pcap file will fail (because the file is jet in use). Remember: while “_U_” should not happen, “_U_” because of busy conversation should never happen. Therefore we recommend limiting the speech time to 120 minutes (the recorder trigger if the value is more than 121 minutes). That can be done in the main window of the innovaphone PBX, field “Max Call duration (h)”, put 2 in. To less 2 hours for conversations? Send us an email we will enlarge that timeout to your requirement.

=== Terminating ===

If you try to stop the application a warning message appears, if you confirm the recorder application stops.

== Files ==

Voice files are stored a subdirectory of the indicated path in the recorder setup.

The files are Wave stereo files where the left channel contains one speaker and the right channel the other one.

There are two working sub directories: the directory “/TMP” contains the central activity log file where the player applications will report their activities (“iRec_Player_Log.txt”). The second is the directory “/REC”, it is a working folder. Both folders are created automatically. The recorder creates a subdirectory for each month, so for June 2013 for example a directory “2013_06” is created and all recorded files in that period will be stored there. Note that in the backup folder no subdirectory folder are created and therefore all files in the backup path are in the same folder.

The recording files are always a couple, one file contains the audio (in wave format, can be reproduced using also standard audio player) and an xml file with the same name containing connection data. Both files are anyway independent and our player handles automatically a single wave file as well as the pair with additional detailed connection data.

One goal of the recorder was to produce a wave file that contains all relevant data.

The format of the name of the Wave file is the following:

"Date and Time of conversation start" + "internal user" + "direction" + "external user" + "time to answer in seconds" + "serial number"

Example:

“2013_06_24_1638_39_o_0800102_7_75c1f48e909d31188fc00903306225f.wav”

Date: 24.06.2013

Time: 16:38

Internal: 39

Direction: o = outgoing

External: 0800107

Time to answer: 7 seconds

Serial: 75c1f48e909d31188fc00903306225f

The file “2013_06_24_1638_39_o_0800102_7_75c1f48e909d31188fc00903306225f.xml” contains the reporting data of this call.

Eventual notes are stored in a file named “2013_06_24_1638_39_o_0800102_7_75c1f48e909d31188fc00903306225f.txt”.

This file is AES encrypt, see relative chapter. If this file is copied with the innovaphone Player it will be automatically decrypt and becomes a standard XML file.

The player retrieves the name of the wave file and displays the data from the xml file if present, otherwise at least the data inside the filename.

If you like you can open the xml file even with an editor and see all the relevant data, much more then displayed using the player.

The player shows also the duration of the call (the recoding) and other details. See relative description.

==Encryption==

The setup files for player and recorder are encrypted, as fix key is used an innovaphone specific secret key. The notes are not encrypted while the reporting and security file (the .xml) is encrypted.

So the reporting and security files are encrypted (those ending with “.xml”) using again as default the innovaphone system key. This default encryption key can be replaced with a customer specific key. In the in the setup of the recorder can be defined a customer key. The only reason to define a customer key is to avoid that other customer can decrypt the files, a remote and strange, but thinkable situation.

If this is done in the Recorder also in all Players must be set this customer decrypt key. Be careful in handling that key, because if you forget the key you will lose all encrypted information. The Player can handle contemporaneously the default key and the specific key. There is no update procedure foreseen if you change the key.

Example:

After 3 month of default operation you decide to insert a customer specific encryption key, for example “MySuperSecret007Key”.

You modify also the Player and insert in the setup this new key. Now you will observe that all data, the one of the first 3 month and the following one, will be decrypt automatically correct; the user will see no difference.

After other 5 Month you decide to return to the default key (leaving blank the key field again in recorder and player). Anything is going well, all records are decrypted correctly.

After other 2 Month you decide to enter a key named “MyBrandNewKey”, doing setup of recorder and player. You will observe now that the data of the month period 0 to 3 , 5 to 7 and after Month 7 will be decrypt while Month 3 to 5 (the one with the old key) will be displayed without CDR data and status “unknown”.

Therefore think well about your key, basically once selected it should remain. If you have the list of all Keys you can of cause change it on the fly in a player and decode the records in the period.

== External Applications ==

The recorder as well the player can be interfaced with external applications like booking or ticketing systems or similar.

The basic idea is that the external application will share common information in his database with the recorder and pilot a player. The user should be able to play a recorder conversation directly from his application interface.

In this chapter the interface is described. If you are not interested is such a feature you can skip this paragraph.

This description is done for the software developer of the external applications. No particular setup for the recorder or player is described, part of other descriptions.

For better understanding the description “hides” all other interfaces.

The “recorder” is a software solution running on a Windows “server” (can also be a simple PC). In the network there will be one or several “players” able to reproducing the recorded conversations.

Under “agent” in this description we understand operators working with the voice recording and using an external application.

It is possible to have a TCP connection between player and recorder but this is not mandatory because the player just access to stored data and read out setup file in the network. The number of player has no limit while the number of player connected to the recorder via TCP is limited to 100. That means that the external application can control up to 100 “agents” trough the recorder. But it is also possible to control a player directly; in this case the remote control has no limit.

Contact us if you have more than 100 agents with voice recording using an external application, we can easily extend this limit.

=== Principle and definition ===

This is the described scenario:

Recorder communicates with Player 1, Player 2 … Player x

The Application server communicates with the Application Client 1, 2, … xx

This description regards the TCP/IP interface in the following picture, the only one to build new from the application point of view.

[[Image:Layout02.png]]

Going on in the description as “Appclient” is intended the User frontend (“Application on terminal x” in the picture).

“AppServer” is called the server of the application (Application Server in the picture), so the server for the ticketing or booking system or whatever.

Keep in mind that just one AppServer can communicate with the Recorder while even each Player can be called even directly from the Appserver or an AppClient. Do not confuse: There are two ways to interface the voice recording system, via TCP and via URL. The smarter and better way is the TCP one. We describe both, read both because in the second section some concepts described in the first one are not repeated.

=== TCP/IP Interfacing ===

This is the preferred and smart way to realize the interface.
All messages and command goes to one single interface as shown in the picture. The Appserver act as a TCP/IP “Master” and will receive from the recorder messages and can send commands to the single Players trough the recorder. So it is a 3rt Party interface, piloting single player using one single IP address. The “play” command for a certain player is send to the recorder (and not to the relative player).

If for example a AppClient wants that the Player starts reproducing a record the command flow will be:

AppClientX press the play key -> AppServer send command to the -> Recorder -> Recorder send a command to -> PlayerX

So the idea is that in the applications is a “Play” and a “Stop” button; if the agent press this button the recording relative to the displayed database record will start to play, pressing stop the play will stop.
Therefore the applications database must contain the record name.

The problem is that the entire information about the record is available just a certain time period after the call end. In most of the cases the application session is terminated or a new one started. Therefore the link is provided in two times.

When voice recording starts, the recorder will send a first record to the AppServer in the following format:

''!FRST!<Extension Number of the Agent>!<UID>!<Agentname>''

<FRST> = indicate that this is the first (of two records)

Extension Number = the Phone number of the Agent

<UID> = a unique ID of the record

<Agentname> = the CN (common name) of the Agent in the PBX

Example:

''!FRST!24!c03a55c2e909d311b6450090331b3e3b!Rossi''

where ''“24”'' is the extension number of the agent, ''“c03a55c2e909d311b6450090331b3e3b”'' is the unique “serial number” of the record and ''“Rossi”'' the name of the agent.

Just the filed ''“!FRST!”'' has a fix length, all the others not; the single field therefore has to be separated searching the “!”.

At this point the applications probably store this information (number, ID and Name) in his database or buffer this info until the Agent has his client ready or similar. Important is that the database record of the application is linked to the record UID.

Basically it is necessary for later data processing that the application server knows the name of the player (in our example “Rossi”). The simplest way to do that is giving the extension in the PBX the right common name (the same name than the application user name). If that is not possible (for example because the application has other items to identify a user) the application has to hold a cross reference table: application user name 1 = recording user name 1 etc. Consider also that not necessarily a record is played only on the player of a certain agent; recording for agent 1 can be required to be played on work station agent 2.

When a call has terminated, the record converted, saved etc. (means, ready to be played) a second record is transmitted from the recording server to the AppServer:

''!LAST!<Extension Number of the Agent>!<UID>!<Track>!<Agentname>''

<Track> = Name of the recorded file, to transmit later to the recorder to play.

Example:

''!LAST!24!93adee5ee909d311b6450090331b3e3b!2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav!Rossi''

You see that the UID is in again and on the same position; even the extension number and name is repeated. In this way the application can easily search the UID in his database (and the name and/or the number) and when found complete the record entry with the record name (in the example ''2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav'').
You see the UID is also part of the record name and in theory the original “stand alone” UID in the application database is no longer required. Therefore a overwriting of the UID field in the application database with the record name is possible.

Note: In the actual version a reverse search is not implemented (that the player told the application to display a record). If implemented in the future the search string will be the entire record name and not just the UID, therefore the stand alone UID has no further sense from the voice recording point of view.

From the timing point of view the first message is critical because the UID has to be written until the Agent has opened his application record and that can be even a short time.

The last string is not very time critical because the retrieving of a record and a update can be done in every moment.

The recorder software has a small send buffer (about 25 recordings) where the messages will be buffered if the AppServer is not reachable or the link is down or. If for example the AppServer is switched off and later on again, the recorder will send to the AppServer the FRST and LAST messages buffered during downtime. The Buffer is a Fifo (first in first out) but not an Overflow-Fifo; if full not the oldest but simply all newer messages are lost. The buffering is done just to buffer short time periods, for example to allow a restart of the AppServer PC without losing information (but not for a “offline” operation).

In the application software design should also be considered the possibility that the AppServer receives a First record, is then stopped, and receives the second one after the restart.

That’s all regarding the recording part, now we discuss the remote control of the player.

Remember that a name can be assigned to a player, for external applications that is mandatory. The name can be defined in the player setup; a good idea to simplify the scenario is to give the player the common name of the phone. So in our example we will name the player of the agent “Rossi” just “Rossi”. Not a must of cause, you can call the player of Rossi even “myFirstAgent” or “1234”; but in doing so the external application must store a table where “Rossi” is mapped to “myFirstAgent”. To avoid such complication we suggest unifying the names and assigning to the phone user, Player name and application user in the same one.

To force a certain player to reproduce a certain recording the AppSever has to transmit to the recorder the following command string:

''TRAC!<PN>!<Track>''

<PN>=player name

Example:

''TRAC!Rossi!2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav''

The Player with the name “Rossi” will start playing the record ''2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav''.

There are not foreseen any error messages, if for example the player will not find the record or is switched off nothing will be transmitted to the AppServer. In case of record not found on the Player a blank result will indicate the fail. If the recorder start reproducing a record a green “RC” label (for Remote Control) near the play symbol shows that a remote control message and not a manual play key press has started the reproduction.

There are available also other commands:

''STOP'' (Stops the actual play)

''EJEC'' (the actual record is unloaded, the player stops)

''PAUS'' (the actual record is paused)

''PLAY'' (the actual record is played again)

Example:

''EJEC!Rossi''

Will force the player Rossi to stop the reproduction of the track and go in an idle mode.

Generally it is not necessary that the AppServer takes care about the actual Player status or observe command flows. If the Player is for example playing a track and the application server send the command to play another track he will Eject the actual track and play the desired one.

Note also that the player can work minimized in the taskbar and play “invisible”, so the user will see just the application. In the setup of the player can also be defined an automatic popup if a remote play is received and automatic hiding if an eject-command is received. If this is enabled in this way the player is minimized in the taskbar and the user works just with the application screen.

The TCP/IP link between recorder and AppServer is based on the fact that the recorder acts as a slave while the AppServer act as a Server. In the Setup of the recorder the IPadress and the port of the AppServer has to be indicated. The recorder expects on the same port where he is transmitting the response from the AppServer.

The recording server performs a keep alive with an interval settable in seconds. The keep alive message send from the recorder to the AppServer each xx seconds is:

''RecKA''

The message has no further meaning and can be thrown away from the AppServer. If any command is received from the Appserver the keep alive will be skipped and repeated after the, in the recorder setup indicated timespan. Unknown messages form the application server will be throw away from the recorder server.

=== URL Interfacing ===

URL interfacing is similar to the TCP one except the player interface. The two methods of interfacing are in alternative, so the application server has to do one of the two (no mix possible).

If this option is enabled in the recorder server setup the first and last messages will be transmitted as an extension of a URL statement. The root URL can be defined in the recorder setup.

If the setup for example contains the URL sting “http://zz.aa.bb.xx/myApp/myapp.php “ (note the blank at the end, any character is possible), the recorder will perform the following command if the recording starts:

“''http://zz.aa.bb.xx/myApp/myapp.php !FRST!24!c03a55c2e909d311b6450090331b3e3b!Rossi “''

The “!LAST” command is transmitted in the same way.

If selected URL interfacing it is not possible send commands from the AppServer to the recorder, so the Appserver just receives URL commands from the recorder.

To force a player to reproduce a track the player has to be interfaced directly. In the player has to be open a remote control port (defined in the player setup); messages coming to this port will be processed.
So addressing a single Player is done sending a command to a specific IP- address and port. Therefore probably in the AppServer a table “Name or Number /IP-AD+Port” has to be stored. So the URL Interfacing is from the player point of view a 1st party interface; so each single player has his own remote control interface.

Note that also the application client (or any other software, for example a browser) can do a player remote control.

The command set for the direct remote access to a single player is similar to the one of the recorder:

''<IPLTRAC><PN>''

There are also available the commands

''IPLPLAY''

''IPLSTOP''

''IPLEJECT''

''IPLPAUS''

Example:

''IPLTRAC2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav''

will force the player to reproduce the indicated record ''2013_09_24_1107_39.o.024_1_93adee5ee909d311b6450090331b3e3b.wav''.

Basically the interface of the player is anyway a TCP/IP interface and no mini Webserver is integrated. But a “Get” from an browser will be detected and decoded, but no answer occurs. That means if you try to launch a command with a browser it will work, but the browser will show you “no page”.

Example:

The Player runs on a PC with the address 192.168.0.14 and as the remote control port is indicated port 9090.

If you post in your browser “''http://192.168.0.14:9090/IPLPLAY''“, the player will start to play the marked record.

If a port for direct remote control is switched on a “RC on” label is displayed in the player status line.

=== General Note ===

The first UID will be detected form the recording using the SOAP interface in the PBX. Therefore all Agents has to be in the same group that the SOAP user object.

Example: You have a simple user object called “MYSOAP”, put that object in an active group called “Recording” and now put all you Agents in the same group.

Remember that basically recording is done even without the group stuff. So the group is just required to detect the UID in “advanced”. But there is also an additional benefit; the reporting has less stress because the recorder will query the reporting just at the end of the call (knowing via SOAP when the “end” is) while calls without the group are detected as “finished” because the reporting has a valid CDR record, and so the recorder polls each 4 second the reporting on active calls. That means that it is in any case a good idea put the agents in a group, even if no external application is running.

== Related Articles ==

[[Reference10:Player_Voice_Recording]]

[[Reference10:Voice_Recorder/Setup]]

[[Howto:Last_Call_Recording]]

[[Howto:Universal_Track_Recording_Tool]]

[[Category:Concept|{{PAGENAME}}]]

Reference8:TAPI Service Provider

2013-12-20T13:16:14Z

Msr: /* Multi Site Configuration */

The ''innovaphone PBX V8.0 based TAPI Service Provider'' (TSP) is an enhanced version of the [[ Reference7:Unified Win32 and x64 TAPI Service Provider | previous TSP version ]] that takes advantage of the [[ Reference8:SOAP API | new SOAP features ]] provided with version 8 PBX firmware. It implements - like the previous versions - TAPI Version 3.0 without MSP (Media Service Provider).

The [[Reference7:Unified Win32 and x64 TAPI Service Provider| previous TSP ]] still must be used for V7 PBX systems.

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

==Applies To==
This information applies to
* innovaphone PBX V8.0 based TAPI Service Provider, Build 8001 and later
* innovaphone PBX V8 and later (that is, this Service Provider runs with PBX Firmware V8 and later)

==More Information==

=== Enhancements ===
; Support for V8 firmware [[Reference8:Administration/PBX/Objects#Devices | devices]] : Each user object device is represented as a TAPI line (all sharing an identical address, the objects extension a.k.a. ''Number'' property). This now allows to select individual registration devices when multiple devices are registered with the same PBX. Please note that in V8, [[ Reference8:Administration/PBX/Objects/Edit_Forks | mobility devices ]] are not shown and thus not represented by TAPI line device. This was introduced in V9 only.
; Support for presence based lines : These are TAPI lines shown which reflect the users presence state. Presence state ''open'' is mapped to a TAPI device status ''in service''. Presence activity ''on-the-phone'' is mapped to a virtual call in state ''connected''.
: '''NB''': V8 PBX Firmware did set presence activity ''on-the-phone'' for each user object having a call. Unfortunately, as this does create performance issues, this behaviour has been removed from V9 PBX Firmware. The ''presence line'' feature may be useless with V9 PBX when the application did rely on this particular V8 PBX behaviour.

===System Requirements===
The TSP will install on any Windows 32bit and x64 platform down to Windows XP/Server 2003. For older systems, you must use a deprecated [[Reference7:TAPI_Service_Provider | previous TSP version]]. For systems running PBX firmware version 6 or earlier, you must use the even older [[Reference:TAPI_Service_Provider | version 5 based TSP]]. Note that there is no x64 version of the version 5 TSP!

The TSP needs to maintain parallel connections to each individual PBX in the system. For larger systems (i.e. systems with a huge number of PBXs), this may create substantial load to the underlying windows machine. The number of parallel activities scheduled by the TSP is thus limited as a function of the available main memory and number of processors. In particular, a maximum of 20 activities per available processor is allowed (up to build 8088, the limit is 60/processor for later builds). If this limit is exceeded, the TSP will issue performance warnings of class WARNINGS in the TSP log file and system TAPI performance will be poor. Use a more capable machine then.

Microsoft Windows operating system version for desktop clients (as opposed to server systems) limit the number and performance of TCP/IP connections. This may lead to bad performance or occasional request failures. We generally recommend to use server operating systems for 3rd party TAPI installations thus.

=== Download ===
The V8 TSP will be available on the ''apps'' section of the [http://download.innovaphone.com/ice/8.00/ V8 download page].

===Installation===
Windows cannot run a Win32 TSP on an x64 platform (although it can run Win32 applications on such platforms). This is why there are 2 versions of the setup, the x64 installer (<code>setup64-release.msi</code>) and the Win32 installer (<code>setup32-release.msi</code>.

The ''release'' setup packages provided will install the retail version. This is recommended for production purposes but provides no debug options whatsoever. To track down possible problems, support may instruct you to install the debug version.

The TSP may be installed on each machine where a desired TAPI based
application is to be run. If for example, Outlook is to be used, then
each client PC running Outlook may have the TSP installed. Although
this is typical for a 1st party configuration, all clients may have full
3rd party functionality, that is, they may control all existing lines.

As an alternative, the TSP can be installed on a single machine and a
3rd party TAPI server product (such as the IXI-Call Server available as
a separate product) may be used to provide the network clients with a
TAPI interface. Also, Microsoft’s Remote TAPI Server should work but is not being tested, so you use it on your own risk.

To install,
* select and download the <code>setup32-release.msi</code> install packages on 32bit platforms or the <code>setup64-release.msi</code> install package on 64bit platforms.
* double-click the install package to launch the installer
[[Image:Unified Win32 and x64 TAPI Service Provider - zipcontent.png]]
* accept the license agreement
* select the target folder
* complete the installer

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 (''Extras'')
* Click on the ''Add...'' button
[[Image:Unified Win32 and x64 TAPI Service Provider - Control Panel Add.png]]
* Select the innovaphone TAPI provider driver
* Fill out the configuration dialogue
* Install the provider by clicking ''OK''

==== File Organization ====
Windows forces all TAPI service provider files to reside in Windows' ''System Folder''. This is the <code>system32</code> folder in your windows install directory (usually <code>C:\windows\system32</code>), even if you are running an x64 platform! The installer will thus copy these files (<code>tsp8.tsp</code> and <code>tsp8UI.dll</code>) in to this directory. All other files however will be copied to the <code>innovaphone AG\innovaphone® PBX V8 TAPI Service Provider</code> folder underneath your systems ''Program Files Folder''.

The subdirectories <code>Debug</code> and <code>Logs</code> are created. <code>Debug</code> contains the driver's debug version, <code>Logs</code> will receive the log files when a debug version is used.

On x64 platform systems, the Win32 version of the configuration DLL (<code>tsp8UI.dll</code>) will be installed to the windows ''Windows on Windows64 System Folder'' (<code>SysWOW64</code>).

====Upgrading to a newer Version====
When you attempt to upgrade the TSP from a previous version, the Windows
installer will first remove any previous installation. When the new
software is installed then, the TSP will be installed again into the
TAPI system.

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

====Upgrading from the old Win32-only Version====
If you upgrade from the older Win32-only versions of the TSP (soap-appl/tapi/7.00 or soap-appl/tapi/5.00), you must first remove the old TSP from ''telephone and modem'' control panel and uninstall the old product from the ''Software'' (or ''Programs and Functions'') control panel.

When you upgrade from the old V7 64-bit TSP (soap-appl/tapi/7.00-64), you should first update this older version to the latest build available.

This procedure ensures that during the upgrade your TAPI lines retain their internal identifiers and thus their meaning in your TAPI application's configuration.

==== Uninstalling the TSP ====
To uninstall the TSP proceed as follows
* Remove the TAPI driver from the TAPI system using ''Telephony and Modem Control Panel''
* close ''Telephony and Modem Control Panel''
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* remove the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

You will notice that Windows may fail to remove the driver files from the ''Windows System Directory''. To clean up remove <code>tsp8.tsp</code> and <code>tsp8UI.dll</code> from the <code>system32</code> folder as well as - on x64 systems - from the <code>SysWOW64</code> folder.

Also, if you did file tracing, any remaining debug files in the <code>Logs</code> folder are left over and need to be removed manually.

The TSP will create some entries in the windows registry which will not be removed on uninstall. It is recommended to leave these entries as is. Only if you are sure you will never install the TSP again on this system or you are sure you will never use it with the PBX installation you used so far, you may want to delete them from the registry.

==== Rolling out First Party TSPs to multiple PCs ====
Normally, when multiple users require CTI and hence TAPI functionality, the best way is to use a server based, multi-client 3rd party CTI application. This will share all functions among all client PCs. If this is not an option, e.g. because the TAPI application in use does not support it, you may want to consider using Microsoft's TAPI Server and remote TSP. See Microsoft's [http://technet.microsoft.com/en-us/library/cc786297%28v=ws.10%29.aspx Telephony service providers overview] and [http://technet.microsoft.com/en-us/library/cc770373.aspx Manage Telephony Servers] documents.

If you still want to use the native innovaphone TSP on a number of PCs (instead of once on a server), you can roll out the TSP using some of the [http://support.microsoft.com/kb/816102/EN-US software deployment schemes Microsoft Server provide]. In such a case, you will likely want to deploy identical configurations to all these PCs. While this theoretically can be done by distributing registry settings, there will be a problem with the PBX access credentials. These are stored in encrypted format in the registry and can only be decrypted on the PC on which they have been set. That is, deploying such registry settings to other PCs will result in a non-functional setup.

To work around this problem, you may store the credentials in clear text in the registry. To do so, you would put the ''Password'' in a REG_SZ value named <code>admin1-free</code> and the ''Account'' into a REG_SZ value named <code>admin2-free</code>. If such a value is found in the proper place in the registry, the values configured using the telephony control panel are ignored.

[[Image:TAPI Service Provider-tsp8-nocrypt.png]]

'''Keep in mind that having credentials in clear in the registry presents a security risk!'''

This feature is available in build 8079 and later.

===Configuration===
The TSP configuration dialogue looks like this:

[[Image:Unified Win32 and x64 TAPI Service Provider - Config UI.png]]

* The ''VERIFY'' button will verify the configuration. Note that the ''Username'' drop down list will only be populated after a successful verify.
* 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 [[Reference7:SOAP_API | 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 Account'' and ''PBX Password''. Also, a suitable ''TAPI User'' must be selected.

==== Controlling the Line Devices handled by TAPI ====

TAPI connects to your PBX as a PBX user referred to as ''TAPI User''. It will see all PBX objects that are members of groups in which the ''TAPI User'' is an active member. If the ''TAPI User'' is not an active member in any group, TAPI will see the ''TAPI User'' object only. This may be useful in a [http://en.wikipedia.org/wiki/Telephony_Application_Programming_Interface 1st party TAPI scenario]. PBX objects are represented as TAPI lines.

The PBX object you use as ''TAPI User'' needs to have at least ''Viewing only'' [[Reference:Administration/PBX/Objects/Edit Rights | 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.

===== 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''.

[[Image:Unified Win32 and x64 TAPI Service Provider - FirstParty.png ]]

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 for the number of lines seen. If it is only one, then it will issue a warning message:

[[Image:Unified Win32 and x64 TAPI Service Provider - OnlyOne.png]]

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.

===== 3rd Party Configuration =====
In a 3rd party configuration, the TSP will work with multiple PBX objects.

[[Image:Unified Win32 and x64 TAPI Service Provider - ThirdParty.png]]

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 limit 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 pseudo PBX user object for use as the ''TAPI User''. This pseudo user is often called <code>_TAPI_</code>. 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 <code>tapi</code>.

==== Selective Call Forwards ====
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 [[Reference7:Administration/PBX/Objects/Edit_CFs | ''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:

[[Image:Unified Win32 and x64 TAPI Service Provider - NoTrunk.png]]

In a vanilla 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''.

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

[[Image:Unified Win32 and x64 TAPI Service Provider - MultiSite.png]]

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 object used as ''TAPI User'' must exist in each PBX with same properties (including name and the password). You may want to use <code>_TAPI_</code> as ''Name''/''Long Name''. This object must be ''active'' member in a group (which you may want to call <code>tapi</code>). A password must be set. The object must have at least ''cfg-grp'' rights
* the slave PBX-objects (or in older firmware versions the slave PBX Node-objects) must be visible to the TSP (that is, must be non-active member of the group the ''TAPI User'' object is an active member of, e.g. <code>tapi</code>) so that the slaves are made known to the TSP.

In a replicated scenario, you would create a ''TAPI user'' as recommended above and [[Reference8:Administration/PBX/Objects#Objects_with_empty_node_or_PBX | leave the ''PBX'' and ''Node'' properties empty ]]. This user should then be used as both ''PBX Account'' and ''TAPI User Username'' in the TAPI configuration dialog.

''Further relevant settings'':

You can disable slave detection by checking ''Do not monitor slaves'' property in the TSP configuration dialogue.

TAPI maintains an ''address'' property per line device. This usually is the lines extension. In a multi site configuration, the address property will be set to the ''Number'' property of the node the respective PBX object is configured in, plus the ''Number'' property of the object itself. So if an object has ''Number'' <code>42</code> and lives in node <code>801</code>, then its correspondence line device will have address <code>80142</code>. By checking the ''Use pure node extensions'' property in the TSP configuration dialogue, you change the algorithm so that only the objects own ''Number'' is used (<code>42</code> in our example).

==== Standby Configurations ====
In a system with standby PBX for the master PBX, you need to specify the ''PBX Standby'' IP address. This will be connected if the master is unavailable. Note that there is no need to explicitly configure slave-standby PBXs.

==== Working with multiple, unrelated PBXs ====
When working with multiple, unrelated PBXs (that is, PBXs that do ''not'' form a PBX tree as slaves and masters do), the TSP cannot derive the list of PBXs to track from the registration status. To support such a configuration, you will need to configure the extraneous master PBXs manually using regedit. Please note that using regedit may harm your system and may even cause inability to boot!

To find and edit the right registry entries, proceed as follows:

* open the key <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>
* open its subkey <code>Device</code>''n'' where ''n'' is the provider id of the installed innovaphone TSP
* Open the <code>FQDN</code> key and add all extra PBXs
* For those PBXs that have a standby PBX, add a value to the <code>StandbyFQDN</code> key (please note: these are parallel lists. So master and standby need to have the same respective index in the <code>FQDN</code> and <code>StandbyFQDN</code> value lists)

The standard configuration UI will not show these extra values. However, it will also not touch them. So even if you use the standard UI to edit, only the first value in the lists will be changed and the remainder left unchanged. You can thus safely use the standard UI to edit all other values. As with multi site configurations, all PBXs need to be accessible using the same ''TAPI User''.

Please note that this method is deprecated and will likely be removed from future versions of the TSP.

==== Setting the Line Device Name ====
The TSP will derive the line device's name from the properties of the respective PBX object. By default the name will be the objects ''Long Name'' followed by the name of the PBX the user ought to register with in parentheses. So if the users ''Long Name'' is <code>Foo Bar</code> and the registration PBX is <code>branch1</code>, the line device will be called <code>Foo Bar [branch1]</code>. You can specify a different pattern by changing the ''TAPI Line Names'' property of the TSP configuration dialogue. The following replacement characters are available:

{|
|+
| Meta || Replacement
|+
| %c || The objects ''Long Name'' (cn)
|+
| %C || The objects ''Long Name'' (cn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Long Name''
|+
| %d || The objects ''Display Name'' (dn)
|+
| %D || The objects ''Display Name'' (dn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Display Name''
|+
| %h || The objects ''Name'' (h323 alias)
|+
| %H || The objects ''Name'' (h323 alias) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Name''
|+
| %t || The ''Name'' of the ''Device'' the line represents
|+
| %e || The objects extension (e164)
|+
| %E || The objects extension (e164) prefixed with the objects node number
|+
| %N || The line address as reported to TAPI
|+
| %n || host name (of master pbx)
|+
| %p || ''':'''''port-number'' (of master pbx's http access, empty if 80)
|+
| %P || raw port number of master pbx
|+
| %u || url-like user name ('''''user''@''host''''')
|+
| %U || user url as per draft-levin-iptel-h323-url-scheme-04 ('''h323:://''user''@''host'':''port''''')
|+
| %X || the PBX name the user is registered with (note that using this pattern may result in a change of the name when a standby situation occurs)
|+
| %x || the PBX name the user is reported by (note that using this pattern may result in a change of the name when the users ''PBX'' attribute changes)
|}

The default pattern is <code>%C (%x)</code>.



==== Miscellaneous Flags ====
; 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 a <code>@</code>.
; Do not show parked Calls : will hide parked calls from the TAPI application (as some get confused and don't know how to handle them)
; Map PBX Devices to Lines : if set, the TSP will create one TAPI line for each individual [[Reference9:PBX/Objects#Devices|PBX device]] configured in a user object. See [[#Enhancements]] above. If you do not set this flag, see [[Support:How should TAPI line device be registered?]]
; Map Presence Status to TAPI Lines : if set, the TSP will create one extra TAPI line for each PBX device object. See [[#Enhancements]] above.
; No special Disconnect Behaviour : normally, lines monitored by TAPI will behave slightly different when a call is terminated. With no TAPI on the line, the call will be disconnected immediately (from a PBX point of view). In cases where the phone would play some tones after termination of the call (e.g. a busy tone when the call has never been connected to the far end), this state is simulated by the phone and not visible to TAPI. Therefore, it is not possible to use TAPI functions on this call any more (as it in reality does not exist any more). When this flag is set, monitored lines will not be treated specially. Available from hotfix 6.

===Trouble Shooting===
The TSP will (from build 8095) 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'').

==== Turning on Debugging ====
There are 2 versions of the TSP, debug and retail, which are both copied to the machine during setup. The retail version is installed into the system directories, whereas the debug version is stored in a separate directory. This is available through a short cut in the Start menu.

The TSP can produce a number of debugging messages which can be helpful to debug issues (in both ''retail'' and ''debug'' builds). By default, debug messages are written to the systems debug buffer mechanism (using OutputDebugString()). Such messages can be examined using standard debugging tools, such as for example <code>dbgview</code> which is [http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx available from Microsoft].

Debug messages have a class associated with it and the amount of messages written can be controlled by enabling or disabling specific classes. This is done by setting a bitmask in the registry value <code>TraceLevel</code> in the <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code> key.

The easiest way to set the TSP's debug level is with the ''TSP Control'' utility (''tsptray.exe'') which is installed with the TSP.

The available classes include

{|
| Bit in <code>TraceLevel</code> || Class
|-
| 0x00000001 || Minimum tracing
|-
| 0x00000002 || TAPI api traces
|-
| 0x00000020 || Basic telephony object creation/destruction
|-
| 0x00000040 || Thread creation/destruction
|-
| 0x00000080 || Request creation/destruction
|-
| 0x00000100 || call related messages
|-
| 0x00000200 || Call id map
|-
| 0x00000400 || Warnings/Errors
|-
| 0x00000800 || Worker thread execution
|-
| 0x00001000 || Full lock/unlock notifications
|-
| 0x00002000 || Win32 Critical section create/destroy
|-
| 0x00004000 || Agent proxy support
|-
| 0x00008000 || constructor/destructor debug
|-
| 0x00010000 || development debugs
|-
| 0x00100000 || verbose debugging
|-
| 0x00200000 || SOAP trace
|-
| 0x00400000 || SOAP message dumps
|-
| 0x01000000 || ATL debug
|-
| 0x02000000 || line related messages
|-
| 0x04000000 || informational messages
|-
| 0x10000000 || dump call infos
|-
| 0x20000000 || dump PBX infos
|-
| 0x80000000 || output log messages to file
|}

If <code>TraceLevel</code> is not set, it defaults to (hex) <code>04000400</code> in retail builds and to (hex) FFFFFFFF in debug builds. A nice value to use is (hex) <code>92200580</code>. The <code>TraceLevel</code> can be changed during runtime of the provider (it may take up to 10 seconds though for the setting to take effect). In normal scenarios there is no need to install the debug version.

Both ''informational messages'' and ''Warnings/Errors'' are always turned on (from build 8095).

: A problem has been reported on Server 2008 x64 systems which may also apply to others. On such systems, the value of <code>TraceLevel</code> may be reset to its default every 10 seconds. A workaround is to change the account the Telephony service is running in from its default (usually ''Network Service'') to e.g. ''Local System''.

===== Crash Dumps =====
From build 8063 the TSP will write crash dumps to the log directory (usually something like <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8 TSP\Logs</code>) in case of a trap. In release installs, these are not very useful. For debug builds though, they include helfpul information. Please provide these files (the can be zipped to a great extent) to support if requested. A crash dump file will be called something like <code>TSP8build-hour#minute-day.month#seqnr.dmp</code>.

===== Forcing a Crash Dump =====
In rare cases, it may be useful to force a TAPI crash for debug reasons. This can be done by issueing a <code>lineMakeCall</code> with called number <code>0815</code>, called-subaddress <code>4711</code> and called-name <code>!crash!</code> or simply calling <code>0815|4711^!crash!</code> from phone.exe.

==== Saving Log Messages to a File ====
The <code>0x80000000</code> value is special, as it does not denote a message class. Instead, it turns on log file writing, both in retail and debug versions. For this to work, the registry value <code>DoTraceFile</code> must be set to <code>1</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code> when the TSP starts. If this value is not present, it defaults to <code>1</code> in both retail and debug builds. Setting it to 0 disables log file writing regardless of any other setting. This may save some CPU cycles for installations with a real large number of lines.

The TSP will keep 24 log files (a days worth) by default. This value can be changed using the <code>NumLogFiles</code> value in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>. Older log files will be removed. Also, when the TSP shuts down, it by default will remove all log files it 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. Form TSP V8 hotfix 8 on, this behaviour can be tweaked by setting the DWORD registry value <code>KeepLogFiles</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>:
{|
| 0 || default || remove all log files on termination
|-
| 1 || || keep the last ''n'' log files (depending on <code>NumLogFiles</code>) on termination
|-
| 2 || || keep all log files
|}

Larger systems (500 monitored lines and more) can slow down considerably when using the debug drivers.

==== Installing the Debug Version ====
To install the debug version, you first install the retail version as outlined above. You then copy the debug driver files from the <code>Debug</code> directory to your windows system directory <code>system32</code>. You may want to use the shortcut to the <code>Debug</code> folder which has been installed to the start menu for convenience.

For the copy to work, proceed as follows
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* copy the debug driver files to your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>

When you open ''Telephony and Modem Control Panel'' again, you should notice that the TSP driver name has changed to the debug version.

==== Switching back to the Retail Version ====
To go back from the debug to the release version, proceed as follows:
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* delete the debug driver files from your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>
* repair the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

Please note that simply re-installing the driver from the original .msi without removing it from the system directory will not work.

===References===
The test applications provided with this setup comes from [http://www.julmar.com Julmar Technology Inc].

=== Limitations ===

Please note that there currently is a limitation to 2000 users being in
all active groups of a particular user. Thus, you cannot configure more
than 2000 users to be handled by TAPI on a single PBX. This is a PBX
limitation (and applies for all PBX groups).

TAPI has a flat line model. That is, all line numbers (aka
''extensions'') are considered to live in a single name space. As a
result, lines with identical numbers cannot be distinguished in TAPI
(although they can exist). All extensions in all nodes of a PBX
numbering tree are represented as TAPI lines. When the TSP works with a
PXB that implements a hierarchical numbering tree, then some lines may
receive identical numbers (their node-local extension which may overlap
between nodes depending on the setting of the ''Use pure node extensions'' property). When a TAPI application uses these numbers to initiate
calls to such lines, the call will work or not work depending on the
calling lines position in the numbering tree (that is, lines within the
same node as the called line will be fine, others may fail).

===Known Problems===
* 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
* The TSP will read its configuration when it is loaded by the system. Thus, configuration changes require a re-load of the TSP. Unfortunately, there is no reliable way to force the system to unload the TSP, so you may have to reboot the system for changes to take effect. See the [[ Howto:Troubleshooting_the_TAPI_service_provider | TAPI trouble shooting article ]] for details
* The TSP will use HTTP basic authentication to talk the PBX. So if you disable basic authentication in the PBX's configuration, the TSP will not work. It is recommended to use HTTPS
* TAPI requires the TSP to assign a unique id to each line device. This ID must not change between re-boots of the system or between upgrades of the TSP. This is done by keeping a persistent table in the windows registry (in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider\lineGUIDs</code>) that maps the PBX's line GUID to a fixed integer value (known as ''permanent line id'' in TAPI speak). This key is retained even on uninstall. To get rid of it, you must remove it manually
* Microsoft installer fails to remove driver files installed to the windows system folder. This is why the TSP driver files are still present after an uninstall of the software. To get rid of them, remove <code>TSP8.tsp</code> and <code>TSP8UI.dll</code> from both ''%windir%''<code>\system32</code> and ''%windir%''<code>\sysWOW64</code>
* From Version 9, hotfix 1, the PBX firmware will not list objects tagged as [[Reference9:PBX/Objects#General_Object_Properties | ''hide from LDAP'' ]] in the result of a [[Reference9:Concept_SOAP_API#UserInfo.5B.5D_FindUser.28string_v501.2C_string_v700.2C_string_v800.2C_string_cn.2C_string_h323.2C_string_e164.2C_integer_count.2C_integer_next.29 | FindUser() ]] call. As a result, such objects will not be shown in the TAPI configuration dialogue ''Username'' drop-down. If you want to use such an object as ''TAPI User'' you can simply type in the name without selecting it from the drop down.
* Sometimes, setting configuration with ''TSP Control'' (not the telephone control panel dialogue) does not work due to windows' ''User Access Control (UAC)'', see [[Howto:TAPI_TSP_Control_Windows7]] for Details
* Various users have reported that first party TSP installations do not work reliably with Microsoft Outlook. Symptoms reported are spurious error pop-ups from Outlook although there was no real problem. We do not recommend first party installations anyway (see [[#Rolling_out_First_Party_TSPs_to_multiple_PCs]] for a reasoning), but these issues are related to Microsoft Outlook only. No such problems have been reported with other first party TAPI applications. Consider using solutions like Estos ProCall instead.
* The number of parallel threads used within the TSP is limited to max. 60 per CPU. As each connected PBX (amongst other things) is handled by a separate thread, if you have a large number of PBXs connected and only have a single CPU, you may run out of threads, resulting in a WARNING messages ''about to spawn new workerthread (n requests, m threads) -- but limit l exceeded''. This usually happens when you run the TSP on a virtualized platform such as vmWare and only dedicate a single CPU. Ignoring this warning results in sluggish behaviour.
==== TAPI on Windows8 / Server 2012 ====
===== User Access Control =====
Windows8 doesn't let you disable UAC completely. This has the disadvantage that ''TSP Control'' (tsptray.exe) cannot change system registry entries, which it needs to do to e.g. change debug settings for the TSP.

There are 2 ways around it:
# use the hidden ''Administrator'' account on Windows 8
# elevate the tsptray.exe application

To use the elevated ''Administrator'' account on Windows 8 you first need to un-hide it:
* log in to an account with administrator rights
* use the ''Windows-Key+X'' shortcut and select ''Command Prompt (Administrator)'' (''Eingabeaufforderung (Administrator)''). An elevated cmd prompt appears
* type <code>net user administrator /active:yes</code>
* the fully elevated ''Administrator'' account is now available and you can log-in to this account as usual
* '''Please make sure the account has a password set - by default, it does not!!'''

To elevate the tsptray.exe application;
* log in to an account with administrator rights
* start a windows explorer
* change directory to <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8-x64 TSP</code>
* right click on <code>tsptray.exe</code> and open the ''properties'' (''Eigenschaften'') menu
* switch to the ''Compatibility'' (''Kompatibilität'') tab
* tick the ''Run as administrator'' (''Program als Administrator ausführen'') check mark
* save the settings

Please note that Windows 8 will not let you run any "Metro App" in elevated mode!

===== HTTPS =====
The TSP will not be able to talk to the PBX using HTTPS with Windows8 or Server2012. This [[Support:DVL-Roadmap_TAPI_V8#HTTPS_SOAP_connections_did_not_work__on_Windows8_.2F_Server_2012|has been fixed]] with V8 TAPI Service Provider (32 and 64bit) - hotfix10.
===== .Net 3.5 missing on Server 2012 =====
Server 2012 has no support for .Net 3.5 by default. Even more, it cannot be installed just by downloading it. Instead, the ''NetFX3 Feature'' needs to be enabled. Here is how:

Microsoft Windows [Version 6.2.9200]
(c) 2012 Microsoft Corporation. Alle Rechte vorbehalten.

C:\Users\Administrator>dism /online /enable-feature /featurename:NetFX3 /all /Source:''<path to windows setup, e.g. d:>''\sources\sxs /LimitAccess

See also
* [http://blogs.technet.com/b/aviraj/archive/2012/08/04/windows-8-enable-net-framework-3-5-includes-net-2-0-and-3-0-i-e-netfx3-feature-in-online-amp-offline-mode.aspx?PageIndex=2 Windows 8: Enable .NET Framework 3.5]
* [http://msdn.microsoft.com/en-us/library/hh506443.aspx Installing the .NET Framework 3.5 on Windows 8]

=== Tweaks ===
There are a few configuration options which should be used rarely. They can be enabled by setting an appropriate registry key.

There are some values in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>:

; ProcessorMask : REG_DWORD. If set, the TSP will use <code>SetProcessAffinityMask(GetCurrentProcess(), set)</code> to limit TSP execution to one or more of the existing processors. Set to <code>0xff</code> by default.

; LineTimeOut : REG_DWORD. Can be set to a number of seconds the TSP should wait for the determination of lines to finish (default 90). On a large PBX, or a PBX with slow slaves, the determination might not finish in the default time frame. If this happens, TAPI applications may show ''Line unnamed'' line entries in their line list. If this is a problem, set it to a larger value (e.g. <code>120</code>).

; IgnoreDevStatus : REG_DWORD. Some applications get confused if TAPI reports line to be disconnected or out-of-service dynamically. Setting this to a non-zero value will disable any such notification.

; ClearFwdOnSet : REG_DWORD. If set to a non-zero value, the TSP will clear all current call forward settings before a lineForward request is executed. This implies that all call forward settings are ''replaced'' by the new settings. Standard behaviour is to only modify the settings, that is, replace all current settings of the same type with the settings found in the lineForward request (for example, if there is only one setting in the request that defines a CFU, then the current CFU settings are replaced by the new one provided. All others, such as e.g. CFNR settings, are left untouched).

: Tapi spec is pretty clear on how this should work: ''The provider should "unforward everything" prior to setting the new forwarding instructions''. Even though, for historical reasons, ClearFwdOnSet=0 has been the default in all TAPI versions prior to V8 hotfix 6, from hotfix 6 on, the default changes to 1, as this has turned out to be the widely accepted interpretation.

; No3PTY : REG_DWORD. See [[Reference8:TAPI_Service_Provider#Notes_on_3PTY_Conferences | Notes_on_3PTY_Conferences]] below.

; HiddenRecordingNumber: REG_SZ. Active recording in an innovaphone PBX is implemented as an implicit 3PTY conference with the recording sink as one of the parties. These will be shown as usual in the TAPI callstate. However, some applications get confused as this results in a situation, where a normal endpoint (read: phone) has more than one active (i.e. ''not on hold'') call. To suppress such calls in the TAPI call states, you can set this tweak to the number of the recording sink as configured in the phone's recording configuration tab. If so, any outgoing call from an endpoint that is registered with a PBX user object with a called number that equals the setting of this tweak, will be suppressed. So if your recording sink has the number <code>44</code>, you would set this registry value to <code>44</code> (this is available from TAPI V8 hotfix 8). Please note that this feature actually suppresses any call info for such calls, however, it does not revert previously announced call infos. So if the call is initiated using ''overlapped dialling'', all call states will be shown until the called number matches the value of <code>HiddenRecordingNumber</code> and all subsequent call states will be suppressed. This will probably leave the call shown in ''dialling'' state. The feature should be used for destinations which are called using ''block dialling'' only thus.

; SilentHold : REG_DWORD. When a call is put on hold using <code>lineHold</code>, both parties will normally hear ''music on hold'' emitted by the PBX. When <code>SilentHold</code> is set to a non-zero value, the initiating party will not hear any ''music on hold'' (this is available from TAPI V8 hotfix 8).

There are some more values in a key underneath <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code> called <code>Device</code>''XX'':

; NoDuplicateConnectedCalls : REG_DWORD. If set to 1, the TSP will never show more than one call per line to be active. Extra active calls will be shown as ''on-hold''. The situation occurs e.g. when a user initiates a 3PTY conference on the phone. This essentially is a bug fix for Microsoft's OCS client which forces any extra active call on-hold, thereby disturbing the 3PTY function. If your are using [http://www.estos.de/download/software/eccg.htm ESTOS' Call Control Gateway]: from version ''2.0.1.1474 - 05.11.2008'' there is a fix for this same problem available. This option thus is deprecated.

===List of supported TSPI functions===

The TSP supports the following TAPI Service Provider Interface Functions. Note that these do not map one to one with TAPI user functions. For more information, see the Microsoft TAPI documentation.

TSPI_lineAnswer
TSPI_lineBlindTransfer
TSPI_lineClose
TSPI_lineCloseCall
TSPI_lineCompleteTransfer
TSPI_lineDevSpecific
TSPI_lineDevSpecificFeature
TSPI_lineDial
TSPI_lineDrop
TSPI_lineForward
TSPI_lineGenerateDigits
TSPI_lineGetAddressCaps
TSPI_lineGetAddressID
TSPI_lineGetAddressStatus
TSPI_lineGetCallAddressID
TSPI_lineGetCallHubTracking
TSPI_lineGetCallIDs
TSPI_lineGetCallInfo
TSPI_lineGetCallStatus
TSPI_lineGetDevCaps
TSPI_lineGetExtensionID
TSPI_lineGetID
TSPI_lineGetLineDevStatus
TSPI_lineGetNumAddressIDs
TSPI_lineHold
TSPI_lineMakeCall
TSPI_lineNegotiateExtVersion
TSPI_lineNegotiateTSPIVersion
TSPI_lineOpen
TSPI_linePark
TSPI_linePickup
TSPI_lineRedirect
TSPI_lineSelectExtVersion
TSPI_lineSendUserUserInfo
TSPI_lineSetAppSpecific
TSPI_lineSetCallData
TSPI_lineSetCallHubTracking
TSPI_lineSetCallParams
TSPI_lineSetCurrentLocation
TSPI_lineSetDefaultMediaDetection
TSPI_lineSetMediaMode
TSPI_lineSetStatusMessages
TSPI_lineSetupTransfer
TSPI_lineSwapHold
TSPI_lineUnhold
TSPI_lineUnpark
TSPI_providerConfig
TSPI_providerCreateLineDevice
TSPI_providerEnumDevices
TSPI_providerGenericDialogData
TSPI_providerInit
TSPI_providerInstall
TSPI_providerRemove
TSPI_providerShutdown
TSPI_providerUIIdentify

=====Notes on Consultation Calls=====
This TSP supports the <code>lineSetupTransfer</code> function. However, strictly speaking, this function is not needed and should not be used. It is merely intended for applications which do not offer a consultation call interface to the user when this function is not available. Instead, <code>TSPI_lineMakeCall</code> can be used where <code>lineSetupTransfer</code> would be otherwise. The notion of a special ''consultation call'' is an idiosyncrasy forced by legacy PBX technologies which were not able to transfer two arbitrary calls. In these scenarios, a potentially to-be-transferred call needed to be linked to the primary call. The PBX can transfer two arbitrary calls and thus there is no need for <code>lineSetupTransfer</code>. This ability is indicated by the <code>LINEADDRCAPFLAGS_TRANSFERMAKE</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE </code> flags. The transfer is then requested by using <code>TSPI_lineCompleteTransfer</code>.

=====Notes on 3PTY Conferences=====
The TSP supports the management of 3PTY conferences. These can be initiated by using <code>TSPI_lineCompleteTransfer</code> with <code>LINETRANSFERMODE_CONFERENCE</code> instead of <code>LINETRANSFERMODE_TRANSFER</code>. This is indicated by the flags <code>LINEADDRCAPFLAGS_CONFERENCEHELD</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE</code>. The 3PTY function is actually implemented by the innovaphone IP phones (such as IP2xx). Therefore, these capabilities are only advertised if the line is based on a PBX user object. Still, some lines where the capabilities are advertised cannot do 3PTY (such as e.g. DECT lines, analogue lines, 3rd party devices, ...). So the call to <code>TSPI_lineCompleteTransfer</code> will succeed but the conference will not be initiated and the subsequent call states will not indicate a conference (as there is no).

Also, if non-telephone devices are registered with a PBX user object and these device have multiple concurrent calls (e.g. a call center connected with a multi-channel XCapi), these will be viewed as 3PTY calls (as this is the way such calls appear to the TAPI: a line with more than one non-held call). If these calls are in fact no 3PTY, this may lead to confusing call indications from TAPI. It is better to register such objects as a PBX gateway object. Special treatment of 3PTY calls can be disabled by setting the registry flag <code>No3PTY</code> (from build 8087 onwards).

A 3PTY conference will create a new call handle for the conference. The only operation available for such a handle is <code>TSPI_lineDrop</code>. This will terminate the conference and restore the state active before the conference was initiated (that is, the phone that implemented the conference will now have 2 calls, one active and one on hold). This is indicated by not setting <code>LINEADDRCAPFLAGS_CONFDROP</code>.

A <code>lineDrop()</code> on one of the 2 ''real'' calls involved will of course cancel this call and thus remove the 3PTY.

======Notes on Intrusion Calls======
A special case of 3PTY is an intrusion call initiated by a [[Reference9:Phone/User/Function-Keys/Partner | partner function key]]. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the intrusion call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is an intrusion call).

======Notes on Recording Calls======
A special case of 3PTY is a recording call. This effectively creates an user-invisible 3PTY on the phone. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the recording call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is a recording call).

Recording calls are shown as normal conferences (unless <code>No3PTY</code> is set). This might be confusing to applications and/or users. See the <code>HiddenRecordingNumber</code> tweak above for a method to hide such calls.

=====Notes on parked Calls=====
The PBX can park calls from and to any existing PBX object, e.g. by virtue of [[Reference8:Configuration/Registration/Function-Keys/Park | specific feature keys]]. They are parked to/from a numeric ''park position''. In SOAP however, calls are parked to an object by providing the objects '''UserInitialize()''' handle and a park position. Parked calls are then reported as straight calls with a distinct signalling state (8). The park position is not conveyed as part of the '''CallInfo''' record. To unpark, '''[[Reference8:SOAP_API#integer_UserPickup.28int_user.2C_string_cn.2C_integer_call.2C_string_group.2C_int_reg.2C_InfoArray_info.29 | UserPickup]]''' can be used providing the parked calls call handle as '''call''' argument.

The TAPI specification is unclear on how the address information required to '''lineUnpark()''' a call can be obtained by an application (except that it is returned from '''linePark()''' if the call was parked using TAPI). The TSP thus indicates parked calls on a line with a call reason <code>LINECALLREASON_PARKED</code>. The caller id information is set to the parked calls call handle. This way, the application can take the caller id information and provide it to '''lineUnpark()''' to unpark a call. If the appication does not support this mode of operation but supports '''lineUnpark()''' and lets the user input the park identifier, the user can just provide the caller id information.

Some applications do not care for parked calls (by examining the call reason) and just blindly report these calls like ordinary connected calls (thereby confusing the user). To work around this problem, reporting parked calls can be turned off in the TSP configuration dialogue.

=====Notes on sending User to User Information =====
The TAPI specification for sending UserUserInfo closely resembles the way ISDN defines this service. Although the innovaphone PBX supports this service both with H.323 and SIP, it is ''not'' supported in this TSP. Instead, sending user to user information is implemented using H.323/SIP messaging. However, there are some important deviations and limitations caused hereby:
* data is ''not transparent''. That is, the TSP only allows for null-terminated unicode to be sent. The data must be of even length and the last two bytes must be null.
* data is ''not sent within the call'', but by initiating a separate call. This implies that the target number used to send the message carrying the data to is 'guessed' from the available call data. For example, if the call is in a connected state and a connected number is known, the message is sent to the connected number. If the call is in the ringback state, then either the called number or - if available - the redirection number is used and so forth.
* message calls are not indicated by the SOAP CallInfo records. As a result, messages (that is, user to user information) cannot be received with TAPI and ''lineReleaseUserUserInfo is not supported''

=====Notes on sending proprietary innovaphone Remote Control Facilities =====
The SOAP [[Reference8:SOAP_API#UserRc.28integer_call.2C_integer_rc.29|UserRc]] function allows to send various [[Reference:Remote Control Facility|facility messages]] to an innovaphone phone device. In some cases, it is useful to be able to invoke this function through a standard TAPI mechanism. This can be achieved by using the TAPI '''lineBlindTransfer''' function. If the ''called party name'' provided as destination for the ''lineBlindTransfer'' (in ''lpszDestAddress'') has the magic value <code>USERRC</code>, then the ''called subaddress'' is converted to an integer and the result is sent as remote control facility to the call the blind transfer is applied for. For details on how to code the ''called party name'' and the ''called subaddress'' into ''lpszDestAddress'' see [http://msdn.microsoft.com/en-us/library/windows/desktop/ms726017%28v=vs.85%29.aspx Microsoft's ''Canonical Address'' specification]. This works from TAPI8 hotfix 4.

For example, initiating a blind transfer to <code>|16^USERRC</code> (empty address, subaddress 16 (that is, [[Reference:Remote Control Facility|''change to handset mode'']]), called name <code>USERRC</code>) will switch the phone having the call to be transferred into handset mode (and <code>|18^USERRC</code> will switch it back to handsfree mode). Of course, no actual transfer will happen in these cases (''lineBlindTransfer'' is merely used as a vehicle to send the facility to the proper call).

Such proprietary facility message can also be sent with ''lineMakeCall'' (that is, in SOAP's [[Reference8:SOAP_API#integer_UserCall.28integer_user.2C_string_cn.2C_string_e164.2C_string_h323.2C_int_reg.2C_InfoArray_info.2C_int_rc.2C_string_srce164.29|UserCall]] function). For example, setting up a call to <code>123|21^USERRC</code> will send an intrusion call to extension 123 and intrude any call that might be active there. This works from TAPI8 hotfix 6. Please note that the innovaphone TAPI service provider does not support TAPI's ''lineCompleteCall'' function with <code>LINECALLCOMPLMODE_INTRUDE</code> though (as TAPI's call model here does not fit with the PBX's call model). Please also note that intrusion calls look like 3PTY calls to TAPI (see [[#Notes_on_Intrusion_Calls|notes on intrusion calls]] above).

Remote control facilities are implemented by the telephone devices, so these functions are subject to the phone firmware in use.

[[Category:Howto|{{PAGENAME}}]]
[[Category:Concept|{{PAGENAME}}]]

Reference8:TAPI Service Provider

2013-12-20T09:45:43Z

Msr: /* Multi Site Configuration */

The ''innovaphone PBX V8.0 based TAPI Service Provider'' (TSP) is an enhanced version of the [[ Reference7:Unified Win32 and x64 TAPI Service Provider | previous TSP version ]] that takes advantage of the [[ Reference8:SOAP API | new SOAP features ]] provided with version 8 PBX firmware. It implements - like the previous versions - TAPI Version 3.0 without MSP (Media Service Provider).

The [[Reference7:Unified Win32 and x64 TAPI Service Provider| previous TSP ]] still must be used for V7 PBX systems.

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

==Applies To==
This information applies to
* innovaphone PBX V8.0 based TAPI Service Provider, Build 8001 and later
* innovaphone PBX V8 and later (that is, this Service Provider runs with PBX Firmware V8 and later)

==More Information==

=== Enhancements ===
; Support for V8 firmware [[Reference8:Administration/PBX/Objects#Devices | devices]] : Each user object device is represented as a TAPI line (all sharing an identical address, the objects extension a.k.a. ''Number'' property). This now allows to select individual registration devices when multiple devices are registered with the same PBX. Please note that in V8, [[ Reference8:Administration/PBX/Objects/Edit_Forks | mobility devices ]] are not shown and thus not represented by TAPI line device. This was introduced in V9 only.
; Support for presence based lines : These are TAPI lines shown which reflect the users presence state. Presence state ''open'' is mapped to a TAPI device status ''in service''. Presence activity ''on-the-phone'' is mapped to a virtual call in state ''connected''.
: '''NB''': V8 PBX Firmware did set presence activity ''on-the-phone'' for each user object having a call. Unfortunately, as this does create performance issues, this behaviour has been removed from V9 PBX Firmware. The ''presence line'' feature may be useless with V9 PBX when the application did rely on this particular V8 PBX behaviour.

===System Requirements===
The TSP will install on any Windows 32bit and x64 platform down to Windows XP/Server 2003. For older systems, you must use a deprecated [[Reference7:TAPI_Service_Provider | previous TSP version]]. For systems running PBX firmware version 6 or earlier, you must use the even older [[Reference:TAPI_Service_Provider | version 5 based TSP]]. Note that there is no x64 version of the version 5 TSP!

The TSP needs to maintain parallel connections to each individual PBX in the system. For larger systems (i.e. systems with a huge number of PBXs), this may create substantial load to the underlying windows machine. The number of parallel activities scheduled by the TSP is thus limited as a function of the available main memory and number of processors. In particular, a maximum of 20 activities per available processor is allowed (up to build 8088, the limit is 60/processor for later builds). If this limit is exceeded, the TSP will issue performance warnings of class WARNINGS in the TSP log file and system TAPI performance will be poor. Use a more capable machine then.

Microsoft Windows operating system version for desktop clients (as opposed to server systems) limit the number and performance of TCP/IP connections. This may lead to bad performance or occasional request failures. We generally recommend to use server operating systems for 3rd party TAPI installations thus.

=== Download ===
The V8 TSP will be available on the ''apps'' section of the [http://download.innovaphone.com/ice/8.00/ V8 download page].

===Installation===
Windows cannot run a Win32 TSP on an x64 platform (although it can run Win32 applications on such platforms). This is why there are 2 versions of the setup, the x64 installer (<code>setup64-release.msi</code>) and the Win32 installer (<code>setup32-release.msi</code>.

The ''release'' setup packages provided will install the retail version. This is recommended for production purposes but provides no debug options whatsoever. To track down possible problems, support may instruct you to install the debug version.

The TSP may be installed on each machine where a desired TAPI based
application is to be run. If for example, Outlook is to be used, then
each client PC running Outlook may have the TSP installed. Although
this is typical for a 1st party configuration, all clients may have full
3rd party functionality, that is, they may control all existing lines.

As an alternative, the TSP can be installed on a single machine and a
3rd party TAPI server product (such as the IXI-Call Server available as
a separate product) may be used to provide the network clients with a
TAPI interface. Also, Microsoft’s Remote TAPI Server should work but is not being tested, so you use it on your own risk.

To install,
* select and download the <code>setup32-release.msi</code> install packages on 32bit platforms or the <code>setup64-release.msi</code> install package on 64bit platforms.
* double-click the install package to launch the installer
[[Image:Unified Win32 and x64 TAPI Service Provider - zipcontent.png]]
* accept the license agreement
* select the target folder
* complete the installer

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 (''Extras'')
* Click on the ''Add...'' button
[[Image:Unified Win32 and x64 TAPI Service Provider - Control Panel Add.png]]
* Select the innovaphone TAPI provider driver
* Fill out the configuration dialogue
* Install the provider by clicking ''OK''

==== File Organization ====
Windows forces all TAPI service provider files to reside in Windows' ''System Folder''. This is the <code>system32</code> folder in your windows install directory (usually <code>C:\windows\system32</code>), even if you are running an x64 platform! The installer will thus copy these files (<code>tsp8.tsp</code> and <code>tsp8UI.dll</code>) in to this directory. All other files however will be copied to the <code>innovaphone AG\innovaphone® PBX V8 TAPI Service Provider</code> folder underneath your systems ''Program Files Folder''.

The subdirectories <code>Debug</code> and <code>Logs</code> are created. <code>Debug</code> contains the driver's debug version, <code>Logs</code> will receive the log files when a debug version is used.

On x64 platform systems, the Win32 version of the configuration DLL (<code>tsp8UI.dll</code>) will be installed to the windows ''Windows on Windows64 System Folder'' (<code>SysWOW64</code>).

====Upgrading to a newer Version====
When you attempt to upgrade the TSP from a previous version, the Windows
installer will first remove any previous installation. When the new
software is installed then, the TSP will be installed again into the
TAPI system.

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

====Upgrading from the old Win32-only Version====
If you upgrade from the older Win32-only versions of the TSP (soap-appl/tapi/7.00 or soap-appl/tapi/5.00), you must first remove the old TSP from ''telephone and modem'' control panel and uninstall the old product from the ''Software'' (or ''Programs and Functions'') control panel.

When you upgrade from the old V7 64-bit TSP (soap-appl/tapi/7.00-64), you should first update this older version to the latest build available.

This procedure ensures that during the upgrade your TAPI lines retain their internal identifiers and thus their meaning in your TAPI application's configuration.

==== Uninstalling the TSP ====
To uninstall the TSP proceed as follows
* Remove the TAPI driver from the TAPI system using ''Telephony and Modem Control Panel''
* close ''Telephony and Modem Control Panel''
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* remove the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

You will notice that Windows may fail to remove the driver files from the ''Windows System Directory''. To clean up remove <code>tsp8.tsp</code> and <code>tsp8UI.dll</code> from the <code>system32</code> folder as well as - on x64 systems - from the <code>SysWOW64</code> folder.

Also, if you did file tracing, any remaining debug files in the <code>Logs</code> folder are left over and need to be removed manually.

The TSP will create some entries in the windows registry which will not be removed on uninstall. It is recommended to leave these entries as is. Only if you are sure you will never install the TSP again on this system or you are sure you will never use it with the PBX installation you used so far, you may want to delete them from the registry.

==== Rolling out First Party TSPs to multiple PCs ====
Normally, when multiple users require CTI and hence TAPI functionality, the best way is to use a server based, multi-client 3rd party CTI application. This will share all functions among all client PCs. If this is not an option, e.g. because the TAPI application in use does not support it, you may want to consider using Microsoft's TAPI Server and remote TSP. See Microsoft's [http://technet.microsoft.com/en-us/library/cc786297%28v=ws.10%29.aspx Telephony service providers overview] and [http://technet.microsoft.com/en-us/library/cc770373.aspx Manage Telephony Servers] documents.

If you still want to use the native innovaphone TSP on a number of PCs (instead of once on a server), you can roll out the TSP using some of the [http://support.microsoft.com/kb/816102/EN-US software deployment schemes Microsoft Server provide]. In such a case, you will likely want to deploy identical configurations to all these PCs. While this theoretically can be done by distributing registry settings, there will be a problem with the PBX access credentials. These are stored in encrypted format in the registry and can only be decrypted on the PC on which they have been set. That is, deploying such registry settings to other PCs will result in a non-functional setup.

To work around this problem, you may store the credentials in clear text in the registry. To do so, you would put the ''Password'' in a REG_SZ value named <code>admin1-free</code> and the ''Account'' into a REG_SZ value named <code>admin2-free</code>. If such a value is found in the proper place in the registry, the values configured using the telephony control panel are ignored.

[[Image:TAPI Service Provider-tsp8-nocrypt.png]]

'''Keep in mind that having credentials in clear in the registry presents a security risk!'''

This feature is available in build 8079 and later.

===Configuration===
The TSP configuration dialogue looks like this:

[[Image:Unified Win32 and x64 TAPI Service Provider - Config UI.png]]

* The ''VERIFY'' button will verify the configuration. Note that the ''Username'' drop down list will only be populated after a successful verify.
* 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 [[Reference7:SOAP_API | 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 Account'' and ''PBX Password''. Also, a suitable ''TAPI User'' must be selected.

==== Controlling the Line Devices handled by TAPI ====

TAPI connects to your PBX as a PBX user referred to as ''TAPI User''. It will see all PBX objects that are members of groups in which the ''TAPI User'' is an active member. If the ''TAPI User'' is not an active member in any group, TAPI will see the ''TAPI User'' object only. This may be useful in a [http://en.wikipedia.org/wiki/Telephony_Application_Programming_Interface 1st party TAPI scenario]. PBX objects are represented as TAPI lines.

The PBX object you use as ''TAPI User'' needs to have at least ''Viewing only'' [[Reference:Administration/PBX/Objects/Edit Rights | 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.

===== 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''.

[[Image:Unified Win32 and x64 TAPI Service Provider - FirstParty.png ]]

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 for the number of lines seen. If it is only one, then it will issue a warning message:

[[Image:Unified Win32 and x64 TAPI Service Provider - OnlyOne.png]]

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.

===== 3rd Party Configuration =====
In a 3rd party configuration, the TSP will work with multiple PBX objects.

[[Image:Unified Win32 and x64 TAPI Service Provider - ThirdParty.png]]

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 limit 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 pseudo PBX user object for use as the ''TAPI User''. This pseudo user is often called <code>_TAPI_</code>. 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 <code>tapi</code>.

==== Selective Call Forwards ====
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 [[Reference7:Administration/PBX/Objects/Edit_CFs | ''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:

[[Image:Unified Win32 and x64 TAPI Service Provider - NoTrunk.png]]

In a vanilla 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''.

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

[[Image:Unified Win32 and x64 TAPI Service Provider - MultiSite.png]]

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 object used as ''TAPI User'' must exist in each PBX with same properties (including name and the password). You may want to use <code>_TAPI_</code> as ''Name''/''Long Name''. This object must be ''active'' member in a group (which you may want to call <code>tapi</code>). A password must be set. The object must have at least ''cfg-grp'' rights
* the PBX/Node and PBX/User objects must be visible to the TSP (that is, must be non-active member of the group the ''TAPI User'' object is an active member of, e.g. <code>tapi</code>)

In a replicated scenario, you would create a ''TAPI user'' as recommended above and [[Reference8:Administration/PBX/Objects#Objects_with_empty_node_or_PBX | leave the ''PBX'' and ''Node'' properties empty ]]. This user should then be used as both ''PBX Account'' and ''TAPI User Username'' in the TAPI configuration dialog.

''Further relevant settings'':

You can disable slave detection by checking ''Do not monitor slaves'' property in the TSP configuration dialogue.

TAPI maintains an ''address'' property per line device. This usually is the lines extension. In a multi site configuration, the address property will be set to the ''Number'' property of the node the respective PBX object is configured in, plus the ''Number'' property of the object itself. So if an object has ''Number'' <code>42</code> and lives in node <code>801</code>, then its correspondence line device will have address <code>80142</code>. By checking the ''Use pure node extensions'' property in the TSP configuration dialogue, you change the algorithm so that only the objects own ''Number'' is used (<code>42</code> in our example).

==== Standby Configurations ====
In a system with standby PBX for the master PBX, you need to specify the ''PBX Standby'' IP address. This will be connected if the master is unavailable. Note that there is no need to explicitly configure slave-standby PBXs.

==== Working with multiple, unrelated PBXs ====
When working with multiple, unrelated PBXs (that is, PBXs that do ''not'' form a PBX tree as slaves and masters do), the TSP cannot derive the list of PBXs to track from the registration status. To support such a configuration, you will need to configure the extraneous master PBXs manually using regedit. Please note that using regedit may harm your system and may even cause inability to boot!

To find and edit the right registry entries, proceed as follows:

* open the key <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>
* open its subkey <code>Device</code>''n'' where ''n'' is the provider id of the installed innovaphone TSP
* Open the <code>FQDN</code> key and add all extra PBXs
* For those PBXs that have a standby PBX, add a value to the <code>StandbyFQDN</code> key (please note: these are parallel lists. So master and standby need to have the same respective index in the <code>FQDN</code> and <code>StandbyFQDN</code> value lists)

The standard configuration UI will not show these extra values. However, it will also not touch them. So even if you use the standard UI to edit, only the first value in the lists will be changed and the remainder left unchanged. You can thus safely use the standard UI to edit all other values. As with multi site configurations, all PBXs need to be accessible using the same ''TAPI User''.

Please note that this method is deprecated and will likely be removed from future versions of the TSP.

==== Setting the Line Device Name ====
The TSP will derive the line device's name from the properties of the respective PBX object. By default the name will be the objects ''Long Name'' followed by the name of the PBX the user ought to register with in parentheses. So if the users ''Long Name'' is <code>Foo Bar</code> and the registration PBX is <code>branch1</code>, the line device will be called <code>Foo Bar [branch1]</code>. You can specify a different pattern by changing the ''TAPI Line Names'' property of the TSP configuration dialogue. The following replacement characters are available:

{|
|+
| Meta || Replacement
|+
| %c || The objects ''Long Name'' (cn)
|+
| %C || The objects ''Long Name'' (cn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Long Name''
|+
| %d || The objects ''Display Name'' (dn)
|+
| %D || The objects ''Display Name'' (dn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Display Name''
|+
| %h || The objects ''Name'' (h323 alias)
|+
| %H || The objects ''Name'' (h323 alias) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Name''
|+
| %t || The ''Name'' of the ''Device'' the line represents
|+
| %e || The objects extension (e164)
|+
| %E || The objects extension (e164) prefixed with the objects node number
|+
| %N || The line address as reported to TAPI
|+
| %n || host name (of master pbx)
|+
| %p || ''':'''''port-number'' (of master pbx's http access, empty if 80)
|+
| %P || raw port number of master pbx
|+
| %u || url-like user name ('''''user''@''host''''')
|+
| %U || user url as per draft-levin-iptel-h323-url-scheme-04 ('''h323:://''user''@''host'':''port''''')
|+
| %X || the PBX name the user is registered with (note that using this pattern may result in a change of the name when a standby situation occurs)
|+
| %x || the PBX name the user is reported by (note that using this pattern may result in a change of the name when the users ''PBX'' attribute changes)
|}

The default pattern is <code>%C (%x)</code>.



==== Miscellaneous Flags ====
; 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 a <code>@</code>.
; Do not show parked Calls : will hide parked calls from the TAPI application (as some get confused and don't know how to handle them)
; Map PBX Devices to Lines : if set, the TSP will create one TAPI line for each individual [[Reference9:PBX/Objects#Devices|PBX device]] configured in a user object. See [[#Enhancements]] above. If you do not set this flag, see [[Support:How should TAPI line device be registered?]]
; Map Presence Status to TAPI Lines : if set, the TSP will create one extra TAPI line for each PBX device object. See [[#Enhancements]] above.
; No special Disconnect Behaviour : normally, lines monitored by TAPI will behave slightly different when a call is terminated. With no TAPI on the line, the call will be disconnected immediately (from a PBX point of view). In cases where the phone would play some tones after termination of the call (e.g. a busy tone when the call has never been connected to the far end), this state is simulated by the phone and not visible to TAPI. Therefore, it is not possible to use TAPI functions on this call any more (as it in reality does not exist any more). When this flag is set, monitored lines will not be treated specially. Available from hotfix 6.

===Trouble Shooting===
The TSP will (from build 8095) 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'').

==== Turning on Debugging ====
There are 2 versions of the TSP, debug and retail, which are both copied to the machine during setup. The retail version is installed into the system directories, whereas the debug version is stored in a separate directory. This is available through a short cut in the Start menu.

The TSP can produce a number of debugging messages which can be helpful to debug issues (in both ''retail'' and ''debug'' builds). By default, debug messages are written to the systems debug buffer mechanism (using OutputDebugString()). Such messages can be examined using standard debugging tools, such as for example <code>dbgview</code> which is [http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx available from Microsoft].

Debug messages have a class associated with it and the amount of messages written can be controlled by enabling or disabling specific classes. This is done by setting a bitmask in the registry value <code>TraceLevel</code> in the <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code> key.

The easiest way to set the TSP's debug level is with the ''TSP Control'' utility (''tsptray.exe'') which is installed with the TSP.

The available classes include

{|
| Bit in <code>TraceLevel</code> || Class
|-
| 0x00000001 || Minimum tracing
|-
| 0x00000002 || TAPI api traces
|-
| 0x00000020 || Basic telephony object creation/destruction
|-
| 0x00000040 || Thread creation/destruction
|-
| 0x00000080 || Request creation/destruction
|-
| 0x00000100 || call related messages
|-
| 0x00000200 || Call id map
|-
| 0x00000400 || Warnings/Errors
|-
| 0x00000800 || Worker thread execution
|-
| 0x00001000 || Full lock/unlock notifications
|-
| 0x00002000 || Win32 Critical section create/destroy
|-
| 0x00004000 || Agent proxy support
|-
| 0x00008000 || constructor/destructor debug
|-
| 0x00010000 || development debugs
|-
| 0x00100000 || verbose debugging
|-
| 0x00200000 || SOAP trace
|-
| 0x00400000 || SOAP message dumps
|-
| 0x01000000 || ATL debug
|-
| 0x02000000 || line related messages
|-
| 0x04000000 || informational messages
|-
| 0x10000000 || dump call infos
|-
| 0x20000000 || dump PBX infos
|-
| 0x80000000 || output log messages to file
|}

If <code>TraceLevel</code> is not set, it defaults to (hex) <code>04000400</code> in retail builds and to (hex) FFFFFFFF in debug builds. A nice value to use is (hex) <code>92200580</code>. The <code>TraceLevel</code> can be changed during runtime of the provider (it may take up to 10 seconds though for the setting to take effect). In normal scenarios there is no need to install the debug version.

Both ''informational messages'' and ''Warnings/Errors'' are always turned on (from build 8095).

: A problem has been reported on Server 2008 x64 systems which may also apply to others. On such systems, the value of <code>TraceLevel</code> may be reset to its default every 10 seconds. A workaround is to change the account the Telephony service is running in from its default (usually ''Network Service'') to e.g. ''Local System''.

===== Crash Dumps =====
From build 8063 the TSP will write crash dumps to the log directory (usually something like <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8 TSP\Logs</code>) in case of a trap. In release installs, these are not very useful. For debug builds though, they include helfpul information. Please provide these files (the can be zipped to a great extent) to support if requested. A crash dump file will be called something like <code>TSP8build-hour#minute-day.month#seqnr.dmp</code>.

===== Forcing a Crash Dump =====
In rare cases, it may be useful to force a TAPI crash for debug reasons. This can be done by issueing a <code>lineMakeCall</code> with called number <code>0815</code>, called-subaddress <code>4711</code> and called-name <code>!crash!</code> or simply calling <code>0815|4711^!crash!</code> from phone.exe.

==== Saving Log Messages to a File ====
The <code>0x80000000</code> value is special, as it does not denote a message class. Instead, it turns on log file writing, both in retail and debug versions. For this to work, the registry value <code>DoTraceFile</code> must be set to <code>1</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code> when the TSP starts. If this value is not present, it defaults to <code>1</code> in both retail and debug builds. Setting it to 0 disables log file writing regardless of any other setting. This may save some CPU cycles for installations with a real large number of lines.

The TSP will keep 24 log files (a days worth) by default. This value can be changed using the <code>NumLogFiles</code> value in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>. Older log files will be removed. Also, when the TSP shuts down, it by default will remove all log files it 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. Form TSP V8 hotfix 8 on, this behaviour can be tweaked by setting the DWORD registry value <code>KeepLogFiles</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>:
{|
| 0 || default || remove all log files on termination
|-
| 1 || || keep the last ''n'' log files (depending on <code>NumLogFiles</code>) on termination
|-
| 2 || || keep all log files
|}

Larger systems (500 monitored lines and more) can slow down considerably when using the debug drivers.

==== Installing the Debug Version ====
To install the debug version, you first install the retail version as outlined above. You then copy the debug driver files from the <code>Debug</code> directory to your windows system directory <code>system32</code>. You may want to use the shortcut to the <code>Debug</code> folder which has been installed to the start menu for convenience.

For the copy to work, proceed as follows
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* copy the debug driver files to your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>

When you open ''Telephony and Modem Control Panel'' again, you should notice that the TSP driver name has changed to the debug version.

==== Switching back to the Retail Version ====
To go back from the debug to the release version, proceed as follows:
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* delete the debug driver files from your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>
* repair the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

Please note that simply re-installing the driver from the original .msi without removing it from the system directory will not work.

===References===
The test applications provided with this setup comes from [http://www.julmar.com Julmar Technology Inc].

=== Limitations ===

Please note that there currently is a limitation to 2000 users being in
all active groups of a particular user. Thus, you cannot configure more
than 2000 users to be handled by TAPI on a single PBX. This is a PBX
limitation (and applies for all PBX groups).

TAPI has a flat line model. That is, all line numbers (aka
''extensions'') are considered to live in a single name space. As a
result, lines with identical numbers cannot be distinguished in TAPI
(although they can exist). All extensions in all nodes of a PBX
numbering tree are represented as TAPI lines. When the TSP works with a
PXB that implements a hierarchical numbering tree, then some lines may
receive identical numbers (their node-local extension which may overlap
between nodes depending on the setting of the ''Use pure node extensions'' property). When a TAPI application uses these numbers to initiate
calls to such lines, the call will work or not work depending on the
calling lines position in the numbering tree (that is, lines within the
same node as the called line will be fine, others may fail).

===Known Problems===
* 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
* The TSP will read its configuration when it is loaded by the system. Thus, configuration changes require a re-load of the TSP. Unfortunately, there is no reliable way to force the system to unload the TSP, so you may have to reboot the system for changes to take effect. See the [[ Howto:Troubleshooting_the_TAPI_service_provider | TAPI trouble shooting article ]] for details
* The TSP will use HTTP basic authentication to talk the PBX. So if you disable basic authentication in the PBX's configuration, the TSP will not work. It is recommended to use HTTPS
* TAPI requires the TSP to assign a unique id to each line device. This ID must not change between re-boots of the system or between upgrades of the TSP. This is done by keeping a persistent table in the windows registry (in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider\lineGUIDs</code>) that maps the PBX's line GUID to a fixed integer value (known as ''permanent line id'' in TAPI speak). This key is retained even on uninstall. To get rid of it, you must remove it manually
* Microsoft installer fails to remove driver files installed to the windows system folder. This is why the TSP driver files are still present after an uninstall of the software. To get rid of them, remove <code>TSP8.tsp</code> and <code>TSP8UI.dll</code> from both ''%windir%''<code>\system32</code> and ''%windir%''<code>\sysWOW64</code>
* From Version 9, hotfix 1, the PBX firmware will not list objects tagged as [[Reference9:PBX/Objects#General_Object_Properties | ''hide from LDAP'' ]] in the result of a [[Reference9:Concept_SOAP_API#UserInfo.5B.5D_FindUser.28string_v501.2C_string_v700.2C_string_v800.2C_string_cn.2C_string_h323.2C_string_e164.2C_integer_count.2C_integer_next.29 | FindUser() ]] call. As a result, such objects will not be shown in the TAPI configuration dialogue ''Username'' drop-down. If you want to use such an object as ''TAPI User'' you can simply type in the name without selecting it from the drop down.
* Sometimes, setting configuration with ''TSP Control'' (not the telephone control panel dialogue) does not work due to windows' ''User Access Control (UAC)'', see [[Howto:TAPI_TSP_Control_Windows7]] for Details
* Various users have reported that first party TSP installations do not work reliably with Microsoft Outlook. Symptoms reported are spurious error pop-ups from Outlook although there was no real problem. We do not recommend first party installations anyway (see [[#Rolling_out_First_Party_TSPs_to_multiple_PCs]] for a reasoning), but these issues are related to Microsoft Outlook only. No such problems have been reported with other first party TAPI applications. Consider using solutions like Estos ProCall instead.
* The number of parallel threads used within the TSP is limited to max. 60 per CPU. As each connected PBX (amongst other things) is handled by a separate thread, if you have a large number of PBXs connected and only have a single CPU, you may run out of threads, resulting in a WARNING messages ''about to spawn new workerthread (n requests, m threads) -- but limit l exceeded''. This usually happens when you run the TSP on a virtualized platform such as vmWare and only dedicate a single CPU. Ignoring this warning results in sluggish behaviour.
==== TAPI on Windows8 / Server 2012 ====
===== User Access Control =====
Windows8 doesn't let you disable UAC completely. This has the disadvantage that ''TSP Control'' (tsptray.exe) cannot change system registry entries, which it needs to do to e.g. change debug settings for the TSP.

There are 2 ways around it:
# use the hidden ''Administrator'' account on Windows 8
# elevate the tsptray.exe application

To use the elevated ''Administrator'' account on Windows 8 you first need to un-hide it:
* log in to an account with administrator rights
* use the ''Windows-Key+X'' shortcut and select ''Command Prompt (Administrator)'' (''Eingabeaufforderung (Administrator)''). An elevated cmd prompt appears
* type <code>net user administrator /active:yes</code>
* the fully elevated ''Administrator'' account is now available and you can log-in to this account as usual
* '''Please make sure the account has a password set - by default, it does not!!'''

To elevate the tsptray.exe application;
* log in to an account with administrator rights
* start a windows explorer
* change directory to <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8-x64 TSP</code>
* right click on <code>tsptray.exe</code> and open the ''properties'' (''Eigenschaften'') menu
* switch to the ''Compatibility'' (''Kompatibilität'') tab
* tick the ''Run as administrator'' (''Program als Administrator ausführen'') check mark
* save the settings

Please note that Windows 8 will not let you run any "Metro App" in elevated mode!

===== HTTPS =====
The TSP will not be able to talk to the PBX using HTTPS with Windows8 or Server2012. This [[Support:DVL-Roadmap_TAPI_V8#HTTPS_SOAP_connections_did_not_work__on_Windows8_.2F_Server_2012|has been fixed]] with V8 TAPI Service Provider (32 and 64bit) - hotfix10.
===== .Net 3.5 missing on Server 2012 =====
Server 2012 has no support for .Net 3.5 by default. Even more, it cannot be installed just by downloading it. Instead, the ''NetFX3 Feature'' needs to be enabled. Here is how:

Microsoft Windows [Version 6.2.9200]
(c) 2012 Microsoft Corporation. Alle Rechte vorbehalten.

C:\Users\Administrator>dism /online /enable-feature /featurename:NetFX3 /all /Source:''<path to windows setup, e.g. d:>''\sources\sxs /LimitAccess

See also
* [http://blogs.technet.com/b/aviraj/archive/2012/08/04/windows-8-enable-net-framework-3-5-includes-net-2-0-and-3-0-i-e-netfx3-feature-in-online-amp-offline-mode.aspx?PageIndex=2 Windows 8: Enable .NET Framework 3.5]
* [http://msdn.microsoft.com/en-us/library/hh506443.aspx Installing the .NET Framework 3.5 on Windows 8]

=== Tweaks ===
There are a few configuration options which should be used rarely. They can be enabled by setting an appropriate registry key.

There are some values in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>:

; ProcessorMask : REG_DWORD. If set, the TSP will use <code>SetProcessAffinityMask(GetCurrentProcess(), set)</code> to limit TSP execution to one or more of the existing processors. Set to <code>0xff</code> by default.

; LineTimeOut : REG_DWORD. Can be set to a number of seconds the TSP should wait for the determination of lines to finish (default 90). On a large PBX, or a PBX with slow slaves, the determination might not finish in the default time frame. If this happens, TAPI applications may show ''Line unnamed'' line entries in their line list. If this is a problem, set it to a larger value (e.g. <code>120</code>).

; IgnoreDevStatus : REG_DWORD. Some applications get confused if TAPI reports line to be disconnected or out-of-service dynamically. Setting this to a non-zero value will disable any such notification.

; ClearFwdOnSet : REG_DWORD. If set to a non-zero value, the TSP will clear all current call forward settings before a lineForward request is executed. This implies that all call forward settings are ''replaced'' by the new settings. Standard behaviour is to only modify the settings, that is, replace all current settings of the same type with the settings found in the lineForward request (for example, if there is only one setting in the request that defines a CFU, then the current CFU settings are replaced by the new one provided. All others, such as e.g. CFNR settings, are left untouched).

: Tapi spec is pretty clear on how this should work: ''The provider should "unforward everything" prior to setting the new forwarding instructions''. Even though, for historical reasons, ClearFwdOnSet=0 has been the default in all TAPI versions prior to V8 hotfix 6, from hotfix 6 on, the default changes to 1, as this has turned out to be the widely accepted interpretation.

; No3PTY : REG_DWORD. See [[Reference8:TAPI_Service_Provider#Notes_on_3PTY_Conferences | Notes_on_3PTY_Conferences]] below.

; HiddenRecordingNumber: REG_SZ. Active recording in an innovaphone PBX is implemented as an implicit 3PTY conference with the recording sink as one of the parties. These will be shown as usual in the TAPI callstate. However, some applications get confused as this results in a situation, where a normal endpoint (read: phone) has more than one active (i.e. ''not on hold'') call. To suppress such calls in the TAPI call states, you can set this tweak to the number of the recording sink as configured in the phone's recording configuration tab. If so, any outgoing call from an endpoint that is registered with a PBX user object with a called number that equals the setting of this tweak, will be suppressed. So if your recording sink has the number <code>44</code>, you would set this registry value to <code>44</code> (this is available from TAPI V8 hotfix 8). Please note that this feature actually suppresses any call info for such calls, however, it does not revert previously announced call infos. So if the call is initiated using ''overlapped dialling'', all call states will be shown until the called number matches the value of <code>HiddenRecordingNumber</code> and all subsequent call states will be suppressed. This will probably leave the call shown in ''dialling'' state. The feature should be used for destinations which are called using ''block dialling'' only thus.

; SilentHold : REG_DWORD. When a call is put on hold using <code>lineHold</code>, both parties will normally hear ''music on hold'' emitted by the PBX. When <code>SilentHold</code> is set to a non-zero value, the initiating party will not hear any ''music on hold'' (this is available from TAPI V8 hotfix 8).

There are some more values in a key underneath <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code> called <code>Device</code>''XX'':

; NoDuplicateConnectedCalls : REG_DWORD. If set to 1, the TSP will never show more than one call per line to be active. Extra active calls will be shown as ''on-hold''. The situation occurs e.g. when a user initiates a 3PTY conference on the phone. This essentially is a bug fix for Microsoft's OCS client which forces any extra active call on-hold, thereby disturbing the 3PTY function. If your are using [http://www.estos.de/download/software/eccg.htm ESTOS' Call Control Gateway]: from version ''2.0.1.1474 - 05.11.2008'' there is a fix for this same problem available. This option thus is deprecated.

===List of supported TSPI functions===

The TSP supports the following TAPI Service Provider Interface Functions. Note that these do not map one to one with TAPI user functions. For more information, see the Microsoft TAPI documentation.

TSPI_lineAnswer
TSPI_lineBlindTransfer
TSPI_lineClose
TSPI_lineCloseCall
TSPI_lineCompleteTransfer
TSPI_lineDevSpecific
TSPI_lineDevSpecificFeature
TSPI_lineDial
TSPI_lineDrop
TSPI_lineForward
TSPI_lineGenerateDigits
TSPI_lineGetAddressCaps
TSPI_lineGetAddressID
TSPI_lineGetAddressStatus
TSPI_lineGetCallAddressID
TSPI_lineGetCallHubTracking
TSPI_lineGetCallIDs
TSPI_lineGetCallInfo
TSPI_lineGetCallStatus
TSPI_lineGetDevCaps
TSPI_lineGetExtensionID
TSPI_lineGetID
TSPI_lineGetLineDevStatus
TSPI_lineGetNumAddressIDs
TSPI_lineHold
TSPI_lineMakeCall
TSPI_lineNegotiateExtVersion
TSPI_lineNegotiateTSPIVersion
TSPI_lineOpen
TSPI_linePark
TSPI_linePickup
TSPI_lineRedirect
TSPI_lineSelectExtVersion
TSPI_lineSendUserUserInfo
TSPI_lineSetAppSpecific
TSPI_lineSetCallData
TSPI_lineSetCallHubTracking
TSPI_lineSetCallParams
TSPI_lineSetCurrentLocation
TSPI_lineSetDefaultMediaDetection
TSPI_lineSetMediaMode
TSPI_lineSetStatusMessages
TSPI_lineSetupTransfer
TSPI_lineSwapHold
TSPI_lineUnhold
TSPI_lineUnpark
TSPI_providerConfig
TSPI_providerCreateLineDevice
TSPI_providerEnumDevices
TSPI_providerGenericDialogData
TSPI_providerInit
TSPI_providerInstall
TSPI_providerRemove
TSPI_providerShutdown
TSPI_providerUIIdentify

=====Notes on Consultation Calls=====
This TSP supports the <code>lineSetupTransfer</code> function. However, strictly speaking, this function is not needed and should not be used. It is merely intended for applications which do not offer a consultation call interface to the user when this function is not available. Instead, <code>TSPI_lineMakeCall</code> can be used where <code>lineSetupTransfer</code> would be otherwise. The notion of a special ''consultation call'' is an idiosyncrasy forced by legacy PBX technologies which were not able to transfer two arbitrary calls. In these scenarios, a potentially to-be-transferred call needed to be linked to the primary call. The PBX can transfer two arbitrary calls and thus there is no need for <code>lineSetupTransfer</code>. This ability is indicated by the <code>LINEADDRCAPFLAGS_TRANSFERMAKE</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE </code> flags. The transfer is then requested by using <code>TSPI_lineCompleteTransfer</code>.

=====Notes on 3PTY Conferences=====
The TSP supports the management of 3PTY conferences. These can be initiated by using <code>TSPI_lineCompleteTransfer</code> with <code>LINETRANSFERMODE_CONFERENCE</code> instead of <code>LINETRANSFERMODE_TRANSFER</code>. This is indicated by the flags <code>LINEADDRCAPFLAGS_CONFERENCEHELD</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE</code>. The 3PTY function is actually implemented by the innovaphone IP phones (such as IP2xx). Therefore, these capabilities are only advertised if the line is based on a PBX user object. Still, some lines where the capabilities are advertised cannot do 3PTY (such as e.g. DECT lines, analogue lines, 3rd party devices, ...). So the call to <code>TSPI_lineCompleteTransfer</code> will succeed but the conference will not be initiated and the subsequent call states will not indicate a conference (as there is no).

Also, if non-telephone devices are registered with a PBX user object and these device have multiple concurrent calls (e.g. a call center connected with a multi-channel XCapi), these will be viewed as 3PTY calls (as this is the way such calls appear to the TAPI: a line with more than one non-held call). If these calls are in fact no 3PTY, this may lead to confusing call indications from TAPI. It is better to register such objects as a PBX gateway object. Special treatment of 3PTY calls can be disabled by setting the registry flag <code>No3PTY</code> (from build 8087 onwards).

A 3PTY conference will create a new call handle for the conference. The only operation available for such a handle is <code>TSPI_lineDrop</code>. This will terminate the conference and restore the state active before the conference was initiated (that is, the phone that implemented the conference will now have 2 calls, one active and one on hold). This is indicated by not setting <code>LINEADDRCAPFLAGS_CONFDROP</code>.

A <code>lineDrop()</code> on one of the 2 ''real'' calls involved will of course cancel this call and thus remove the 3PTY.

======Notes on Intrusion Calls======
A special case of 3PTY is an intrusion call initiated by a [[Reference9:Phone/User/Function-Keys/Partner | partner function key]]. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the intrusion call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is an intrusion call).

======Notes on Recording Calls======
A special case of 3PTY is a recording call. This effectively creates an user-invisible 3PTY on the phone. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the recording call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is a recording call).

Recording calls are shown as normal conferences (unless <code>No3PTY</code> is set). This might be confusing to applications and/or users. See the <code>HiddenRecordingNumber</code> tweak above for a method to hide such calls.

=====Notes on parked Calls=====
The PBX can park calls from and to any existing PBX object, e.g. by virtue of [[Reference8:Configuration/Registration/Function-Keys/Park | specific feature keys]]. They are parked to/from a numeric ''park position''. In SOAP however, calls are parked to an object by providing the objects '''UserInitialize()''' handle and a park position. Parked calls are then reported as straight calls with a distinct signalling state (8). The park position is not conveyed as part of the '''CallInfo''' record. To unpark, '''[[Reference8:SOAP_API#integer_UserPickup.28int_user.2C_string_cn.2C_integer_call.2C_string_group.2C_int_reg.2C_InfoArray_info.29 | UserPickup]]''' can be used providing the parked calls call handle as '''call''' argument.

The TAPI specification is unclear on how the address information required to '''lineUnpark()''' a call can be obtained by an application (except that it is returned from '''linePark()''' if the call was parked using TAPI). The TSP thus indicates parked calls on a line with a call reason <code>LINECALLREASON_PARKED</code>. The caller id information is set to the parked calls call handle. This way, the application can take the caller id information and provide it to '''lineUnpark()''' to unpark a call. If the appication does not support this mode of operation but supports '''lineUnpark()''' and lets the user input the park identifier, the user can just provide the caller id information.

Some applications do not care for parked calls (by examining the call reason) and just blindly report these calls like ordinary connected calls (thereby confusing the user). To work around this problem, reporting parked calls can be turned off in the TSP configuration dialogue.

=====Notes on sending User to User Information =====
The TAPI specification for sending UserUserInfo closely resembles the way ISDN defines this service. Although the innovaphone PBX supports this service both with H.323 and SIP, it is ''not'' supported in this TSP. Instead, sending user to user information is implemented using H.323/SIP messaging. However, there are some important deviations and limitations caused hereby:
* data is ''not transparent''. That is, the TSP only allows for null-terminated unicode to be sent. The data must be of even length and the last two bytes must be null.
* data is ''not sent within the call'', but by initiating a separate call. This implies that the target number used to send the message carrying the data to is 'guessed' from the available call data. For example, if the call is in a connected state and a connected number is known, the message is sent to the connected number. If the call is in the ringback state, then either the called number or - if available - the redirection number is used and so forth.
* message calls are not indicated by the SOAP CallInfo records. As a result, messages (that is, user to user information) cannot be received with TAPI and ''lineReleaseUserUserInfo is not supported''

=====Notes on sending proprietary innovaphone Remote Control Facilities =====
The SOAP [[Reference8:SOAP_API#UserRc.28integer_call.2C_integer_rc.29|UserRc]] function allows to send various [[Reference:Remote Control Facility|facility messages]] to an innovaphone phone device. In some cases, it is useful to be able to invoke this function through a standard TAPI mechanism. This can be achieved by using the TAPI '''lineBlindTransfer''' function. If the ''called party name'' provided as destination for the ''lineBlindTransfer'' (in ''lpszDestAddress'') has the magic value <code>USERRC</code>, then the ''called subaddress'' is converted to an integer and the result is sent as remote control facility to the call the blind transfer is applied for. For details on how to code the ''called party name'' and the ''called subaddress'' into ''lpszDestAddress'' see [http://msdn.microsoft.com/en-us/library/windows/desktop/ms726017%28v=vs.85%29.aspx Microsoft's ''Canonical Address'' specification]. This works from TAPI8 hotfix 4.

For example, initiating a blind transfer to <code>|16^USERRC</code> (empty address, subaddress 16 (that is, [[Reference:Remote Control Facility|''change to handset mode'']]), called name <code>USERRC</code>) will switch the phone having the call to be transferred into handset mode (and <code>|18^USERRC</code> will switch it back to handsfree mode). Of course, no actual transfer will happen in these cases (''lineBlindTransfer'' is merely used as a vehicle to send the facility to the proper call).

Such proprietary facility message can also be sent with ''lineMakeCall'' (that is, in SOAP's [[Reference8:SOAP_API#integer_UserCall.28integer_user.2C_string_cn.2C_string_e164.2C_string_h323.2C_int_reg.2C_InfoArray_info.2C_int_rc.2C_string_srce164.29|UserCall]] function). For example, setting up a call to <code>123|21^USERRC</code> will send an intrusion call to extension 123 and intrude any call that might be active there. This works from TAPI8 hotfix 6. Please note that the innovaphone TAPI service provider does not support TAPI's ''lineCompleteCall'' function with <code>LINECALLCOMPLMODE_INTRUDE</code> though (as TAPI's call model here does not fit with the PBX's call model). Please also note that intrusion calls look like 3PTY calls to TAPI (see [[#Notes_on_Intrusion_Calls|notes on intrusion calls]] above).

Remote control facilities are implemented by the telephone devices, so these functions are subject to the phone firmware in use.

[[Category:Howto|{{PAGENAME}}]]
[[Category:Concept|{{PAGENAME}}]]

Howto:IQM - Overview

2013-11-20T14:02:23Z

Msr: /* License and Demo */

The innovaphone PBX-Queue Monitor (iQM) is an application to monitor a Waiting Queue (WQ) and agents in an innovaphone PBX.

The application becomes more and more powerful and therefore even complex. This Overview will give you some basic information about the Queue Monitor.

The Queue Monitor in all documents will be also called “iQM”, the Waiting Queue abbreviated WQ.

The innovaphone Wiki is typically a technical resource. This document will explain anyway the iQM more from a sales or user point of view. All detailed information’s can be found following the links.
Please note also that this document contain all the relevant links while the single issues will refer to this document. In this way a new document must just be listed in this article (and not in each iQM document).



==Applies To==
This information applies to

innovaphone PBX version 9

innovaphone Queuemonitor 1.50

innovaphone Queuemonitor client 1.50

Windows 7

==How to read iQM documentation==

If you compare the screen with the pictures and screen-shots in some situations you will see a difference. The reason is that we write the documentation at a certain point and if you install a newer version of iQM not all pictures are always updated. But that will not influence the explaination of the article in that point. If an update is necessary to understand we update always the picture. So take the pictures as example (as they are) and be not worried if your screen is different (for example you have one item or key more).

“Typically” is another key issue. PBX can be configures in thousand modes and customer has even more ideas. So if we say for example “the Agent has a key on a Phone for enter and exit a group” don’t say “yes, but my customer do not want or need that”. We intend “normally” and “it is a good idea”; up to you and your customer decide what he wants.

“Agent” is just an expression to explain that this user is part of a group answering calls from a waiting queue, but basically it is a normal user in a PBX.

Of cause if we wrote “PBX” we always understand an innovaphone PBX. Please note also that IP-Phones or Phones are intended as innovaphone IP-Phones. In theory also IP110, but generally those basic phone are not used for Agent.

==Why customer wants an iQM==
The innovaphone PBX can handle perfectly and in a very clever mode calls in waiting queues, playing sound during the waiting time, announce the position in the queue and many other features. But all that is done without any display.

The iQM do basically two things:

1. He shows the actual and historical situation about calls in a WQ. This is interesting for the administrator or supervisor.

2. The agents can see what is going on in the WQ, this is important for acting.

Sound poor, but if you read all, you will see it is a lot.

The following picture shows a caller, the distribution of the call to different agents and the iQM.

[[image:IQM010.png‎]]

Customers will never say “I need an iQM”, but either “how can I see if caller gives up because we do not answer quickly enough?” or similar.

The common basic operating questions for a supervisor (and/or the agents) are:

• How many calls are in the Queue?

• How long is waiting the “oldest” call?

• How many callers give up, typically because annoyed waiting?

Depending on those parameters agents will hurry up or not and a supervisor can add agent ore shorten the wrap-up time. So the parameters “waiting time of the oldest call”, “number of calls waiting” and “number of abandoned calls” are important and displayed in real time.

Next interesting questions are:

• How many agents are in the system and how many of them are logged to the service?

• How many agents are free/busy and ringing?

• How many agents are in wrap-up time and so available soon?

Depending in those parameters additional agents can be logged or wrap-up time modified. Observing the real-time indicators a supervisor will see instantly if a situation becomes critical.

In managing agents statistical counters are even an important issue:

• How many call where processed this hour/today/ this month?

• How long did the caller wait this hour/day/month

• How many calls are abandoned this hour/day/month

And it would also be interesting to know the peak and average value of all that.
A supervisor could also have the problem to measure those values in a defined time period.
All this real time questions are of cause interesting if comparable with stored periods. Therefore iQM displays always also the stored values, so for example the counters of the last hour, day and month. Historic counters allowed to see immediately how the contact center is working compared to previous periods.

In some cases the requests are not so stressed and real time depending. For example a customer want just understand if and when calls are going lost or if and when there are a lot of calls. This can be done using warning and alarming thresholds.

And of cause all those counters and events should be stored even in a file for post-processing. Post processing of stored call data could be done with any external tool like Excel or Access.

If you are not Shure if iQM is doing or not a thing your customer ask have a look to the feature section.

==iQM server and iQM clients==

The iQM is a software installed and running on a Windows PC. The iQM server “talks” to the PBX using the SOAP interface. Sounds technically and it is, means just that the PC receives and send data to the PBX. Those data are displayed in counters and real time indicators and can also trigger alarms.

The agents can install client software on their workplace PC and also see the real timer indicators, but even other information’s and features.

The client software “talks” with the iQM server (and NOT with the PBX). So even if you have a lot of agents the workload of the PBX will not raise (just the CPU load of the iQM server).

Actually the system is limited to 100 Agent, but that is just an arbitrary limitation of a counter and can be easily modified.

The following picture shows the iQM server talking with the PBX and 3 Agents with iQM clients.

So an iQM client without a iQM server will not work, but on the same PC can be installed a server and a client.

Even more iQM server can be installed on one single PC.

A client can also run with a different layout and display wallboard data. Therefore in an iQM system several wallboard can be installed (and therefore there is no special software for “wallboard” but just a setup in the iQM client software is doing that).

[[image:IQM021.png‎]]

If iQM is running the status of the Queue can also be displayed on innovaphone IP-Phones.

The following picture shows the display of agent 24 talking with calling party 35123, there is one call waiting:

[[image:IQM071.png‎]]

Format CC-AA-LL where CC=number of calls waiting in the queue, AA=number of ready agents and LL=number of abandoned calls.

No agent software has to be installed (but of cause it can) because the iQMserver is updating the display of the Agent.

This feature can be enabled individually for each Agent and an Agent can switch on/off this indication.

See relative link for description and setup.

==License and Demo ==
The iQM requires one iQM license for a WQ. So if in your scenario you have for example two WQ you will need two iQM Licences.

The license are stored in the PBX.

No license is required for the iQM client (the Agents), so if you have 4 ore 10 Agents is not the issue.

If an IQM server starts and will not find a license in the PBX he will go automatically in demo mode and terminate after 20 minutes. The demo mode is fully features and even the clients will work.

The iQM software can be downloaded, check also the unofficial directory for news version, contact eventually innovaphone.

Attention: if an iQM Server should look also in a 2nd WQ a additional iQM license is required!

Examples:

iQM working on one WQ straight: 1 iQM license

iQM working on one WQ + standby PBX: 1 iQM license

iQM watching on one WQ but look also a 2nd WQ: 2 iQM license

iQM watching on one WQ but look also a 2nd WQ + standby PBX: 2 iQM license

2 iQM watching each on one WQ and look also each to the other WQ + standby operation for both: 4 iQM license.

==Feature list==
The following list shows the features of the version 1.40.

Feature list and feature description is always boring and often even not clear. So if you like that kind of information go on, if you like see examples you have to read the documentation.

===iQM Server===
- Real time indicator: longest waiting time, number of calls in a waiting queue and number of abandoned calls

- Warning Threshold for each real time indicator, the indicator becomes red

- Alarm Threshold for each real time indicator. If reached, date and time of the event is displayed and a counter is incremented. So the supervisor will see at a glance when the event occurs the last time and how many times the threshold was exceeded. Thresholds can be switched on and off, if a threshold is reached the button will flash.

- Configured threshold for each counter and mode (Warning and Alarm) is displayed.

- If a threshold is reached the PC can play an alarm sound, default the MOH of the PBX, but it is possible to define also a wave file. It is possible to limit the duration of the play (alarm auto reset)

- Email notification with the relevant data if a threshold is reached.

- 8 counter panels showing a total of 72 counters, each panel display: total waiting time, longest waiting time, average waiting time. Total number of calls, peak of calls in the WQ, average number of calls in the WQ. Total number of abandoned calls, peak number of abandoned calls, average number of abandoned calls.

- The panels shows those counters for: the actual hour, the last hour, today, yesterday, this month, last month, from startup (total), form the last manual reset.

- Reset Counter, with this counter a period can be measured. If the reset is pressed an Email with the data of the counters before the reset can be send.

- The panel shows the actual hour, the date of today, the actual month, date and time when the last day was saved, date and time when the reset was pressed.

- Display of date and time when the application started and elapsed time from the last restart (days and time)

- Indication of the PBX address, status of the link, soap session and eventual warning messages. If a warning message is displayed a warning triangle appears. Warning messages are for example “the indicated WQ has the SOAP flag switched off.”

- Version of firmware is displayed if the innovaphone logo is clicked.

- The panel can show just the main counters (small) or all the counters (large).

- Shut down of the application is protected by a warning message.

- The position on the PC display is stored each time the application is shut down in a regular mode.

- All counters are stored if the application is shut down in a regular mode.

- Each hour all counters are saved automatically.

- Real time counters of Agents: Number if Agents defined, Agent logged in the answering group, Agents ready for receiving call, number of busy Agents, number of Agents in call (ringing), number of Agents in wrap up.

- Separate form showing number of Agents ready, and the 3 real time indicators waiting time, calls and abandoned calls. In a list the Agents are displayed: number, name, in or out of the answering group, status (free, busy, ringing), and presence status. The height of the windows depends on the numer of Agents in the list.

- Wrap up time can be switched on and defined in seconds. If Agents have an individual wrap up time this can be switched of. So the supervisor can for example switch of the individual wrap up time and switch on the general one.

- Wrap up timeout is starting for each type of calls. So even if an Agent is doing an outbound call the wrap up time will start. Please note that the WQ itself can also handle wrap up, but it works different. See relative sections in the description.

- Individual wrap up time can be set for each Agent.

- If a change in the setup of the iQM require a restart this is indicated in the main window.

- Dynamic PBX are supported

- HTTPS is supported

- Directory for logging and data base can be set

- Email with the actual counters each hour or/and each day

- The ID of the iQM in the Email can be defined (important if more iQM are running to distinguish the sender)

- Logging (logfiles) of data each hour and day

- iQM Label configurable

- 5 skins (colors)

- Multi language (English, German, Italian, French pre-installed), localization (other languages) possible without changing the firmware (just modifying Text files)

- iQM Windows always in foreground possible

- iQM works even if minimized in Taskbar

- Port address for client communication settable.

- Up to 100 iQM clients possible.

===iQM client===

iCM client running as client (and not as Dashboard):

[[image:IQM101.png‎]]

- Real time indicator longest waiting time, number of calls and abandoned calls.

- Warning if iQM server is in warning.

- Real time indicator number of ready Agents.

- Display of iQM and PBX status.

- Display own status (online = in group or offline = out of the answer group).

- Manual change of actual status (in/out group).

- Pause key, the pause time can be defined in the setup and is displayed. Elapsing time is displayed in real time.

- Switch on/off Activity control

- Activity control detecting phone busy, movement of the mouse and keystrokes on the PC. Timeout for no activity can be configured.

- Auto login: in Agent is logged out because of the activity control and he act again (Phone or keyboard or mouse) he will be logged in automatically (settable).

- Automatic logout if calls on a set are not answered, time settable, behavior like activity control.

- Port address for Server communication settable.

- Windows always in foreground possible.

- Pop-up if minimized in Taskbar if counters go to warning.

- Language settable, (English, German, Italian, French pre-installed), localization (other languages) possible without changing the firmware (just modifying Text files). Language of each Agents can be different (individual setup).

- Setup can be protected with password.

- Keyboard of the PC can be used to answer and drop calls if an iQM window is active. Answer calls with backspace and drop with Esc.

- Independent Window for Agent list: List shows extension, name, log status (logged Yes/No), status (idle, busy, and ringing) and Presence Status. Up to 20 Agents at a glance, then scrollbars appears for scrolling. Double click on an Agent Number will call the Agent. If the caller is busy the actual call will go on hold. Pressing Esc will transfer the call.

- Independent Window for abandoned call list. The list is shared with all other clients and shows the abandoned calls (number and date/time). The list is limited to the last 20 abandoned calls, if full the oldest will be lost. A small counter inside of the abandoned call counter in the main Agent windows shows the number of abandoned calls in the list. A call in the list can be recalled doing a double click on the number (the Agent Phone will dial out if idle). Agent name and date/time of this recall is displayed in the list. A call can also be quitted from an Agent pressing a key. In both case (recall or quit) the small counter in the Agent main view counts down.

- Multiple numbers in the recall list are detected and a recall or quit causes a multiple confirmation.

- Independent Window for the waiting queue. Up to 10 calls are displayed (just the Number and position), if more calls are in the queue a scrollbar appears and the list can be scrolled. A double click on a call will connect the Agent with the caller. Therefore a call can be picked from the WQ. If the Agent is in ringing status the actual call will return to the WQ and the Agent is connected to the picked call.

- The windows (main, queue, recall and agent list) store their position when closed and therefore will appear in the same position when started again.

- The Windows can dock automatically on the main window.

- A time period in minutes can be defined, if elapsed the agent will be exit from the group. It is possible that the countdown of this forced pause timer will be interrupted if the agent is manual offline. The counter starts again if the Status key is pressed.

- Automatic log in if Agent is forced pause (Auto Paused) after a time period.

iCM client running as Dashboard:

[[image:IQM085.png‎]]

- Ratio dashboard selectable (4:3 or 16:9)

- Maximum Number of calls and time selectable

- Number of calls, waiting time and ready Agent in real time and graphical bars

- Expected waiting time for a new call (based on number of calls and average waiting time)

- Number of logged out and Agents in wrap up, counter and graphical

- Actual time

- Number of calls and abandoned calls today

- Warning if abandoned calls or threshold overflow

- Warning if not served calls and unlogged Agents

The Dashboard can also display the iQM server counter data in realtime:

[[image:IQM060.png‎]]

==Related Articles==

[[Howto:Queue_Monitor_-_Overview]]

[[Howto:PBX-QueueMonitor]]

[[Howto:Queue_Monitor_-_Setup_and_Localization]]

[[Howto:PBX-QueueMonitor_Client]]

[[Howto:IQM_Dashboard]]

[[Howto:Additional_call-ID_information]]

[[Howto:IQM_IP-Phones_setup_and_iQM_Phone_Display_features]]

[[Howto:IQM_Second_Waiting_Queue]]

[[Howto:IQM_Active/Standby_PBX]]

[[Howto:IQM_manipulative_behaviors]]

[[Howto:IQM_Statistical_Excel_Data_for_Agent_and_Queue]]

[[Howto:IQM_Agent_Hot-desking]]

[[Category:Howto|{{PAGENAME}}]]

Reference10:PBX/Config/General

2013-11-04T16:10:41Z

Msr: /* Common */

The fundamental operating modes of the PBX are configured on this page.

== Configuration ==

=== Common ===

;PBX Mode: The PBX operating mode
:* '''Off''' - The PBX is disabled. After enabling the PBX a browser refresh is needed to activate additional PBX webpages.
:* '''Master''' - The PBX on this device acts as Master. Within a multisite installation exactly one PBX must be configured as Master.
:* '''Standby''' - The PBX on this device acts as Standby for the Master. As long as the master is available, this PBX is not active, but just monitors the Master. If the Master is not available this PBX is active.
:* '''Standby-Slave''' - The PBX on this device acts as Standby for a Slave. As long as the slave is available, this PBX is not active, but just monitors the slave. If the slave is not available this PBX is active.

;System Name: The system Name. On all PBX within a multisite installation the same System Name must be configured. For H.323 endpoints this name is the gatekeeper identifier, for SIP endpoints it is the server name.

;Use as Domain: Uses the ''System Name'' as domain name, together with the name field in the user object the PBX constructs the email address (used for sending emails out ox myPBX). This mechanism is also used for Federation, to federate with other domains.

;PBX Name: The name of the PBX on this device. With this name a PBX is associated to a node. The field 'Name' (not Long Name) of a PBX Node object relates to this name.

;Unknown Registrations: If this checkmark is set, the PBX accepts 'unknown' registrations. This means registrations with no matching object configured. If from an endpoint registered in this way a number of an object is dialed, which has no registration active and no 'HW-ID' configured the name used for the registration is configured as 'HW-ID' of this object. This is an easy way to deploy large numbers of phones.

:'''With PBX Pwd only:''' If checked unknown registrations without PBX password are rejected.

;Music On Hold URL: A URL for the Music On Hold. This file is read by the PBX using HTTP and sent to a held endpoint via RTP. The format of this URL is

:'''<nowiki>http://<addr>/<file>.$coder?coder=g729,g711a,g711u,g723&repeat=true</nowiki>'''. <addr> is the IP address of the http server, no dns name is allowed here. <file> is the filename. $coder will be replaced by the actual coder used.

:Parameters: ''coder=g729,g711a,g711u,g723'' is the list of available coders. Only these coders must be specified for which a corresponding file exists. ''repeat=true'' should be specified in order to loop the file endlessly. ''random=true'' can be used to start the music on hold on a random point (this will work only if the URL is not local though).

:By default the built-in Music-On-Hold is played (Pseudo URL: "MOH?coder=g729,g711a,g723&repeat=true"). You can also play a dial tone (Pseudo URL "TONE") or a ring-back tone (Pseudo URL "TONE?tone=ringback").

:If you configure a wrong (or invalid) URL then you will have silence as MOH. To prevent this situation when the MoH for some specific context/user(see below) is missing and silence is played instead of any MoH, an additional parameter ''fallback=true'' is available. If the file provided in the URL is missing (HTTP Error 404 Not Found is delivered by the HTTP Server) and the parameter ''fallback'' is provided, the default MoH will be played instead of silence. To use a custom file as fallback MoH, instead of default MoH, any file name can be provided with the ''fallback'' parameter: e.g. ''fallback=other_filename''. The file other_filename.g7xx must be placed in the same folder as a file provided with URL.

:Within the URL %<id> can be used to put in some context information of the call. The information refers to the party which has put the receiving party on hold. For information about the receiving party itself, the id has to be preceeded by '.' (e.g. '''.l''').

:'''l''' Long Name

:'''h''' Name (H.323 id)

:'''n''' Number

:'''N''' Node

:'''P''' PBX

;External Music On Hold: To offload the device from playing the Music on hold, the Music On Hold can be played by a seperate device. This device can register with a name configured here. To retrieve the Music On Hold a call is sent to this device. For each held endpoint a call is sent.

;Response Timeout: Global timeout (in seconds) after which any action for no response is taken (e.g. Call Forward on No Response). A timeout configured at any object overrides this value.

;Dial Complete Timeout: Global timeout (in seconds) after which any action for incomplete dialed number is taken (e.g. incomplete destination at trunk object).

;No. of Regs w/o Pwd: Number of registration without password authentication which are allowed per user. If 0 is configured no registration without password is possible.

;Recall Timeout: A value configured here enables recall after transfer. If a call is transfered and not answered within this time, the call is sent back to the transfering endpoint.

;Max Call Duration (h): Number of hours until a call with media is disconnected automatically. Affects all calls with initialized media channels signalled via PBX.

;Group Default Visibility: Allows to restrict default visibility to active group members. If changed active subscriptions are not affected. Is used to prevent standard users from getting access to sensitive informations like activites/presences of group members in myPBX. If not generally allowed by the administrator via this setting, normal users are not able to change it via myPBX.

;Pickup Prefix V7: In V7, the pickup prefix is obsolete. Please use the pbx object [[:Reference7:Administration/PBX/Objects/DTMF Features|DTMF Featurecodes]].

;Presence with Alert: Enable presentation of presence on phone upon alert. Setting applies for all PBX users. Alternatively, display of presence subject only delivered by Exchange can be prohibited - see [[Reference10:Concept_Exchange_Calendar_Connector#Exchange|Exchange Calendar Connector : Omit Subject]]

;Enable External Transfer: Unless this checkbox is set any attempt to transfer an external call back to an external destination will result in disconnection of the call.

;No CLIR on Internal calls: If checked numbers are displayed even if received with presentation restricted. When sending a call presentation restricted can still be set and should be honored by a public network.

;RTP Proxy: If this checkbox is set, all media traffic is routed thru the PBX. Check this only if you need to have this, since it creates CPU load on the PBX. With the '''Except Addresses are identical or private''' checkmark, the RTP proxy can be restricted. This is useful in the case endpoints are registred, which are located in private network and for calls within the same private network no RTP proxy shall be done.

;Generate CDRs: If this checkbox is set, the PBX generates CDRs for all calls. See [[Reference9:Concept_Call_Detail_Record_CDR_PBX]] for a description of the CDRs.

;Route Root-Node External Calls to: Destination object (Long Name) of Root-Node external calls. This configuration option is available on the Master or Standby PBX only. Any call call which cannot be terminated inside the PBX is sent to this destination as long as neither the source nor the destination of the call can be associated with a node with a PBX configured. This object must be assigned to this PBX.

;Route PBX-Node External Calls to: Destination object (Long Name) of PBX-Node external calls. Any call which cannot be terminated inside the PBX is sent to this destination as long as the source nor the destination of the call can be associated with the node of this PBX. If a call is sent from or to an object defined inside the node of this PBX or in a node hierachically below the node of this PBX the call is associated to the node of this PBX. This object must be assigned to this PBX, that is, it has to register to this PBX.

;Route Internal Calls to: Destination object (Long Name) to which any call is sent for which a PBX internal destination was found, except for those calls that originated from that object. This can be used to apply special routing on PBX internal calls.

;Escape Dialtone from: The PBX object (Long Name) to which a call is made to get a dialtone if a dialtone is configured for the escape of a node. As above, this object must be assigned to this PBX.

;Prefix for Intl/Ntl/Subscriber: Prefixes to be used to map International, National and Subscriber numbers.
:* '''International Prefix''' (''000'' in Germany).
:* '''National Prefix''' (''00'' in Germany).
:* '''Subscriber Numbers''' (E.g ''073009'').

;Tones: The tones scheme to be used for PBX generated dialtones. This applies to dialtones generated for node prefixes, ringback on transfer and some more.

=== Slave PBX ===

If the PBX is operated in Slave mode, then the Slave PBX section is displayed

;Master: The IP address of the PBX master

;License Only: If set, the PBX obtains license from master, but acts as master in all other respects.

;Alternate Master: The IP address of an alternative PBX master (standby, if available)

;Password: The password to be used for registration at the Master as configured in the corresponding PBX Object

;Master GK-ID: The System Name/Gatekeeper ID of the PBX Master were will register (Optional, usually used for DynPBX).

;Replication: This parameter allows you to select the replication style for the slave PBX: either ''All'' or ''Local'' (only users that need to be known in this PBX)

;Route Master calls if no Master to: If the master is not available, master calls are sent to this destination

;Max Calls to Master/No Reroute: This parameter can be used to limit the calls to the master. If a call is sent to the master and there are already calls to/from the master equal to or exceeding this value, the call is rejected if '''No Reroute''' is set or is handled as if the master was not available otherwise.

;License Limits: Here we can set limit of licensing for this Slave PBX for Port, Mobility, Operator and Softwarephone.

For complete replication from master to slave, check also password in [[Reference9:Administration/PBX/Security]]

=== Standby PBX ===

If the PBX is operated in Standby mode, then the Standby PBX section is displayed

;Master: The IP address of the PBX master

;Replicate from Master: Turns on full replication from the master PBX

For complete replication from master to standby, check also password in [[Reference9:Administration/PBX/Security]]

== License Status ==

=== Licenses ===

A list of all installed PBX license with their current usage is displayed here.

;Count: The total number of installed licenses of this type.

;Usage: The total usage of this license type

;Local: The usage of this license on this PBX

;Slaves: The usage of this license on PBX's registered to this PBX.

see [[Reference10:Licenses]] for a description of the licenses.

=== Registrations ===

The current number of registrations and the limit as defined by the base license is displayed here. Because this limit is defined by the base license it includes any registrations because of standby as well, which require no registration license.

Reference9:PBX/Objects/Executive

2013-05-24T07:33:30Z

Msr: /* Additional hint */

The Executive PBX object is used to implement the executive/secretary functions. The executive’s telephone registers with this object. Furthermore, two groups can be defined for this object: the primary secretary, which is directly subordinate to the boss, and the secondary secretary, which stands in for the primary secretary.

There is still a third group that can be defined – its members may call the executive directly without the call being signaled on the phones of the secretaries. All calls to the executive are sent to the primary secretaries. If no registration exists for the primary secretary, then the calls are forwarded to the secondary secretary. If no secretaries are registered at all, the calls are forwarded to the executive. All calls to the secretaries are signaled as a diverted call, with the executive displayed as the diverting party.

Every call received by the executive that was previously received by the secretaries is likewise signaled as a diverted call. It is thus possible to adjust the executive’s ring tone, so that it rings differently if the call was initiated by one of the secretaries. If a call is received directly on the executive’s phone, that is, not via the secretaries, it can be signaled with a different ring tone.

== General Configuration Options ==

The information about general configuration options shared by all objects can be found at [[Reference9:PBX/Objects]].

== Configuration Options which can be defined by a Template ==

Some of the configuration options of a user object can be defined by Templates. More information about these options can be found at [[Reference9:PBX/Objects/Config_Template]]

== User configuration options ==

The Executive object support the same options as a User object. The description of User configuration options can be found at [[Reference9:PBX/Objects/Config_Template]]

== Executive configuration options ==

The following specifications are made in the Executive section:
;Primary: The Primary secretary group, when added, may be selected here.

;Secondary: The Secondary secretary group, when added, may be selected here.

;Direct Call: The Direct Call secretary group, when added, may be selected here.

;Call Executive: Calls to the executive are also signaled on the executive’s phone, if this check box is checked. Normally, calls are signaled to the secretary only.

;Use Call offer: Calls to the executive, which are forwarded to the secretary are offered even if the secretary is in a call and call waiting is disabled.

The executive must be active member in the groups used for the primary and secondary secretaries as well as for the direct calls.

== Features available for Executive/Secretary Functions ==

=== Monitoring of Secretary Availability ===

The executive can configure a function key which displays if the secretary is available. Availabe means that the secretary phone is member of the executive primary group. The function key which is to be configured for this is a partner key, for which the Secretary is entered as partner (use name not number) and 'Secretary' has to be selected as 'Partner Type'.

=== Additional hint ===

In case of a scenario with several secretaries subordinating an executive, incoming calls will be directed to the primary secretary first.
If the primary secretary is busy it may be required to forward the calls for the executive to the second secretary.
This can be done by set the "Busy on ... Calls" to at least 1 for the primary secretary.

Reference9:PBX/Objects/Edit Rights

2013-04-22T12:16:43Z

Msr: /* Viewing only */

With this page PBX administration rights can be configured for a user. The user may login to the system using the 'Name' and the 'Password' configured in the User object as authentication.

== Levels ==

See note on [[Reference9:Services/HTTP/Server | ''Password protect all HTTP pages'' ]] for limitations when this flag is used.

=== Full PBX Administration ===

All settings of the PBX and PBX objects may be changed the same way as a system administrator can do. Including the rights for users.

=== Administration of all Objects ===

All settings of all PBX objects may be changed. The 'General', 'Password' and 'Filter' settings may not be changed.

=== Administration of non critical Objects ===

Objects which are marked as 'critical' and the 'critical' flag itself may not be changed.

=== Groups/Call Forwards only ===

Only group memberships and call forward settings of non-critical objects may be changed.

=== Viewing only ===
you can only view the objects, it`s not allowed to configure ore change any settings.

== Limit to Node ==

Except for the 'Full PBX Administration' right the rights to change any objects can also be limited to a single node.

Reference9:PBX/Objects/Edit Rights

2013-04-22T12:07:48Z

Msr: /* Levels */

With this page PBX administration rights can be configured for a user. The user may login to the system using the 'Name' and the 'Password' configured in the User object as authentication.

== Levels ==

See note on [[Reference9:Services/HTTP/Server | ''Password protect all HTTP pages'' ]] for limitations when this flag is used.

=== Full PBX Administration ===

All settings of the PBX and PBX objects may be changed the same way as a system administrator can do. Including the rights for users.

=== Administration of all Objects ===

All settings of all PBX objects may be changed. The 'General', 'Password' and 'Filter' settings may not be changed.

=== Administration of non critical Objects ===

Objects which are marked as 'critical' and the 'critical' flag itself may not be changed.

=== Groups/Call Forwards only ===

Only group memberships and call forward settings of non-critical objects may be changed.

=== Viewing only ===

== Limit to Node ==

Except for the 'Full PBX Administration' right the rights to change any objects can also be limited to a single node.

Reference8:TAPI Service Provider

2013-04-22T12:06:50Z

Msr: /* Configuration */

The ''innovaphone PBX V8.0 based TAPI Service Provider'' (TSP) is an enhanced version of the [[ Reference7:Unified Win32 and x64 TAPI Service Provider | previous TSP version ]] that takes advantage of the [[ Reference8:SOAP API | new SOAP features ]] provided with version 8 PBX firmware. It implements - like the previous versions - TAPI Version 3.0 without MSP (Media Service Provider).

The [[Reference7:Unified Win32 and x64 TAPI Service Provider| previous TSP ]] still must be used for V7 PBX systems.

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

==Applies To==
This information applies to
* innovaphone PBX V8.0 based TAPI Service Provider, Build 8001 and later
* innovaphone PBX V8 and later (that is, this Service Provider runs with PBX Firmware V8 and later)

==More Information==

=== Enhancements ===
; Support for V8 firmware [[Reference8:Administration/PBX/Objects#Devices | devices]] : Each user object device is represented as a TAPI line (all sharing an identical address, the objects extension a.k.a. ''Number'' property). This now allows to select individual registration devices when multiple devices are registered with the same PBX. Please note that in V8, [[ Reference8:Administration/PBX/Objects/Edit_Forks | mobility devices ]] are not shown and thus not represented by TAPI line device. This was introduced in V9 only.
; Support for presence based lines : These are TAPI lines shown which reflect the users presence state. Presence state ''open'' is mapped to a TAPI device status ''in service''. Presence activity ''on-the-phone'' is mapped to a virtual call in state ''connected''.
: '''NB''': V8 PBX Firmware did set presence activity ''on-the-phone'' for each user object having a call. Unfortunately, as this does create performance issues, this behaviour has been removed from V9 PBX Firmware. The ''presence line'' feature may be useless with V9 PBX when the application did rely on this particular V8 PBX behaviour.

===System Requirements===
The TSP will install on any Windows 32bit and x64 platform down to Windows XP/Server 2003. For older systems, you must use a deprecated [[Reference7:TAPI_Service_Provider | previous TSP version]]. For systems running PBX firmware version 6 or earlier, you must use the even older [[Reference:TAPI_Service_Provider | version 5 based TSP]]. Note that there is no x64 version of the version 5 TSP!

The TSP needs to maintain parallel connections to each individual PBX in the system. For larger systems (i.e. systems with a huge number of PBXs), this may create substantial load to the underlying windows machine. The number of parallel activities scheduled by the TSP is thus limited as a function of the available main memory and number of processors. In particular, a maximum of 20 activities per available processor is allowed (up to build 8088, the limit is 60/processor for later builds). If this limit is exceeded, the TSP will issue performance warnings of class WARNINGS in the TSP log file and system TAPI performance will be poor. Use a more capable machine then.

Microsoft Windows operating system version for desktop clients (as opposed to server systems) limit the number and performance of TCP/IP connections. This may lead to bad performance or occasional request failures. We generally recommend to use server operating systems for 3rd party TAPI installations thus.

=== Download ===
The V8 TSP will be available on the ''apps'' section of the [http://download.innovaphone.com/ice/8.00/ V8 download page].

===Installation===
Windows cannot run a Win32 TSP on an x64 platform (although it can run Win32 applications on such platforms). This is why there are 2 versions of the setup, the x64 installer (<code>setup64-release.msi</code>) and the Win32 installer (<code>setup32-release.msi</code>.

The ''release'' setup packages provided will install the retail version. This is recommended for production purposes but provides no debug options whatsoever. To track down possible problems, support may instruct you to install the debug version.

The TSP may be installed on each machine where a desired TAPI based
application is to be run. If for example, Outlook is to be used, then
each client PC running Outlook may have the TSP installed. Although
this is typical for a 1st party configuration, all clients may have full
3rd party functionality, that is, they may control all existing lines.

As an alternative, the TSP can be installed on a single machine and a
3rd party TAPI server product (such as the IXI-Call Server available as
a separate product) may be used to provide the network clients with a
TAPI interface. Also, Microsoft’s Remote TAPI Server should work but is not being tested, so you use it on your own risk.

To install,
* select and download the <code>setup32-release.msi</code> install packages on 32bit platforms or the <code>setup64-release.msi</code> install package on 64bit platforms.
* double-click the install package to launch the installer
[[Image:Unified Win32 and x64 TAPI Service Provider - zipcontent.png]]
* accept the license agreement
* select the target folder
* complete the installer

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 (''Extras'')
* Click on the ''Add...'' button
[[Image:Unified Win32 and x64 TAPI Service Provider - Control Panel Add.png]]
* Select the innovaphone TAPI provider driver
* Fill out the configuration dialogue
* Install the provider by clicking ''OK''

==== File Organization ====
Windows forces all TAPI service provider files to reside in Windows' ''System Folder''. This is the <code>system32</code> folder in your windows install directory (usually <code>C:\windows\system32</code>), even if you are running an x64 platform! The installer will thus copy these files (<code>tsp8.tsp</code> and <code>tsp8UI.dll</code>) in to this directory. All other files however will be copied to the <code>innovaphone AG\innovaphone® PBX V8 TAPI Service Provider</code> folder underneath your systems ''Program Files Folder''.

The subdirectories <code>Debug</code> and <code>Logs</code> are created. <code>Debug</code> contains the driver's debug version, <code>Logs</code> will receive the log files when a debug version is used.

On x64 platform systems, the Win32 version of the configuration DLL (<code>tsp8UI.dll</code>) will be installed to the windows ''Windows on Windows64 System Folder'' (<code>SysWOW64</code>).

====Upgrading to a newer Version====
When you attempt to upgrade the TSP from a previous version, the Windows
installer will first remove any previous installation. When the new
software is installed then, the TSP will be installed again into the
TAPI system.

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

====Upgrading from the old Win32-only Version====
If you upgrade from the older Win32-only versions of the TSP (soap-appl/tapi/7.00 or soap-appl/tapi/5.00), you must first remove the old TSP from ''telephone and modem'' control panel and uninstall the old product from the ''Software'' (or ''Programs and Functions'') control panel.

When you upgrade from the old V7 64-bit TSP (soap-appl/tapi/7.00-64), you should first update this older version to the latest build available.

This procedure ensures that during the upgrade your TAPI lines retain their internal identifiers and thus their meaning in your TAPI application's configuration.

==== Uninstalling the TSP ====
To uninstall the TSP proceed as follows
* Remove the TAPI driver from the TAPI system using ''Telephony and Modem Control Panel''
* close ''Telephony and Modem Control Panel''
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* remove the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

You will notice that Windows may fail to remove the driver files from the ''Windows System Directory''. To clean up remove <code>tsp8.tsp</code> and <code>tsp8UI.dll</code> from the <code>system32</code> folder as well as - on x64 systems - from the <code>SysWOW64</code> folder.

Also, if you did file tracing, any remaining debug files in the <code>Logs</code> folder are left over and need to be removed manually.

The TSP will create some entries in the windows registry which will not be removed on uninstall. It is recommended to leave these entries as is. Only if you are sure you will never install the TSP again on this system or you are sure you will never use it with the PBX installation you used so far, you may want to delete them from the registry.

==== Rolling out First Party TSPs to multiple PCs ====
Normally, when multiple users require CTI and hence TAPI functionality, the best way is to use a server based, multi-client 3rd party CTI application. This will share all functions among all client PCs. If this is not an option, e.g. because the TAPI application in use does not support it, you may want to consider using Microsoft's TAPI Server and remote TSP. See Microsoft's [http://technet.microsoft.com/en-us/library/cc786297%28v=ws.10%29.aspx Telephony service providers overview] and [http://technet.microsoft.com/en-us/library/cc770373.aspx Manage Telephony Servers] documents.

If you still want to use the native innovaphone TSP on a number of PCs (instead of once on a server), you can roll out the TSP using some of the [http://support.microsoft.com/kb/816102/EN-US software deployment schemes Microsoft Server provide]. In such a case, you will likely want to deploy identical configurations to all these PCs. While this theoretically can be done by distributing registry settings, there will be a problem with the PBX access credentials. These are stored in encrypted format in the registry and can only be decrypted on the PC on which they have been set. That is, deploying such registry settings to other PCs will result in a non-functional setup.

To work around this problem, you may store the credentials in clear text in the registry. To do so, you would put the ''Password'' in a REG_SZ value named <code>admin1-free</code> and the ''Account'' into a REG_SZ value named <code>admin2-free</code>. If such a value is found in the proper place in the registry, the values configured using the telephony control panel are ignored.

[[Image:TAPI Service Provider-tsp8-nocrypt.png]]

'''Keep in mind that having credentials in clear in the registry presents a security risk!'''

This feature is available in build 8079 and later.

===Configuration===
The TSP configuration dialogue looks like this:

[[Image:Unified Win32 and x64 TAPI Service Provider - Config UI.png]]

* The ''VERIFY'' button will verify the configuration. Note that the ''Username'' drop down list will only be populated after a successful verify.
* 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 [[Reference7:SOAP_API | 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 Account'' and ''PBX Password''. Also, a suitable ''TAPI User'' must be selected.

==== Controlling the Line Devices handled by TAPI ====

TAPI connects to your PBX as a PBX user referred to as ''TAPI User''. It will see all PBX objects that are members of groups in which the ''TAPI User'' is an active member. If the ''TAPI User'' is not an active member in any group, TAPI will see the ''TAPI User'' object only. This may be useful in a [http://en.wikipedia.org/wiki/Telephony_Application_Programming_Interface 1st party TAPI scenario]. PBX objects are represented as TAPI lines.

The PBX object you use as ''TAPI User'' needs to have at least ''Viewing only'' [[Reference:Administration/PBX/Objects/Edit Rights | 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.

===== 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''.

[[Image:Unified Win32 and x64 TAPI Service Provider - FirstParty.png ]]

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 for the number of lines seen. If it is only one, then it will issue a warning message:

[[Image:Unified Win32 and x64 TAPI Service Provider - OnlyOne.png]]

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.

===== 3rd Party Configuration =====
In a 3rd party configuration, the TSP will work with multiple PBX objects.

[[Image:Unified Win32 and x64 TAPI Service Provider - ThirdParty.png]]

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 limit 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 pseudo PBX user object for use as the ''TAPI User''. This pseudo user is often called <code>_TAPI_</code>. 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 <code>tapi</code>.

==== Selective Call Forwards ====
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 [[Reference7:Administration/PBX/Objects/Edit_CFs | ''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:

[[Image:Unified Win32 and x64 TAPI Service Provider - NoTrunk.png]]

In a vanilla 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''.

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

[[Image:Unified Win32 and x64 TAPI Service Provider - MultiSite.png]]

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 [[Reference7:Administration/PBX/Objects#Objects_with_empty_node_or_PBX | leave the ''PBX'' and ''Node'' properties empty ]].
You can disable slave detection by checking ''Do not monitor slaves'' property in the TSP configuration dialogue.

TAPI maintains an ''address'' property per line device. This usually is the lines extension. In a multi site configuration, the address property will be set to the ''Number'' property of the node the respective PBX object is configured in, plus the ''Number'' property of the object itself. So if an object has ''Number'' <code>42</code> and lives in node <code>801</code>, then its correspondence line device will have address <code>80142</code>. By checking the ''Use pure node extensions'' property in the TSP configuration dialogue, you change the algorithm so that only the objects own ''Number'' is used (<code>42</code> in our example).

==== Standby Configurations ====
In a system with standby PBX for the master PBX, you need to specify the ''PBX Standby'' IP address. This will be connected if the master is unavailable. Note that there is no need to explicitly configure slave-standby PBXs.

==== Working with multiple, unrelated PBXs ====
When working with multiple, unrelated PBXs (that is, PBXs that do ''not'' form a PBX tree as slaves and masters do), the TSP cannot derive the list of PBXs to track from the registration status. To support such a configuration, you will need to configure the extraneous master PBXs manually using regedit. Please note that using regedit may harm your system and may even cause inability to boot!

To find and edit the right registry entries, proceed as follows:

* open the key <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>
* open its subkey <code>Device</code>''n'' where ''n'' is the provider id of the installed innovaphone TSP
* Open the <code>FQDN</code> key and add all extra PBXs
* For those PBXs that have a standby PBX, add a value to the <code>StandbyFQDN</code> key (please note: these are parallel lists. So master and standby need to have the same respective index in the <code>FQDN</code> and <code>StandbyFQDN</code> value lists)

The standard configuration UI will not show these extra values. However, it will also not touch them. So even if you use the standard UI to edit, only the first value in the lists will be changed and the remainder left unchanged. You can thus safely use the standard UI to edit all other values. As with multi site configurations, all PBXs need to be accessible using the same ''TAPI User''.

Please note that this method is deprecated and will likely be removed from future versions of the TSP.

==== Setting the Line Device Name ====
The TSP will derive the line device's name from the properties of the respective PBX object. By default the name will be the objects ''Long Name'' followed by the name of the PBX the user ought to register with in parentheses. So if the users ''Long Name'' is <code>Foo Bar</code> and the registration PBX is <code>branch1</code>, the line device will be called <code>Foo Bar [branch1]</code>. You can specify a different pattern by changing the ''TAPI Line Names'' property of the TSP configuration dialogue. The following replacement characters are available:

{|
|+
| Meta || Replacement
|+
| %c || The objects ''Long Name'' (cn)
|+
| %C || The objects ''Long Name'' (cn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Long Name''
|+
| %d || The objects ''Display Name'' (dn)
|+
| %D || The objects ''Display Name'' (dn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Display Name''
|+
| %h || The objects ''Name'' (h323 alias)
|+
| %D || The objects ''Name'' (h323 alias) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Name''
|+
| %t || The ''Name'' of the ''Device'' the line represents
|+
| %e || The objects extension (e164)
|+
| %E || The objects extension (e164) prefixed with the objects node number
|+
| %N || The line address as reported to TAPI
|+
| %n || host name (of master pbx)
|+
| %p || ''':'''''port-number'' (of master pbx's http access, empty if 80)
|+
| %P || raw port number of master pbx
|+
| %u || url-like user name ('''''user''@''host''''')
|+
| %U || user url as per draft-levin-iptel-h323-url-scheme-04 ('''h323:://''user''@''host'':''port''''')
|+
| %X || the PBX name the user is registered with (note that using this pattern may result in a change of the name when a standby situation occurs)
|+
| %x || the PBX name the user is reported by (note that using this pattern may result in a change of the name when the users ''PBX'' attribute changes)
|}

The default pattern is <code>%C (%x)</code>.



==== Miscellaneous Flags ====
; 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 a <code>@</code>.
; Do not show parked Calls : will hide parked calls from the TAPI application (as some get confused and don't know how to handle them)
; Map PBX Devices to Lines : if set, the TSP will create one TAPI line for each individual [[Reference9:PBX/Objects#Devices|PBX device]] configured in a user object. See [[#Enhancements]] above.
; Map Presence Status to TAPI Lines : if set, the TSP will create one extra TAPI line for each PBX device object. See [[#Enhancements]] above.
; No special Disconnect Behaviour : normally, lines monitored by TAPI will behave slightly different when a call is terminated. With no TAPI on the line, the call will be disconnected immediately (from a PBX point of view). In cases where the phone would play some tones after termination of the call (e.g. a busy tone when the call has never been connected to the far end), this state is simulated by the phone and not visible to TAPI. Therefore, it is not possible to use TAPI functions on this call any more (as it in reality does not exist any more). When this flag is set, monitored lines will not be treated specially. Available from hotfix 6.

===Trouble Shooting===
The TSP will (from build 8095) 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'').

==== Turning on Debugging ====
There are 2 versions of the TSP, debug and retail, which are both copied to the machine during setup. The retail version is installed into the system directories, whereas the debug version is stored in a separate directory. This is available through a short cut in the Start menu.

The TSP can produce a number of debugging messages which can be helpful to debug issues. By default, debug messages are written to the systems debug buffer mechanism (using OutputDebugString()). Such messages can be examined using standard debugging tools, such as for example <code>dbgview</code> which is [http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx available from Microsoft].

Debug messages have a class associated with it and the amount of messages written can be controlled by enabling or disabling specific classes. This is done by setting a bitmask in the registry value <code>TraceLevel</code> in the <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code> key.

The available classes include

{|
| Bit in <code>TraceLevel</code> || Class
|-
| 0x00000001 || Minimum tracing
|-
| 0x00000002 || TAPI api traces
|-
| 0x00000020 || Basic telephony object creation/destruction
|-
| 0x00000040 || Thread creation/destruction
|-
| 0x00000080 || Request creation/destruction
|-
| 0x00000100 || call related messages
|-
| 0x00000200 || Call id map
|-
| 0x00000400 || Warnings/Errors
|-
| 0x00000800 || Worker thread execution
|-
| 0x00001000 || Full lock/unlock notifications
|-
| 0x00002000 || Win32 Critical section create/destroy
|-
| 0x00004000 || Agent proxy support
|-
| 0x00008000 || constructor/destructor debug
|-
| 0x00010000 || development debugs
|-
| 0x00100000 || verbose debugging
|-
| 0x00200000 || SOAP trace
|-
| 0x00400000 || SOAP message dumps
|-
| 0x01000000 || ATL debug
|-
| 0x02000000 || line related messages
|-
| 0x04000000 || informational messages
|-
| 0x10000000 || dump call infos
|-
| 0x20000000 || dump PBX infos
|-
| 0x80000000 || output log messages to file
|}

If <code>TraceLevel</code> is not set, it defaults to (hex) <code>04000400</code> in retail builds and to (hex) FFFFFFFF in debug builds. A nice value to use is (hex) <code>92200580</code>. The <code>TraceLevel</code> can be changed during runtime of the provider (it may take up to 10 seconds though for the setting to take effect). In normal scenarios there is no need to install the debug version.

Both ''informational messages'' and ''Warnings/Errors'' are always turned on (from build 8095).

: A problem has been reported on Server 2008 x64 systems which may also apply to others. On such systems, the value of <code>TraceLevel</code> may be reset to its default every 10 seconds. A workaround is to change the account the Telephony service is running in from its default (usually ''Network Service'') to e.g. ''Local System''.

===== Crash Dumps =====
From build 8063 the TSP will write crash dumps to the log directory (usually something like <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8 TSP\Logs</code>) in case of a trap. In release installs, these are not very useful. For debug builds though, they include helfpul information. Please provide these files (the can be zipped to a great extent) to support if requested. A crash dump file will be called something like <code>TSP8build-hour#minute-day.month#seqnr.dmp</code>.

===== Forcing a Crash Dump =====
In rare cases, it may be useful to force a TAPI crash for debug reasons. This can be done by issueing a <code>lineMakeCall</code> with called number <code>0815</code>, called-subaddress <code>4711</code> and called-name <code>!crash!</code> or simply calling <code>0815|4711^!crash!</code> from phone.exe.

==== Saving Log Messages to a File ====
The <code>0x80000000</code> value is special, as it does not denote a message class. Instead, it turns on log file writing, both in retail and debug versions. For this to work, the registry value <code>DoTraceFile</code> must be set to <code>1</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code> when the TSP starts. If this value is not present, it defaults to <code>1</code> in both retail and debug builds. Setting it to 0 disables log file writing regardless of any other setting. This may save some CPU cycles for installations with a real large number of lines.

The TSP will keep 24 log files (a days worth) by default. This value can be changed using the <code>NumLogFiles</code> value in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>. Older log files will be removed. Also, when the TSP shuts down, it by default will remove all log files it 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. Form TSP V8 hotfix 8 on, this behaviour can be tweaked by setting the DWORD registry value <code>KeepLogFiles</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>:
{|
| 0 || default || remove all log files on termination
|-
| 1 || || keep the last ''n'' log files (depending on <code>NumLogFiles</code>) on termination
|-
| 2 || || keep all log files
|}

Larger systems (500 monitored lines and more) can slow down considerably when using the debug drivers.

==== Installing the Debug Version ====
To install the debug version, you first install the retail version as outlined above. You then copy the debug driver files from the <code>Debug</code> directory to your windows system directory <code>system32</code>. You may want to use the shortcut to the <code>Debug</code> folder which has been installed to the start menu for convenience.

For the copy to work, proceed as follows
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* copy the debug driver files to your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>

When you open ''Telephony and Modem Control Panel'' again, you should notice that the TSP driver name has changed to the debug version.

==== Switching back to the Retail Version ====
To go back from the debug to the release version, proceed as follows:
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* delete the debug driver files from your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>
* repair the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

Please note that simply re-installing the driver from the original .msi without removing it from the system directory will not work.

===References===
The test applications provided with this setup comes from [http://www.julmar.com Julmar Technology Inc].

=== Limitations ===

Please note that there currently is a limitation to 2000 users being in
all active groups of a particular user. Thus, you cannot configure more
than 2000 users to be handled by TAPI on a single PBX. This is a PBX
limitation (and applies for all PBX groups).

TAPI has a flat line model. That is, all line numbers (aka
''extensions'') are considered to live in a single name space. As a
result, lines with identical numbers cannot be distinguished in TAPI
(although they can exist). All extensions in all nodes of a PBX
numbering tree are represented as TAPI lines. When the TSP works with a
PXB that implements a hierarchical numbering tree, then some lines may
receive identical numbers (their node-local extension which may overlap
between nodes depending on the setting of the ''Use pure node extensions'' property). When a TAPI application uses these numbers to initiate
calls to such lines, the call will work or not work depending on the
calling lines position in the numbering tree (that is, lines within the
same node as the called line will be fine, others may fail).

===Known Problems===
* 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
* The TSP will read its configuration when it is loaded by the system. Thus, configuration changes require a re-load of the TSP. Unfortunately, there is no reliable way to force the system to unload the TSP, so you may have to reboot the system for changes to take effect. See the [[ Howto:Troubleshooting_the_TAPI_service_provider | TAPI trouble shooting article ]] for details
* The TSP will use HTTP basic authentication to talk the PBX. So if you disable basic authentication in the PBX's configuration, the TSP will not work. It is recommended to use HTTPS
* TAPI requires the TSP to assign a unique id to each line device. This ID must not change between re-boots of the system or between upgrades of the TSP. This is done by keeping a persistent table in the windows registry (in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider\lineGUIDs</code>) that maps the PBX's line GUID to a fixed integer value (known as ''permanent line id'' in TAPI speak). This key is retained even on uninstall. To get rid of it, you must remove it manually
* Microsoft installer fails to remove driver files installed to the windows system folder. This is why the TSP driver files are still present after an uninstall of the software. To get rid of them, remove <code>TSP8.tsp</code> and <code>TSP8UI.dll</code> from both ''%windir%''<code>\system32</code> and ''%windir%''<code>\sysWOW64</code>
* From Version 9, hotfix 1, the PBX firmware will not list objects tagged as [[Reference9:PBX/Objects#General_Object_Properties | ''hide from LDAP'' ]] in the result of a [[Reference9:Concept_SOAP_API#UserInfo.5B.5D_FindUser.28string_v501.2C_string_v700.2C_string_v800.2C_string_cn.2C_string_h323.2C_string_e164.2C_integer_count.2C_integer_next.29 | FindUser() ]] call. As a result, such objects will not be shown in the TAPI configuration dialogue ''Username'' drop-down. If you want to use such an object as ''TAPI User'' you can simply type in the name without selecting it from the drop down.
* Sometimes, setting configuration with ''TSP Control'' (not the telephone control panel dialogue) does not work due to windows' ''User Access Control (UAC)'', see [[Howto:TAPI_TSP_Control_Windows7]] for Details

=== Tweaks ===
There are a few configuration options which should be used rarely. They can be enabled by setting an appropriate registry key.

There are some values in <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>:

; ProcessorMask : REG_DWORD. If set, the TSP will use <code>SetProcessAffinityMask(GetCurrentProcess(), set)</code> to limit TSP execution to one or more of the existing processors. Set to <code>0xff</code> by default.

; LineTimeOut : REG_DWORD. Can be set to a number of seconds the TSP should wait for the determination of lines to finish (default 90). On a large PBX, or a PBX with slow slaves, the determination might not finish in the default time frame. If this happens, TAPI applications may show ''Line unnamed'' line entries in their line list. If this is a problem, set it to a larger value (e.g. <code>120</code>).

; IgnoreDevStatus : REG_DWORD. Some applications get confused if TAPI reports line to be disconnected or out-of-service dynamically. Setting this to a non-zero value will disable any such notification.

; ClearFwdOnSet : REG_DWORD. If set to a non-zero value, the TSP will clear all current call forward settings before a lineForward request is executed. This implies that all call forward settings are ''replaced'' by the new settings. Standard behaviour is to only modify the settings, that is, replace all current settings of the same type with the settings found in the lineForward request (for example, if there is only one setting in the request that defines a CFU, then the current CFU settings are replaced by the new one provided. All others, such as e.g. CFNR settings, are left untouched).

: Tapi spec is pretty clear on how this should work: ''The provider should "unforward everything" prior to setting the new forwarding instructions''. Even though, for historical reasons, ClearFwdOnSet=0 has been the default in all TAPI versions prior to V8 hotfix 6, from hotfix 6 on, the default changes to 1, as this has turned out to be the widely accepted interpretation.

; No3PTY : REG_DWORD. See [[Reference8:TAPI_Service_Provider#Notes_on_3PTY_Conferences | Notes_on_3PTY_Conferences]] below.

; HiddenRecordingNumber: REG_SZ. Active recording in an innovaphone PBX is implemented as an implicit 3PTY conference with the recording sink as one of the parties. These will be shown as usual in the TAPI callstate. However, some applications get confused as this results in a situation, where a normal endpoint (read: phone) has more than one active (i.e. ''not on hold'') call. To suppress such calls in the TAPI call states, you can set this tweak to the number of the recording sink as configured in the phone's recording configuration tab. If so, any outgoing call from an endpoint that is registered with a PBX user object with a called number that equals the setting of this tweak, will be suppressed. So if your recording sink has the number <code>44</code>, you would set this registry value to <code>44</code> (this is available from TAPI V8 hotfix 8). Please note that this feature actually suppresses any call info for such calls, however, it does not revert previously announced call infos. So if the call is initiated using ''overlapped dialling'', all call states will be shown until the called number matches the value of <code>HiddenRecordingNumber</code> and all subsequent call states will be suppressed. This will probably leave the call shown in ''dialling'' state. The feature should be used for destinations which are called using ''block dialling'' only thus.

; SilentHold : REG_DWORD. When a call is put on hold using <code>lineHold</code>, both parties will normally hear ''music on hold'' emitted by the PBX. When <code>SilentHold</code> is set to a non-zero value, the initiating party will not hear any ''music on hold'' (this is available from TAPI V8 hotfix 8).

There are some more values in a key underneath <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code> called <code>Device</code>''XX'':

; NoDuplicateConnectedCalls : REG_DWORD. If set to 1, the TSP will never show more than one call per line to be active. Extra active calls will be shown as ''on-hold''. The situation occurs e.g. when a user initiates a 3PTY conference on the phone. This essentially is a bug fix for Microsoft's OCS client which forces any extra active call on-hold, thereby disturbing the 3PTY function. If your are using [http://www.estos.de/download/software/eccg.htm ESTOS' Call Control Gateway]: from version ''2.0.1.1474 - 05.11.2008'' there is a fix for this same problem available. This option thus is deprecated.

===List of supported TSPI functions===

The TSP supports the following TAPI Service Provider Interface Functions. Note that these do not map one to one with TAPI user functions. For more information, see the Microsoft TAPI documentation.

TSPI_lineAnswer
TSPI_lineBlindTransfer
TSPI_lineClose
TSPI_lineCloseCall
TSPI_lineCompleteTransfer
TSPI_lineDevSpecific
TSPI_lineDevSpecificFeature
TSPI_lineDial
TSPI_lineDrop
TSPI_lineForward
TSPI_lineGenerateDigits
TSPI_lineGetAddressCaps
TSPI_lineGetAddressID
TSPI_lineGetAddressStatus
TSPI_lineGetCallAddressID
TSPI_lineGetCallHubTracking
TSPI_lineGetCallIDs
TSPI_lineGetCallInfo
TSPI_lineGetCallStatus
TSPI_lineGetDevCaps
TSPI_lineGetExtensionID
TSPI_lineGetID
TSPI_lineGetLineDevStatus
TSPI_lineGetNumAddressIDs
TSPI_lineHold
TSPI_lineMakeCall
TSPI_lineNegotiateExtVersion
TSPI_lineNegotiateTSPIVersion
TSPI_lineOpen
TSPI_linePark
TSPI_linePickup
TSPI_lineRedirect
TSPI_lineSelectExtVersion
TSPI_lineSendUserUserInfo
TSPI_lineSetAppSpecific
TSPI_lineSetCallData
TSPI_lineSetCallHubTracking
TSPI_lineSetCallParams
TSPI_lineSetCurrentLocation
TSPI_lineSetDefaultMediaDetection
TSPI_lineSetMediaMode
TSPI_lineSetStatusMessages
TSPI_lineSetupTransfer
TSPI_lineSwapHold
TSPI_lineUnhold
TSPI_lineUnpark
TSPI_providerConfig
TSPI_providerCreateLineDevice
TSPI_providerEnumDevices
TSPI_providerGenericDialogData
TSPI_providerInit
TSPI_providerInstall
TSPI_providerRemove
TSPI_providerShutdown
TSPI_providerUIIdentify

=====Notes on Consultation Calls=====
This TSP supports the <code>lineSetupTransfer</code> function. However, strictly speaking, this function is not needed and should not be used. It is merely intended for applications which do not offer a consultation call interface to the user when this function is not available. Instead, <code>TSPI_lineMakeCall</code> can be used where <code>lineSetupTransfer</code> would be otherwise. The notion of a special ''consultation call'' is an idiosyncrasy forced by legacy PBX technologies which were not able to transfer two arbitrary calls. In these scenarios, a potentially to-be-transferred call needed to be linked to the primary call. The PBX can transfer two arbitrary calls and thus there is no need for <code>lineSetupTransfer</code>. This ability is indicated by the <code>LINEADDRCAPFLAGS_TRANSFERMAKE</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE </code> flags. The transfer is then requested by using <code>TSPI_lineCompleteTransfer</code>.

=====Notes on 3PTY Conferences=====
The TSP supports the management of 3PTY conferences. These can be initiated by using <code>TSPI_lineCompleteTransfer</code> with <code>LINETRANSFERMODE_CONFERENCE</code> instead of <code>LINETRANSFERMODE_TRANSFER</code>. This is indicated by the flags <code>LINEADDRCAPFLAGS_CONFERENCEHELD</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE</code>. The 3PTY function is actually implemented by the innovaphone IP phones (such as IP2xx). Therefore, these capabilities are only advertised if the line is based on a PBX user object. Still, some lines where the capabilities are advertised cannot do 3PTY (such as e.g. DECT lines, analogue lines, 3rd party devices, ...). So the call to <code>TSPI_lineCompleteTransfer</code> will succeed but the conference will not be initiated and the subsequent call states will not indicate a conference (as there is no).

Also, if non-telephone devices are registered with a PBX user object and these device have multiple concurrent calls (e.g. a call center connected with a multi-channel XCapi), these will be viewed as 3PTY calls (as this is the way such calls appear to the TAPI: a line with more than one non-held call). If these calls are in fact no 3PTY, this may lead to confusing call indications from TAPI. It is better to register such objects as a PBX gateway object. Special treatment of 3PTY calls can be disabled by setting the registry flag <code>No3PTY</code> (from build 8087 onwards).

A 3PTY conference will create a new call handle for the conference. The only operation available for such a handle is <code>TSPI_lineDrop</code>. This will terminate the conference and restore the state active before the conference was initiated (that is, the phone that implemented the conference will now have 2 calls, one active and one on hold). This is indicated by not setting <code>LINEADDRCAPFLAGS_CONFDROP</code>.

A <code>lineDrop()</code> on one of the 2 ''real'' calls involved will of course cancel this call and thus remove the 3PTY.

======Notes on Intrusion Calls======
A special case of 3PTY is an intrusion call initiated by a [[Reference9:Phone/User/Function-Keys/Partner | partner function key]]. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the intrusion call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is an intrusion call).

======Notes on Recording Calls======
A special case of 3PTY is a recording call. This effectively creates an user-invisible 3PTY on the phone. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the recording call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is a recording call).

Recording calls are shown as normal conferences (unless <code>No3PTY</code> is set). This might be confusing to applications and/or users. See the <code>HiddenRecordingNumber</code> tweak above for a method to hide such calls.

=====Notes on parked Calls=====
The PBX can park calls from and to any existing PBX object, e.g. by virtue of [[Reference8:Configuration/Registration/Function-Keys/Park | specific feature keys]]. They are parked to/from a numeric ''park position''. In SOAP however, calls are parked to an object by providing the objects '''UserInitialize()''' handle and a park position. Parked calls are then reported as straight calls with a distinct signalling state (8). The park position is not conveyed as part of the '''CallInfo''' record. To unpark, '''[[Reference8:SOAP_API#integer_UserPickup.28int_user.2C_string_cn.2C_integer_call.2C_string_group.2C_int_reg.2C_InfoArray_info.29 | UserPickup]]''' can be used providing the parked calls call handle as '''call''' argument.

The TAPI specification is unclear on how the address information required to '''lineUnpark()''' a call can be obtained by an application (except that it is returned from '''linePark()''' if the call was parked using TAPI). The TSP thus indicates parked calls on a line with a call reason <code>LINECALLREASON_PARKED</code>. The caller id information is set to the parked calls call handle. This way, the application can take the caller id information and provide it to '''lineUnpark()''' to unpark a call. If the appication does not support this mode of operation but supports '''lineUnpark()''' and lets the user input the park identifier, the user can just provide the caller id information.

Some applications do not care for parked calls (by examining the call reason) and just blindly report these calls like ordinary connected calls (thereby confusing the user). To work around this problem, reporting parked calls can be turned off in the TSP configuration dialogue.

=====Notes on sending User to User Information =====
The TAPI specification for sending UserUserInfo closely resembles the way ISDN defines this service. Although the innovaphone PBX supports this service both with H.323 and SIP, it is ''not'' supported in this TSP. Instead, sending user to user information is implemented using H.323/SIP messaging. However, there are some important deviations and limitations caused hereby:
* data is ''not transparent''. That is, the TSP only allows for null-terminated unicode to be sent. The data must be of even length and the last two bytes must be null.
* data is ''not sent within the call'', but by initiating a separate call. This implies that the target number used to send the message carrying the data to is 'guessed' from the available call data. For example, if the call is in a connected state and a connected number is known, the message is sent to the connected number. If the call is in the ringback state, then either the called number or - if available - the redirection number is used and so forth.
* message calls are not indicated by the SOAP CallInfo records. As a result, messages (that is, user to user information) cannot be received with TAPI and ''lineReleaseUserUserInfo is not supported''

=====Notes on sending proprietary innovaphone Remote Control Facilities =====
The SOAP [[Reference8:SOAP_API#UserRc.28integer_call.2C_integer_rc.29|UserRc]] function allows to send various [[Reference:Remote Control Facility|facility messages]] to an innovaphone phone device. In some cases, it is useful to be able to invoke this function through a standard TAPI mechanism. This can be achieved by using the TAPI '''lineBlindTransfer''' function. If the ''called party name'' provided as destination for the ''lineBlindTransfer'' (in ''lpszDestAddress'') has the magic value <code>USERRC</code>, then the ''called subaddress'' is converted to an integer and the result is sent as remote control facility to the call the blind transfer is applied for. For details on how to code the ''called party name'' and the ''called subaddress'' into ''lpszDestAddress'' see [http://msdn.microsoft.com/en-us/library/windows/desktop/ms726017%28v=vs.85%29.aspx Microsoft's ''Canonical Address'' specification]. This works from TAPI8 hotfix 4.

For example, initiating a blind transfer to <code>|16^USERRC</code> (empty address, subaddress 16 (that is, [[Reference:Remote Control Facility|''change to handset mode'']]), called name <code>USERRC</code>) will switch the phone having the call to be transferred into handset mode (and <code>|18^USERRC</code> will switch it back to handsfree mode). Of course, no actual transfer will happen in these cases (''lineBlindTransfer'' is merely used as a vehicle to send the facility to the proper call).

Such proprietary facility message can also be sent with ''lineMakeCall'' (that is, in SOAP's [[Reference8:SOAP_API#integer_UserCall.28integer_user.2C_string_cn.2C_string_e164.2C_string_h323.2C_int_reg.2C_InfoArray_info.2C_int_rc.2C_string_srce164.29|UserCall]] function). For example, setting up a call to <code>123|21^USERRC</code> will send an intrusion call to extension 123 and intrude any call that might be active there. This works from TAPI8 hotfix 6. Please note that the innovaphone TAPI service provider does not support TAPI's ''lineCompleteCall'' function with <code>LINECALLCOMPLMODE_INTRUDE</code> though (as TAPI's call model here does not fit with the PBX's call model). Please also note that intrusion calls look like 3PTY calls to TAPI (see [[#Notes_on_Intrusion_Calls|notes on intrusion calls]] above).

Remote control facilities are implemented by the telephone devices, so these functions are subject to the phone firmware in use.

[[Category:Howto|{{PAGENAME}}]]
[[Category:Concept|{{PAGENAME}}]]

Howto:How to configure the Phones LDAP client

2013-04-22T11:03:37Z

Msr: /* Applies To */

The IP200 (also the IP110 ,IP202 and IP230 etc.) features a powerful telephone number directory.

It will perform number-to-name resolution for incoming calls and name-to-number resolution for outgoing calls (using the IP200 built-in alphanumeric keyboard).

The directory can access up to 3 sources for lookup: the internal (flash-based) list, the PBX user list and an external LDAP server.

This article describes how to configure the IP200’s LDAP interface for various application scenarios.

It is meant as a complement to the existing standard product documentation, so please refer to this for general configuration issues.

==Applies To==
This information applies to

* IP110
* IP200
* IP202
* IP230
* IP240
* IP240-1000
* IP72
* IP2x2

==More Information==

===Quick start===

This topic is for people with good understanding of LDAP and with little time for reading, who simply want to see immediate results in the IP200.

Needed: IP address of target LDAP server, distinguished Name and password of LDAP user entry with read access to the directory, distinguished Name as starting point for LDAP searches (base DN).

*Open the IP200’s applet, proceed to directory/LDAP from external Server
*Check Enable External LDAP server access
*Enter the target server’s IP address
*Leave port empty (default 389 is used)
*Enter the Distinguished Name and Password or leave both fields empty, if an anonymous search is to be performed.
*As LDAP Mode select basic
*Disable Sort by 1st LDAP Name attribute
*As Base enter the base DN
*For Object Filter try with either inetorgperson or user or organizationalperson
*Leave all remaining fields empty, save and activate the new configuration
*On the IP200’s alphabetic keypad hit an arbitrary letter-key and verify whether results are shown in the display. The letter should be the first letter of a person’s surname known to be present in the directory.

If nothing happens, you’ll need to work yourself through the remainder of this article.

===LDAP===
LDAP stands for Lightweight Directory Access Protocol; a small-footprint descendant of ITU’s older X.500 series, respectively DAP (directory access protocol). Originally developed by a group at the University of Michigan LDAP is now the de-facto standard for accessing information held within so-called Directory Servers. The protocol standardization is harboured by the IETF and specified by several RFCs. RFC 2251 is the least to name, it covers LDAPv3 - the current culmination which is implemented in innovaphone products.

The protocol is made up of operations like: Bind, Search, Add, Delete,…. The operations in turn are realized through messages. The two most notable operations are listed below.

All of those can be taking place between a client and a server, immediately after a TCP connection (port 389) has been established towards the server end.
*Bind Operation: This Operation is handling authentication issues. It is accomplished once throughout a session. While LDAP itself is offering a wealth of authentication methods the innovaphone products currently just support clear-text authentication.

The Messages are: Bind Request and Bind Result

*Search Operation: A client is sending a so-called LDAP Search Filter within a Search Request. This filter details what is being searched for.

The Messages are: A single Search Request, zero or more Search Result Entry messages and a completing Search Result Done.

===LDAP query modes===
The IP200 term LDAP mode refers to what is known in the LDAP world as LDAP control. The most important to know is that searches can fail if the server does not support the selected mode. See “LDAP Mode not supported by remote Server” below for more details on that.

The next thing to keep in mind is that the paged results and virtual list view will not be used (even if configured), if both an external LDAP server and the PBX user list are queried.

To benefit from these modes, there are 2 options:
*Disable e.g. the LDAP access to the IP-PBX permanently (in the applet)
*In the telephones user interface, enter the menu Search (Extern), (Suche (Extern)). This will query only the external LDAP server and thus use the configured mode (if available).

Here is how the 3 available modes work:
*Basic: No further functionality, search results can only be narrowed by entering more letters like in an advance list.
*Paged Results: The down-arrow key should work. From the point a search result has been received and the telephone display shows the content, a user can scroll down further. Upward scrolling is not possible.
*Virtual List View: Both scrolling directions, upwards and downwards should work after a search result came back.

===Storing telephone numbers in your LDAP directory===
There are virtually endless variations to store telephone numbers in directories. Just to name a few +49 (7031) 73009-0, +497031730090, (07031) 730090, 0049 (0) 7031 73009-0...

Most LDAP servers do not apply magic when searching for telephony numbers, that is, they treat them as plain text. So if you have +49 (7031) 73009-0 in your directory and you search for +497031730090 via LDAP, there will be no match. It is thus critical to store telephone numbers in a proper format.

Here is how the IP200 is setting up the LDAP search request for resolution of an incoming number (CLI):

*Based on the phones location information, the incoming number is expanded to a full E.164 number. This is - assumed the CLI is 0070317300999 and the phone location is set to country code 49, area code 7031, national line prefix 0, international line prefix 00, trunk access prefix 0 and trunk subscriber number 73009 – normalized to +4970317300999. (For more information on the location settings, please refer to the IP200’s administrator manual)

*An LDAP search expression is created which will search for 3 patterns

#The raw number as received in the call (please note that this will include the trunk access prefix): 0070317300999
#A pattern which will search for the normalized number with some decoration: +49*7*0*3*1*7*300999
#A pattern which will search for the normalized number with full decoration: +49*7*0*3*1*7*3*0*0*9*9*9

This expression will find all reasonable notations for a normalized number in the LDAP server.

As a side note: when the directory searches the local flash directory, it will only use pattern 1 above.

===Multiple numbers for a single contact===
The way the IP200 constructs its search pattern actually forbids storing multiple numbers in a single attribute. In order to work around this a server must either allow for multiple instantiation of the respective telephone number attribute (e.g. telephoneNumber). Each instance of the attribute would contain a single number. Or the server maintains several telephone attributes with different names.

For instance the Active Directory™ does both. If a new user is configured to the system, a dialogue with lots of tab-dialogues and user properties can be edited. The number that can be entered on the General page will later settle in the attribute telephoneNumber. More instances of this attribute will be created, if you clicked on Other.. right next to it. The Telephones page will allow you to configure a home phone number, a mobile phone number and so on. These latter numbers will result in additional attributes like homePhone, mobile and so on. On the IP200, the effect is that a single user shows up multiple times in the telephone display, once for each telephone number found in the directory.

For more information regarding the attributes used for searching, see the IP200’s administrator manual.

==LDAP Servers==
===Active Directory™===

Supported LDAP Modes: basic and paged results.

To access the database, you will need a DN of a Windows™ domain user with read access to the directory.

The IP200 will use this DN, together with the users password to authenticate itself against the Active Directory.

Distinguished Name and Password: It is assumed you are logged in to Windows domain with administrator privileges on one of your domain controllers.

Open a command prompt and enter:

ldifde.exe -s 127.0.0.1 -f user.ldf

[ See below for information regarding ldifde.exe ]

As a result user.ldf will contain the entire user database as stored within the Active Directory.

Open the file with a text editor and search for the user, whose credentials you want to configure in the ip200 (you may want to create a pseudo user with limited rights for this).

Look for the users line beginning with dn:. The content behind is what we’re looking for.

Here is an excerpt for a user named test:

dn: CN=test,CN=Users,DC=inno-bln,DC=com
changetype: add
memberOf: CN=Administrators,CN=Builtin,DC=inno-bln,DC=com
accountExpires: 9223372036854775807
adminCount: 1
badPasswordTime: 0
badPwdCount: 0
codePage: 0
cn: test
countryCode: 0
displayName: test
dSCorePropagationData: 20010725142708.0Z
dSCorePropagationData: 16010101000001.0Z
mail: test@inno-bln.com

As Distinguished Name we’re configuring CN=test,CN=Users,DC=inno-bln,DC=com in the IP200.

The password cannot be learned from the file.

You can select paged results as LDAP mode (see above for details on LDAP modes).

As Base you should enter what you configured as domain during the Active Directory installation.

Usually something of the form: dc=mycompany,dc=com. If in doubt, you can use ldp.exe to determine the base DN.

Connect to your domain controller and look for the attribute defaultNamingContext respectively namingContexts.

If the IP200 shall search for Active Directory users, enter user as object filter. If it shall search for contacts only, use contact. To search both, enter <code>(|(objectclass=user)(objectclass=contact))</code>. The latter is an “Or” filter string. Using the field “objectcategory” in the filter prefix can be more efficient for the server than using “objectclass” (the default value), since the former is indexed on the Active Directory server by default, whereas the latter is not indexed by default.

The Attribute 1..3 settings can be left empty, the internal default should suffice.

However, if e.g. Surnames (sn) aren’t properly maintained in the Active Directory you eventually will have to fall back to a common attribute.

In this case try with cn as Attribute 1, leave the other fields empty.

Leave Phone 1 .. 4 empty.

Leave Mail empty.

===iPlanet Directory Server 5.0===
[ iPlanet currently seems to be known as Sun Java System Directory Server 5.2 ]

The product is the successor of Netscape’s Directory Server 4.12, so some or all of the recommendations may apply to this product too.

Supported LDAP Modes: basic and virtual list view.

To access the database, you will need a DN of an iPlanet user with read access to the directory. The IP200 will use this DN, together with the users password to authenticate itself against the iPlanet. It is suggested to create a dummy user with restricted privileges for this. You will need to use the value of the entrydn configuration attribute (from the iPlanet property editor) as distinguished name in the IP200 configuration.

It is recommended to select basic as LDAP mode (see above for details on LDAP modes). If you intend to use virtual list view, be sure to read the next chapter carefully. We found this mode to be slow on the iPlanet.

As Base you will need to configure the value entrydn property of the iPlanet sub tree containing the objects to be searched. This will be something of the form: ou=tree,dc=domain,dc=tld. If in doubt, use iPlanet’s property editor to determine proper value.

All users are stored as objects of type inetOrgPerson. So simply enter inetOrgPerson as object filter.

The Attribute 1..3 settings can be left empty, the internal default should suffice. You may want to experiment with either cn or sn for Attribute 1 for better results.

Leave Phone 1 .. 4 empty unless you add telephone numbers to different numbers in the iPlanet management console. If so, you need to specify the respective attribute names as Phone 1 .. 4, starting with telephoneNumber.

Leave Mail empty.

===Using virtual list views with iPlanet===
To use virtual list views on an iPlanet server, there must be a browsing index for the sub tree used as base dn. This can be created using the iPlanet management console. However, performance can be slow. The remainder of this chapter aims at helping get the best performance out of the iPlanet.

To take advantage of the created index for virtual list view queries, the query must match exactly the index created. To assure best performance, it is critical thus to configure the IP200’s LDAP search expression so that it in fact will trigger the index. When an index is created, the iPlanet server internally creates two new directory entries. One is of objectclass vlvSearch and the other of objectclass vlvIndex. You will need to find some attributes of these nodes. The simplest way to get at this information is to have a look at the file <code>..\bin\slapd-xxx\config\dse.ldif</code>. You will need to find the data related to the newly created index.

Here is an example:

dn: cn=by MCC ou=People dc=inno-bln dc=com,cn=MCC ou=People dc=inno-bln dc=com, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
objectClass: top
objectClass: vlvIndex
cn: by MCC ou=People dc=inno-bln dc=com
vlvSort: cn,givenname,o,ou,sn
creatorsName: uid=admin,ou=administrators,ou=topologymanagement,o=netscaperoot
modifiersName: uid=admin,ou=administrators,ou=topologymanagement,o=netscaperoot
createTimestamp: 20011114120401Z
modifyTimestamp: 20011114120401Z

and

dn: cn=MCC ou=People dc=inno-bln dc=com, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
objectClass: top
objectClass: vlvSearch
cn: MCC ou=People dc=inno-bln dc=com
vlvBase: ou=People,dc=inno-bln,dc=com
vlvScope: 1
vlvFilter: (|(objectclass=*)(objectclass=ldapsubentry))
creatorsName: uid=admin,ou=administrators,ou=topologymanagement,o=netscaperoot
modifiersName: uid=admin,ou=administrators,ou=topologymanagement,o=netscaperoot
createTimestamp: 20011114120400Z
modifyTimestamp: 20011114120400Z
numSubordinates: 1

Based on this information, we can fine-tune the IP200’s configuration as follows. As Base you will need to specify the value of the vlvBase attribute. In our example, we would need to configure ou=People,dc=inno-bln,dc=com. Please note the value 1 for the vlvScope attribute above. This means the server does not recurse down from the base to look for potential search hits.

Instead of inetOrgPerson you need to specify the value of the vlvFilter as object filter.

In our example, we would need to configure (|(objectclass=*)(objectclass=ldapsubentry)). This will restrict the search to what is covered by the index.

However, we still need to request the proper search order for the index to be used. This defined by the value of the vlvSort attribute.

In our example, we would need to configure cn,givenname,o,ou,sn as sort order. Unfortunately, this cannot be configured via the phone’s applet. Instead, you need to change the respective line in the IP200’s configuration file.

You will need to append the /ldap-sort sortmode option to the config file line:
config change PHONEDIR0

In our example, it would look like

config change PHONEDIR0 /ldap-sort cn,givenname,o,ou,sn other options

Please note that in iPlanet, vlv entries can have an ACL associated. If you get Insufficient Access Rights replies, you may need to inspect the access rights.

===MS Exchange 5.5===
Microsoft™’s Exchange 5.5 incorporates an LDAP server, known as the Directory Store (DS).

There are a few limitations, with one being really annoying: The DS does not expose everything to LDAP the Exchange 5.5 might know. In particular, the public folders used to store contact records are not accessible via LDAP. The only data that can be queried is the global address list. We thus recommend using [[Howto:Metadirectory - Estos - 3rd Party Product| ESTOS MetaDirectory]] to access Exchange contact data.

LDAP Modes supported: basic and paged results

Distinguished Name and Password: our tests were done without any authentication, i.e. with empty user information and with an empty password.

Base: use the exchange domain as base.

Use ldp.exe to examine the rootDSE and retrieve the value of the namingContext attribute.

This is usually something of the form:

o=myexchangedomain
Object Filter: we recommend using a filter, which restricts results to objects, which actually have a telephone number.
This will remove confusing entries like distribution lists and the like: (&(objectclass=organizationalperson)(telephonenumber=*))
Attribute 1..3: Enter: cn for Attribute 1
Phone 1 .. 4: Leave empty.
Mail: Leave empty.

===OpenLDAP 2.07 or later===
Distinguished Name and Password: enter cn=useraccount-you-want-to-use,dc=host,dc=tld as Distinguished Name and configure the respective secret as password.

LDAP Mode: basic.
Base: use dc=host,dc=tld, as in the distinguished name above.
Object Filter: use inetorgperson.
Attribute 1..3: leave empty.
Phone 1 .. 4: leave empty
Mail: leave empty

===Lotus Domino R5===
Very much like Exchange 5.5 the Domino Server does not speak LDAP natively. And like OpenLDAP: not a single LDAP control is supported. Also, certain Domino fields need to be configured for read-access.

For the anonymous search requests to work, the field OfficePhoneNumber had to be configured explicitly. Without this hand-crafting, the LDAP attribute telephoneNumber never made its way towards the ip200. In the Lotus Notes Server Configuration, you will need to make sure the attributes FirstName, FullName, LastName, MailDomain and OfficePhoneNumber are listed under Anonymous users can query: in the LDAP property tab with at least Read access.

LDAP Modes supported: basic

Distinguished Name and Password: the tests done using anonymous LDAP search requests, i.e. with an empty user information and password.

Base: please consult your local Domino Administrator for the desired organization name – it will be something of the form o=myorganization.

Experience with a Domino R6 did show, that the Base had to be left empty.

That is, the Domino did not offer any naming context, except an empty one.

Object Filter: user inetOrgPerson or leave empty (inetorgperson is default).
Attribute 1..3: Can be left empty, since the default will suffice (sn,givenName,Company).
Phone 1 .. 4: leave empty.
Mail: leave empty.

===Cisco call manager===
The Cisco Call Manager (CM) also incorporates an LDAP server, that’s meant to be queried by Cisco’s’ IP phones.

Note that it’ll be likely to run on a different port than 389.

LDAP Mode: use basic.

Distinguished Name and Password: please query your CM Administrator for the desired information – it will be something like cn=Directory Manager,o=cisco.com accompanied by a password.

Base: Please query your CM Administrator for the desired information – it will be something like: ou=users,o=cisco.com

Object Filter: leave empty (inetorgperson is default).
Attribute 1..3: Can be left empty, since the default will suffice (sn,givenName,Company).
Phone 1 .. 4: Leave empty
Mail: Leave empty

===Estos MetaDirectory===
MetaDirectory is an LDAP server and also a data consolidation tool. That is, it will retrieve contact data from various sources and replicate it into a single LDAP database for search and retrieval. This is a very powerful tool.

Please find more information here:
*[[Howto:Metadirectory - Estos - 3rd Party Product]]
*[[Howto:Maintain Quickdial Numbers In Estos MetaDirectory]]

===innovaphone PBX===
An IP200 will by default query its own PBX for directory data. There is no special configuration required to do this (except that it must be enabled in the config applet). However, in complex multi-PBX scenarios it may be necessary to query a different PBX for directory data (e.g. a master PBX in a location scenario).

Here is how to configure an innovaphone PBX as external LDAP server:

*Server: IP address of the PBX
*Port: 389
*User Name and Password: use what is configured as valid LDAP server access in the PBX under Config/LDAP Server. Read-only access is sufficient.
*Search Base: use cn=pbx0
*LDAP Mode: use virtual list view.
*Object Filter: use (objectclass=*)
*Name Attributes : use cn as attribute
*Number Attributes :use e164 as attribute
*H323 ID Attr :use h323 as attribute, if you have objects to call with no number
*Mail: use h323

==Troubleshooting==
Ldifde.exe is a standard command-line LDAP client. It is part of the Windows 2000 server software. The program allows exporting and importing the contents of an Active Directory into/from so-called LDIF files.

The LDIF data format is standardized by an RFC and has the benefit to be readable with a text editor. We’re using ldifde to read out some information that in turn is required for the configuration of the telephone.

Ldp.exe is an unsupported Microsoft Win32 application that can be installed from the support\tools folder of the Windows 2000 server CD. Actually it is a fairly well featured LDAP client. Despite of poor documentation it is very valuable in handling the first LDAP configuration questions.

Ldp.exe may be helpful in reading a servers rootDSE, browsing a servers directory, determining potential LDAP Search Bases and so on. To see a servers rootDSE simply select Connection/connect within ldp.exe. The application then automatically queries the server for the rootDSE and presents it in the right pane window. The rootDSEs namingContexts attribute lists some possible values for the base DN.

Once connected you can authenticate to a server by choosing Connection/Bind.

The default (no Advanced, Domain not checked) conducts a clear-text or SIMPLE authentication (what the ip200 is doing).

In contrast to MS Internet Explorer the Netscape Browser may serve as a fairly well featured LDAP client. Beyond Netscape Messenger’s LDAP capabilities the Browser does support the LDAP-URL specified in RFC1959. The only constraint is the necessity for anonymous read access. The browser even does not give any error message if the LDAP Bind operation fails.

Here’s how you can read an LDAP server’s rootDSE:

ldap://server/??base

Every object underneath a hypothetical DN o=myorg:

ldap://server/o=myorg??sub

To obtain meaningful traces from the IP200, you will need to switch on the /trace and /ldap-trace options of the IP200’s PHONEDIR0 config line.

Make sure to append these traces to your current configuration, such that it looks something like

config change PHONEDIR0 /trace /ldap-trace further-options

===Common Problems===
0:1607:171:3 - ldir(S): LDAP BIND failed=> 49,"Invalid Credentials"

Either the distinguished name/password for the server login is wrong or the server does not support clear text authentication.

0:1153:561:4 - ldir(S): LDAP SEARCH failed=> 12,"A Critical Extension (LDAP Control) Is Unavailable"

The server does not support a search control you are using.

Make sure the Sort by 1st LDAP name attribute is unchecked and there is no /ldap-sort option in the config file.

If this does not help, try basic as LDAP mode.

== Related Articles ==
*[http://www.microsoft.com/windowsserver2003/techinfo/overview/ldapcomp.mspx Ldap for beginners]
*[[Howto:Metadirectory - Estos - 3rd Party Product]]
*[[Howto:Maintain Quickdial Numbers In Estos MetaDirectory]]

[[Category:Howto|{{PAGENAME}}]]

Reference10:Events/0x00020003

2013-04-17T08:35:47Z

Msr: New page: An external transfer was attempted even if not allowed. The to be transfered calls were disconnected instead. External Transfer can be enabled using the 'PBX/General/Enable External Transf...

An external transfer was attempted even if not allowed. The to be transfered calls were disconnected instead. External Transfer can be enabled using the 'PBX/General/Enable External Transfer' checkmark

Howto:Innovaphone conferencing

2013-02-15T10:11:34Z

Msr: /* Known Problems */

innovaphone conferencing is a nice sample solution to enhance the conference bridge available on the innovaphone gateways (so-called “BC Conference”).

Installing innovaphone conferencing you will have the following conferencing features:

* Users are announced with name when joining and leaving the conference room.
* The conference room can be labelled; before entering in the room the user will hear the name of the conference.
* Before entering in the room the names of the member’s already in are prompted.
* innovaphone conferencing stores all recorded names for further access; you have to record your name just one time.

==Applies To==
This information applies to

innovaphone PBX with DSP channels for conferencing
developed with V9 build 90267



==More Information==

innovaphone conferencing allows you to setup a very comfortable audio conference.

If a number calls the innovaphone conferencing for the first time the system asks, after playing the welcome message, to record a name.

The recording can be done immediately, just following the voice menu (“Please record your name, start recording with star and stop with any key”). After recording, the recorded name is played again. The record can be modify in any moment and anyway before entering in the conference room.

If the same number calls the innovaphone conferencing system again, the system will not ask to record the name but welcome the caller, with the previously recorded name. So once recorded, innovaphone conferencing stores the names for the calling number.

If the conference room is still empty, the system asks you to label the conference room. This is done via a voice menu invitation to record the name of the conference, even this recording can be modified later on. However if the conference room is already named, the caller is not invited automatically to label the room but the name of the conference if played.

The following example shows a call to the innovaphone conferencing, where the NAME and the LABEL was already recorded:

“innovaphone conferencing, welcome MARTIN STRELLER to SALES conference room”

After this introduction the main access menu is played:

“Press star to join the conference room, press one to record your name or press two to label the conference room”

From this menu the caller can record again his name or label the conference room. The star-key allows the access to the conference room.
If the conference unit is not reachable (configuration or network problems) or no conference channel is available (all available DSPs are used), a warning message is played.

If the caller is the first member, he will hear “You are the first conference member”. If there are already members in the conference room, he will hear their names.

Example:

“In the conference room you will find ANDREAS FINK, KLAUS WALLNÖFER”

After playing the list of the conference members, the caller access the conference room and all the members hear a warning ton (“beep”) followed by the name of the new entry.

Example:

“MARTIN STRELLER joined the conference”

If a conference member exits from the conference room, the remaining members will hear a warning tone followed by the name of who has left.

Example:

“ANDREAS FINK leaves the conference”

When the last user leaves the conference room, the room label will be automatically cleared.

===Configuration===

Download the xml and wave files, copy them on a directory of your PC and unzip the folder.
Create a directory on the compact flash (CF) card and copy all files in. Now you have to create the following empty sub directories:
“names”
“member”
“leave”
“join”

Once done you will see the following directory structure (show in the Datafreeway explorer):

[[Image:IC05.png]]

The remaining setup has to be done in the PBX.

First configure a BC Conference object. Leave all items to their default settings, except the one specified. Basically the BC Conference object doesn’t need a number because the access to it will be trough a XML script and names.

[[Image:IC03.png]]

Therefore it is important that the ''Name'' of the BC conference object is “innoconf”, the ''Description'' and ''Long name'' are not important.
The ''Display Name'' should be nice, because if the user is in the conference room, he will see this name on the display (while he is in the menu “outside” the conference room, he will see the display name of the XML, so even from a display point of view the user knows exactly “where he is”).

Please note the required setup in the third tab:

[[Image:bc-conference-config.png]]

Now assign in the main PBX menu a new group to the the BC conference object and flag the group as “active”. In the following example we call the group “CallBC”:

[[Image:IC06.png]]

Now you have to create two voicemail objects. No voicemail license is required for this.
Create the first one and name it as you like. No number is required since this XML is never shown anywhere.
Important: Set the codec option as shown in the following example to $_pbxcoder=g729.
In our example, we created a directory called “innoConf” on the CF card. The XML file name is “innoconfB.xml”:

[[Image:IC01.png]]

Now put the voicemail object executing the “innoconfB.xml” file in the same group than the BC conference object, but NOT as an active member.

Last step: create the second voicemail object. The number of that object is the “innovaphone conferencing” number and the ''Display Name'' of this object will be shown to the user calling the innovaphone conferencing. A good example is “conference access” or a similar name.
Important: Add the flag “$_pbxfwd=true” to the URL of the voicemail object. The name of the xml file is “innoconfA.xml” (in the example in the directory “innoConf”).

[[Image:IC02.png]]

===Static conference room name===
Some time or some customer has more or less always the same conference name and not interested in labeling (or “naming”) a conference room. If this is your case here is how avoid that in each new conference the name has to be record again. To activate that option you have to edit the file named innconfB.xml. To do that copy the file first from the CF to the PC, modify it, and then copy it back again (in other words: it is not a good idea edit directly on the CF). Open the file with the editor and you will see something like that:

[[Image:NoConfName.png]]

If you delete the indicated line the name of the conference room will not be cleared if the last user exit the conference unit and therefore if the conference is called again, the name of the conference is still there and the user will not here “please label your conference” but go directly to the main menu (where he can still doing that).

===Localization===
The innovaphone conferencing is delivered with professional prompts recorded by [[Howto:Voice_Prompts_-_GM_Voices%2C_Inc._-_3rd_Party_Product|the voice recording company GM Voices]].

The prompts are provided in 11 languages.

If your preferred language is not available, it is very simple to create prompts in other languages. You have just to translate the following prompts:

Filename (containing prompts in English)

Welcome ("innovaphone conferencing")

ConfName ("Please label your conference room")

RecStart ("Start recording with star and stop with any key")

To ("to")

UserWelcome ("welcome")

Conference ("conference room")

MyName ("Please record your name")

FirstUser ("You are the first conference member")

Join ("joined the conference")

Leave ("leaves the conference")

InTheConf ("in the conference room you will find")

MMenu ("press star to join the conference room, press one to record your name or press two to label the conference room")

noconf ("There is no conference channel available")

After recording, do the post processing (see relative wiki articles) and convert the file format to 8 kHz, 16 bit mono. Finally, convert the wav files to the .g729 and .g711A format (using the [[Howto:Convert_wave_files_to_G7xxx_with_softcod | softcod utility]] or by using the [[Howto:How_to_convert_wave_files_in_to_G7xx_coder_files_for_the_HTTP_interface#V6_SR1_note | conversion function of the CF card]]).
One hint: When the conference room is labelled, the engine will prompt “to” + “conference room” + the name.

===Multiple conference rooms===

Innovaphone conferencing is done to give the customer one enhanced conference room on one system. If a customer asks for parallel and independent innovaphone conferencing rooms on the same system, please follow this instructions.
First you have to configure as many BC conferences objects in the PBX, as separate conference rooms by the customer. Each BC conferences object has its own name and groups. Then create for each room a different directory on the compact flash card. Next create the required pairs of voicemail objects. You have to edit the “innoconfA.xml” file (use a simple text editor). We recommend editing the file on your PC and then copying it on the CF card. Finally, ou have to modify the name of the BC conference object:

[[Image:IC07.png]]

If for example you named the second BC conference object “mySecondOne” you have to modify the line from:
<pbx-fwd name=" innoconf " barge-in="false" out-cause="$cause"/>
to:
<pbx-fwd name=" mySecondOne " barge-in="false" out-cause="$cause"/>

===Known Problems===
* No support at the moment for unknown callers (without number - CLIR activated).
* If in the same time two user access the innovaphone conferencing system and the room is empty - both will hear “You are the first conference member”. However once in the conference, both names will be announced.
*There is a small delay between the real enter and exit of a user and the announcement (between 0-4 seconds). This is done to avoid too much load for CF card and CPU.
* On multiple conference rooms on the same system, for each room you have to record your name again.

*When you use our innovaphone Virtual Appliance (IPVA) as directory structure, and a member leave the conference room, the remaining members did not hear a warning tone followed by the name of who has left. Then you must change the following string in the innoconfA.xml.
from: <store-cookie root="leave" name="$CF" value=""/>
to: <store-cookie root="leave" name="$CF" value="x"/>

== Related Articles ==
[[Howto:Creating_fine_announcements_and_music_on_hold|Howto:Creating fine announcements and music on_hold]]

[[Howto:Installing_the_voicemail/music_on_hold_on_a_compact_flash_card|Installing the voicemail/music on hold on a compact flash card]]

== Download ==
*[http://download.innovaphone.com/ice/wiki-src#innoconf http://download.innovaphone.com/ice/wiki-src#innoconf] - download the complete file package of scripts and files described in this article.



[[Category:Sample|{{PAGENAME}}]]
[[Category:Howto]]

Howto:Bypass the setup wizard/install

2013-01-23T18:35:37Z

Msr: /* Resolution */

==Applies To==
This information applies to

* all innovaphone devices,

Firmware V6 SR2 and later.



==More Information==

===Problem Details===
From Version 6, Service Release 2 on, innovaphone devices will run a configuration wizard when accessed reset to factory settings. While this is a great to speed up deployment of innovaphone boxes, it may be required to bypass the wizard in certain situations.

===Resolution===
To bypass the wizard, access <code><nowiki>http://x.x.x.x/admin.htm</nowiki></code> (or <code><nowiki>http://x.x.x.x/administrator.htm</nowiki></code> for V7 and later) instead of <code><nowiki>http://x.x.x.x</nowiki></code> to access the standard configuration interface.

Nb: from version 9 firmware on, the URL to bypass the wizard is <code>http://x.x.x.x/admin.xml?xsl=admin.xsl</code>.

To get rid of the wizard permanently, you may remove the <code>/home SETUP/wizard.xml</code> parameter from the <code>config change HTTP0</code> line.



[[Category:Howto|{{PAGENAME}}]]

Howto:Bypass the setup wizard/install

2013-01-23T10:43:20Z

Msr: /* Resolution */

==Applies To==
This information applies to

* all innovaphone devices,

Firmware V6 SR2 and later.



==More Information==

===Problem Details===
From Version 6, Service Release 2 on, innovaphone devices will run a configuration wizard when accessed reset to factory settings. While this is a great to speed up deployment of innovaphone boxes, it may be required to bypass the wizard in certain situations.

===Resolution===
To bypass the wizard, access <code><nowiki>http://x.x.x.x/admin.htm</nowiki></code> (or <code><nowiki>http://x.x.x.x/administrator.htm</nowiki></code> for V7 and later) instead of <code><nowiki>http://x.x.x.x</nowiki></code> to access the standard configuration interface.

Nb: from version 9 firmware and version 10 firmware, the URL to bypass the wizard is <code>http://x.x.x.x/admin.xml?xsl=admin.xsl</code>.

To get rid of the wizard permanently, you may remove the <code>/home SETUP/wizard.xml</code> parameter from the <code>config change HTTP0</code> line.



[[Category:Howto|{{PAGENAME}}]]

Reference9:General/Admin

2012-09-19T07:55:02Z

Msr: /* User/Password */

Basic parameters for the Administration access of the device are configured here.

== Device Name ==

The name of the device. This name is displayed in the browser as a title. It is also added to the product id sent with outgoing registrations. This way it is displayed e.g. on the registrations page of the PBX.

== User/Password ==

The administrator account. This account can be used for telnet access (if configured) and all password protected pages of the web user interface. By default all pages except Administration/General/Info are password protected. The web server of the device can be configured to protect all pages. The password has to be entered twice.

The password cannot be left empty. If an empty password is entered, the password won't be changed.
The length of the password is limited to 15 characters.

== Additional Administrator Accounts ==

Additional user accounts. These user accounts can have viewer or full administrator privileges.

== Help URL ==

The URL to access the online help. By default an URL of <nowiki>"http://wiki.innovaphone.com/index.php?Title=Reference<magor firmware version number>:<page name>"</nowiki> is used. This links to online help pages in the Reference namespace of the innovaphone wiki.

For example on a V9 device configure following Help URL to link to the local wikitogo installation:

<code>http://192.168.0.100:8081/index.php?Title=Reference9:</code>

== Delegated Authentication ==
In v8 devices can delegate authentication of administrative users to an authentication server using Kerberos. To enable remote user authentication the device has to join the realm of an innovaphone Kerberos server. Delegated authentication can only be used with HTTPS.

=== Join realm ===

The server location of the realm has to be configured, first (see section "Authentication Servers").

Click "Join realm" and specify the username and password of an administrator in the target realm to add the device to the remote host database. This works only with innovaphone servers. If you want to authenticate users from a third-party server setup cross-realm authentication.

=== Leave realm ===

An administrator username and password from the realm is needed to deregister from the realm and remove the device from the remote host database. If the server does not exist any longer the registration can be deleted manually.

=== Disable local authentication ===

If this option is selected only users from the Kerberos server are accepted. Logins using local administrator accounts will be rejected. Activating this feature together with [[Reference9:Phone/Protect|"Protect configuration at phone"]] option will disable you to make any changes on the phone.

== Authentication Servers ==

The addresses of Kerberos servers have to be configured locally on each host or client device.

If there is no server configured for a realm, the device will try to locate it using DNS. Normally this should work for Windows servers in the LAN.

File:Routesgetlost7.png

2012-05-30T14:44:30Z

Msr:

File:Routesgetlost6.png

2012-05-30T14:18:22Z

Msr:

File:Routesgetlost5.png

2012-05-30T14:17:50Z

Msr: