innovaphone wiki - User contributions [en]

Reference13r3:Concept App Service Recordings

2023-03-09T14:42:49Z

Eurix:

[[Category:Concept|Apps]]

== Description ==
Recordings is an application running on the App platform which allows capturing the audio streams during a telephone call.
The user's phone can be configured to send bidirectional audio streams to the Recordings App and store them into the database.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform build 110016 or up
* Firmware 13r3 or up
* Recordings App
* Recordings App licenses (per User)
* Device with PCAP Recording Interface:
** innovaphone deskphones
** innovaphone SoftphoneApp
** innovaphone gateway interfaces
* Reporting App

== Apps ==

=== Recordings App (innovaphone-recordings) ===
[[Image: Usrrecord.png]]

User version of the App allow you to:
* Access to the user specific records
* Access to the user specific logs
* Filter records by name, by date
* Play, Listen or Download the recording as a .WAV file
* Protect against deleting or delete a recording

=== Recordings Admin App (innovaphone-recordingsadmin) ===
[[Image:Adminrecord.png]]

Admin version of the app allow you to:
* Access to all records
* Access to all logs
* Set up the records auto deletion retention time in days
* Set the PBX name
* Set specific trace levels
* Filter records by name, by date
* Play, Listen or Download the recording as a .wav file
* Protect against deleting or delete a recording

== PBX Manager Plugin ==

With the Recordings PBX Manager Plugin, an App Object can be created, edited and deleted on the PBX.

== Configuration ==
* Download the Recordings App via App Store.
* Install the App on the App Platform Manager.
* Create an instance for the Recordings App on the App Platform Manager.
* Create a new PBX recordings APP-Object with the PBX Manager Plugin.
* Create a new PBX recordingsadmin APP-Object with the PBX Manager Plugin.
* Assign recordingsadmin App to authorized (admin) users, which will be allowed to open the Admin UI of the Recordings App.
* Assign recordings App to users who will use the Recordings App.
* Start recordingsadmin App and configure the name of the PBX in the settings via upright option
* assign Record to (URL) to recording devices/objects in format
: <code>http://</code>''ap.domain.tld''<code>/</code>''domain.tld''<code>/</code>''recordings-instance-name''<code>/</code>Files
:on deskphones, softphones or gateway interfaces.
:On innovaphone deskphones, enable recording via Phone/User-X/Recording by setting ''Mode'' to <code>transparent</code> and ''Recorder'' to <code>HTTP Server</code>.
:On innovaphone softphones, recordings config is only visible, if the user has the appropriate app(innovaphone-recorder) license.

=== Access List ===
Unlike Recordings Admin App, which lists recordings of all users, Recordings App for users limits the listing of recordings to those made by the using user himself.

A possibility to extend the listing of the recordings to other extensions/users is provided by the Access List. In the Access List, additional extension can be defined, which will be listed to the Users of the App. This way the Recordings App Service can be accessed via different App Objects, with different Access Lists.

This way scenarios, like sharing recordings between team members or supervisor access to recordings of call agents are possible. 
For the configuration, see : [[HowTo_Recordings_V13r3#Access_list_configuration_through_the_Recordings_Plugin]]

=== Deletion of recordings ===
In the PBX Manager plugin, it can be configured how a deletion of a recording is processed. There are 2 modes selectable: "Recoverable" and "Permanent". If "Recoverable" is selected, the users attached to this app object
will transfer a recording to the recycle bin upon a delete operation, otherwise the recordings will be permanently deleted.

=== Scheduled deletion of old recordings ===
You can configure a time period between ''1 and 11000 days'' (in maximum round about 30 years), after which recordings are automatically removed. You can enter ''0 days'' here to disable the scheduled deletion.

== Call Information ==
A new method of acquiring the call information is implemented. It requires an installed and running App Service "Reports". "Reports" does not
need own licenses to be run with recordings. With this new method, it is possible to provide detailed call flow information for each recording.
Furthermore, the previously used CDR slot on the PBX for recordings is not needed anymore.

== Licensing ==

An appropriate license ''App(innovaphone-recorder)'' must be installed on the PBX to enable Recordings App functionality for specified users.
The recordings config on the softphone is only available for users with a valid license.

The Recorder App License can be assigned directly to a specific User Object or via a Config Template.

The recordings for users without an assigned Recorder App License will be unrecoverable deleted if the Recordings App is restarted.

== Recording on Special Interfaces ==

* Trunk Interface/Gateway

The Trunk Interface acts as a substitute for the user's phone. For outgoing calls the call initiator is the owner of the recording and for him a license is required. With incoming calls, the first user answering the call owns the recording and a license for this user is required.

* Waiting Queue

The user answering the call is the owner, a license for this user is required.

== Upgrade from V13r2 to V13r3 Recordings App ==

=== Compatibility ===

A V13r3 Recordings App can not be used in an 13r2 PBX environment and requires at least build 110016 of the application platform.

=== License Changes ===

Licensing is the same as version 13r2

=== Database Conversion ===

Databases from previous versions (13r1,13r2) will be converted automatically

=== Removing CDR slot on PBX ===

The CDR slot that was used by previous installations of recordings can be freed.

=== Update App Object configuration ===

If upgrading from a previous version, the app objects configuration of Recordings and Reports must be manually updated via the PBX Manager. Recordings now gets its CDR info directly from reporting, we need to select the good reporting instance, set the flag ''"Services"'' on the app object recordings with the AP recordings. Furthermore we also need to set the flag ''"Websocket"'' at the app object reports with the AP reporting.

Open the PBX manager to edit AP recordings :
* Click your respective AP recordings (coloured icon) to open it, this will open on the right side its menu.
** Click on recordings (type User), and verify that the respective reporting instance is selected and '''click OK''' to apply settings. ''Hint: reporting instance will be listed in a drop-down list.''

And then to edit AP reporting :
* Click your respective AP reporting(coloured icon) to open it, this will open on the right side its menu.
** Click on Reports and just simply '''click OK''' to apply settings.
To verify you can open in your PBX the app object Reports to see if ''"Websocket"'' is set. Same for the app object Recordings with ''"Websocket"'', ''"Admin"'', ''"Services"''.

=== Download recording ===

Once a recording is converted to .wav format, it can be downloaded. In version 13r3, this is done in a zip archive containing the wave audio file and a .pdf file containing
the call information.

== Troubleshooting ==

=== Recordings App Service ===
The App Service for Recordings App provides a log output on the App instance, after the Diagnostics option "App" is activated for the selected instance.

Additional Trace Level Options for the App Service are configurable via Recordings Admin App. These settings are available via an additional Menu in the upper right corner of the Recordings Admin UI:

*Recording - PCAP interface related traces, useful on issues with IP-Phone and Interface Media transmission from Endpoint to the App Service
*Call Information - traces related to the CDR information
*Converting - traces for conversion process from VoIP codecs to WAV
*License - traces for on licensing issues
*UI - traces related to the user interface of the Recordings App

The name of the Master PBX must be configured via the Recordings Admin App, otherwise a message ''PBX Name missing'' will be displayed.

=== PBX Configuration ===
*WebSocket connection from App Object to the Recordings App should show ''connected''
*A correct configuration of the CDR interface is required for transmission of metadata to the App Service "Reports". In case the connection between recordings and App Service "Reports" is not successful, a red "broken link" is shown on top of the recordingsadmin and an entry in the event log will be added.

=== PCAP Recording Interfaces ===
*Check URL for PCAP Recording provided on the IP-Phone or VoIP-Interface of a VoIP Gateway
*A Trace with enabled HTTP-Client option should show a successful HTTP PUT Request towards URL of the Recordings Service PCAP interface (e.g. <code>HTTPCLIENT WEBDAV_FILE_HTTP.2: PUT http://ap.company.com/company.com/recordings/Files/f9e5956e47d460010630009033302ab1-009033302ab1-11--username.pcap</code>)

== Known Problems ==
=== Test Mode ===
The App Licenses are not supported in the [[Reference12r1:General/License|Test Mode]] at the moment, instead a [https://wiki.innovaphone.com/index.php?title=Reference:My_Innovaphone#Download_test_licenses Test License] should be used.

== Related Articles ==
[[HowTo_Recordings_V13r3]]

Reference13r3:Concept App Service Recordings

2023-03-09T14:42:03Z

Eurix:

[[Category:Concept|Apps]]

== Description ==
Recordings is an application running on the App platform which allows capturing the audio streams during a telephone call.
The user's phone can be configured to send bidirectional audio streams to the Recordings App and store them into the database.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform build 110016 or up
* Firmware 13r3 or up
* Recordings App
* Recordings App licenses (per User)
* Device with PCAP Recording Interface:
** innovaphone deskphones
** innovaphone SoftphoneApp
** innovaphone gateway interfaces
* Reporting App

== Apps ==

=== Recordings App (innovaphone-recordings) ===
[[Image: Usrrecord.png]]

User version of the App allow you to:
* Access to the user specific records
* Access to the user specific logs
* Filter records by name, by date
* Play, Listen or Download the recording as a .WAV file
* Protect against deleting or delete a recording

=== Recordings Admin App (innovaphone-recordingsadmin) ===
[[Image:Adminrecord.png]]

Admin version of the app allow you to:
* Access to all records
* Access to all logs
* Set up the records auto deletion retention time in days
* Set the PBX name
* Set specific trace levels
* Filter records by name, by date
* Play, Listen or Download the recording as a .wav file
* Protect against deleting or delete a recording

== PBX Manager Plugin ==

With the Recordings PBX Manager Plugin, an App Object can be created, edited and deleted on the PBX.

== Configuration ==
* Download the Recordings App via App Store.
* Install the App on the App Platform Manager.
* Create an instance for the Recordings App on the App Platform Manager.
* Create a new PBX recordings APP-Object with the PBX Manager Plugin.
* Create a new PBX recordingsadmin APP-Object with the PBX Manager Plugin.
* Assign recordingsadmin App to authorized (admin) users, which will be allowed to open the Admin UI of the Recordings App.
* Assign recordings App to users who will use the Recordings App.
* Start recordingsadmin App and configure the name of the PBX in the settings via upright option
* assign Record to (URL) to recording devices/objects in format
: <code>http://</code>''ap.domain.tld''<code>/</code>''domain.tld''<code>/</code>''recordings-instance-name''<code>/Files</code>
:on deskphones, softphones or gateway interfaces.
:On innovaphone deskphones, enable recording via Phone/User-X/Recording by setting ''Mode'' to <code>transparent</code> and ''Recorder'' to <code>HTTP Server</code>.
:On innovaphone softphones, recordings config is only visible, if the user has the appropriate app(innovaphone-recorder) license.

=== Access List ===
Unlike Recordings Admin App, which lists recordings of all users, Recordings App for users limits the listing of recordings to those made by the using user himself.

A possibility to extend the listing of the recordings to other extensions/users is provided by the Access List. In the Access List, additional extension can be defined, which will be listed to the Users of the App. This way the Recordings App Service can be accessed via different App Objects, with different Access Lists.

This way scenarios, like sharing recordings between team members or supervisor access to recordings of call agents are possible. 
For the configuration, see : [[HowTo_Recordings_V13r3#Access_list_configuration_through_the_Recordings_Plugin]]

=== Deletion of recordings ===
In the PBX Manager plugin, it can be configured how a deletion of a recording is processed. There are 2 modes selectable: "Recoverable" and "Permanent". If "Recoverable" is selected, the users attached to this app object
will transfer a recording to the recycle bin upon a delete operation, otherwise the recordings will be permanently deleted.

=== Scheduled deletion of old recordings ===
You can configure a time period between ''1 and 11000 days'' (in maximum round about 30 years), after which recordings are automatically removed. You can enter ''0 days'' here to disable the scheduled deletion.

== Call Information ==
A new method of acquiring the call information is implemented. It requires an installed and running App Service "Reports". "Reports" does not
need own licenses to be run with recordings. With this new method, it is possible to provide detailed call flow information for each recording.
Furthermore, the previously used CDR slot on the PBX for recordings is not needed anymore.

== Licensing ==

An appropriate license ''App(innovaphone-recorder)'' must be installed on the PBX to enable Recordings App functionality for specified users.
The recordings config on the softphone is only available for users with a valid license.

The Recorder App License can be assigned directly to a specific User Object or via a Config Template.

The recordings for users without an assigned Recorder App License will be unrecoverable deleted if the Recordings App is restarted.

== Recording on Special Interfaces ==

* Trunk Interface/Gateway

The Trunk Interface acts as a substitute for the user's phone. For outgoing calls the call initiator is the owner of the recording and for him a license is required. With incoming calls, the first user answering the call owns the recording and a license for this user is required.

* Waiting Queue

The user answering the call is the owner, a license for this user is required.

== Upgrade from V13r2 to V13r3 Recordings App ==

=== Compatibility ===

A V13r3 Recordings App can not be used in an 13r2 PBX environment and requires at least build 110016 of the application platform.

=== License Changes ===

Licensing is the same as version 13r2

=== Database Conversion ===

Databases from previous versions (13r1,13r2) will be converted automatically

=== Removing CDR slot on PBX ===

The CDR slot that was used by previous installations of recordings can be freed.

=== Update App Object configuration ===

If upgrading from a previous version, the app objects configuration of Recordings and Reports must be manually updated via the PBX Manager. Recordings now gets its CDR info directly from reporting, we need to select the good reporting instance, set the flag ''"Services"'' on the app object recordings with the AP recordings. Furthermore we also need to set the flag ''"Websocket"'' at the app object reports with the AP reporting.

Open the PBX manager to edit AP recordings :
* Click your respective AP recordings (coloured icon) to open it, this will open on the right side its menu.
** Click on recordings (type User), and verify that the respective reporting instance is selected and '''click OK''' to apply settings. ''Hint: reporting instance will be listed in a drop-down list.''

And then to edit AP reporting :
* Click your respective AP reporting(coloured icon) to open it, this will open on the right side its menu.
** Click on Reports and just simply '''click OK''' to apply settings.
To verify you can open in your PBX the app object Reports to see if ''"Websocket"'' is set. Same for the app object Recordings with ''"Websocket"'', ''"Admin"'', ''"Services"''.

=== Download recording ===

Once a recording is converted to .wav format, it can be downloaded. In version 13r3, this is done in a zip archive containing the wave audio file and a .pdf file containing
the call information.

== Troubleshooting ==

=== Recordings App Service ===
The App Service for Recordings App provides a log output on the App instance, after the Diagnostics option "App" is activated for the selected instance.

Additional Trace Level Options for the App Service are configurable via Recordings Admin App. These settings are available via an additional Menu in the upper right corner of the Recordings Admin UI:

*Recording - PCAP interface related traces, useful on issues with IP-Phone and Interface Media transmission from Endpoint to the App Service
*Call Information - traces related to the CDR information
*Converting - traces for conversion process from VoIP codecs to WAV
*License - traces for on licensing issues
*UI - traces related to the user interface of the Recordings App

The name of the Master PBX must be configured via the Recordings Admin App, otherwise a message ''PBX Name missing'' will be displayed.

=== PBX Configuration ===
*WebSocket connection from App Object to the Recordings App should show ''connected''
*A correct configuration of the CDR interface is required for transmission of metadata to the App Service "Reports". In case the connection between recordings and App Service "Reports" is not successful, a red "broken link" is shown on top of the recordingsadmin and an entry in the event log will be added.

=== PCAP Recording Interfaces ===
*Check URL for PCAP Recording provided on the IP-Phone or VoIP-Interface of a VoIP Gateway
*A Trace with enabled HTTP-Client option should show a successful HTTP PUT Request towards URL of the Recordings Service PCAP interface (e.g. <code>HTTPCLIENT WEBDAV_FILE_HTTP.2: PUT http://ap.company.com/company.com/recordings/Files/f9e5956e47d460010630009033302ab1-009033302ab1-11--username.pcap</code>)

== Known Problems ==
=== Test Mode ===
The App Licenses are not supported in the [[Reference12r1:General/License|Test Mode]] at the moment, instead a [https://wiki.innovaphone.com/index.php?title=Reference:My_Innovaphone#Download_test_licenses Test License] should be used.

== Related Articles ==
[[HowTo_Recordings_V13r3]]

Reference13r3:Concept App Platform

2022-05-30T13:42:09Z

Eurix: /* RPCAP */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or up
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How_to_implement_large_PBXs#Technical_data_and_recommended_number_of_users_supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App_services_and_multi-threading|App services and multi-threading]] below).

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!

* Multiple CPUs are supported, default is one CPU

* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)

* partitions:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: your_domain_name.key)
-----END RSA PRIVATE KEY-----

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How_to_retrieve_files_from_the_AP | Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/11/auth-pg-hba-conf.html

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13_Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= App Platform replication =

== Requirements ==

* 13r3 on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can sepcify a non default port which must be then forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.

= Known Issues =

== Reboot after an image update hangs (ARM gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
Try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line: '''root=/dev/sda3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

== Reboot after an image update doesn't start as update is already running ==

If it happens, that the App Platform doesn't want to start an update because one is already running, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it. 
* Set '''Kernel command line''' to '''/dev/ram0'''. 
* Set '''Initrd file''' to '''ramdisk.ext2.xz'''. 
* Set '''Ramdisk size''' to '''100000'''. 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 

Please don't forget to disable RPCAP after your testing!

String für Wireshark Remote-Interface: "IP-ADRESS-APPS-Platform\trace"

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and CDRs (or other data written to a DB) won't be received during this time.

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

== How to recover from a broken File System ==
Sometimes you may find messages in the ''messages'' log file (in ''var/log'') like

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

When the Linux file system is broken, you can try to repair it using some command line Linux tools.

If this doesn't fix your issue, you need to replace the SSD with a new one, re-install the App Platform and any applications and restore your backups.

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line (user: root, pw: iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code>
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

Reference10:Concept Voice Recording 2014

2021-12-06T14:34:57Z

Eurix:

== Introduction ==

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 records are stored in a first step on the Compact flash or WebDAV server and processed then form the recorder tool.

Voice recording can be done on a logical or fiscal gateway (BRI, GW, SIP etc.), and therefore all kind of audio traffic can be recorded. Technically spoken a gateway is doing media relay and writes the audio data to the WebDAV or CF.

The second way to record is recording directly from the Innovaphone IP-Phone. In this case the phone itself writes the audio data to the CF or WebDAV server.

See the “Scenarios” for further details.

The solution requires an Innovaphone PBX, the reporting tool 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.

IMPORTANT: All users that should be recorded need the REPORTING! We recommend reporting for all user, see chapter “Requirements” for further details.

== Requirements ==
As webdav server just the innovaphone webdav server (on a GW, IPVA or innovaphone LinuxAP) is supported.

The recorder use HTTP and HTTPS access and not a webdav protocol to access.

The Recorder must be physically and logically “nearby” the main PBX. “nearby” means in the same location (not remote), in the same network and also on a physical machine.

Our solutions are tested on single physical machines and we are not able to support the huge amount of virtualisation software (and there edition and version).

We recommend to user normal Windows software, so not a “server” edition.

Disable "Power Saving Mode" on the windows machine that runs the recorder application, so the SOAP connection it's not interrupt.

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, but not recommended.
Please note that a working Webdav is mandatory, otherwise records will be lost! If recording is critical please define a second logical GW with recording and record on an independent webdav too as backup (you have to clear that drive manually to avoid disk full). Do never use the Flash memory ad webdav.

===PBX===
You require a PBX version 11 or 12.

For Version 13 see [[Reference10:Concept_Voice_Recording_2014#Known_Problems|section known problems]] !

===Reporting===

The recording feature requires the linux-platform-based innovaphone Reporting. Please update your platform to the latest Hotfix. Minimum Build 10043 is required.

'''Note:''' VoiceRecording (2014) will [[Reference10:Concept_Voice_Recording_2014#Version_13|not work with the new V13-reporting]].

Each user for whom calls are physically recorded (by creating a pcap file for the call using the ''Record to (URL)'' feature) must have reporting enabled and hence requires a reporting license. Although the recorder will discard all physically recorded calls if the user involved has no recording license, it still needs the CDR information for the call (without this information, the recorder can not determine the user the recorded file belongs to). If the recorder needs to process files for which no CDR is available, it will malfunction.

So generally, we recommend that all users in the PBX should have the reporting on as this is the simplest solution. However, if this is not feasible, then all users for whom recording pcap files are created must have reporting. Please note that if you configure the pcap creation on the trunk gateway all users that possibly could do calls through this trunk (which practically means: all users) must have recording. To limit the number of recording licenses you need to configure pcap creation on the endpoints (i.e. phones) rather.

=== Recorder ===

This document describes Build 1134.

Application package can be retrieved from our [http://download.innovaphone.com/ice/10.00/#recording download page].

The recorder and Player application was tested on Windows 10, win 7 or higher should also be fine, framework 4.5 is required (no Windows XP).

Disk space: One minute of conversation requires about 1 MB of memory if stored in Wave or Pcap Format.
The wave voice data is not pure PCM, but a G.711 format in a wave container. PCM requires about 2 times much more disk space and is not used for storing. The audio files can also be encrypted. Encryption would double the required disk space.

The recorded conversation is a stereo file where the external caller is on the left channel whiles the internal one in the right channel.

It is possible to down mix the conversation to mono; this would save about 50%.

It is also possible to compress the audio data to mp3.

The following table shows the required disk space for one minute of conversation:

[[Image:RecSetup07.png]]

Example: 500 GB Hard disk, mp3 compression without encryption -> 1.389 days = 3,8 years of conversation

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 11 innovaphone PBX and a actual Build of the 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/mSATA/WebDAV not real high (but remember always 1 Minute =1 MB, so if you must record 30 conversations for 30 minutes = 900MB).

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.

=== Codecs ===
Recording can only be done using G.711, G.729 or G.722 (Build 1134) codec.

Note: if you update an older recorder version to build 1134 delete first the file pcap2wav.exe in the directory where the recorder run and/or in the log path of the recorder.

=== 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 4.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).

In theory it should work on any CPU, the Player was tested under Win7 32BIT, Win7 64Bit and Win8 64Bit and Win10.

===License===

The license model is based on user, so for each user to record a license is required.

The current implementation allows a recording of objects of type user or executive. Recordings on other objects will be discarded.

So in short: Per recorded user or executive object you need to have
* one recording license
* one reporting license

In start-up the recorder will read out the number of recording license in the PBX. After that the recorder will read out all users and check if a user is in the recording group (defined in the recorder setup). If a user with that group is found one license is counted down. If there are no more license but user in group detected they will be skipped. The recorder shows how many license where detected in the PBX and how many user are in the recording group. If there are more users than licenses a warning is show.

Remember that just users in the recorder user table are recorded; all other records are automatic deleted! This can be usefully if for example for internal reasons not just the user to record passes through the recording gateway but also others; not being in the group the records will be destroyed. But of course this will cause senseless PBX CPU workload because a recording anyway is done, just the recorder will delete after the files.

=== 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!

== 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 and 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)

• Mark record during a conversation on the IP-Phone (build 1077)

• Https from Build 10087 on

• Slave sites from Build 10089 on

• G722 Codec from Build 1134 on

• PCAP recording from Build 1134 on

• Work as a service from Build 1134 on

• Work as http player server and/or PCAP to Wave/MP3 converter from Build 1134 on

• Work as a service from Build 1135 on

=== 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 channel 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 channel

• 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 channels 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

• Browse last played records (build 1071)

• Browse marked records on this player (build 1071)

• Browse marked records in a system wide available directory (build 1071)

• Mark records on player and for system wide access (build 1071)

• Copy records marked in a player to the system wide available directory (build 1071)

• Write a central log for all player listening’s (build 1071)

• Work over http connections (build 1074)

• Limit view to a list of extensions (build 1077)

• Play PCAP files (build 1134)

• Double password for unlocking (build 1134)

== Scenarios ==

If 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 on a central point ===

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 recording 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/G729/G722 on a logical gateway as endpoint. If you want record internal calls in this way calls must always transit a logical gateway (with the media relay flag on).

=== Recording with the IP-Phone ===

Recording can be done also directly from the innovaphone IP-Phone.
If switched on all calls from and to this phone are recorded, there are no recording rules. Calls could be stored in different files, because a new call means also a new file. If for example a phone put on hold a conversations and establish a second call this second call will be stored a an separate file.

Doing voice recording using the IP-Phone or using a Gateway has advantages and disadvantages; it depends on your point of view and the scenario.

Here some issues to remember:

Recording on a gateway is like the old “ISDN Recording”: anything passing that interface is recorded. That has the advantage that any type of endpoint (IP, 3rt party, Dect, analog etc.) will be recorded. The disadvantage is that internal calls are not recorded. Also the CPU load of the PBX will rise while recording with an IP-Phone has nearly no influence.

Recording directly from the Phone has the limitation that just innovaphone IP-Phone are able to doing that. Only innovaphone IP-Phones IP2x2, IP11x, IP241 and IP240A with bigger DRAM (http://wiki.innovaphone.com/index.php?title=Howto:Upgrade_IPxxxA_to_support_more_DRAM_Memory) can performing Voice Recording directly.
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).

In the V11r1 IP recording on the phone can just switched on or off in the setup, not from the user. In V11r2 recording can switched on and off by the user (similar to the 3party version).

'''Note''': The recording described here does not require a phone 3 party conference; therefore a 3party conference is possible on the phone while Voice Recording 2014 is running.

== Recording Modes ==
=== Standard Recording ===

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

Note: A recorder canoperate just in one mode (for example "Standard"). Mixed scenario are possible but require two or more recorders, the setup in this case has to be done very carefully.

=== 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 sub-directory TCR in your PCAP recording directory and copy the xml in, create a VM-Object in the PBX and insert those parameters in the recorder setup (TCR panel). Example: Your PCAp directory is http://172.16.88.98/DRIVE/CF0/REC, therefore the directory create is is http://172.16.88.98/DRIVE/CF0/REC/TCR. 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.

Please note that the directory where the PCAP files are stored can be „the same“ than the one using „normal“ recording. The TCR XML is just a subdirectory of the PCAP recording directory!

===Delete Records===
Build 1188

A user can skip (not store) some conversations. This is done using a similar mechanism used with the TCR. If at the end of the conversation a file is found this record will be deleted. Therefore it works only if this file is created during the conversation. This can be done calling the XML TCRec.xml (with a feature key, the recording feature of a innvaphone IP Phone, putting the actual call on hold and call the xml or using an external application). The file has to be created in the recording directory/TMP.

File format: TCA-XXX_XXX.txt where xxx= the agent number.

Example: TCA-1234_1234.txt -> the record of the actual conversation of the agent 1234 will not be recorded.

The field itself could be empty, but observe that with Linux at least one character should be in.

Please note also that the time of the reporting, PBX and webdav must be the same. The Feature works also with the (old) CF.
If a record is skipped because of theis feature he log will show the message “User Mark Record to delete found TCF=” and the Agent number.

=== Random recording ===
The recorder can work in this mode also as an alternative to the Standard- or Threat call recording. Random recording will record just a sample of calls on normal Agents (User), typically for quality check purposes.

The system allows record just each x call where x can be set in the setup. The system can even record just each y call for an agent. Only “to recording” calls are counted, not calls in general.

Example: “Record in System just each 3. Call”’: the system will store one record and then skip the following 2 one.

Example: “Record for a Gent just each 2. Call”: for each agent one call will be recorded and one not.

Both setups can be set isolated, but combined (3rd in system and 2nd for a agent) the system will first skip 2 calls and then for the specific agent skip each 2nd one.

Calls typically are not foreseeable especially if they are more agent involved and therefore it is for a single agent a “random” recording.

This feature requires build 1071 or higher.

=== PCAP Recording (1134) ===
If switched on the recorder keeps the native PCAP file format. While encryption is possible also in this recording mode no down mix to mono or single cannel recording (just the internal caller) id possible, of cause MP3 can also not be switched on in this recording mode.

Please note that this mode is mandatory if the recorder works as a service. A second recorder working in foreground can convert PCAP to wave or MP3 and also process the additional audio down mix. See relative articles.

=== Manual/Transparent/Optional recording ===

V11r2 (in the Phone) is required.

If the recording is done using a innovaphone IP Phone there are 3 recording modes possible:

- Manual: the user switch recording on/off using a Feature key

- Transparent: recording is always on

- Optional: recording is on by default but the user can switch it off using a feature key

The manual and optional mode is widely used because the operator can switch on and off recording during a conversation. For example if the customer want to buy the operator starts recording and give the advice that from now on the recording is on (by the way: that can be played also automatically modifying the [[Howto:Last_Call_Recording|last call recording]]). Switching off recording is usefully also if for example during a conversation a secret info (like a password) is stated and should not be recorded ad all.

The Recording link (url) to the Webdav or CF is defined in the user setup:

[[Image:RecSetup08.png]]

The mode is selected in the "recording" section:

[[Image:RecSetup09.png]]

Note: The recording described here does NOT require a phone 3 party conference; therefore a 3party conference is possible on the phone while recording is running.

===Manual recording with announcement===
(build 1198)

If a customer want to start and stop a recording this can be done using a innovaphone IP-Phone as described in the previous chapter.

This chapter described how to solve if on top there is also the requirement to play automatically an announcement at the beginning of the recording (typically something like “We advise you that this conversation will be recorded…”).

The problem is that audio can be reproduced only if you set “Dialup Recorder” in the phone, but doing this there is no PCAP and therefore CDR information. If you select “HTTP” then there is PCAP information/CDR information but no audio.

The workaround is that you select “Dialup Recorder” but as destination do not put in a XML or WQ but a trunk and then the XML or WQ. The result will be a call to the (recording) trunk and then to the XML/WQ.

Set up the Recording to Dialup Recorder in your phone

[[Image:DialUpRecorder.png]]

Example: You have a XML or WQ playing first the required announcement and then silence, this object has the number “76”.

[[Image:RecordingSilence.png]]

Example for the second announcement: http://172.16.115.20/webdav/announcement/silence.$coder?coder=g711a,g711u,g729&repeat=true
You can download the silence announcement in our voicemail folder.

Set up a trunk object

[[Image:Mrec01.png]]

In our example with the number "57" with the option “automatic hangup” selected pointing to a GW,

[[Image:Mrec02.png]]

in this GW the PCAP recording is done.

[[Image:Mrec03.png]]

be sure to choose Media Relay On:

[[Image:MR1.png]]

and create a Route:

[[Image:Route.png]]

Set in the setup of the Recorder, tab “General” both numbers

[[Image:Mrec04.png]]

and switch on “Convert to mono”.

Limitations: it is convenient (but not a must) to convert the call to mono and save some disk space because in this operational mode the announcement is on the left channel and both party on the right one.

Please note that also the call direction (in or out) is always flagged “out” even on incoming calls.

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

== Last Call Recording/Repeat ==

See relative article.

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

== Working as a Fileserver for the Player ==

In this operational mode the recorder will not record any file or communicate with the PBX or the reporting but just act a http Fileserver for the innovaphone Player. The application can run in this mode on the same PC than the one of the recording, in huge scenarios for better workload share it is better to separate the two applications. For more information see the article “Player over http”.

== Working as a PCAP converter ==

The recorder can also keep the original pcap file format; this is mandatory if the recorder work as a service. The player is able to reproduce even files in PCAP file format.

If a recorder works in PCAP recording mode no audio down mix to mono or single audio cannel is possible. Please note that encryption of PCAP can be done in the recorder.

If the customer wants down mix features and/or wave or mp3 files a recorder can be started in converter foreground mode doing this.

Similar to the Fileserver mode the recorder will not perform any recording task or communicate with PBX or reporting. Please note that the same application can work as a PCAP recorder and fileserver at the same time, the application has not to be started twice; in large scenarios for a better workload sharing anyway it is possible to start the two modes even on different PC´s.

In this working mode the recorder scan periodically all sub directory of the storing directory and if a PCAP file is detected it will be converted to Wave or mp3 and the down mix options will be observed.

If the original PCAP file is encrypted also the resulting wave or mp3 file will be encrypted. If the original PCAP file is not encrypted encryption is only done if the relative flag in the setup of the converter is switched on.

The idea of the converter mode is that the application is always on; the recording service provide the PCAP files and performs all the other tasks like the communication with the PBX, the file copy from the CF/mSATA/Webdav, renaming, encryption, TCR etc. while the converter in a second step convert. Anyway it is also possible start the converter in a second moment; of cause if there are many files to convert it will require some time until all PCAP files are converted. Therefore a typical situation is that the converter runs always, but if this operation fails (or example after a restart of the PC where only the service will start automatically or a logout of the user) the missing work can be done in a second moment or form another PC.

For the operation of the recorder as a service see relative article.

== Command line arguments ==
The recorder application “innovaphone_Recorder.exe” can be started with command parameters.

This option is only required if the application is started as a service (se relative article).

The order of the parameter has neither influence nor eventual characters between.

The Setup parameters itself are not case sensitive, but the value (the path itself) is case sensitive.

recpath=c:\abc is equal to RECPATH=c:\abc but not equal to <> RECPATH=c:\AbC

Example for fine imputs:

innovaphone_recorder.exe recpath=c:\myiqmdir\ setup

innovaphone_recorder.exe /recpath=c:\myiqmdir\/setup

innovaphone_recorder.exe recpath=c:\myiqmdir\ -setup

The parameter “Setup” forces the application to open just the setup. No timer or interfaces are started. An exit of the setup will terminate the program.

The parameter “recpath” defines where the setup is stored.

The parameter can be inserted in the cmd box (DOS like) or using a batch file. Please note that the cmd should be executed as administrator (windows 8: press the windows key, enter cmd and select pressing the right mouse key “execute as administrator”).

A batch file can be created easy, open the editor and enter the command string, for example

innovaphone_recording.exe setup

Now save the file as a batch file, for example RecordingSetup.bat in the directory where the Recorder is. If you click the file the application will start just showing the setup.

Note also here that it could be necessary to start the batch file with the administrator rights. Of cause you can make a shortcut for example to the Desktop.

If you start the recorder as a service it is also usefully being able to stop the service and start the recorder in foreground using the same setup, therefore just running in foreground, mainly for trouble shooting and maintenance reasons.

Also in this case you can start the recorder in a command line indicating the setup path or create a bat file.

If you have to start more recorder on one single PC (for example a recorder and a recorder as a fileserver) it will be also necessary indicate individual setup path using a command parameters.

Also the batch files should be started with administrator rights. To start an batch file with admin rights a little trick must be applied. After writing your .bat file, create a shortcut and put it for example on your desktop. Now press the right mouse, select property and select “Advanced Properties”.

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

== Installation Step 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 course, 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. Your 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/System_Setup#Gateway_Setup . If you want to do a test with internal phones you have to assure that in call 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 course 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. 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 required 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.

For installation as a service see relative article.

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

=== Date ===

As most application also the recorder requires a correct date and time. But also the PBX Date and time must be correct and the same as the one on the recording PC.

Basically obviously, writing a file all file data should be correct, and also the CDR ticket data should.

So verify that both, PBX and PC have always a correct and synchronized date and time.

== Voice Recorder operation ==

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

[[Image:RecE112B2.png]]

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

For operation as a service see relative article.

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

*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.

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]]

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

Basically calls that should not be recorded should not be recorded even on the CF, this is desirable, but not always feasible.

In normal operations the recorder is connected to the PBX with a SOAP link and can so detect when a call is finished and the party involved. If there is a PCAP file and a SOAP connection fine, because in the very first step anything is clear and the recorder can decide to save or to just delete the PCAP file. But there is also the possibility that the recorder starts up later and “found” PCAP files stored in the meantime. In this case there could be or even not any SOAP information, if the call terminated before the recorder starts there will no SOAP info. Therefore if PCAP files are detected without any SOAP indication the recorder ask the reporting if there is any record to that PCAP. If yes the processing will follow the normal way, stored or just deleted. But if the reporting has no data there are more possible reasons. CDR data or the reporting could be “late”, so maybe in a few seconds data are in and processed. Or the reporting was just temperately busy or offline, a good idea is wait and try later again. Exactly that the recorder is doing, from build 1070 on the number of trial can be set in a range from 5 to 9999, default value is 5. On earlier build this value was set fix to 1444. Arrived to zero the call is deleted. Deleting recorded calls not knowing about the party involved is critical and therefore the recorder is so carefully.

The real problem is if in a system there are extensions creating PCAP files, but they did not produce CDR tickets / have no CDR license. In this case after a start-up each stored call will produce a PCAP file, the reporting query will fail and the recorder will try later again. To avoid large quantity of PCAP files and slow call processing switch on the reporting feature on each extension creating PCAP files. Or avoid that extension without a reporting creates PCAP files.

Receiving an answer form the reporting the recorder understand immediately the involved parties and can delete the file if the caller was not an Agent or store it.

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

=== Audio encryption ===
The security system is based on AES encrypted xml data file. That file contains the CDR data but even the security parameter of the audio file. Therefore if an audio file is manipulated (changed in any way) that will be detected and show in the player (the “manipul” red label is on while off and the green “original” on if the audio file is the original one).

That means that the audio file itself is not encrypted, some customers want reproducing the file even with other media player.

But there are also customer that have another view and are worried about for example that such an audio file once copied is no more controllable. Or they simply do not thrust that the security features described works fine.

Therefore also the audio file itself can be AES encrypted if that option is switched on in the recorder. The player will detect automatically that an audio file is encrypted and reproduced it anyway.
Here how a player shows a detected Audio encryption:

[[Image:SEC21.png]]

Of cause an encrypted audio file can be reproduced just with the innovaphone player, no other media player will work.

Please note that any innovaphone player can do the decryption, so if you want to assure that just “your” player can reproduce you have to define a customer decrypt key in the recorder (and player).

The recorder shows switched on encryption in the main view (see picture above).

Audio encryption has also disadvantages, recorder and player has more workload and require more disk space; in fact size of the audio files will double if encrypted!

==Audio compression==

=== Wave ===
As default the files are saved in the wave format. More precisely in G711 because wave is a container format and pure PCM would require near the double disk size than G711.

=== PCAP (Build 1134) ===

A recorder can save files also in the original PCAP format. As well as using wave or MP3 format encoding is supported also using PCAP files. A PCAP file require more or less the same disk space than wave recordings. Also the Player form Build 1134 on support PCAP file play.

Note: If the recorder work as a service only PCAP Recording is possible. See relative article.

Note: The Recorder can work also as PCAP to Wave or MP3 converter and/or http Player server. See relative articles.

=== MP3 ===

As an option a mp3 compression can be activated. The required disk size is about 75% less, so one minute in wave requires about 1Mb while the same data in mp3 will require 250kb.

If you wonder why the savings are not much higher consider that even the wave format itself is jet compressed as explained.

All other functions like encryption (an encrypted file size is again doubled, so one minute of mp3 audio encrypted requires about 500kb) or reproducing are the same, the user has nothing to do and the player works always in the same mode.

There is just one situation where an action is required: if the recorder works for a certain period with wave and then with mp3 (or vice versa) in the directory of that month there will be mixed files (wave and mp3). The player detect this and shows automatically an additional key where the user must switch between those two formats: if a directory has just one type of files no action is required and the button is hided.

===MP3 Stereo to Mono conversion===

If the MP3 option is on, files could also be converted form stereo to mono. The file size savings will be nearly 50%, so one minute conversation in mono MP3 requires about 130kB.

Note that conversion from wav to mp3 causes quality lost and stereo to mono even. Once converted, there is no possibility to return to the original format in terms of quality or format. So a bad mono mp3 quality cannot be recovered and even the stereo separation of the cannels cannot be done once converted to mono.

===MP3 just internal channel===

An interesting option in using MP3 is to record just one channel, the left (default) or the right one. The result is a mono file (130kB/min) where just one party is recorded.

If a GW point to an external trunk the internal user is always talking on the left channel. Therefore with this option on just the voice of the internal user is recorded, and doing that in many countries is simply allowed without any restrictions (basically I can record myself).

If recording is done on the phone the channel assignment is vice-versa, the internal caller (the phone) is recorded always in the right channel. Therefore in the setup of the recorder can be selected which cannel should be recorded. That means also that no mixed scenarios (GW and Phone recording) are supported for that feature.

[[Image:SetupR01.png]]

== Redundancy ==

The recorder is able to handle redundancy scenarios with active and standby devices.
The recorder has to handle 3 sources in different scenarios, the PBX itself, the reporting and the CF or webdav server. Those devices can be all together in one single device (for example in an active IP6010 with reporting and CF and a standby IP6010 with reporting and CF) or on different devices (for example an active and a standby IP800 and two reporting on two different PCs).
Another example is active and standby PBX on Gateways but reporting on a high availability VMware environment, so at the end just one reporting from the recorder point of view.

Therefore the standby can be defined for each of those devices.
If you have no redundancy scenario just leave blank the relative setup values.

=== Active/Standby PBX ===

The failure of the PBX is detected because the SOAP connection will go down. If that happen the recorder will try to establish an alternative link to the standby PBX, if that fails he try again with the primary PBX and so one. That means also that a breakdown of the SOPA connection, for example if you reset the PBX, will require some more seconds until the system is up again (because first the recorder try the standby PBX, this will also fail and after that the main SOAP will be up again).

Note that after a restart the recorder try always the first the main address and then the standby one.

In the panel of the recorder near the PBX status indicator is shown the actual link: if the “ACT” lamp is green than the active PBX is tempted, if gray and the “STB” lamp on the standby link is on.

Please note that the recorder can handle differences in active and standby mode just regarding the IP address. All other parameter must be the same, so for example the path to the reporting must be the same.

=== Active/Standby Reporting ===

If the link to the reporting fails and there is a standby address indicated the recorder try to reach the reporting using the standby IP address for the reporting. If there is just one reporting leave the standby address blank.

As you (hopefully) know the reporting can also be installed on two devices, in that case both PBX (the active and the standby one) will transmit CDR ticket to both reporting applications. The reporting database is replicated and therefore if both devices are on the recorder will find the same informations on each reporting. So in theory if both are on it is not important where the reports are requested. In fact if the active reporting fails the recorder will try a connection to the standby reporting. Now if the active device and relative reporting is on again the recorder could also continue get records from the standby reporting. And he will do that until he is restarted or the standby reporting is down because the reporting will answer. If that is not desired flag the option in the recorder setup (“follow Standby/Active PBX”); doing so the recorder will communicate again with the reporting on the active PBX if the active PBX is up again. So basically the switch is done on link down but also following the SOAP.

=== Active/Standby CF/mSATA ===

If the PCAP files are buffered on a CF/mSATA and the PBX goes down also the recorder has to re-map his drive to the standby PBX. In the setup there is a flag in the PCAP section (“follow Standby/Active PBX”), if on the recorder will try to reach the CF of the standby PBX (he takes the IP address of the standby PBX) in the setup.

In scenarios where an external Webdav server is used that flag should not be switched on. The redundancy in that case is demanded to the external devices (for example VMware).

So if you have a “classic” innovaphone redundancy (for example two IP6010 with reporting and CF) indicate the standby address in the PBX and Reporting panel and switch on the “follow Standby/Active PBX” in the reporting and PCAP panel and anything is fine.

== 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 available only on a local port (127.0.0.1) and used for interfacing with the reporting (see relative article). The following description is just for internal use.

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

If you post in your browser “''http://127.0.0.1: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.

== Recording rules ==

The recording rules describe how the innovaphone PBX and the innovaphone voice recorder works in complex situations.

While basic calls are simple and straight forward in logic, voice recording behavior becomes non clear in complex situations.

What about voice recording if for example a recorded user transfers the call to a “normal” user? Answer: This call will be entirely recorded and booked under the recording user by design; those behaviors are intended under “recording rules”.
From a technical point of view mostly no other solution is possible, from a political point of view any rule could be endless discussed.

Remember that in this chapter “Agent” is just the wording for “user enabled to recording with license” while “user” is a “normal” user, eventually even recording pcap files, but he is not in the recording user group.

In theory senseless recording should not be done. So deleting a record because it should not be stored is a task of the recorder; not recording at all if not necessary is better. That can be achieved avoiding or forcing extensions to the recording gateways or doing recoding directly from the IP-Phone.

The length (or contend) of a record depends; if the recording is done on a GW the entire call will be recorded (if not you will find a note in the rules), from his very first answer to the end. Therefore all the parties involved are even recorded. If recording is done on the phone level just the active call time on that phone will be recorded.

Generally spoken there are not necessary recording rules if the recording is done from the innovaphone IP-Phone: the recording starts when the phone answer the call and ends when the phone hangs up.

So the following table shows the recording rules if recording is done on a GW level.

“External” is the external calling or called party. Of cause if you record even internals calls (forcing all calls in a GW) in some situation the “External” is in reality a internal user, but this will not change the rules. The recorder recognizes the “external” party involved simply because it is the longest number involved.

The recorder stores always even the reporting data and therefore all details are visible in case of doubts. The audio filename anyway if formed just from the internal user number and the external user number even if more numbers are involved in the call (for example in a 3party conference).

Example: External call from number 012345 goes to the Agent number 24, after 3 second he will answer: the result will be a file name like “2014-05-12 14:00_24_i_012345_3_UID”.

Later on in the player you can search “24” or “012345” (or a fraction of it like “0123*” ecc.). In the reporting you can search also all other fields (like other involved extensions) and start the player than from the reporting (see relative function in the innovaphone player).

Note: the following rules works on any type of call transfer (with or without announcement).

“Delete” means that the call will be deleted on the CF. “Call” means that they talk. For example “Agent calls External” indicated the direction and means also that the involved parties talk (or at least produce a pcap file).

Rules:

• External call to Agent = Agent

• External call to User = Deleted

• External call to Agent, User pick-up the call = Agent

• External call to User, Agent pick-up the call = Agent

• External call to broadcast group, Agent answer = Agent

• External call to broadcast group, User answer = Deleted

• External call to User, User hold and transfer to Agent = Agent

• External call to Agent A, Agent A hold and transfer to Agent B = Agent A

• External call to Agent A, Agent B pick up the call = Agent A

• External call to WQ, WQ call XML with DTMF input, XML call WQ, WQ call Agent = Agent (just the external Number is considered, not the DTMF codes and numbers between)

• External call to WQ, Agent A transfer call to Agent with or without announcement = Agent A (from Build1185)

• External call to WQ, Agent transfer call to User without announcement = Agent (from Build1185)

• External call to WQ, Agent transfer call to User with announcement = Deleted (from Build1185)

• External call to WQ, User transfer call with or without announcement to Agent = Deleted (from Build1185)

• Agent call External = Agent

• Agent call External, Agent hold and call transfer to User = Agent

• Agent call User, User hold and transfer to External = Deleted

• Agent call External, Agent hold and talk with User but no call transfer = Agent (just external conversation is recorded)

• Agent A call External, Agent A hold and transfer to Agent B = Agent A

• Agent B call External, Agent B hold and transfer to Agent A = Agent B

• User call to Agent, Agent hold and transfer to External = Agent

• User call External, User hold and transfer to Agent = Agent

• User call External = Deleted

• User call External, User hold and talking with Agent but no call transfer = Deleted

• User call Agent, Agent hold and Agent talk with External = Agent (just the external conversation is recorded)

• External call to Agent, Agent has activated a unconditional call forward (CFU) to a User = Deleted

• External Call to Agent, Agent has activated a call forward on busy (CFB) to a User and is busy = Deleted

• External Call to Agent, Agent has activated a call forward on no response (CFNR) to a User, User answer after timeout = Agent

• External call to Agent A, Agent A has activated a unconditional call forward (CFU) to Agent B = Agent B

• External Call to Agent A, Agent A has activated a call forward on busy (CFB) to Agent B and is busy = Agent B

• External Call to Agent A, Agent A has activated a call forward on no response (CFNR) to Agent B, Agent B answer after timeout = Agent A

Note: If Threat call recording is on a call can be marked to store from the calling or called agent. But if both parties are Agent, the called Agent has to dial the code for storing: if the caller dials the code the record will not be saved.

From version 11 on the generated pcap file have a different format. While in former versions the name of a pcap file was a unique single long number form version 11r1 on the ticket as two additional id, one is build form the serial number of the device and the other one if an increasing number. This new format is also generated when recording is done form directly the phone. The recorder can handle both formats automatically, no special setup is required.

We want to focus your attention on the reason of the new format. If for example the recording is done on the phone the phone will generate a new pcap file each time a new call is opened form the PBX point of view.

Example: Phone rings and the user answers, the recording starts with record 1. Then the user put the call on hold and call another extension, this generates record number 2. Then the phone returns to the first call and continuous talking that will be the 3td call. Of cause using the player you will see those 3 calls one after the other (using the user as filter). That this is one situation you recognize looking the reporting details displayed and if you select the 3 calls the player will play one after the other (switch on the loop key) and you listen the entire call in one shoot.

== TAN ==

Build 1167

TAN stand for “Transaction authentication number” used mainly in electronic banking and is a 6 digit long number. Of cause also other applications could use numbers like ticket systems or project handling.

In voice recording a record should be assigned to a TAN and a filter (search) should be possible. The actual integrated function work exclusive with a 6 digit number.

Please note that also a automatic association is possible as described in the relative chapter in this document: in this case all TAN issues are handled by the 3rt party application while this feature works without 3rt party application.

The operation depends of the Recording Mode in the innovaphone IP-phone.

If the Recording Mode in the IP-phone is switched on to “transparent” or “off” during a conversation the agent press the redial key.

If the Recording Mode in the phone is switched to “manual” or “optional” during a conversation the agent press a feature key (Redirect).

Than the agent enter the prefix for the TAN feature (the prefix for the TAN feature depends of the setup, see installation) and the 6 digit TAN code (without * and #) of this conversation.

During that operation the agent is in conversation with the far party, no DTMF tones are transmitted. In any moment (but during the conversation, not after) the Agent press the redial button to store the number. His phone release and ring again, during that the far party hear a call control tone. If the agent picks up the receiver the connection is again established. Therefore it is good practice to inform the far party that he will be shortly disconnected for operational reasons.

The call can be terminated now in any moment normally, the TAN information will be in the record and also in the reporting. The Recorder has not to be online in that moment because all information about the TAN is in the reporting.

A record can be edited in any moment using the player (if relative permission is switched on in the setup). A TAN can be edited (for example because erroneous operation in the online operation) and to any record can be added a TAN number. Please note that once a TAN number was add to the record the number can be modified but not cancel. Best practice is to assign “000000” as TAN for “no TAN records”. Please note that the option to add TAN to records and filter for TAN can be used also without the recorder just using the player.
In the player a filter for TAN can be activated and combined with any other filter. To filter enter the 6 digit TAN code and press enter. To reset the filter clear at least one digit and press enter.

[[Image:TAN02.png]]

In the record name the TAN is at the end of the filename, starting with a “T”.

The TAN feature is designed to work with innovaphone IP-Phones. The feature works also if a player-server is installed (http access to records). The feature is integrated in the reporting, therefore a player could be controlled directly as usual also from the reporting.

The feature works in the same way regardless if the Agent was called or has called a customer.

=== Setup ===

In the Setup of the Agent, Tab “permission” the “TAN” checkmark enables the player to search and modify TAN numbers. If that checkmark is on the main view of the player shows automatically the relative optional window with tooltip support.

[[Image:TAN01.png]]

To enable the online input during the conversation there are more setups required. Copy the xml “TAN.xml” on the CF/msata/webdav and create a VM object pointing on it. The number of this object will be the “TAN prefix”. Open the Recorder setup, tab “PBX” and enter the TAN prefix.

TCR require a XML (TAN.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] ).

== Known Problems ==

===CDR on trunk===
It is recommended to switch on also the CDR on the involved trunk line if the recording is done on the trunk. If a call on a trunk cause a PCAP file without involving an internal object with reporting (for example a call rerouted to an external destination) there is no CDR ticket for that PCAP file.

===Version 13===
The V12 Recording (this description) works also with an V13 installations. The licenses are identical to the V13 (this recorder can also work with V13 licenses).

Please note that this product require a V12 reporting and is not compatible with the V13 reporting. Therefore if you run this recording in a V13 environment you have to setup on a different platform (for example a Vmware) a V12 reporting.
Also, the V13 mSata/FLASH Webdav cound is not used by the recording V10. You must use a V12 Application Platform Webdav (or an IPVA AP Webdav) to store the pcap files. Typically no problem, since the reporting must already be installed in V12 and a subsequent Ap platform has booted up.

===Open a ticket===

If you have a problem with the recording tool you have to open a ticket as usual. Describe your problem, but send us also the following information:

- Setup of your PBX (with standard password or tell us the password)

- Version of the reporting

- Attach all log and error files and the setup of the recorder. All those files are in the log folder (so zip the entire folder), you find the path and link to the folder in the recorder setup.

- Make some screenshots if possible.

- Open the reporting and do a query where the recorded conversations are in (if possible). Do an export in XML and attached it.

=== No CDR ticket after start-up ===

If a record is not found on the CF and there is no SOAP info about that (for example if you start the recording and there are old terminated calls) the recording checks if the reporting has a related record. If a record is found and it is an Agent involved the record is stored as usual, if no Agent is involved the record will be deleted.

But if there is a recording file found and in the recording there is no related record, the recorder cold simply deletes that record; but this could be fatal. For example the reporting could answer once bad, or the link between the reporting and the PBX is temporary down; in that cases the recording will be lost if simply deleted. Therefore the recorder waits in this situation and asks the reporting again after 2 hours. If even after 2 hours the reporting answer with no record found the file will be deleted (otherwise normally processed and stored or deleted as described before).

Note that the reporting is not aware about the health of the connection between PBX and the Reporting. If the recorder gets no answer from the reporting an alarm occurs and the reporting will not proceed with the storage. But the answer “no record found” is not a clear situation for the software. Therefor this situation has to be avoided and occurs for example if pcaps are recorded, but the users involved have no reporting while the recorder is down and starts up later. So the recorder will “find” pcap files but no reporting information.

During online operation this will not happen, because the SOAP driver will tell the recorder that a specific record has to be deleted, and so the recorder will not check the reporting. This is done even to speed up the recorder because the communication with the reporting is relatively slow. If for example there are many users doing a recording (because a bad setup or simply because a huge PBX) and there are only few users to record a huge amount of files are simply to delete without any further processing. Deleting of files is relatively fast during online operation while in case of startup and then recover historic records it becomes slow, and very slow if there are no CDR tickets. The online deleting of files is just “relatively fast” because the SOAP is very fast but the recorded file has to be closed before deleting. Trying to delete a not closed file will cause an error, if that happen the system after e while will recover, but it is not nice. On top there is no way on a CF to understand if a file is in use or not. Therefore the system will wait 2 seconds before deleting a file.

=== No CDR ticket online ===

There is even an unclear situation in online operation. Imagine that an Agent transmits no CDR information to the reporting (for example because there is no reporting license assigned to that user) or, because of a bad setup in the PBX, the ticket will not arrive to the reporting. A call of an Agent is terminated, the SOAP driver informs the upper layer of the software about that and now the recording ask the reporting about the CDR details. Note that the reporting is not down; the recorder can reach the reporting and get also answers (otherwise the REP alarm would be on). If after a detected call end of an Agent signaled by SOAP and a timeout of 5 seconds no CDR is in the reporting a garbage select routine is activated in the recorder software; this routine ask a second time after other 5 seconds the reporting. If even now the response is “no record found” the reporting waits for this call 2 hours. After 2 hours a third time the reporting is asked, if no record is found the pcap is deleted, otherwise normal processed.

If a record is waiting in the 2 hours timeout status in the field “status” the countdown proceed is shown, for example “P1443”, after 5 seconds “P1442” and so one (number*5/60 = time in minutes to zero).

To fix it just stop the recording, solve the problem if possible (if you are lucky for example the CDR data are in the PBX buffer and will be send to the reporting when connection is up again), if not save the Pcap file, at least it will not be deleted. Then delete the pcap file on the CF to avoid a slowdown of the entire system.

A simple but good idea is to enable the CDR on the recording trunk line, in this case “some information” for the call is retrieved all time and at least the system will not face that problem.

All described can be the result of a bad or erroneous setup, or the customer is aware of that and simply not interested in a good working application. So a “no record” answer could be a real alarm or not. Therefore in the setup that can be selected.

See recording setup, panel reporting, option “Alarm if no CDR ticket found”.

=== Asynchronous reporting/PBX date and time ===

PBX and reporting must have the same date and time. If not, the reporting will detect that and display error and warning messages about a possible manipulation in the files.

So check first the actual date and time of PBX and reporting.

IPVA: Remember that date can be set in the reporting in administration, General, Configure NTP server.

===Voice Recorder Window is truncated===

It could happen that the Voice Recorder Window is truncated. The reason for this is the screen resolution setting in windows. To solve the problem, the screen resolution adaptation must be switched off (set to 100%) in windows system settings.

=== Player Crash on start-up===

If the player won’t start try first play a wave file using the Windows media Player. If the Windows Media Player cannot reproduce the wave file (for example because there is no audio device or the audio device is not ready) the player will not start up. Fix first the PC problem.

=== Recorder stopped responding after the start ===

We have had reports that recording did not run on windows 2008 r2. Symptoms were: recorder stopped responding after the start (recorder hang) and the link to the PBX was down. This had been fixed by running sfc.exe.

=== PBX Trap ===

If the PBX is doing a restart during a recording no CDR record will be produced. Therefore the partial PCAP File will be dropped. If the trap of the PBX is during a file copy from the Webdav, the recorder try up to 5 minutes, but will recover the operation automatically after that time.

===Recorder stopped converting records into mp3===
It can happen that the recorder does not convert any recordings into mp3, even if the mp3 driver is detected and the mp3 conversion is turned on.
In that case, you should check if the name of the storage path contains special characters like <code>()",</code> or space.

===Using Network Drives===
Windows mapping of network drives and also the integrated possibility to map networks drive do not work correctly because of windows bugs.
If destination of the storage you are using is a Webdav folder and you want to use a mapped drive (for example F: or N:), mapping the drive using Windows feature will cause writing/reading issues, and Recording won't convert the file in .wav in the storage path.
Work around: To avoid this, use a third party software like "Net Drive" to create the network map.

== Related Articles ==

[[Reference10:Player_Voice_Recording]]

[[Reference10:Voice_Recorder/Setup]]

[[Howto:Last_Call_Recording]]

[[Howto:Universal_Track_Recording_Tool]]

[[Howto:Integration_reporting_and_voice_recording]]

[[Howto:Soft-migration_%28looping_in_a_innovaphone_gateway%29_and_Voice_Recording]]

[[Howto:Player_over_http]]

[[Howto:Marking_a_record_in_Voicerecording]]

[[Howto:Voice_Recording_in_Master_Slave_scenarios]]

[[Howto:Recorder_as_a_service]]

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

[[Reference13r2:Concept App Service Recordings]]

Reference13r2:Concept App Service Recordings

2021-07-06T12:40:31Z

Eurix:

[[Category:Concept|Apps]]
== Description ==

Recordings is an application running on the App platform which allows to capture the audio streams during a telephone call.
The users phone can be configured to send bi-directional audio streams to the Recordings App and store them into the database.

== Applies To ==

* innovaphone PBX from version 13r2

== Requirements ==
* innovaphone PBX
* innovaphone Application Platform
* Firmware V13r2xx
* Recordings App

'''not compatible with V13 Softphone!'''

== Apps ==

=== recordings ===
[[Image: Usrrecord.png]]
* User version of the App allow you to :
* Access to the user specific records
* Access to the user specific logs
* Filter records by name, by date
* Play, Listen or Download the recording as a .WAV file

Protect against deleting or delete a recording

=== recordingsadmin ===
[[Image:Adminrecord.png]]
Admin version of the app allow you to :
* Access to all records

* Access to all logs
* Set up the records auto deletion retention time in days

* Set the recordings group name

* Set specific trace levels
* Filter records by name, by date
* Play, Listen or Download the recording as a .wav file
* Protect against deleting or delete a recording

== PBX Manager Plugin ==

With the Recordings PBX Manager Plugin an App Objects can be created, edited and deleted on the PBX.

== Configuration ==
* Download the Recordings App via App Store.
* Install the App on the App Platform Manager.
* Create a instance for the Recordings App on the App Platform Manager.
* Create a new PBX recordings Object with the PBX Manager Plugin.
* Create a new PBX recordingsadmin Object with the PBX Manager Plugin.
* Assign recordingsadmin App to authorized (admin) users, which will be allowed to open the Admin UI of the Recordings App.
* Assign recordings App to users who will use the Recordings App.
* Start recordings App and configure with recordingsadmin App the name of the PBX

== Licensing ==

For recordings to work the appropriate license “Service(innovaphone-recordings)” must be installed on the pbx. During installation and configuration of the recordings App Object via PBX Manager a certain amount from the total of installed licenses

Is allocated to the object. There are different modes of licence operation depending on number of users and the number of licences:

* open mode

If the number of licenses allocated to the recordings object are greater or equal to the number of users there is no need to configure a specific recordings group.
All users can record.

If the number of licenses allocated to the recordings object are less than the number of users on the PBX the licenses will be allocated on a first come first serve basis. Unlicensed recordings will nevertheless be kept in the DB,
however they will not be accessible. They will be made accessible automatically when a sufficient number of additional licenses is installed/allocated to the recordings object. These unlicensed recordings will be kept as long as the
licensed ones.

* Group mode

If the number of licenses allocated to the recordings object is less that the number of users and when it must be ensured that a certain group of user can record and access their recordings, these users who must be put into a group.
If the members in the group exceeds the number of allocated licenses, the licenses are allocated first come first serve. As in the open mode unlicensed recordings will be kept, however the grace period of adding additional licenses
is one day, after which these recordings are physically, unrecoverably deleted.

=== Recording on Special Interfaces ===

* Trunk Interface

The Trunk Interface acts as a substitute for the users phone. For outgoing calls the call initiator is the owner of the recording and for him a license is claimed. With incoming calls, the first user answering the call own the recording and a license for this user is claimed.

* Waiting Queue

The user answering the call is owner, a license for him is claimed.

== Upgrade from V13r1 to V13r2 Recordings App ==

=== Compatibility ===

A V13r1 Recordings App can be used in the V13r2 PBX and App Platform environment.

=== License Changes ===
With V13r2 required License Type for the Recordings App changes from a Service License to an App License. Customers with already activated Service Licenses should ask for License Conversion at <code>license@innovaphone.com</code>.

=== Database Conversion ===
On first start after update from V13r1 to V13r2 Recordings App, the App Service will start a database conversion procedure. Depending on the number of recordings in the database, time for conversion my take up to 30 minutes for a database with 100000 recordings.

It is recommended to export the Recordings App database for backup purposes, prior updating the App.

== Troubleshooting ==

=== Recordings App Service ===
The App Service for Recordings App provides a log output on the App instance, after the Diagnostics option "App" is activated for the selected instance.

Additional Trace Level Options for the App Service are configurable via Recordings Admin App. This settings are available via additional Menu in the upper right corner of the REcordings Admin UI:

*Recording - PCAP interface related traces, useful on issues with IP-Phone and Interface Media transmission from Endpoint to the App Service
*Call Information - traces related to the CDR information
*Converting - traces for conversion process from VoIP codecs to WAV
*License - traces for on licensing issues
*UI - traces related to the user interface of the Recordings App

The name of the MAster PBX must be configured via the Recordings Admin App, otherwise a message ''PBX Name missing'' will be displayed.

=== PBX Configuration ===
*WebSocket connection from App Object to the recordings app should show ''connected''
*A correct configuration of the CDR interface is required for transmission of metadata to the recordings service. In case this transmission is not successful, a recording will show a ''NoCDR'' message, instead of username

=== PCAP Recording Interfaces ===
*Check URL for PCAP Recording provided on the IP-Phone or VoIP-Interface of a VoIP Gateway
*A Trace with enabled HTTP-Client option should show a successful HTTP PUT Request towards URL of the Recordings Service PCAP interface (e.g. <code>HTTPCLIENT WEBDAV_FILE_HTTP.2: PUT http://ap.company.com/company.com/recordings/Files/f9e5956e47d460010630009033302ab1-009033302ab1-11--username.pcap</code>)

Howto:A Simple Recording Solution On-Top of The innovaphone Voicemail

2021-07-06T12:36:41Z

Eurix:

==Applies To==
This information applies to

* innovaphone PBX V9 and later

'''Pay Attention:'''
This solution is not working anymore with V13 VM or the actual VM script!
Because die actual vm stores all in the user directory with the "h323" name, die script uses the "cn" name as store-place!

==More Information==
This article explains how a simple recording solution could be set up on-top of an innovaphone Voicemail (VM).

Please note, that this recording solution is exemplary and free. It can be adapted in such, that it doesn't require the VM. It consists of 3 parts:
* Recording of the conversation. This is done by the record.xml script and doesn't need voicemail licenses.
* Listen to recorded conversations by phone. This is done by using the voicemail script and therefore needs voicemail licenses.
* Send recorded conversations by mail. This is done by using the email.xml script and doesn't need voicemail licenses.

As a result, if you want only to listen to the recorded messages on your PC/by mail, then voicemail licenses are not needed.

The recording mode itself (manual, automatic and optional) be done in the mode as described in: [[:Reference:Configuration/Registration/Recording]] 
The recording stores G.711a files into the "stored messages"-area of a user's voicebox. Recorded messages can be listened to by calling a user's voicebox and by proceeding into the main menu option ''2'' for stored messages.

Please be informed, that recording usually requires the agreement of the calling peer and as such must be indicated to the peer. Please note that the file ''note.xxx'' contains the advising file played at the beginning of the recording. You can replace the note-files with own announcements. Make sure to [[Howto:How to convert wave files in to G7xx coder files for the HTTP interface | convert]] them and put them on the CF. If you don’t like to play anything just delete those files.

By default, the email notification is disabled. If you want to enable it, remove comments for the event type="call-end" in the record.xml file and change the following in email.xml:
<assign out="$file" value=""/>
to
<assign out="$file" value="$vm"/>

The standard email.xml file of the voicemail package is used for sending the mails, so the same [[Howto:Send_Email_MWI_Notification_From_The_innovaphone_Voicemail | limitation and troubleshooting]] applies.

===Configuration===
The outline for the following configuration scenario shall be as follows:
* The VM is pre-installed on a CompactFlash card and is available at the number ''66''.
* The configured URL for the VM is ''http://127.0.0.1/drive/CF0/vm/vm.xml''.
* An IP phone ''49:Klaus'' may exist.
* Klaus has a voicebox configured which is available at ''http://127.0.0.1/drive/CF0/vm/Klaus/''
* The recording solution requires an additional voicemail object, which shall be available as 67:vm-record.
* copy the solution files (record.xml and note.xxx) into the VM directory, such that record.xml resides in the same directory of the VM's vm.xml and becomes HTTP-available as http://127.0.0.1/drive/CF0/vm/record.xml.

Create a new Voicemail Object at ''Administration/PBX/Objects/New''
* Enter ''vm-record'' as ''Long Name'' and ''Name''.
* Enter ''67'' as ''Number''
* Enter ''http://127.0.0.1/drive/CF0/vm/record.xml'' as ''URL''.

Browse to the phone's Web UI: ''Configuration/RegistrationX/Recording''
* As ''Mode'' enter ''manual''. (or ''transparent'' if all calls should be recorded)
* As ''Number'' enter ''67''.
* Flag "Two Way Media" option.

====Optional settings====
A possibility to record only calls from/to specific numbers is implemented in the version 1001. Therefore the calling numbers can be placed in the sub-folder '''numbers''' as files containing the calling number in the file name (e.g. 072234567).

To enable this function edit the script and change the value of the variable '''selective_recording''' to '''true'''.

<assign out="selective_recording" value="true"/>

===Testing===
Klaus is engaged in a call.
* During the call press the redial-button. The phone's display should now indicate something like "Recording".

After the call has been finished Klaus calls his voicebox 6649. He enters main menu option ''2''. The recorded message should now be among the stored messages.

== File Format ==
The voice files have the following format:

<Username>/<Record>+<cdpn>+<cgpn>+<date>+<time>+<NumberInMinute>+.g711a

Where
<Username> = separate directory for each user
<Record> = fix text field
<cdpn> = extension which did the recording
<cgpn> = the remote party
<date> = system (PBX) date
<time> = system (PBX) time
<NumberInMinute> = Record in this minute
.g711a = coding

Example:
Record_37-24-01.08.2009-09.03_1.g711a

Extension 37 did voice recording, the far partner was extension 24, date 01.08.2009 at 09:03, the first record in this minute.

Please note that the date and time format always has the format DD.MM.JJJJ and hh:mm.
The file name of course must be unique. In the rare occasion that a user would start a second recording with the same remote party in the same minute (for example if he is toggling with the recording key), an incremental number is added.

Example:

Record_37-24-31.07.2009-13.58_1.g711a
Record_37-24-31.07.2009-13.58_2.g711a
Record_37-24-31.07.2009-13.58_3.g711a

Normally all recordings will end with “_1”.

Please feel free to modify the xml, for example using other separators.

== Known Problems ==
The system sends the e-mail at the end of the conversation to the mail system. If the mail-system is down or not reachable, the e-mail gets lost. Please note that you can find the records anyway on the CF in the user folder. Since the records are not deleted after the mail is sent, you must delete them manually or adjust the xml script.

== Download ==
*[http://download.innovaphone.com/ice/wiki-src#simplerec http://download.innovaphone.com/ice/wiki-src/] - download the complete file package of scripts and files described in this article.

== Related Articles ==
[[Howto:How_to_Configure_the_innovaphone_Voicemail|How to Configure the innovaphone Voicemail]]

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

Howto:A Simple Recording Solution On-Top of The innovaphone Voicemail

2021-07-06T12:35:16Z

Eurix:

==Applies To==
This information applies to

* innovaphone PBX V9 and later

Pay Attention:
This solution is not working anymore with V13 VM or the actual VM script!
Because die actual vm stores all in the user directory with the "h323" name, die script uses the "cn" name as store-place!

==More Information==
This article explains how a simple recording solution could be set up on-top of an innovaphone Voicemail (VM).

Please note, that this recording solution is exemplary and free. It can be adapted in such, that it doesn't require the VM. It consists of 3 parts:
* Recording of the conversation. This is done by the record.xml script and doesn't need voicemail licenses.
* Listen to recorded conversations by phone. This is done by using the voicemail script and therefore needs voicemail licenses.
* Send recorded conversations by mail. This is done by using the email.xml script and doesn't need voicemail licenses.

As a result, if you want only to listen to the recorded messages on your PC/by mail, then voicemail licenses are not needed.

The recording mode itself (manual, automatic and optional) be done in the mode as described in: [[:Reference:Configuration/Registration/Recording]] 
The recording stores G.711a files into the "stored messages"-area of a user's voicebox. Recorded messages can be listened to by calling a user's voicebox and by proceeding into the main menu option ''2'' for stored messages.

Please be informed, that recording usually requires the agreement of the calling peer and as such must be indicated to the peer. Please note that the file ''note.xxx'' contains the advising file played at the beginning of the recording. You can replace the note-files with own announcements. Make sure to [[Howto:How to convert wave files in to G7xx coder files for the HTTP interface | convert]] them and put them on the CF. If you don’t like to play anything just delete those files.

By default, the email notification is disabled. If you want to enable it, remove comments for the event type="call-end" in the record.xml file and change the following in email.xml:
<assign out="$file" value=""/>
to
<assign out="$file" value="$vm"/>

The standard email.xml file of the voicemail package is used for sending the mails, so the same [[Howto:Send_Email_MWI_Notification_From_The_innovaphone_Voicemail | limitation and troubleshooting]] applies.

===Configuration===
The outline for the following configuration scenario shall be as follows:
* The VM is pre-installed on a CompactFlash card and is available at the number ''66''.
* The configured URL for the VM is ''http://127.0.0.1/drive/CF0/vm/vm.xml''.
* An IP phone ''49:Klaus'' may exist.
* Klaus has a voicebox configured which is available at ''http://127.0.0.1/drive/CF0/vm/Klaus/''
* The recording solution requires an additional voicemail object, which shall be available as 67:vm-record.
* copy the solution files (record.xml and note.xxx) into the VM directory, such that record.xml resides in the same directory of the VM's vm.xml and becomes HTTP-available as http://127.0.0.1/drive/CF0/vm/record.xml.

Create a new Voicemail Object at ''Administration/PBX/Objects/New''
* Enter ''vm-record'' as ''Long Name'' and ''Name''.
* Enter ''67'' as ''Number''
* Enter ''http://127.0.0.1/drive/CF0/vm/record.xml'' as ''URL''.

Browse to the phone's Web UI: ''Configuration/RegistrationX/Recording''
* As ''Mode'' enter ''manual''. (or ''transparent'' if all calls should be recorded)
* As ''Number'' enter ''67''.
* Flag "Two Way Media" option.

====Optional settings====
A possibility to record only calls from/to specific numbers is implemented in the version 1001. Therefore the calling numbers can be placed in the sub-folder '''numbers''' as files containing the calling number in the file name (e.g. 072234567).

To enable this function edit the script and change the value of the variable '''selective_recording''' to '''true'''.

<assign out="selective_recording" value="true"/>

===Testing===
Klaus is engaged in a call.
* During the call press the redial-button. The phone's display should now indicate something like "Recording".

After the call has been finished Klaus calls his voicebox 6649. He enters main menu option ''2''. The recorded message should now be among the stored messages.

== File Format ==
The voice files have the following format:

<Username>/<Record>+<cdpn>+<cgpn>+<date>+<time>+<NumberInMinute>+.g711a

Where
<Username> = separate directory for each user
<Record> = fix text field
<cdpn> = extension which did the recording
<cgpn> = the remote party
<date> = system (PBX) date
<time> = system (PBX) time
<NumberInMinute> = Record in this minute
.g711a = coding

Example:
Record_37-24-01.08.2009-09.03_1.g711a

Extension 37 did voice recording, the far partner was extension 24, date 01.08.2009 at 09:03, the first record in this minute.

Please note that the date and time format always has the format DD.MM.JJJJ and hh:mm.
The file name of course must be unique. In the rare occasion that a user would start a second recording with the same remote party in the same minute (for example if he is toggling with the recording key), an incremental number is added.

Example:

Record_37-24-31.07.2009-13.58_1.g711a
Record_37-24-31.07.2009-13.58_2.g711a
Record_37-24-31.07.2009-13.58_3.g711a

Normally all recordings will end with “_1”.

Please feel free to modify the xml, for example using other separators.

== Known Problems ==
The system sends the e-mail at the end of the conversation to the mail system. If the mail-system is down or not reachable, the e-mail gets lost. Please note that you can find the records anyway on the CF in the user folder. Since the records are not deleted after the mail is sent, you must delete them manually or adjust the xml script.

== Download ==
*[http://download.innovaphone.com/ice/wiki-src#simplerec http://download.innovaphone.com/ice/wiki-src/] - download the complete file package of scripts and files described in this article.

== Related Articles ==
[[Howto:How_to_Configure_the_innovaphone_Voicemail|How to Configure the innovaphone Voicemail]]

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

Reference13r1:PBX/Objects/Conference

2021-06-17T13:21:52Z

Eurix:

The PBX conference object manages conference rooms with announcements and PIN protection.

The conference calls themselves are connected by one or more ''conference servers (MCU)'' registered to this object as devices. If more than one conference server is used, the different media types of the calls can be split to the different servers. innovaphone conference interfaces (CONF/SCNF) can be registered to this object to provide audio conferences with application sharing.

== General Configuration ==

The information about general configuration options shared by all objects can be found at [[{{NAMESPACE}}:PBX/Objects]].

== Devices ==
; Hardware Id
: The hardware Id must match with a hardware Id of a device on the General page of the object (not the Gateway). The device is registered to this object and provides the conference service.
; innovaphone device
: This should be ticked if the MCU is an innovaphone device.
; Media Types
: If a media type is ticked, calls to the registration includes this media type.
; Channels Licenses
: use PBX-Channels-Licenses to enable conference functionality
; Number of channels
: The number of the available channels of the MCU device or maximum number of channels to be used. Leaving it empty means 0 (no channels)
; MCU Room Numbers
: If the device isn't an innovaphone device and has several rooms, the room numbers which are dialed can be configured here.
; Registration
: If a registration to this hardware Id exists, the IP address of the registrar is shown here.

== Options ==
; Announcement URL
: The URL where the announcements were saved. A '$type' within the URL is substituted for the announcement type string, e.g. ''<nowiki>http://127.0.0.1/webdav/conference/$type.$coder?coder=g722,g711u,g711a,g723,g729,opus-nb,opus-wb</nowiki>''. The announcement types are listed [[{{NAMESPACE}}:PBX/Objects/Conference/Announcement_types | here]].
; Extern Announcement Name/No: The conference object uses the internal HTTP interface, but announcements can also be provided by an external destination which name or number is to be configured here.
; Room number length
: If the room number length is zero, there is only one room available. If it isn't zero, static rooms can be configured and temporary rooms can be created with the operator.
; PIN
: If the room number length is zero, the PIN of the single conference room can be configured here. It can be empty or consists of four digits.
; Operator enabled
: If ticked, the operator is active. It can be reached if no room number is dialed.
; Trace
: If ticked, the trace of this PBX object is enabled.

== Rooms ==
Up to ''30'' static rooms can be configured. If the room is called by the first member, the configured number of channels and all media types must be available otherwise the room isn't available. If the last member of a room leaves it, the reserved channels are released again.
A room is defined by:
; Room number
: The room number must be unique; it length depends on the room number length option.
; Number of channels
: The number of channels which must be available to open a room at dial-in. If this count of member is reached, the room is full and no further caller can take part.
; Media types
: If a media type is ticked, it is used for the call. If not all ticked media types are available at dial-in, the room can't be opened.
; PIN
: The room PIN can be empty or consists of four digits. The PIN can't be a part of the dialing number.

== Operator ==
If the operator is enabled, users can dial in and create ad-hoc rooms. The requested number of channels for new rooms must be available and are reserved till the last member leaves the room.
; Operator Number
: The number which must be dialed instead of a room number to start the operator. Room numbers mustn't match with this number; numbers of new ad-hoc rooms are checked against it.
: '''Calls to the conference will be routed by default to the operator if no operator number is defined.'''
; PIN
: The operator PIN can be empty or consists of four digits. The PIN can't be a part of the dialing number.
; Media Types for ad-hoc rooms
: The media types which are used for the ad-hoc rooms. The room is also created if not all media types are available, but at least the audio channels.
; IVR Menu
: - PIN for access to operator
: - 3-digit room number
: - Maximum participants followed by #
: - 4 digit PIN followed by # (or only # for room without pin)

Note: Overlap dialing to the Operator number it's not supported, it's necessary to dial the Conference Object Number plus the Operator Number "En-Block".

== Announcements ==
For the supported announcements, please refer to [[{{NAMESPACE}}:PBX/Objects/Conference/Announcement types]].

== Notifications ==
For notification of new participants entering the room, the routing can be adjusted to play a simple DTMF-tone.
Follow the config drawing below for setup:

[[image:conf_interface_notification.png]]

Remark: This does not apply to software conference interfaces (SNCF) as they do not support generation of DTMF sequences.

== myPBX-built-in Conference App ==

Remark: This is a myPBX-only-feature and has nothing to do with myAPPs-based V13-ConferenceAPP!

Starting with V12r2, a conference room can be accessed via built-in application icon in myPBX
; Configuration
: - define at least one room with a dedicated number
: - in the Apps tab of the ''User'' or ''ConfigurationTemplate'' object the room is shown as license named <confobjectname>.<roomnumber>. Tick to grant for user
: - within myPBX, the app has to be made visible via app administration page
; Licensing
: - for conference-app use, a conferencing-app-license (order no. 02-00050-001) is required per user
: - as conference-app is a built-in myPBX app, a myPBX (order no. 02-00031-001) or UC (order no. 02-00044-001) -license is required per user as well

[[Category:Concept_Conference]]

Reference13r1:PBX/Config/General

2021-06-16T07:14:02Z

Eurix:

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.
:* '''Slave''' - The PBX on this device acts as Slave. Within a multisite installation several PBXes can be configured as Slave.
:* '''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.

;DNS: DNS Name of the PBX. If configured this will be used for myPBX redirects if a client tries to register at a PBX on which the user is not configured.

;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 only registrations with a PBX authentication or a verified certificate in case of H.323/TLS are accepted. In this case either "PBX Pwd" or "TLS only" is set in a device generated.

;Reverse Proxy Addresses: Up to 8 addresses (no DNS names allowed) can be entered in this field, separated by comma. Registrations from one of these addresses are assumed to be routed through a Reverse Proxy. To the address '/<certificate name>' can be added to also check the TLS certificate of the Reverse Proxy. If the reverse proxy certificate is to be verified, the certificate or the issuer of the reverse proxy certificate must be trusted in the PBX.
; Assume TLS: If the ''Assume TLS'' checkmark is set, it is assumed, that the reverse Proxy did a successful check of the TLS certificate against the registration name.

;IP address for App Platform
: The ip address of an App Platform can be configured here, with a DNS name used for it. If myApps uses a host to access the PBX different from the configured DNS name of the PBX, the hostname in any App url, which matches the configured AP DNS, is replaced by the AP IP. This way it is possible to configure a PBX with DNS names and access it with myApps when the DNS is not yet set up. If the checkmark ''Operation without DNS'' is set as well any matching DNS name is replaced also when an App service requests the URL of another App service (Example: Users requesting the URL of Devices for provisioning) and in the URL sent to the App services itself (Example: Devices uses this URL to construct the URL set at devices for the Devices registration).

: Note that this mode is intended to be able to run the PBX using DNS names while the DNS is not yet in place. Once the DNS is up and running, neither the DNS name of the AP nor its IP address should be configured here.

;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=g711a,g711u,g722,g723,g729,opus-nb,opus-wb&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,opus-nb,opus-wb'' 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").

:The maximum length of the URL is limited to 500 characters (bytes).

: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. A special filename ''fallback=ringback'' can be used to generate a ringback tone (equivalent to ''TONE?tone=ringback'') instead to play an alternative file.

: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 preceded by '.' (e.g. '''.l''').

:'''l''' Long Name
:'''h''' Name (H.323 id)
:'''n''' Number
:'''N''' Node
:'''P''' PBX
:'''d''' Diverting Name
:'''#d''' Diverting Number

: See [[Howto:Dynamic_MOH]] for more details on how to use dynamic music on hold.

;External Music On Hold: To offload the device from playing the Music on hold, the Music On Hold can be played by a separate 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.
Pls. note that registrations from 127.0.0.1 w/o password will be accepted anyway

;Security block time(s): Time for which a registration to a user is blocked after attempt with wrong password. Default is 20s. With a value of 0 this features is turned off.

;Recall Timeout: A value configured here enables recall after transfer. If a call is transferred and not answered within this time, the call is sent back to the transferring 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 information like activities/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.

;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.

;Media Relay:
:;Off: No Media Relay is done in the PBX
:;On: All media traffic is routed through the PBX. With the '''No Media Relay if Addresses are identical or private''' checkmark, this is not done if the two call endpoints registration addresses are either private or equal (i.e. external endpoints behind the same NAT router). To identify an address as private the "Private Networks" configuration from ''IP4/General/Settings'' is used.
:;Auto: Media traffic is routed through the PBX if calls are between private and public registration addresses but not for calls between private and private or public and public registration addresses. To identify an address as private the "Private Networks" configuration from ''IP4/General/Settings'' is used. In v11 this was the behaviour if ''RTP Proxy'' was ''on''.
: Please note that when media relay is in effect for a call, '''video is not working'''. With ICE (available from v12r1), media relay in the PBX should be obsolete except for special applications. Check ''On'' or ''Auto'' only if you need to have this, since it creates CPU load on the PBX.

;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.

;Reverse Lookup URL
: A String in the LDAP URL Format according [https://tools.ietf.org/html/rfc2255 RFC2255] which will be used by the PBX to make a lookup for all external numbers.
: Number resolutions will be forwarded to internal applications like generated CDRs, Phone App etc..
: Example: ''ldaps://ap.innovaphone.com/dc=entries?givenname,sn,company?sub?(metaSearchNumber=+%n)?bindname=innovaphone.com\contacts''
:* dn: ''dc=entries''
:* attributes: ''givenname,sn,company''
:* scope: ''sub''
:* filter: ''(metaSearchNumber=+%n)''
:** %n is a placeholder for the given cgpn
:* extension: ''bindname=innovaphone.com\contacts''
:** The username for the authentication.
:'''Variables'''
:* %n - cgpn
:* %u - h323 name of the current object
: Also there is an additional field for the LDAP password
: Examples are listed in the [[Reference13r1:Concept_Number_Resolution_and_LDAP#PBX_Configuration|Concept Article]]

;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.
:'''For calls from local PBX only''': If set on a master, calls from a slave are not sent to this destination but sent back to the slave where the call came from. On the slave the call is then sent to a destination configured with 'Route Root-Node External Calls to'.

;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 hierarchically 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/Area-Code/Country-Code: Prefixes to be used to map International, National and Subscriber numbers.
:* '''International Prefix''' (<code>000</code> in Germany).
:* '''National Prefix''' (<code>00</code> in Germany).
:* '''Subscriber''' (in Germany, <code>0</code> is a commonly used trunk line access code).
::The SubscriberID is used for hotkey-actions within myAPPs-launcher. By use of node-objects, adjust the Subscriber Prefix in the respective [[{{NAMESPACE}}:PBX/Objects/Node#Number_Mapping_.28International.2C_National.2C_Subscriber_Prefix.29|node object number mapping]].
::For myPBX-launcher hotkeys, refer to the [[{{NAMESPACE}}:Phone/User/Directories#Dialing_location|dialing location settings]].

:* '''Area-Code''' (in Germany for example, the town Mannheim has area code <code>621</code>).
:* '''Country-Code''' (for Germany, <code>49</code> would be used)

: These settings resemble the same settings found in the [[{{NAMESPACE}}:PBX/Objects/Node | Node ]] and [[{{NAMESPACE}}:PBX/Objects/PBX | PBX ]] object. However, they apply to the ''root'' node instead (and should be consistent through all PBXs in a multi-PBX system).

;Adjust LDAP results for e.164: Add a "+" prefix to an PBX-internal LDAP-contact-search result. This is used for 3rd-party- and DECT-phones which are not able to benefit from the Dialing Location settings in case of LDAP-search in an E.164-setup.

;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

;Registration: The VOIP protocol used for the registration to the master. Possible choices are H.323, H.323/TCP or H.323/TLS.

;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 (The length of the password is limited to 16 characters)

;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). For the replication process the [[Reference9:PBX/Config/Security|PBX Password]] is used which have to be the same password on all PBXes in the system.

;dyn PBX ID: This parameter allows to set replication from a specific DynPBX configured on the Master Device.

;Use local static User DB: A dynPBX has also this checkmark. The database of the main PBX is used, but be careful due to the increased memory usage. The dynPBX will create its own PBX datastructure which allocates memory.

;Route Master calls if no Master to: If the master is not available, master calls are sent to this destination. Destination has to be an object with active registration.

;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

;use TLS: Use LDAPS (TLS) instead of LDAP (TCP).

For complete replication from master to slave or 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.

Reference13r1:Concept App Platform

2019-08-21T07:06:15Z

Eurix:

Reference13r1:Concept App Service Calendar

2019-07-16T09:26:06Z

Eurix: /* Impersonation user */

[[Category:Concept|Apps]]

The App Service Calendar is an App Service which can be installed on an innovaphone App Platform. It is used to synchronize the exchange calendar of the users that have been added to the PBX. For now, the synchronized appointments will be used to update the presence of the users. Doing this, the calendar replaces the previous exchange connector.

== Applies To ==

* innovaphone PBX from version 13r1

== Apps ==

=== innovaphone-calender ===
Runs as a service without UI. Handles the synchronization of the Exchange calendar as well as the update of the users presence.

=== innovaphone-calender-admin ===
(Still experimental) Gives some administrative options and can be used to get the current status.

== PBX Manager Plugins ==
With the calendar plugin, apps can be created and deleted. Also the calendar can be configured.

== Concepts ==
The calendar will get a list of all users available in the PBX. This list will be used to figure out the users available in Exchange (which means, that a user, that isn't available in PBX won't be synchronized by the calendar). Finally, all appointments of the users Exchange calendar will be synchronized to the calendars database and used to update the users presence. The calendar also registeres himself to Exchange to get notified about changes in a users calendar.

=== Synchronization ===
To synchronize all users available, calendar uses the impersonation system offered by Exchange. To activate the synchronization, use the PBX manager to edit the settings for the calendar. There, only the email address and the password for the impersonation user must be given.

=== PBX Settings ===
The calender will replicate the users of the PBX to check, if they can be synchronized with Exchange. Because there can be multiple PBX available, the calendar will only accept one. This one must be set in the calendar settings of the PBX manger by giving the name of the master PBX.

=== Impersonation user ===
Impersonation is the way Exchange offers for services to synchronize multiple Exchange users. An impersonation user means, that a user has the Application Impersonation right. Calendar then uses that user to synchronize every other user found. Be aware of who has access to the impersonation users mail address and password, because that user has all rights to read, modify and add appointments, emails, tasks, etc. in Exchange for every other user. The calender itself must safe the password, but it will be stored in encrypted form to the database. For more information about impersonation user, ask your Exchange administrator.
For Example: https://www.techieshelp.com/exchange-2013-configuring-impersonation-applications/

=== Autodiscover ===
The calendar uses autodiscover to get the Exchange Server version used as well as the address to use for synchronizing (which is done using the Exchange Web Services). Because of this, the impersonation user must have a valid mailbox, or autodiscover for that user will fail and the calendar won't be able to get the required information. It could be that Autodiscover it must be activated first. Ask your Exchange Administrator for more information.

=== Users and primary SMTP address ===
The calendar will get a list of users available in the PBX. After that, he tries to resolve the primary SMTP address for each user. This must be done to be able to synchronize the user. So make sure that the email information given to the users object in the PBX contains at least one address that also exists in Exchange, or the resolving will fail. Note that multiple addresses can given to the users object seperated by semicolon.

== Presence ==
The calendar will create a presence string for the appointments and send it to the PBX. The language and timezone of that presence can be defined in the calendar settings. However, the string also contains some information seperated by hashtags a client can use to rebuild the presence string for its own language and timezone settings (like it will be done by the innovaphone devices). Note that the appointment title itself won't be translated!

=== Presence string format ===
The format of the presence string created by the calendar:

Presence = "Free" / "Free until " Date-Time Next-Appointment / Appointment-Info "until " Date-Time [Next-Appointment]
Date-Time = [Date] [Time] ; Must be at least one of them
Date = Day ("." / "/") Month ("." / "/") Year ; Real format depends on localization settings
Day = 2DIGIT ; 01-31
Month = 2DIGIT ; 01-12
Year = 4DIGIT ; e. g. 2017
Time = Hour ":" Minute ["a.m." / "p.m."] ; Real format depends on localization settings
Hour = 2DIGIT ; 01-12 or 00-23
Minute = 2DIGIT
Next-Appointment = "(" ["Busy: " / "Away: "] Appointment-Info ")"
Appointment-Info = Title | "Private" ;
Title = ; Well - any string in UTF8 Format that can include what ever you whant...

After the presence string, a couple of hash-tags will be added (if Presence is not only "Free"). This tags will
be sent so that a client can re-build with the cleint's localization settings. The tags will be added with the
following rules (note that the order of the tags is not variable):

Tags = "" / "#" Activity " " [Info-Len " "] Date-Time " " [Whole-Day " "] [Next-Activity " " Next-Appointment]
Activity = "free" / "busy" / "away"
Info-Len = "#len:" DIGIT ":" DIGIT ; The first DIGIT is the number of characters (UTF-8 conform) and the second the number of bytes
of the len of the Appointment-Info. This tag only exists if the presence starts with Appointment-Info.
Date-Time = "#until:" DIGIT; DIGIT = Date-Time in sec as 64bit value.
Whole-Day = "#whole-day" ; Only if the appointment or the following one (depending on the case) or next is a
whole-day appointment. In that case, until should only print the date
Next-Activity = "#next-activity" Activity ; Only, if there is a next is the start of the next appointment (see above).
Next-Appointment = "#next:" DIGIT ":" DIGIT ":" DIGIT ":" DIGIT ;
Where the first DIGIT is the position of the next activities Appointment-Info inside the presence
string and the second DIGIT the Appointment-Info length. Those values are given in number of charactes (UTF-8 conform).
The third DIGIT has the same meaning as the first, so that it is given in number of bytes, while the last DIGIT
has the meaning of the second one, but also in bytes.

=== Additional Notes ===

* The presence starts with "Free until", if there is an upcoming appointment.
* If the presence starts with Appointment-Info, Date-Time will be the end of that appointment or the start of the next appointment, if the next appointment starts at or before the current one ends.
* Date-Time will be time-only, if the is the same day as when the precense text will be build, date only, if the appointment (or Next-Appointmant in case that next is a appointment start) is a whole-day appointment.
* Next-Appointment only will be written, if the presence won't start with an Appointment-Info.

=== Example presence strings ===
Free
Free until 10:30 (Busy: Meeting with Caption Sparrow) #free #until:12345 #next-activity:busy #next:24:28:48:28
Meeting with Caption Sparrow until 12:30 #busy #len:28:28 #until:12345
Free until 24.12.2017 (Busy: Christmas) #free #until:54321 #whole-day #next-activity:busy #next:29:9:29:2
Christmas until 27.12.2017 #busy #len:9 #until:42424242 #whole-day
Sleeping until 22.08.2017 07:00 #away #len:8 #until:3333333

Reference13r1:Concept App Service Calendar

2019-07-16T09:25:57Z

Eurix: /* Impersonation user */

[[Category:Concept|Apps]]

The App Service Calendar is an App Service which can be installed on an innovaphone App Platform. It is used to synchronize the exchange calendar of the users that have been added to the PBX. For now, the synchronized appointments will be used to update the presence of the users. Doing this, the calendar replaces the previous exchange connector.

== Applies To ==

* innovaphone PBX from version 13r1

== Apps ==

=== innovaphone-calender ===
Runs as a service without UI. Handles the synchronization of the Exchange calendar as well as the update of the users presence.

=== innovaphone-calender-admin ===
(Still experimental) Gives some administrative options and can be used to get the current status.

== PBX Manager Plugins ==
With the calendar plugin, apps can be created and deleted. Also the calendar can be configured.

== Concepts ==
The calendar will get a list of all users available in the PBX. This list will be used to figure out the users available in Exchange (which means, that a user, that isn't available in PBX won't be synchronized by the calendar). Finally, all appointments of the users Exchange calendar will be synchronized to the calendars database and used to update the users presence. The calendar also registeres himself to Exchange to get notified about changes in a users calendar.

=== Synchronization ===
To synchronize all users available, calendar uses the impersonation system offered by Exchange. To activate the synchronization, use the PBX manager to edit the settings for the calendar. There, only the email address and the password for the impersonation user must be given.

=== PBX Settings ===
The calender will replicate the users of the PBX to check, if they can be synchronized with Exchange. Because there can be multiple PBX available, the calendar will only accept one. This one must be set in the calendar settings of the PBX manger by giving the name of the master PBX.

=== Impersonation user ===
Impersonation is the way Exchange offers for services to synchronize multiple Exchange users. An impersonation user means, that a user has the Application Impersonation right. Calendar then uses that user to synchronize every other user found. Be aware of who has access to the impersonation users mail address and password, because that user has all rights to read, modify and add appointments, emails, tasks, etc. in Exchange for every other user. The calender itself must safe the password, but it will be stored in encrypted form to the database. For more information about impersonation user, ask your Exchange administrator.
-For Example: https://www.techieshelp.com/exchange-2013-configuring-impersonation-applications/-

=== Autodiscover ===
The calendar uses autodiscover to get the Exchange Server version used as well as the address to use for synchronizing (which is done using the Exchange Web Services). Because of this, the impersonation user must have a valid mailbox, or autodiscover for that user will fail and the calendar won't be able to get the required information. It could be that Autodiscover it must be activated first. Ask your Exchange Administrator for more information.

=== Users and primary SMTP address ===
The calendar will get a list of users available in the PBX. After that, he tries to resolve the primary SMTP address for each user. This must be done to be able to synchronize the user. So make sure that the email information given to the users object in the PBX contains at least one address that also exists in Exchange, or the resolving will fail. Note that multiple addresses can given to the users object seperated by semicolon.

== Presence ==
The calendar will create a presence string for the appointments and send it to the PBX. The language and timezone of that presence can be defined in the calendar settings. However, the string also contains some information seperated by hashtags a client can use to rebuild the presence string for its own language and timezone settings (like it will be done by the innovaphone devices). Note that the appointment title itself won't be translated!

=== Presence string format ===
The format of the presence string created by the calendar:

Presence = "Free" / "Free until " Date-Time Next-Appointment / Appointment-Info "until " Date-Time [Next-Appointment]
Date-Time = [Date] [Time] ; Must be at least one of them
Date = Day ("." / "/") Month ("." / "/") Year ; Real format depends on localization settings
Day = 2DIGIT ; 01-31
Month = 2DIGIT ; 01-12
Year = 4DIGIT ; e. g. 2017
Time = Hour ":" Minute ["a.m." / "p.m."] ; Real format depends on localization settings
Hour = 2DIGIT ; 01-12 or 00-23
Minute = 2DIGIT
Next-Appointment = "(" ["Busy: " / "Away: "] Appointment-Info ")"
Appointment-Info = Title | "Private" ;
Title = ; Well - any string in UTF8 Format that can include what ever you whant...

After the presence string, a couple of hash-tags will be added (if Presence is not only "Free"). This tags will
be sent so that a client can re-build with the cleint's localization settings. The tags will be added with the
following rules (note that the order of the tags is not variable):

Tags = "" / "#" Activity " " [Info-Len " "] Date-Time " " [Whole-Day " "] [Next-Activity " " Next-Appointment]
Activity = "free" / "busy" / "away"
Info-Len = "#len:" DIGIT ":" DIGIT ; The first DIGIT is the number of characters (UTF-8 conform) and the second the number of bytes
of the len of the Appointment-Info. This tag only exists if the presence starts with Appointment-Info.
Date-Time = "#until:" DIGIT; DIGIT = Date-Time in sec as 64bit value.
Whole-Day = "#whole-day" ; Only if the appointment or the following one (depending on the case) or next is a
whole-day appointment. In that case, until should only print the date
Next-Activity = "#next-activity" Activity ; Only, if there is a next is the start of the next appointment (see above).
Next-Appointment = "#next:" DIGIT ":" DIGIT ":" DIGIT ":" DIGIT ;
Where the first DIGIT is the position of the next activities Appointment-Info inside the presence
string and the second DIGIT the Appointment-Info length. Those values are given in number of charactes (UTF-8 conform).
The third DIGIT has the same meaning as the first, so that it is given in number of bytes, while the last DIGIT
has the meaning of the second one, but also in bytes.

=== Additional Notes ===

* The presence starts with "Free until", if there is an upcoming appointment.
* If the presence starts with Appointment-Info, Date-Time will be the end of that appointment or the start of the next appointment, if the next appointment starts at or before the current one ends.
* Date-Time will be time-only, if the is the same day as when the precense text will be build, date only, if the appointment (or Next-Appointmant in case that next is a appointment start) is a whole-day appointment.
* Next-Appointment only will be written, if the presence won't start with an Appointment-Info.

=== Example presence strings ===
Free
Free until 10:30 (Busy: Meeting with Caption Sparrow) #free #until:12345 #next-activity:busy #next:24:28:48:28
Meeting with Caption Sparrow until 12:30 #busy #len:28:28 #until:12345
Free until 24.12.2017 (Busy: Christmas) #free #until:54321 #whole-day #next-activity:busy #next:29:9:29:2
Christmas until 27.12.2017 #busy #len:9 #until:42424242 #whole-day
Sleeping until 22.08.2017 07:00 #away #len:8 #until:3333333

Howto:Set Type of Service (ToS) DiffServ DSCP Values for innovaphone Windows Applications

2019-02-14T10:26:45Z

Eurix:

==Applies To==
This information applies to all innovaphone Windows Applications sending the RTP Data (this is currently the SoftwarePhone (audio) and the myPBX launcher (video))

==More Information==

===Problem Details===

In contrast to the innovaphone devices, that allows you to [[Reference9:IP4/General/Settings|specify the IP v4 TOS header field value]] used for voice and signalling IP packets, the MS Windows based applications like SoftwarePhone and myPBX do not have any possibility to set ToS Values on the RTP packets due restriction of the Microsoft Windows operating system.

Instead to set the ToS Value in the Application the [http://technet.microsoft.com/en-us/library/dd919203%28WS.10%29.aspx Policy-based Quality of Service (QoS)] provided by the MS Windows operating system can be used to mark the IP packets.

Usually the configuration of the Policy-based Quality of Service is done by defining a [http://technet.microsoft.com/en-us/library/hh831689.aspx Group Policy Object (GPO) in the Group Policy Management Console (GPMC)]. This could be done for a single computer or distributed to a number of computers via the domain controller.

{|border="2" cellspacing="4" cellpadding="3" rules="all" style="margin:1em 1em 1em 0; border:solid 1px #AAAAAA; border-collapse:collapse;empty-cells:show;"
|+ Microsoft Windows QoS Policy Mappings for innovaphone Applications
!Policy Name!!Application Path!!Protocol!!Source Port!!Destination Port!!Source IP / Mask!!Destination IP / Mask!!DSCP Value!!Throttling Rate
|-
| innovaphone myPBX Video RTP||%programfiles(x86)%\\innovaphone\\myPBX\\myPBX.exe||UDP||50000:50100||*||*||*||34||-1
|-
| innovaphone myPBX Signalling HTTP||%programfiles(x86)%\\innovaphone\\myPBX\\myPBX.exe||TCP||*||80||*||*||26||-1
|-
| innovaphone myPBX Signalling HTTPS||%programfiles(x86)%\\innovaphone\\myPBX\\myPBX.exe||TCP||*||443||*||*||26||-1
|-
| innovaphone SoftwarePhone Audio RTP||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||UDP||2050:16000||*||*||*||46||-1
|-
| innovaphone SoftwarePhone Signalling RAS||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||UDP||*||1718:1719||*||*||26||-1
|-
| innovaphone SoftwarePhone Signalling H225||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||TCP||*||2048:59999||*||*||26||-1
|-
| innovaphone SoftwarePhone Signalling H323/TCP||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||TCP||*||1720||*||*||26||-1
|-
| innovaphone SoftwarePhone Signalling H323/TLS||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||TCP||*||1300||*||*||26||-1
|-
| innovaphone SoftwarePhone Signalling SIP||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||TCP/UDP||*||5060||*||*||26||-1
|-
| innovaphone SoftwarePhone Signalling SIPS||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe|| TCP||*||5061||*||*||26||-1
|}

The DSCP Values in the above example are default DSCP values used by innovaphone devices, according to the Wiki article [[Howto:Calculate Values for Type of Service %28ToS%29 from DiffServ or DSCP Values]]. You may change this values to meet requirements on your traffic prioritisation and routing equipment.

In the Windows 8, Server 2012, Windows 10 and later it is possible to use [http://technet.microsoft.com/en-us/scriptcenter/powershell.aspx PowerShell] to configure the values with the [https://technet.microsoft.com/en-us/library/hh967471(v=wps.630).aspx NetQosPolicy] Cmdlet.

The above table can be added to the Grou Policies by the following powershell commands (administrator account access right required):

<code>
New-NetQosPolicy -Name "innovaphone myPBX Video RTP" -DSCPAction 34 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\myPBX\myPBX.exe" -IPProtocolMatchCondition UDP -IPSrcPortStartMatchCondition 50000 -IPSrcPortEndMatchCondition 50100
New-NetQosPolicy -Name "innovaphone myPBX Signalling HTTP" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\myPBX\myPBX.exe" -IPProtocolMatchCondition TCP -IPDstPortMatchCondition 80
New-NetQosPolicy -Name "innovaphone myPBX Signalling HTTPS" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\myPBX\myPBX.exe" -IPProtocolMatchCondition TCP -IPDstPortMatchCondition 443
New-NetQosPolicy -Name "innovaphone SoftwarePhone Audio RTP" -DSCPAction 46 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition UDP -IPSrcPortStartMatchCondition 2050 -IPSrcPortEndMatchCondition 16000
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling RAS" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition UDP -IPSrcPortStartMatchCondition 1718 -IPSrcPortEndMatchCondition 1719
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling H225" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition TCP -IPSrcPortStartMatchCondition 2048 -IPSrcPortEndMatchCondition 59999
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling H323 TCP" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition TCP -IPDstPortMatchCondition 1720
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling H323 TLS" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition TCP -IPDstPortMatchCondition 1300
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling SIP" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition Both -IPDstPortMatchCondition 5060
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling SIPS" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition TCP -IPDstPortMatchCondition 5061
</code>

Please note, the QoS policies added via powershell NetQosPolicy cmdlet are not visible in the Group Policies Editor (gpedit.msc). To list the configured QoS policies use <code>Get-NetQosPolicy</code> cmdlet.

The GPO on the PCs will refresh from time to time automatically. To apply the changes to the GPO immediately following command can be used:
Gpupdate.exe /force

===Known Problems===
In some cases setting of the following registry key is required to ensure the DSCP values are applied:

HKEY_LOCAL_MACHINE /SYSTEM / CurrentControlSet / Tcpip / "Do not use NLA" = 1

Reboot of the PC is required afterwards.

==Related Articles==
* [[Howto:Calculate Values for Type of Service (ToS) from DiffServ or DSCP Values]]
* [[Howto:Firmware Upgrade V6 V7 and later#Default ToS Values]]
* [[Howto:The IPv4 TOS field and DiffServ]]
* [[Reference9:IP4/General/Settings]]
* [[Reference:Configuration/IP/Settings]]
* [[Howto:Softphone recommended settings]]

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

Howto:Set Type of Service (ToS) DiffServ DSCP Values for innovaphone Windows Applications

2019-02-13T13:51:54Z

Eurix:

==Applies To==
This information applies to all innovaphone Windows Applications sending the RTP Data (this is currently the SoftwarePhone (audio) and the myPBX launcher (video))

==More Information==

===Problem Details===

In contrast to the innovaphone devices, that allows you to [[Reference9:IP4/General/Settings|specify the IP v4 TOS header field value]] used for voice and signalling IP packets, the MS Windows based applications like SoftwarePhone and myPBX do not have any possibility to set ToS Values on the RTP packets due restriction of the Microsoft Windows operating system.

Instead to set the ToS Value in the Application the [http://technet.microsoft.com/en-us/library/dd919203%28WS.10%29.aspx Policy-based Quality of Service (QoS)] provided by the MS Windows operating system can be used to mark the IP packets.

Usually the configuration of the Policy-based Quality of Service is done by defining a [http://technet.microsoft.com/en-us/library/hh831689.aspx Group Policy Object (GPO) in the Group Policy Management Console (GPMC)]. This could be done for a single computer or distributed to a number of computers via the domain controller.

{|border="2" cellspacing="4" cellpadding="3" rules="all" style="margin:1em 1em 1em 0; border:solid 1px #AAAAAA; border-collapse:collapse;empty-cells:show;"
|+ Microsoft Windows QoS Policy Mappings for innovaphone Applications
!Policy Name!!Application Path!!Protocol!!Source Port!!Destination Port!!Source IP / Mask!!Destination IP / Mask!!DSCP Value!!Throttling Rate
|-
| innovaphone myPBX Video RTP||%programfiles(x86)%\\innovaphone\\myPBX\\myPBX.exe||UDP||50000:50100||*||*||*||34||-1
|-
| innovaphone myPBX Signalling HTTP||%programfiles(x86)%\\innovaphone\\myPBX\\myPBX.exe||TCP||*||80||*||*||26||-1
|-
| innovaphone myPBX Signalling HTTPS||%programfiles(x86)%\\innovaphone\\myPBX\\myPBX.exe||TCP||*||443||*||*||26||-1
|-
| innovaphone SoftwarePhone Audio RTP||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||UDP||2050:16000||*||*||*||46||-1
|-
| innovaphone SoftwarePhone Signalling RAS||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||UDP||*||1718:1719||*||*||26||-1
|-
| innovaphone SoftwarePhone Signalling H225||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||TCP||*||2048:59999||*||*||26||-1
|-
| innovaphone SoftwarePhone Signalling H323/TCP||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||TCP||*||1720||*||*||26||-1
|-
| innovaphone SoftwarePhone Signalling H323/TLS||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||TCP||*||1300||*||*||26||-1
|-
| innovaphone SoftwarePhone Signalling SIP||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe||TCP/UDP||*||5060||*||*||26||-1
|-
| innovaphone SoftwarePhone Signalling SIPS||%programfiles(x86)%\\innovaphone\\SoftwarePhone\\softwarephone.exe|| TCP||*||5061||*||*||26||-1
|}

The DSCP Values in the above example are default DSCP values used by innovaphone devices, according to the Wiki article [[Howto:Calculate Values for Type of Service %28ToS%29 from DiffServ or DSCP Values]]. You may change this values to meet requirements on your traffic prioritisation and routing equipment.

In the Windows 8, Server 2012, Windows 10 and later it is possible to use [http://technet.microsoft.com/en-us/scriptcenter/powershell.aspx PowerShell] to configure the values with the [https://technet.microsoft.com/en-us/library/hh967471(v=wps.630).aspx NetQosPolicy] Cmdlet.

The above table can be added to the Grou Policies by the following powershell commands (administrator account access right required):

<code>
New-NetQosPolicy -Name "innovaphone myPBX Video RTP" -DSCPAction 34 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\myPBX\myPBX.exe" -IPProtocolMatchCondition UDP -IPSrcPortStartMatchCondition 50000 -IPSrcPortEndMatchCondition 50100
New-NetQosPolicy -Name "innovaphone myPBX Signalling HTTP" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\myPBX\myPBX.exe" -IPProtocolMatchCondition TCP -IPDstPortMatchCondition 80
New-NetQosPolicy -Name "innovaphone myPBX Signalling HTTPS" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\myPBX\myPBX.exe" -IPProtocolMatchCondition TCP -IPDstPortMatchCondition 443
New-NetQosPolicy -Name "innovaphone SoftwarePhone Audio RTP" -DSCPAction 46 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition UDP -IPSrcPortStartMatchCondition 16384 -IPSrcPortEndMatchCondition 32767
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling RAS" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition UDP -IPSrcPortStartMatchCondition 1718 -IPSrcPortEndMatchCondition 1719
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling H225" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition TCP -IPSrcPortStartMatchCondition 2048 -IPSrcPortEndMatchCondition 59999
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling H323 TCP" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition TCP -IPDstPortMatchCondition 1720
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling H323 TLS" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition TCP -IPDstPortMatchCondition 1300
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling SIP" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition Both -IPDstPortMatchCondition 5060
New-NetQosPolicy -Name "innovaphone SoftwarePhone Signalling SIPS" -DSCPAction 26 -NetworkProfile All -AppPathNameMatchCondition "%programfiles(x86)%\innovaphone\SoftwarePhone\softwarephone.exe" -IPProtocolMatchCondition TCP -IPDstPortMatchCondition 5061
</code>

Please note, the QoS policies added via powershell NetQosPolicy cmdlet are not visible in the Group Policies Editor (gpedit.msc). To list the configured QoS policies use <code>Get-NetQosPolicy</code> cmdlet.

The GPO on the PCs will refresh from time to time automatically. To apply the changes to the GPO immediately following command can be used:
Gpupdate.exe /force

===Known Problems===
In some cases setting of the following registry key is required to ensure the DSCP values are applied:

HKEY_LOCAL_MACHINE /SYSTEM / CurrentControlSet / Tcpip / "Do not use NLA" = 1

Reboot of the PC is required afterwards.

==Related Articles==
* [[Howto:Calculate Values for Type of Service (ToS) from DiffServ or DSCP Values]]
* [[Howto:Firmware Upgrade V6 V7 and later#Default ToS Values]]
* [[Howto:The IPv4 TOS field and DiffServ]]
* [[Reference9:IP4/General/Settings]]
* [[Reference:Configuration/IP/Settings]]
* [[Howto:Softphone recommended settings]]

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

Reference9:Phone/User/Recording

2018-04-09T09:47:11Z

Eurix:

The recording feature permits to record conversations on a recording device. Recording is implemented as a 3 party (3PTY) conference between the two conversation peers and the recording device. While a conversation is recorded no other 3 party conference can be opened. A ``Recording´´ message in the status line and/or the label/LED-pattern of a function key with the ``Recording´´ function assigned indicates that the current conversation is recorded.

* '''Mode''':
** Manual: Recording of the active call is manually started and stopped by pressing the Redial key or a function key with the ``Recording´´ function assigned.
** Transparent: Recording is started automatically as soon as a call is connected and stopped when there is no call left. It cannot be stopped manually.
** Optional: Recording is started automatically as soon as a call is connected. It can be stopped and restarted manually by pressing the Redial key or a function key with the ``Recording´´ function assigned.

* '''Number''': The telephone number of the recording device.

* '''Name''': The H.323 name of the recording device (if any).

* '''External call only''': Restrict recording to calls from/to external lines.

* '''Function Key Control Only''': Recording can be started and stopped by a ``Recording´´ function key only. The Redial key keeps it's normal function (context dependent, for example it initiates a blind transfer of the active call). No ``Recording´´ message is displayed in the status line if this checkmark is set, the recording state is indicated by the associated key label/LED-pattern only.

* '''Two Way Media''': Enable reciving of media data from the recording device. By default the recording call from the phone to the recording device is established in sendonly mode because usually a recording device does not send any media data. ``Two Way Media´´ need to be checked only in special application cases, for example when the Innovaphone Operator "Greeting Function" or a "Recording prompt" is used.

==== Call Data ====
The recording call from the phone to the recording device is a straight fresh call with the recording phones telephone number as calling line id. However, the remote party number (that is, the party the agent is talking to) will be sent with this call as diverting number<ref name=from>available from V6 SR2</ref>
(H.450 leg2 information in H.323 and '''Diversion:''' header in SIP, respectively). Please note that when the agent does consultation calls while recording, the recorded stream always follows the active call. The changing remote party numbers are notified in the recording call through a CT-COMPLETE with number/h323id (which is interworked to an ''UPDATE'' or ''re-INVITE'' request with updated '''P-Asserted-Identity:''' header in SIP).

The diversion info sent in the recording call will indicate an incoming call as ''diversion user busy'' and an outgoing call as ''diversion-no-answer''.

This special attribution can be suppressed with the <code>/recording-without-remote-party-info</code> flag for the <code>PHONE SIG</code> config line (e.g. <code>config add PHONE SIG /recording-without-remote-party-info</code>).

<references/>

Howto:XCAPI

2018-02-23T08:08:05Z

Eurix:

==Applies To==
This information applies to

* Configuring the XCAPI with the innovaphone Gateways and innovaphone PBX

== Introduction ==

This document is intended to support you with the integration of the XCAPI (version 3.4.0.0) into an existing environment of
current innovaphone gateways (Version 6 and following). In the following sections we describe the essential steps of configuration to allow for optimal cooperation of both the XCAPI and the innovaphone PBX/gateway. At this point, we suppose that the innovaphone PBX, the hardware the XCAPI is running on and both the XCAPI and your CAPI applications are already installed properly. For some extended information on installation procedures please refer to the respective manuals. A short installation manual for the XCAPI is available at the XCAPI Homepage (http://www.te-systems.de/community/index.php?L=0).

Both XCAPI and Innovaphone support H.323 and SIP and we can configure the Trunk between them using the Gateway/Relay or directly registering XCAPI on the PBX. ''However the only method recommended is registering XCAPI directly on the innovaphone PBX using SIP Protocol. All other setups are no longer supported thus''.

=== Configuring the innovaphone ===
In this example, we are going to use one PBX gateway object (XCAPI-SIP-GW) and register XCAPI on this Object.

==== Creating a Gateway Object in the PBX ====
Log in to the PBX administration and create a new gateway object. The name of the object is "XCAPI-SIP-GW", and the number is 93 in this case.

[[Image:2-pbx-gw-object-gw-4-config.PNG]]

[[Image:XCAPI_no_iband_disconnect.PNG]]

Note: At this Gateway Object we should select the option "No Inband Disconnec" to avoid issues with external call transfer that are rejected.

=== XCAPI Configuration ===
When the XCAPI configuration is started for the first time, there are no configured controllers. Use the link "Click here to add a controller" in the overview page to start the controller wizard.

[[Image:controller-wizard-0.PNG]]

==== Add new VoIP controller ====
On the welcome page of the controller wizard, select to add a new VoIP controller.

[[Image:controller-wizard-1.PNG]]

==== Network Interface ====
In the next dialog, select the network interface that you want to use for the SIP connection between the XCAPI and the innovaphone gateway.

[[Image:controller-wizard-2.PNG]]

==== Select VoIP environment template ====
From the list of predefined VoIP environments, select a innovaphone (PBX object) template.

[[Image:controller-wizard-3.PNG]]

==== Signalling Protocol ====
We must select SIP as protocol to be used by XCAPI.

[[Image:controller-wizard-4.PNG]]

==== innovaphone (PBX Object) ====
Here we must insert the innovaphone PBX System Name or IP address. This will depend on the option "Use as Domain" at PBX->Config.

If we have "Use as Domain" we insert the system name of the PBX:

[[Image:controller-wizard-5a.PNG]]

Then if the System name it's not resolved by DNS we need to configure SIP Proxy in the XCAPI Configuration after we finish the Wizard:

[[Image:controller-wizard-5b.PNG]]

If there is no "Use as Domain" we configure the IP address of the PBX:

[[Image:controller-wizard-5.PNG]]

==== User Information ====
Here we insert the GW Object Name previously created at "Username" field, the use of password it's optional.

[[Image:controller-wizard-6.PNG]]

==== Description and channels ====
Enter a meaningful description and the number of lines that the XCAPI can use to communicate with the innovaphone gateway simultaneously.

[[Image:controller-wizard-7.PNG]]

==== Confirmation ====
Check if all necessary information has been entered correctly (green symbols on the left) and confirm all data by clicking Finish.

[[Image:controller-wizard-8.PNG]]

Then the new controller appears in the XCAPI configuration. Save the changes and stop all running CAPI applications before restarting them.

[[Image:controller-wizard-9.PNG]]

== Known Problems ==

=== No MOH ===

* In XCAPI version 3.3.249 when XCAPI puts call on hold it uses media attribute "send-only", this could affect some call scenarios by not providing MOH to the held party. In order to PBX provide the MOH the hold must be set with media attribute "inactive" instead. In future releases of XCAPI it's planned that "inactive" will be set already in the template for innovaphone PBX meanwhile you can edit in the configuration this option like the image bellow shows. Also other option that should be enable it's "Send attribute "Recvonly" when being held" for the cases that XCAPI it's put on hold.

[[Image:controller-wizard-10.PNG]]

* If you perform a consultation transfer with XCAPI (example using Voxtron Agent hold incoming PSTN call and does consultation transfer with alerting to another agent) and the held party doesn't hear the MOH/Alerting from the PBX then the reason could be the default option in XCAPI configuration to "Discard incoming audio data when held".

[[Image:controller-wizard-11.PNG]]

=== Failure on Registration due missing Username ===

* Gateway Object with Password requires extra step of configuration on XCAPI settings after XCAPI wizard it's finished. For that reason we need to insert the Name/Number for registration at field "Username(Authorization)" at XCAPI SIP Settings.

[[Image:controller-wizard-12.PNG]]

=== Incoming call declined by PBX ===

*If the registration is successful but an incoming call is declined by the PBX due to an unknown contact header you should enter the xcapi object name as contact parameter in the XCAPI configuration.
Notice: When using MWI by SIP notify, the Contact Header of the SIP Notify must be identical to the Contact Header of the SIP Registration. The Contact for the Registration will be create automatically. Perhaps a registration by number would be a solution. Normally, the Contact field must be left blank.

[[Image: Xcapi-contact.png]]

- On v10sr8/V10sr9 the previous behaviour was fixed so the Contact Info should have no value, if you set value like the example this will cause problems with the SIP Register after a restart of the Gateway.

- On v10sr10 there is a fix for the SIP Register issue, so you can set a name on the Contact Info or leave it blank both methods will work.

=== One way audio using SRTP ===
XCapi does not support SRTP unless the optional XSSA Module is installed. If SRTP is used anyway, one-way-audio may occur (from XCapi to innovaphone endpoint).

If you do not want to install XSSA (and thus use un-encrypted RTP to the XCapi), you may (from XCAPI Version 3.4.x on) enable the XCAPI Tweak <''REJECT_UNACCEPTABLE_SDP''> to reject calls with unsupported SAVP (i.e. SRTP) media requests.

[[Image:XCAPI_Tweak_reject_unacceptable_SDP.jpg]]

The calling innovaphone device will then re-initiate the call w/o SRTP.

For more information about XSSA please contact TE-Systems.

If the SIP Security Additions are available, the enable "SIP Security Addittions" should be activated to have SRTP like in the picture bellow:

[[Image:XCAPI_SIP_SIPSecurity.png]]

=== T38 / Fax failed ===
T38 will not supported if the option "Software Fax über Sprachkanäle benutzen" is enabled. If required disable this option.

[[Image:Xcapi_controller_features_softax.png]]

=== Screenshots of a example XCAPI configuration ===
PBX V9/V10 - Xcapi 3.5.31.0

Changes which are different to the config of the Wizard are highlighted.

[[Media:XCAPI_Config.zip]]

=== MWI is not working when XCAPI is connected via GK-Interfaces ===
You must set "Interworking/QSIG" in the route from the XCAPI GK-Interface to the PBX-Registration

===Support of DTLS===
At the moment(Summer 2015) XCAPI does not support DTLS. So please make sure that you are not using DTLS only at phones calling the XCAPI. This may change in the future.

== Related Articles ==



* http://www.xcapi.de
* http://www.te-systems.de

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

Reference12r2:PBX/Config/myPBX

2018-02-08T13:16:30Z

Eurix:

myPBX is the web application of the innovaphone PBX for end users.

= Configuration =
== Common Settings ==
* '''Enable''' Turns the application on or off. It is disabled by default.
* '''Launcher URL''' The URL that should be configured in the myPBX launcher.
* '''Start in web browser''' Click this link to start myPBX in the web browser right away.

== Authentication ==
myPBX can use the Netlogon service of the Box for authenticating users against a Windows domain. For that the Netlogon service has to be connected to a domain controller.
* '''PBX only''' Login is allowed with PBX user password only.
* '''Netlogon only''' Login is allowed with Windows password only.
* '''PBX and Netlogon''' Login is allowed with both PBX user password and Windows password.

== Password policy ==
Defines rules for password changes in myPBX.
* '''Minimum length''' The minimum number of characters for new passwords.
* '''Minimum number of categories''' Defines the number of different character types that new passwords must consist of, namely
** upper case letters
** lower case letters
** numeric digits
** special characters
* '''Forbid password changes''' Disables the possibility to change the password in myPBX and over the myPBX protocol.

== Call List Service ==
myPBX can use the innovaphone reporting as a database for call lists.

* '''Type''' The type of the reporting service
** <code>off</code>: do not use reporting for call lists
** <code>LOCAL-AP</code>: running on the same box
** <code>REMOTE-AP</code>: running on a different box. The myPBX client decides which protocol to use (HTTP or HTTPS), depending on the URL (http or https)used to connect to the PBX.
** <code>LOCAL-CF</code>: use the local CF card for call-lists. This is possible on devices without the Linux AP running. The call list service must be configured for this under [[Reference11:Services/Call-Lists]].

For LOCAL-AP or REMOTE-AP
* '''Host''' The IP address of the reporting service
* '''User''' The ''User'' name of the ''Linux web server credentials'' of the Linux application platform providing the reporting service
* '''Password''' The password of the ''Linux web server credentials''

For LOCAL-CF
* '''Host''' The IP address or Hostname of the device which hosts the myPBX service (don't use loopback IP Address)
* '''User''' The admin user of the device which hosts the myPBX service
* '''Password''' The admin password of the device which hosts the myPBX service

'''Note:''' Additional Administrator Accounts can't be used as "User" for the LOCAL-CF feature. It must be the main administration login of the device.

== Preferences ==
* '''Logo URI''' The URI to a customized logo image that will be displayed in the myPBX Launcher, myPBX web application and at the phone on the "phone-app". The image size should be 220x150px or less. Leave empty to keep the standard logo. The file format should be PNG or JPEG or an other format that is supported by web browsers.

= Access =
== URLs ==
There is a start page that opens the application in a dedicated browser window and that allows for choosing the language from a list.
http://IP-ADDRESS/PBX0/MY/start.htm

The application can also be accessed directly. This is the URL to be configured at the myPBX launcher or a smart phone.
http://IP-ADDRESS/PBX0/MY/client.htm
In this case the language can be selected by adding <code>?lang=XX</code> to the URL with <code>XX</code> being the ISO 639-1 language code. For an example <code>fr</code> means French.

== Login ==
People can login using the credentials from their PBX user object:

* user name (H.323-ID)
* password

Only users with a password can login.

= Related Articles =
* [[{{NAMESPACE}}:Services/Call-Lists]]
* [[{{NAMESPACE}}:Services/Netlogon/Config]]
* [[{{NAMESPACE}}:Concept myPBX]]

Reference7:Configure Active Directory Replication

2018-01-18T14:23:54Z

Eurix: Speicherort ist zwingend erforderlich im Aufruf

=Applies To=
This information applies to

*innovaphone PBX V7 and later
*Microsoft Windows Server Platforms

Tested with MS Windows 2000 Server and MS Windows 2003 Server.

=More Information=
Active Directory (AD) replication allows to import Windows Users into an innovaphone PBX as user objects. It is a read-only replication. Nothing is going to be written into the AD.

An attribute mapping mechanism allows to map arbitrary AD-attributes into arbitrary innovaphone-attributes.

=Configuration=
The configuration can be divided into the two tasks [[#AD Settings|AD Settings]] and [[#Attribute Mapping|Attribute Mapping]]. This article focusses on Attribute Mapping.

*Maps for incoming attributes must be configured. An In-Map controls which content of which incoming attribute goes into a runtime symbol table.
*Maps for outgoing or local attributes must be configured. An out-map controls which runtime symbol table entry fills a local attribute.

=AD Settings=
Please see [[Reference7:Configuration/LDAP/Replicator|Reference7:Configuration/LDAP/Replicator]] for common server settings as IP address, DN, User, Password, LDAP Filter.

==Replicating in a Domain Forest==
[[Image:domain-forest.png|left|thumb|100px|Domain Forest, built up by 3x DCs]]
A company ''foo.bar'' maintains three domain controllers (DC).
*A root DC for the naming context ''dc=foo, dc=bar''
*A sub DC for the naming context ''dc=sales, dc=foo, dc=bar''
*A sub DC for the naming context ''dc=support, dc=foo, dc=bar''

The task may now be to replicate all users within ''dc=foo, dc=bar'' recursing down into all sub-domains.
By default this isn't possible, because MS designed a DC to only answer LDAP search requests with search results it is authoritative for.

The role of a global catalog (GC) is supposed to overcome this limitation. A DC acts as a GC if contacted on TCP port 3268.

Therefore..if it's desired to replicate from a forest of DCs
* Enter as ''LDAP/Replicator/Server'' the destination as ''[IP Address]:[port]''
**''IP Address'' shall be the IP address of the root DC
**''port'' must be ''3268''

'''Note''': Be sure to have read below [[#Replicated_Objects_Lost_After_erroneous_Changes_in_Active_Directory|Replicated Objects Lost After erroneous Changes in Active Directory]]

=Attribute Mapping=
There are a list of [[#Grammar For In-Maps|In-Maps]] and a list of [[#Grammar For Out-Maps|Out-Maps]]. That's it.
In-Maps allow for regular expressions<ref>Regular Expression, http://en.wikipedia.org/wiki/Regular_expression. We use POSIX 1003.2 regular expressions syntax, see e.g. https://www.freebsd.org/cgi/man.cgi?query=re_format&sektion=7&apropos=0&manpath=FreeBSD+10.3-RELEASE+and+Ports for a detailed description</ref>. Out-Maps merely consist of symbol names or literals (constants).

#On reception of of a source-ldap object, all existing attributes will be investigated and a corresponding in-map is being looked-up for each attribute
#If there are many in-maps per attribute, all maps will be executed sequentially and the value assignment will be placed (if the pattern matches)
#In case of a matching map, then values will be maintained within a symbol table (see grammar: 'identifier' production)
#Values within the symbol table will be overwritten (if already existing)
#After completion, the target-ldap-object will be generated by means of the Out-Maps. If a value application without a value in the symbol table will be found (i.e. no In-Map matched and wrote something into the symbol), then the source-ldap-object is to be discarded

Because of the possible discard of a source object in step #5 above, you must provide a default value for all objects which should be replicated although there is no value in it for an attribute used in an Out-Map! (see in the examples below how to do that)

==Grammar For In-Maps==
An in-map is a pair of <source-attr-name> (An AD-attribute name) and <assignment_pattern>.
Approximate Grammar:

<pre>
assignment_pattern ::= <symboldefinitions> ':' <regexp>
| <symboldefinitions>

symboldefinitions ::= <symboldefinitions> <symboldefinition>
| <symboldefinition>

symboldefinition ::= <identifier> '=' <value_expression>
| <identifier>

value_expression ::= '/' <VALUES> '/'

VALUES ::= <VALUES> <VALUE>
| <VALUE>

VALUE ::= '\' <NUM> # Back Reference
| '\'' <ALLCHARS> '\'' # Literal
| <ALLCHARS> # Const, synonymous to Literal

identifer ::= '%' <ALNUM>

regexp ::= <ALLCHARS>

ALNUMS ::= ALNUMS ALNUM
| ALNUM

ALNUM ::= ['a'-'z'|'A'-'Z'|'0-'9']

ALLCHARS ::= [.*]
</pre>

==In-Map Examples, Maps for ''telephoneNumber''==

* %dw=/\1/:07031 12345-(.*)
that assigns the extension to the symbol %dw

* %dw=/\2/%root=/\1/:07031(.*) -(.*)
this assigns the extension to the symbol %dw and the root-/subscriber number to %root.

* If the <value_expression> was skipped, it defaults to \n, wher n is the running index of the symbol_definition (starting with 1). The second example from above can therefore be written as: %root%dw:07031(.*) -(.*)

* A default value for a symbol may be defined by simply applying an an always-match-constant-value. That is, for instance for telephoneNumber
%dw=/0/:.*

* Because of the rule, that a missing regexp defaults to ''':(.*)''' , this can be written as
%dw=/0/

* If an attribute value is to copied straight, one simply writes
%e164

* which is identical with
%e164=/\1/:(.*)

==Grammar For Out-Maps==
An out-map is a pair of <destination-attr-name> (name of an innovaphone attribute) and <destination_values>.
Approximate Grammar:
<pre>
destination_values ::= <destination_values> <destination_value>
| <destination_value>

destination_value ::= <identifier>
| '\'' <ALLCHARS> '\'' # Literal
| <ALLCHARS> # Const, synonymous to Literal
</pre>
This grammar allows to fill the e.g. local cn-attribute not only with a single identifier, but with an intermixed concatenation of several identifiers and literals alike e.g.: ''"%sn', '%givenName"'' - yielding for instance: ''"Doe, Jon"''.

==Example==
The following example focusses on the generation of the e164-, node- and loc-attribute.
*Only Sindelfingen-Numbers (+49(7031)...) will match
*The numbering node (a.k.a. node-attribute) will then be set to ''root''.
*The hosting PBX (a.k.a. loc-attribute) will be set to ''sifi''.

Within the AD exists..:
''Btw, the Filter was configured to: (&(objectclass=User)(telephoneNumber=*))''
<pre>
Peter's telephoneNumber: +49(7031)12345-75
John's telephoneNumber: +49(7031)12345-74
Mary's telephoneNumber: +49(7031)12345-43
</pre>

Map configuration underneath Configuration/LDAP/Replicator:
<pre>
In Maps
Source Attribute Assignment Pattern Description
-------------- ------------------ -----------
cn %cn
telephoneNumber %tel%loc=/sifi/%node=/root/:\+49.*7031.*12345-(.*) Sindelfingen numbers with leading '+' at begin: then backref=1 into %tel. Constant=sifi into %loc. Constant=root into %node.
displayName %dn

Out Maps
Dest.-Attribute Destination Value
-------------- ----------------
cn %cn
e164 %tel
loc %loc
node %node
dn %dn
</pre>

This is how the output is written into the flash:
<pre>
mod cmd FLASHDIR0 add-item 102 (cn=Peter Schmidt)(repsrc=ad)(guid;bin=2B1DAA4655AE244D845734951F5F2F1B)(node=root)(loc=sifi)(dn=Peter Schmidt)(e164=74)(usn=3675)
mod cmd FLASHDIR0 add-item 102 (cn=John Doe)(repsrc=ad)(guid;bin=904AF5506116354E9E86BE9A6C5D67FF)(node=root)(loc=sifi)(dn=John Doe)(e164=75)(usn=3676)
mod cmd FLASHDIR0 add-item 102 (cn=Mary Fernandez)(repsrc=ad)(guid;bin=575743792731EE478EFB40754885BAAB)(node=root)(loc=sifi)(dn=Mary Fernandez)(e164=43)(usn=3678)
</pre>

'''Note''': According to the [[#Grammar For Out-Maps|Out-Maps Grammar]] a local attribute can be synthesized from multiple symbols and literals. Here comes an example for the aggregated synthesis of the local '''CN''' attribute.
<pre>
In Map
Source Attribute Assignment Pattern Description
-------------- ------------------ -----------
...
sn %sn Surname (e.g. Fernandez) into %sn
givenName %gn Name (e.g. Mary) into %gn
...

Out Map
Dest.-Attribute Destination Value
-------------- ----------------
...
cn %sn', '%gn
...
</pre>
yielding:
<pre>
mod cmd FLASHDIR0 add-item 102 (cn=Fernandez, Mary)(repsrc=ad)(guid;bin=575743792731EE478EFB40754885BAAB)(node=root)(loc=sifi)(dn=Mary Fernandez)(e164=43)(usn=3678)
</pre>

==AD Attributes Of Interest==
The following list names the attributes to be configured as ''Source Attribute'' within an In-Map or to be referenced within the LDAP filter:
*cn: The Common Name
**single-valued
**possible usage: for ''cn'' attribute

*sn: The Surname
**single-valued
**possible usage: for DECT display name ''dn'' attribute

*givenName: The Given Name.
**single-valued
**possible usage: for DECT display name ''dn'' attribute

*telephoneNumber: The primary business telephone number. To be found on a user's ''General'' tab.
**single-valued
**mostly in international form with leading plus sign (e.g. +49(7031)12345-44)
**possible usage: for ''e164'' attribute

*memberOf: Group memberships. Groups are named here by their Distinguished Name (DN).
**multi-valued
**possible usage: for ''root'' attribute
**'''Note''':Though there might be desires - PBX groups must still be configured manually. PBX groups cannot be configured through AD Replication.

*samAccountName: The logon name
**single-valued
**possible usage: for ''h323'' attribute

*mail: Email Address
**single-valued
**possible usage: for ''email''<ref name="v10">From on V10: email attribute contains a user's email address</ref> attribute

===Notes on replicating the new-in-V10 ''email'' User Attribute ===
*proxyAddresses: Email Address
**multi-valued
**possible usage: for ''email''<ref name="v10"/> attribute

From V10 upwards, a new user attribute ''email'' is present in a PBX user entry (see [[Reference10:PBX/Objects#General_Object_Properties | ''E-Mail'' in PBX/Objects]]). This is stored as a distinct attribute on the LDAP level, so it can be replicated from the active directory. Please note that since V9, it is recommended to use the users primary email addresses' user part as ''h323'' attribute (e.g. if the users primary email address is <code>user@innovaphone.com</code>, then the h323 attribute should be set to <code>user</code>). If you do so, there is no need to set the ''email'' attribute. However, if you set the ''h323'' to something else, you should set the ''email'' attribute in addition.

To do so, you first need to determine how the user's primary email address is stored in your AD. We recommend to use AD's ''proxyAddresses'' attribute. This is a multi-valued attribute. Each value contains an address prefixed with a protocol specifier (e.g. <code>smtp:</code> or <code>sip:</code>). If there are multiple addresses for a single protocol, the primary address for this protocol has the protocol specifier in capital letters (e.g. <code>SMTP:</code>). SMTP addresses in the ''proxyAddresses'' attribute always include the domain part (e.g. <code>@innovaphone.com</code>). As from V9 up it is recommended to use the customers domain as PBX ''System Name'' property and have the ''Use as Domain'' check-mark ticked, the value in the ''email'' attribute shall consist of the user-part only (e.g. <code>user</code> instead of <code>user@innovaphone.com</code>).

Having said this, appropriate replication patterns are

<code type="text">
Source Attribute Assignment Pattern Description
---------------- ------------------ -----------
proxyAddresses %mail=/\1/:SMTP:(.*) full email address if domain does not match
proxyAddresses %mail=/\1/:SMTP:(.*)@sample.com simplified email address if domain matches

Dest. Attribute Destination Value
---------------- ------------------
email %mail
</code>

In many companies, multiple email addresses are used per user. For example, a user ''Fred Firestone'' with windows account name (''samAccountName'') ''ffi'' may have the proxy addresses ''smtp:ffi@sample.com'' and ''SMTP:ffirestone@sample.com''. If the windows account name shall be used as value for the ''h323'' attribute, you can note the fact that the ''h323'' attribute contains another valid email address by prefixing the value of the ''email'' attribute with <code>.;</code>. Appropriate mappings could thus look like:

<code type="text">
Source Attribute Assignment Pattern Description
---------------- ------------------ -----------
sAMAccountName %sAMAccountName use windows account as Name
proxyAddresses %mail=/\1/:SMTP:(.*) full email address if domain does not match
proxyAddresses %mail=/\1/:SMTP:(.*)@innovaphone.com simplified email address if domain matches

Dest. Attribute Destination Value
---------------- ------------------
email .;%mail apply h323 (Name) as valid email
h323 %sAMAccountName set h323 to windows account

</code>

It is unclear (to us :-)) if AD's ''email'' attribute always holds the primary SMTP address.

=Tips&Tricks=

==Investigating/Dumping An AD Object==
If you want to learn or study about how the AD stores user objects and which attributes are available per user, the tool '''ldifde.exe'''<ref name="ldifde">Using LDIFDE, http://support.microsoft.com/kb/237677 or LDIFDE, http://technet2.microsoft.com/WindowsServer/en/Library/32872283-3722-4d9b-925a-82c516a1ca141033.mspx?mfr=true</ref> will be of help.
Ldifde.exe is a Microsoft command line program which is part of a Windows Server installation. It allows to dump the complete AD content or parts of it into LDIF<ref>RFC2849, LDAP Data Interchange Format</ref> files.

To Dump the AD object for a Windows user ''John Doe'' into a file ''out.txt''
*On a Windows Server open up a command line box.
*Enter:
<pre>
ldifde -s 127.0.0.1 -r "(sn=doe)" -f out.txt
</pre>
Btw, from the file you can also learn which Distinguished Names (DNs) are available. A DN may be required as user name within the common server settings on the LDAP/Replicator page.

To Dump all AD user objects into a file ''out.txt''
*On a Windows Server open up a command line box.
*Enter:
<pre>
ldifde -s 127.0.0.1 -r "(objectclass=User)" -f out.txt
</pre>

==Deleting AD-Replicated Objects==
You may delete up to 100 objects in one instance.
*Proceed to [[Reference7:Configuration/LDAP/Expert|Reference7:Configuration/LDAP/Expert]]
*Enter the LDAP filter ''(repsrc=*)'' into the search edit field an click on '''Show'''
*Check the column selector to select all displayed objects
*Click '''Delete''' within the toolbar. A confirmation dialog will be shown.
*Confirm

==Display Non-AD-Replicated Objects==
*Proceed to [[Reference7:Configuration/LDAP/Expert|Reference7:Configuration/LDAP/Expert]]
*Enter the LDAP filter ''(!(repsrc=*))'' into the search edit field an click on '''Show'''

==Out-Filtering Disabled Windows Accounts==
Windows maintains the numerical attribute ''userAccountControl''<ref>userAccountControl, http://support.microsoft.com/?scid=kb%3Ben-us%3B305144</ref> for each user object within the AD.
If Bit 2 is set, the user account was disabled.

A NOT-Filter term, featuring a matching-rule, ensures that this bit isn't set, i.e. that it is not a disabled account:
*''(!(userAccountControl:1.2.840.113556.1.4.803:=2))''

A complete AND-filter may therefore look like this one:
*''(&(objectclass=User)(telephoneNumber=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))''

==Filtering For Group Memberships==
The multi-value AD attribute ''memberOf'' carries the information which groups a user is belonging to. Groups are named within the AD by their Distinguished Name (DN), instead of by their friendly name.
This is how the AD could be storing a group membership ''Berlin'':
*memberOf: ''CN=Berlin,CN=Users,DC=innovaphone,DC=sifi''

If you wanted to filter for members of the group ''Berlin'', the following AND-filter would do the job:
*''(&(objectclass=User)(memberOf=CN=Berlin,CN=Users,DC=innovaphone,DC=sifi))''

'''Note:''' The filter must be crafted for an equality match. According to MSDN ''memberOf'' does not allow for substring/wildcard matches.

==Merging Old PBX Users Into An AD-Replicated Database==
If AD-replication is about to be administrated for a PBX with an existing portfolio of user objects, the question may arise for how to retain those existing objects. This section explains the background and the required administrative steps.

When looking into a PBX's downloadable configuration file an existing object may grossly look as the following example:
<pre>
mod cmd FLASHDIR0 add-item 102 (cn=Martin Streller)(dn=Martin S.)(h323=mst)(e164=173)(loc=va-sifi)(pbx=etc,..)(pbx=and so on,..)(node=root)(guid;bin=8D7A0AB9E909D311B539009033080010)(usn=106540)
</pre>
Various informations are stored within individual attributes cn(common name), dn(display name), h323(diallable name), e164(number), loc(pbx name), pbx(groups, diversions,...), node (numbering node). One attribute - the ''guid'' - is the actual identifier for an entire pbx object. It is the actual hook or grip for an object. Once assigned a guid will remain static for the whole object's lifetime.

With the AD-replication the ''guid'' is also going to play the same role as an identifier. However, the ''guid'' will be taken from the AD. In detail from the AD attribute ''objectGUID'', which is semantically the same as the ''guid'' of a pbx object. Therefore the necessity arises to manually tweak the ''guid'' as if set by an AD-replication run. After applying this required step the resulting and modified object example from above may look alike:
<pre>
mod cmd FLASHDIR0 add-item 102 (cn=Martin Streller)(dn=Martin S.)(h323=mst)(e164=173)(loc=va-sifi)(pbx=etc,..)(pbx=and so on,..)(node=root)(repsrc=ad)(guid;bin=4C7BA6C8568CAF4D85BA37486EF39A26)(usn=106540)
</pre>
The alert reader will notice that not only the '''guid''' was changed. An additional attibute '''repsrc''' with the value '''ad''' joined the set of attributes. This ''repsrc''-attribute is required internally for all AD-replicated objects. It helps to separate AD-replicated objects from all of the other objects.

With that background in mind, the following recipe summarizes the steps to accomplish.
*Download and save the entire configuration of the box.
*Configure the AD-replication.
*Download the resulting new configuration.
*Open a copy of the old configuration within a suitable editor.
**For all affected objects, replace the ''guid'' attribute with the respective ''guid'' from the new configuration.
**For all affected objects, add the attribute ''repsrc'' with the value ''ad''.
**Copy the AD-replication settings: from the new configuration, copy the line beginning with <pre>config change LDAPREP0 /server...</pre>
**Copy the AD-replication password: from the new configuration, copy the line beginning with <pre>vars create LDAPREP0/AUTH ...</pre>
*Upload the edited old configuration into the box and reboot.

==Assigning Default/Dummy Content Into a Variable==
Sometimes not all AD objects to be replicated, contain all the required attributes to fill values into all of the "Out Maps"-attributes.
In order to avoid empty attributes, a dummy content may be provided. The following example outlines how to handle e.g. objects without an email address.
<pre>
In Maps
Source Attribute Assignment Pattern Description
-------------- ------------------ -----------
cn %cn%mail=/default@example.com/ cn & default dummy content for mail
mail %mail A real email will override the default content. Must follow in-map with default assignment.
..

Out Maps
Dest.-Attribute Destination Value
-------------- ----------------
cn %cn
email %mail
..
</pre>

=Troubleshooting=
Watch out for the '''LDAP/Replicator-Status''' page. This page is going to display errors alike
*''Invalid Credentials'', implying wrong credentials for the LDAP authentication.
*''Cannot Connect'', meaning the configured IP address may be wrong.
*''Connect Timeout'', indicating the AD may be down.

If there are non-specific errors listed, a further click on '''Flash Directory Status''' may reveal error messages from the flash directory module acting below the replication module.
[[Image:Ad-repl-status.PNG|center|thumb|200px|Replicator-Status]]

==Suddenly, New Objects Aren't Replicated. What Can I Do?==
Few support cases dealt with customers missing the replication of newly created user objects. This section outlines a strategy to identify a root cause. It is based on the MS Ldap client ldifde<ref name="ldifde"/>.

Create a batch file and prepare and adapt to your needs, a command line for ldifde as follows:
<code type="text">
ldifde -a "<me>\<domain>" "<pw>" -s 192.168.0.5 -g -d "DC=<my-company>,DC=com" -r "(&(objectclass=User)(telephoneNumber=*))" -v -f result.txt -j c:\tmp
</code>
*'''-a''' user, password credentials for the LDAP bind authentication
*'''-s''' Server IP address
*'''-t''' optional port
*'''-g''' disable some MS specifics
*'''-d''' The root DN underneath which to search
*'''-r''' The LDAP filter
*'''-v''' Print verbose informations to the console
*'''-f''' The file, results will be written to
*'''-j''' The path, where the log should be stored, it's mendatory

The paramaters should be aligned to the configuration underneath '''Services/LDAP/Replicator'''. In addition it might be a good idea to reduce the size of the file result.txt by providing the command line option
*'''-l "cn"''' This option asks the AD only for the attribute cn.

Then watch-out for the missing objects. If they're still not present in the result set, then modifiy the LDAP filter '''-r'''. Simplified filters may be:
*'''"(objectclass=User)"''' Ask for all ''user'' objects
*'''"(sn=Schmidt)"''' Ask for the surname/family name ''Schmidt''
*'''"(sn=Sch*)"''' Ask for all surnames/family names starting with ''Sch''

If the missing objects eventually appear in the result set, then remove the '''-l''' option, in order to retrieve the objects in their entirety with all attributes. Look at the object's attribute and try to draw a conclusion.

Possible causes reported from the field were:
*Group membership didn't fit
*Telephone number wasn't administrated correctly

=Known Problems=
==Freshly Deleted AD-Objects Aren't Deleted Locally==
Although the replicator receives change notify results from the AD, the AD might not send notifications about the deletion of objects.
The replicator will be deleting affected objects only after a stop+start of the replication session.

Lab experiments showed that the AD sent such deletion notifications only, if the replicator had authenticated with administrator credentials - which practically isn't recommendable.

To recover from this peculiarity the following procedure should be implemented:
*Please obey paragraph [[#Out-Filtering Disabled Windows Accounts|Out-Filtering Disabled Windows Accounts]] under the Tips&Tricks section.
*Don't delete AD objects as the first step of the administration procedure for user objects scheduled for deletion.
*Instead: Disable such objects as the first step.

==Increasing CPU Load if poll Timer is set==
If you have an AD Forrest you need to configure a poll timer, because the Notify mechanism isn’t working. If you configure a one minute poll timer, a full replication is done every minute. This causes a high CPU load with low priority.
Furthermore the AD has a mechanism to reestablish a connection if the '''MaxConnIdleTime''' is running out. If the connection is reestablished a full replication is done. The default value is 900 seconds (15 minutes). You can change this value with Ntdsutil.exe.

==Replicated Objects Lost After erroneous Changes in Active Directory==
When the LDAP replication succeeds and a PBX object is found not to be present in the replication result any more, it will be removed from the PBX. This ensures that objects removed from the AD are removed in the PBX also.

However, if an object is missing from the replication result by accident (e.g. because the replication is based on AD groups and the user is mistakenly removed from the group), the corresponding PBX object will be removed too. When the problem is fixed, the object will be re-created again. However, all object properties which are not derived from the AD will be lost (in other words, you will end up with a naked object with all manually set properties lost). To recover from such a situation, the AD problem needs to be fixed and the most recent PBX backup must be applied then.

Note that erroneously changing the LDAP access from ''Global Catalog(GC) Mode'' to ''Non-GC Mode'' will create such a situation too. A GC on port 3268 usually covers a broader database than an AD working in non-GC mode. Therefore it is highly likely to lose just some or even all replicated objects after the GC-mode has been turned off. Re-enabling the GC-mode alone does not recover from this situation for the reasons explained above. In this case, restoring the most recent backup will fix the issue, as this backup will also restore the correct LDAP replicator configuration.

=Notes=
<references/>



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

Freeedit:Wiki Edit Sandbox

2012-10-18T12:52:24Z

Eurix:

Tobias '''TeleSys'''

1234

Stefano '''Eksaip'''

TESt TEST '''TEST'''

K.S '''DTG'''

[CC:'''Roman''']

Thrainer Thomas '''Kufgem'''

Roberto Arletti '''DAM SISTEMI''' SRL

Lars Lerjefors '''Telmekom''' srl

test test

Dawid '''BELL'''

iuuo

Jens '''inexio'''

Christopher '''inexio'''

R.H. '''MediaMobil'''

A.R. '''DeTeWe'''

TEsting

D.B. '''ooperon'''

Mathias Rüger '''Telcat Multicom GmbH'''
MDN '''care-call'''

'''you are crazy to ask such questions.....'''

P.K. '''CN'''

M.B. '''CW'''

Christian, '''Incotec GmbH'''

Tobias, '''TelNet GmbH'''

-thG-

Michael, '''Frank GmbH'''

Dennis, '''Bechtle'''

Bert, '''Volksbank Stuttgart eG'''

Martin, '''Inikon AG'''

Silvio, '''Orange Open Solution SRL'''

Marcin '''Emtel System'''

Łukasz '''Emtel System'''

Christophe '''e-BO Enterprises'''

Bram '''Ooperon'''

Jo-Jo '''IPD'''

Georg '''IPD'''

Franco '''Fiemme Sistemi'''